This topic describes the
xCurl library, a Microsoft Game Development Kit (GDK) compliant implementation of the libCurl APIs. We recommend
xCurl as the HTTP API for Microsoft Game Development Kit (GDK) titles.
xCurl simplifies title development by adhering to all security requirements and best practices without requiring any special title logic or handling. However, it does not support WebSocket communication. If you need to implement WebSocket communication, use libHttpClient instead.
xCurl differs from
libCurl in that
xCurl is implemented on top of WinHttp and automatically follows all the extra Microsoft Game Development Kit (GDK) requirements and best practices. While
libCurl itself doesn't meet the security requirements for the Microsoft Game Development Kit (GDK) console platform, use
xCurl to maintain your same
libCurl HTTP implementation across all platforms while changing only one header include and library linkage.
libCurl APIs aren't implemented in
xCurl because they don't meet the security requirements for Microsoft Game Development Kit (GDK) titles. The differences are described later in this topic.
xCurl relies on the Gaming Runtime and can't be initialized until XGameRuntimeInitialize is called.
To understand how
xCurl methods work, see the libCurl API documentation.
WinHttp are the only secure options for HTTP on Xbox console.
WinHttp implementations work on both Windows PC and Xbox console with no code changes required. However, on Windows PC, you can use
libCurl or any other HTTP stack directly with your Microsoft Game Development Kit (GDK) title.
Add xCurl to your project
xCurl in a Microsoft Game Development Kit (GDK) game on a Windows 10 PC or an Xbox console, include the
xCurl extension SDK headers and libraries in your project.
Ensure that you've installed the Gaming Runtime Development Kit (GRDK) on your development PC.
Open the .vcxproj file for your game, and then add the following element. This links the import library and includes xCurl.dll with the build output.
xCurlhas a different header to differentiate itself from
libCurl. In the locations where curl.h would be included in your game, replace the header with xCurl.h, shown as follows.
xCurl is equivalent to
libCurl compiled with the following build flags.
xCurl handles network initialization automatically. You can setup and perform requests at any point in your title's lifecycle. Any request started before the network is initialized will be delayed and queued until the network becomes initialized; in this manner xCurl ensures that your requests will be made at the earliest possible opportunity without any extra handling required by your title.
xCurl handles suspend and resume automatically. On suspend, all outstanding requests will be canceled immediately and fail with
CURLE_NO_CONNECTION_AVAILABLE. Additionally, querying
CURLINFO_OS_ERRNO on these requests will return
HRESULT_FROM_WIN32(PROCESS_SUSPEND_RESUME) just like any other GRTS API in case you want to handle these failures differently from general network disconnect failures.
xCurl handles remain valid throughout the title lifecycle including across suspend/resume boundaries. There is no need to cleanup or initialize any
xCurl handle on suspend/resume. Any new requests started after suspend will be delayed until resume and the subsequent network initialization to ensure that they will start as soon as possible without requiring any extra handling by your title.
When using the multi interface for
xCurl, your title should continue to call
curl_multi_perform along with optionally
curl_multi_wait on suspend while there are outstanding requests.
xCurl will block suspend until all in-progress requests are completed, and failing to call
curl_multi_perform may cause your title to timeout during suspend. We recommend continuing to call curl_multi_perform throughout the entire lifecycle regardless of the suspend/resume state.
xCurl handles all intricacies of the suspend state internally.
All HTTPS requests through
xCurl follow the communication security best practices (NDA topic).
xCurl automatically enforces any special certificate pinning specified through your title's "Single Sign-on Portal".
On development kits you may specify the unencrypted HTTP scheme,
http://, for debug traffic and testing purposes. For all RETAIL requests, you must specify the HTTPS scheme,
https://, in order to be XR-12 compliant. xCurl requests that do not explicitly specify a scheme will infer the HTTPS scheme.
xCurl does not perform automatic token insertion. To retrieve Xbox Live tokens, your title should call the
XUserGetTokenAndSignatureUtf16Async GRTS APIs to retrieve the authorization and signature headers, and then use the
CURLOPT_HEADERFUNCTION options in a call to
curl_easy_setopt to set the headers before making the request.
Memory and concurrency considerations
xCurl shares the same concurrent request limitations that apply to
WinHttp. Titles should limit concurrent requests to eight or less to ensure that all calls operate correctly. This concurrency limit applies to concurrent requests that are issued from any of
WinHttp, and Xbox Service APIs.
xCurl uses a flip buffer to receive data. This allows it to start filling a second buffer while providing the full buffer to the read callback and then switch to provide the second buffer to the read callback while the first is being filled. However, if the read callback takes too long or if
curl_multi_perform is not called frequently enough in multi mode, WinSock kernel memory may build up. For more information on WinSock kernel memory, see socket memory considerations.
Controlling xCurl allocations
xCurl uses the Windows heap and can have its allocations tracked through
XMemSetWin32HeapTrackingHooks. Alternately, memory functions can be provided at initialization time like
In addition to curl_global_init_mem,
xCurl provides the optional xCurl_global_init_mem. The callbacks that are provided to this version of
init are similar to other Microsoft Game Development Kit (GDK) memory callbacks and provide more information than the standard
libCurl callbacks about the data that's being allocated.
The following options are supported by
easy handles in
Sockets and fd_set
xCurl doesn't expose the underlying socket that's used for transport. Therefore,
xCurl does not implement any option and API that would be used for socket operations. This also removes the ability to use
fd_sets to wait on data to arrive through
poll. To wait for work to arrive, use
The following APIs are not present in
The following options have no effect.
Share interface is not implemented.
Pause and resume transfers
This feature is currently unsupported. Returning CURL_WRITEFUNC_PAUSE or CURL_READFUNC_PAUSE from a callback results in an aborted operation that can't be resumed.