XCurl 概述

项目
03/29/2024

本主题介绍 xCurl 库，该库是符合 libCurl API 的 Microsoft 游戏开发工具包（GDK）实现。建议将 xCurl作为 Microsoft 游戏开发工具包（GDK）的 HTTP API 游戏。 xCurl 通过遵守所有安全要求和最佳做法来简化游戏开发，而不需要任何特殊的游戏逻辑或处理。但是，它不支持 WebSocket 通信。如果需要实现 WebSocket 通信，请改用 libHttpClient。

XR-134：要使用 Web 协议进行数据传输，为 Xbox 主机开发的游戏不得使用自定义 HTTP 堆栈实现。请改用由操作系统提供且可通过操作系统维护的堆栈。这可确保 Xbox 玩家随着时间的推移获得稳定性和安全性改进。

xCurl 不同于 libCurl，因为 xCurl 是在 WinHttp 之上实现的，并自动遵循 Microsoft 游戏开发工具包 (GDK) 的要求和最佳做法，包括进程周期管理 (PLM)。虽然 xCurl 是与 libCurl 兼容的 API，但 xCurl 中的传输层仅使用 WinHttp，并且不使用 libCurl。因此，xCurl 不需要与 libCurl 的开源实现（包括 bug 修复、版本号等）保持同步。建议开发人员使用 xCurl，以跨所有平台维持相同的 libCurl HTTP 实现，同时只更改一个标头 include 和库链接。

多个 libCurl API 未在 xCurl 中实现，因为它们不常用于游戏开发方案，或者在 WinHttp 中没有可映射到的等效功能。本主题稍后介绍区别。

xCurl 依赖于游戏运行时，并且在 XGameRuntimeInitialize 被调用之后才能初始化。

要了解 xCurl 方法的工作原理，请参阅 libCurl API 文档。

注意

xCurl 和 WinHttp 是 Xbox 主机上 HTTP 的唯一与 XR 兼容的选项。 xCurl 和 WinHttp 实现适用于 Windows 电脑和 Xbox 主机，无需更改代码。但是，在 Windows 电脑上，可以直接将 libCurl 或任何其他 HTTP 堆栈与 Microsoft 游戏开发工具包 (GDK) 游戏一起使用 - XR-134 不适用于 Windows 电脑。

开发人员支持

xCurl 由 WinHttp 提供支持而不是 libCurl，并且它是 Microsoft 游戏开发工具包 (GDK) 的一部分。

应通过 Microsoft 游戏开发工具包 (GDK) 游戏的建议支持路径发送支持请求。这包括联系 Microsoft 代表或通过 Xbox 开发人员论坛联系开发人员支持团队。

将 XCurl 添加到项目

若要在Windows 10电脑或 Xbox 主机上的 Microsoft 游戏开发工具包（GDK）游戏中使用 xCurl ，请在项目中包括 xCurl 扩展 SDK 标头和库。

确保已在开发电脑上安装了游戏运行时开发包 (GRDK)。
打开游戏的 .vcxproj 文件并添加以下元素。这将会链接导入库，并将 XCurl.dll 包含在生成输出中。
```
<GDKExtLibNames>Xbox.xCurl.API</GDKExtLibNames>
```
xCurl具有不同的标头，可将自身与 libCurl 区分开来。在游戏中要包含 curl.h 的位置，需要用 xcurl.h 替换标头，如下所示。
```
#include <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 方式失败。此外，在这些请求上为 CURLINFO_OS_ERRNO 查询 curl_easy_getinfo 将像其他 GRTS API 一样返回 HRESULT_FROM_WIN32(PROCESS_SUSPEND_RESUME)，以防想以不同于一般网络断开故障的方式处理这些故障。

所有的 xCurl 图柄在整个游戏生命周期内都保持有效，包括在暂停/恢复的界限内。在暂停/恢复时不需要清理或初始化任何 xCurl 图柄。任何在暂停后开始的新请求将推迟直到恢复以及随后的网络初始化，以确保它们将尽快启动，而不需要游戏进行任何额外的处理。

注意

将多接口用于 xCurl时，当存在未完成的请求时，游戏应继续调用 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 的并发请求限制相同。游戏应将并发请求限制为不超过 8 个，以确保所有呼叫正常运行。此并发限制适用于从 xCurl、WinHttp 和 Xbox 服务 API 中的任何一个发出的并发请求。

xCurl 使用翻转缓冲器来接收数据。这允许它在向读取回调提供完整缓冲区的同时开始填充第二个缓冲区，然后在填充第一个缓冲区时切换到向读取回调提供第二个缓冲区。然而，如果读取回调的时间太长，或者在多模式下 curl_multi_perform 的调用不够频繁，WinSock 的内核内存可能会积累起来。有关 WinSock 内核内存的详细信息，请参阅套接字内存注意事项。

控制 XCurl 分配

默认情况下，xCurl 使用 Windows 堆并可通过 XMemSetWin32HeapTrackingHooks 追踪其分配。或者，初始化时可提供内存函数，例如 libCurl。

除了 curl_global_init_mem，xCurl 还提供了可选的 xCurl_global_init_mem。提供给此版本的 init 的回调与其他 Microsoft 游戏开发工具包（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

该 CURLShare 界面未实现。

暂停和恢复传输

目前不支持此功能。从回调中返回 CURL_WRITEFUNC_PAUSE 或 CURL_READFUNC_PAUSE 会导致无法恢复的中止操作。

另请参阅

libCurl API

在合作伙伴中心设置 Web 服务（NDA 主题）要求授权

Xbox One 主机上的 Fiddler

通信安全最佳做法概述（NDA 主题）要求授权

通过