> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.
# xCurl 概觀
> xCurl 概觀
本文說明 `xCurl` 程式庫，這是符合 Microsoft Game Development Kit (GDK) 規範的 [libCurl](https://curl.haxx.se/libcurl/) API 實作。`xCurl` 會遵循所有安全性需求和最佳做法，而不需要任何特殊的遊戲邏輯或處理，藉此簡化遊戲開發。不過，它不支援 WebSocket 通訊。如果您需要實作 WebSocket 通訊，請改用 [libHttpClient](/zh-TW/build/console-features/networking/web-requests/http-networking#libhttpclient)。
`xCurl` 與 `libCurl` 的不同之處在於，`xCurl` 是以 [WinHttp](/zh-TW/build/console-features/networking/web-requests/intro-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](/zh-TW/reference/system/xgameruntimeinit/functions/xgameruntimeinitialize) 之前無法初始化。
若要了解 `xCurl` 方法的運作方式，請參閱 [libCurl API](https://curl.haxx.se/libcurl/c/) 文件。
`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* 包含在組建輸出中。
```xml theme={null}
Xbox.xCurl.API
```
1. `xCurl` 使用不同的標頭，以與 `libCurl` 區隔。在遊戲中會包含 *curl.h* 的位置，將標頭取代為 *xCurl.h*，如下所示。
```cpp theme={null}
#include
```
## 設定
`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 文章)](/zh-TW/build/game-principles/security/communication-security-overview)。`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 核心記憶體的詳細資訊，請參閱[通訊端記憶體考量](/zh-TW/build/console-features/networking/game-mesh/winsock-intro-networking#SocketMemory)。
### 控制 xCurl 配置
根據預設，`xCurl` 會使用 Windows 堆積，並可透過 `XMemSetWin32HeapTrackingHooks` 追蹤其配置。或者，也可以像 `libCurl` 一樣在初始化時提供記憶體函式。
除了 [curl\_global\_init\_mem](https://curl.haxx.se/libcurl/c/curl_global_init_mem.html) 之外，`xCurl` 還提供選擇性的 [xCurl\_global\_init\_mem](/zh-TW/reference/networking/xcurl/functions/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](https://curl.haxx.se/libcurl/c/)
[在 Partner Center 設定 Web 服務 (NDA 文章)](/zh-TW/services/xbox-services/fundamentals/s2s-auth-calls/custom-service-config/web-services/live-web-services)
[XBOX One 主機上的 Fiddler](/zh-TW/build/console-features/networking/tools/fiddler-setup-networking)
[通訊安全性最佳做法概觀 (NDA 文章)](/zh-TW/build/game-principles/security/communication-security-overview)
## Related topics
- [xCurl overview](/build/console-features/networking/web-requests/intro-xcurl.md)
- [xCurl 概述](/zh-CN/build/console-features/networking/web-requests/intro-xcurl.md)
- [xCurl 개요](/ko/build/console-features/networking/web-requests/intro-xcurl.md)
- [xCurl の概要](/ja-jp/build/console-features/networking/web-requests/intro-xcurl.md)
- [Información general de xCurl](/es/build/console-features/networking/web-requests/intro-xcurl.md)