Skip to main content
本文說明 xCurl 程式庫，這是符合 Microsoft Game Development Kit (GDK) 規範的 libCurl API 實作。xCurl 會遵循所有安全性需求和最佳做法，而不需要任何特殊的遊戲邏輯或處理，藉此簡化遊戲開發。不過，它不支援 WebSocket 通訊。如果您需要實作 WebSocket 通訊，請改用 libHttpClient。 xCurl 與 libCurl 的不同之處在於，xCurl 是以 WinHttp 為基礎實作，並自動遵循 Microsoft Game Development Kit (GDK) 需求和最佳做法，包括處理程序生命週期管理 (PLM)。雖然 xCurl 與 libCurl 的 API 相容，但 xCurl 內的傳輸層只使用 WinHttp，而不使用 libCurl。因此，xCurl 不需要與 libCurl 的開放原始碼實作保持同步，包括錯誤修正、版本號碼等。開發人員可以使用 xCurl 在所有平台上維持相同的 libCurl HTTP 實作，只需變更一個標頭 include 和程式庫連結即可。 有幾個 libCurl API 未在 xCurl 中實作，原因是這些 API 在遊戲開發案例中不常使用，或在 WinHttp 中沒有可對應的同等功能。本文稍後會說明這些差異。 xCurl 依賴 Gaming Runtime，在呼叫 XGameRuntimeInitialize 之前無法初始化。 若要了解 xCurl 方法的運作方式，請參閱 libCurl API 文件。
xCurl 和 WinHttp 實作可在 Windows PC 和 XBOX 主機上運作，而不需要變更程式碼。

​
開發人員支援

xCurl 由 WinHttp 而非 libCurl 提供支援，且是 Microsoft Game Development Kit (GDK) 的一部分。 支援要求應透過 Microsoft Game Development Kit (GDK) 遊戲的建議支援管道傳送，例如連絡您的 Microsoft 代表，或透過 XBOX 開發人員論壇與開發人員支援小組聯繫。

​
將 xCurl 新增至您的專案

若要在 Windows 10 PC 或 XBOX 主機上的 Microsoft Game Development Kit (GDK) 遊戲中使用 xCurl，請在專案中包含 xCurl 延伸模組 SDK 標頭和程式庫。
  1. 確認您已在開發電腦上安裝 Gaming Runtime Development Kit (GRDK)。
  2. 開啟遊戲的 .vcxproj 檔案，然後新增下列元素。這會連結匯入程式庫，並將 xCurl.dll 包含在組建輸出中。
  1. xCurl 使用不同的標頭，以與 libCurl 區隔。在遊戲中會包含 curl.h 的位置，將標頭取代為 xCurl.h，如下所示。

​
設定

xCurl 等同於使用下列組建旗標編譯的 libCurl。
  • HTTP_ONLY
  • CURL_NO_OLDIES
  • CURL_DISABLE_PROXY
  • CURL_DISABLE_COOKIES
  • CURL_DISABLE_DOH
  • CURL_DISABLE_PROGRESS_METER
  • CURL_DISABLE_MIME
  • USE_SCHANNEL

​
網路初始化

xCurl 會自動處理網路初始化。您可以在遊戲生命週期的任何時間點設定並執行要求。在網路初始化之前啟動的任何要求都會延遲並排入佇列，直到網路完成初始化為止。xCurl 可確保您的要求在最早的時機發出，而不需要遊戲進行任何額外處理。

​
遊戲暫停/繼續

xCurl 會自動處理暫停和繼續。暫停時，所有未完成的要求都會立即取消，並以 CURLE_NO_CONNECTION_AVAILABLE 失敗。此外，針對這些要求查詢 curl_easy_getinfo 的 CURLINFO_OS_ERRNO 會傳回 HRESULT_FROM_WIN32(PROCESS_SUSPEND_RESUME)，與其他任何 GRTS API 相同，方便您以不同於一般網路中斷失敗的方式處理這些失敗。 所有 xCurl 控制代碼在整個遊戲生命週期中 (包括跨越暫停/繼續邊界) 都保持有效。不需要在暫停/繼續時清除或初始化任何 xCurl 控制代碼。暫停後啟動的任何新要求都會延遲到繼續及後續的網路初始化之後。此延遲可確保這些要求盡快啟動，而不需要遊戲進行任何額外處理。
當您的遊戲使用 xCurl 的 multi 介面時，若仍有未完成的要求，遊戲在暫停時應繼續呼叫 curl_multi_perform，並可選擇性地呼叫 curl_multi_poll 或 curl_multi_wait。xCurl 會阻止暫停，直到所有進行中的要求都完成為止，若未呼叫 curl_multi_perform，可能會導致遊戲在暫停期間逾時。我們建議無論暫停/繼續狀態為何，都在整個生命週期中持續呼叫 curl_multi_perform。xCurl 會在內部處理暫停狀態的所有複雜細節。

​
安全性功能

所有透過 xCurl 的 HTTPS 要求都會遵循通訊安全性最佳做法 (NDA 文章)。xCurl 會自動強制執行透過遊戲的「單一登入入口網站」指定的任何特殊憑證關聯。不支援使用 CURLOPT_SSL_VERIFYPEER 停用憑證驗證。 在開發套件上，您可以針對偵錯流量和測試目的指定未加密的 HTTP 配置 http://。對於所有 RETAIL 要求，您必須指定 HTTPS 配置 https://，以提供建議的保護層級。未明確指定配置的 xCurl 要求會推斷為 HTTPS 配置。
xCurl 不會自動插入權杖。若要擷取 XBOX Live 權杖，您的遊戲應呼叫 XUserGetTokenAndSignatureAsync 或 XUserGetTokenAndSignatureUtf16Async GRTS API 以擷取授權和簽章標頭，然後在呼叫 curl_easy_setopt 時使用 CURLOPT_HEADER、CURLOPT_HTTPHEADER 或 CURLOPT_HEADERFUNCTION 選項，在發出要求之前設定標頭。

​
記憶體和並行考量

xCurl 與 WinHttp 有相同的並行要求限制。遊戲應將並行要求限制在八個以內，以確保所有呼叫都能正確運作。此並行限制適用於從 xCurl、WinHttp 及 XBOX Service API 中任何一個發出的並行要求。 xCurl 使用翻轉緩衝區接收資料。此模式可在遊戲從第一個緩衝區讀取時填入第二個緩衝區，藉此提供更高的輸送量。不過，如果讀取回呼花費太長時間，或在 multi 模式下未足夠頻繁地呼叫 curl_multi_perform，WinSock 核心記憶體可能會累積。如需 WinSock 核心記憶體的詳細資訊，請參閱通訊端記憶體考量。

​
控制 xCurl 配置

根據預設，xCurl 會使用 Windows 堆積，並可透過 XMemSetWin32HeapTrackingHooks 追蹤其配置。或者，也可以像 libCurl 一樣在初始化時提供記憶體函式。 除了 curl_global_init_mem 之外，xCurl 還提供選擇性的 xCurl_global_init_mem。提供給此版本 init 的回呼與其他 Microsoft Game Development Kit (GDK) 記憶體回呼類似，且比標準 libCurl 回呼提供更多關於所配置資料的資訊。

​
支援的選項

xCurl 中的 easy 控制代碼支援下列選項。
  • CURLOPT_VERBOSE
  • CURLOPT_HEADER
  • CURLOPT_NOBODY
  • CURLOPT_FAILONERROR
  • CURLOPT_UPLOAD
  • CURLOPT_PUT
  • CURLOPT_ACCEPT_ENCODING
  • CURLOPT_TRANSFER_ENCODING
  • CURLOPT_FOLLOWLOCATION
  • CURLOPT_MAXREDIRS
  • CURLOPT_POST
  • CURLOPT_COPYPOSTFIELDS
  • CURLOPT_POSTFIELDS
  • CURLOPT_POSTFIELDSIZE
  • CURLOPT_POSTFIELDSIZE_LARGE
  • CURLOPT_POSTREDIR
  • CURLOPT_REFERER
  • CURLOPT_USERAGENT
  • CURLOPT_HTTPHEADER
  • CURLOPT_HTTPGET
  • CURLOPT_HTTP_VERSION
  • CURLOPT_CUSTOMREQUEST
  • CURLOPT_HEADERDATA
  • CURLOPT_ERRORBUFFER
  • CURLOPT_WRITEDATA
  • CURLOPT_READDATA
  • CURLOPT_INFILESIZE
  • CURLOPT_INFILESIZE_LARGE
  • CURLOPT_CURLU
  • CURLOPT_URL
  • CURLOPT_PORT
  • CURLOPT_TIMEOUT
  • CURLOPT_TIMEOUT_MS
  • CURLOPT_CONNECTTIMEOUT
  • CURLOPT_CONNECTTIMEOUT_MS
  • CURLOPT_DEBUGFUNCTION
  • CURLOPT_DEBUGDATA
  • CURLOPT_HEADERFUNCTION
  • CURLOPT_WRITEFUNCTION
  • CURLOPT_READFUNCTION
  • CURLOPT_SSL_VERIFYPEER
  • CURLOPT_SSL_VERIFYHOST
  • CURLOPT_SSLCERT
  • CURLOPT_BUFFERSIZE
  • CURLOPT_UPLOAD_BUFFERSIZE
  • CURLOPT_PRIVATE
  • CURLOPT_IGNORE_CONTENT_LENGTH
  • CURLOPT_HTTP_TRANSFER_DECODING
  • CURLOPT_HTTP_CONTENT_DECODING

​
不支援的功能

​
通訊端和 fd_set

xCurl 不會公開用於傳輸的基礎通訊端。因此，xCurl 不會實作任何用於通訊端作業的選項和 API。此限制也移除了使用 fd_sets 透過 select 和 poll 等候資料抵達的能力。若要等候工作抵達，請使用 curl_multi_wait 和 curl_multi_poll。 下列 API 不存在於 xCurl 中
  • curl_easy_send
  • curl_easy_recv
  • curl_multi_socket
  • curl_multi_socket_action
  • curl_multi_socket_all
  • curl_multi_assign
  • curl_multi_fdset
下列選項沒有作用，並會傳回 CURLE_NOT_BUILT_IN 錯誤。
  • CURLOPT_LOCALPORT
  • CURLOPT_CONNECT_ONLY
  • CURLOPT_SOCKOPTFUNCTION
  • CURLOPT_SOCKOPTDATA
  • CURLOPT_OPENSOCKETFUNCTION
  • CURLOPT_OPENSOCKETDATA
  • CURLOPT_CLOSESOCKETFUNCTION
  • CURLOPT_CLOSESOCKETDATA
  • CURLOPT_XOAUTH2_BEARER
  • CURLOPT_PROGRESSFUNCTION
  • CURLOPT_PROGRESSDATA
  • CURLOPT_XFERINFOFUNCTION
  • CURLOPT_XFERINFODATA
  • CURLOPT_NOPROGRESS
  • CURLINFO_LASTSOCKET
  • CURLINFO_ACTIVESOCKET
  • CURLMOPT_SOCKETFUNCTION
  • CURLMOPT_SOCKETDATA
  • CURLMOPT_PIPELINING
  • CURLMOPT_PUSHFUNCTION

​
CURL Share

未實作 CURL Share 介面。

​
暫停和繼續傳輸

目前不支援此功能。從回呼傳回 CURL_WRITEFUNC_PAUSE 或 CURL_READFUNC_PAUSE 會導致作業中止且無法繼續。

​
另請參閱

libCurl API 在 Partner Center 設定 Web 服務 (NDA 文章) XBOX One 主機上的 Fiddler 通訊安全性最佳做法概觀 (NDA 文章)
Last modified on October 6, 2026