Skip to main content
Cet article décrit la bibliothèque xCurl, une mise en œuvre des API libCurl conforme au Microsoft Game Development Kit (GDK). xCurl simplifie le développement de titres en respectant toutes les exigences et meilleures pratiques de sécurité sans nécessiter de logique ou de traitement particulier de la part du titre. Toutefois, elle ne prend pas en charge la communication WebSocket. Si vous devez mettre en œuvre une communication WebSocket, utilisez plutôt libHttpClient. xCurl diffère de libCurl en ce sens que xCurl est mise en œuvre par-dessus WinHttp et suit automatiquement les exigences et les meilleures pratiques du Microsoft Game Development Kit (GDK), y compris la gestion de la durée de vie des processus (PLM). Bien que xCurl soit compatible au niveau de l’API avec libCurl, la couche de transport de xCurl utilise exclusivement WinHttp et n’utilise pas libCurl. Ainsi, xCurl n’a pas besoin d’être synchronisée avec la mise en œuvre open source de libCurl, y compris les correctifs de bogues, les numéros de version et plus encore. Les développeurs peuvent utiliser xCurl pour conserver la même mise en œuvre HTTP libCurl sur toutes les plateformes en modifiant seulement une inclusion d’en-tête et une liaison de bibliothèque. Plusieurs API libCurl ne sont pas mises en œuvre dans xCurl, soit parce qu’elles ne sont pas couramment utilisées dans les scénarios de développement de jeux, soit parce qu’elles n’ont pas de fonctionnalité équivalente dans WinHttp à laquelle elles pourraient être associées. Les différences sont décrites plus loin dans cet article. xCurl dépend du Gaming Runtime et ne peut pas être initialisée tant que XGameRuntimeInitialize n’a pas été appelée. Pour comprendre le fonctionnement des méthodes xCurl, consultez la documentation de l’API libCurl.
Les mises en œuvre de xCurl et de WinHttp fonctionnent sur PC Windows et sur console XBOX sans aucune modification du code.

​
Soutien aux développeurs

xCurl est propulsée par WinHttp, et non par libCurl, et fait partie du Microsoft Game Development Kit (GDK). Les demandes de soutien doivent être envoyées par les voies de soutien recommandées pour les titres Microsoft Game Development Kit (GDK), par exemple en communiquant avec votre représentant Microsoft ou avec l’équipe de soutien aux développeurs par l’intermédiaire des forums des développeurs XBOX.

​
Ajouter xCurl à votre projet

Pour utiliser xCurl dans un jeu Microsoft Game Development Kit (GDK) sur un PC Windows 10 ou une console XBOX, incluez les en-têtes et les bibliothèques du SDK d’extension xCurl dans votre projet.
  1. Assurez-vous d’installer le Gaming Runtime Development Kit (GRDK) sur votre PC de développement.
  2. Ouvrez le fichier .vcxproj de votre jeu, puis ajoutez l’élément suivant. Cela lie la bibliothèque d’importation et inclut xCurl.dll dans la sortie de la build.
  1. xCurl utilise un en-tête différent pour se distinguer de libCurl. Aux endroits où curl.h serait inclus dans votre jeu, remplacez l’en-tête par xCurl.h, comme suit.

​
Configuration

xCurl équivaut à libCurl compilée avec les indicateurs de build suivants.
  • HTTP_ONLY
  • CURL_NO_OLDIES
  • CURL_DISABLE_PROXY
  • CURL_DISABLE_COOKIES
  • CURL_DISABLE_DOH
  • CURL_DISABLE_PROGRESS_METER
  • CURL_DISABLE_MIME
  • USE_SCHANNEL

​
Initialisation du réseau

xCurl gère automatiquement l’initialisation du réseau. Vous pouvez configurer et effectuer des requêtes à tout moment du cycle de vie de votre titre. Toutes les requêtes lancées avant l’initialisation du réseau sont retardées et mises en file d’attente jusqu’à ce que le réseau soit initialisé. xCurl garantit que vos requêtes sont effectuées le plus tôt possible sans qu’aucun traitement supplémentaire ne soit requis de la part de votre titre.

​
Suspension et reprise du titre

xCurl gère automatiquement la suspension et la reprise. Lors de la suspension, toutes les requêtes en attente sont immédiatement annulées et échouent avec CURLE_NO_CONNECTION_AVAILABLE. De plus, l’interrogation de curl_easy_getinfo pour CURLINFO_OS_ERRNO sur ces requêtes retourne HRESULT_FROM_WIN32(PROCESS_SUSPEND_RESUME), comme pour toute autre API GRTS, au cas où vous voudriez gérer ces échecs différemment des échecs généraux de déconnexion réseau. Tous les handles xCurl restent valides tout au long du cycle de vie du titre, y compris d’une suspension à une reprise. Il n’est pas nécessaire de nettoyer ou d’initialiser un handle xCurl lors de la suspension ou de la reprise. Toutes les nouvelles requêtes lancées après la suspension sont retardées jusqu’à la reprise et à l’initialisation subséquente du réseau. Ce délai garantit qu’elles démarrent dès que possible sans nécessiter de traitement supplémentaire de la part de votre titre.
Lorsque votre titre utilise l’interface multi de xCurl, il doit continuer d’appeler curl_multi_perform, éventuellement avec curl_multi_poll ou curl_multi_wait, lors de la suspension tant qu’il y a des requêtes en attente. xCurl bloque la suspension jusqu’à ce que toutes les requêtes en cours soient terminées, et ne pas appeler curl_multi_perform pourrait entraîner l’expiration du délai de votre titre pendant la suspension. Nous recommandons de continuer d’appeler curl_multi_perform tout au long du cycle de vie, quel que soit l’état de suspension ou de reprise. xCurl gère en interne toutes les subtilités de l’état suspendu.

​
Fonctionnalités de sécurité

Toutes les requêtes HTTPS effectuées par l’intermédiaire de xCurl suivent les meilleures pratiques de sécurité des communications (article sous NDA). xCurl applique automatiquement tout épinglage de certificat particulier spécifié dans le « Single Sign-on Portal » de votre titre. L’utilisation de CURLOPT_SSL_VERIFYPEER pour désactiver la validation des certificats n’est pas prise en charge. Sur les trousses de développement, vous pouvez spécifier le schéma HTTP non chiffré, http://, pour le trafic de débogage et à des fins de test. Pour toutes les requêtes RETAIL, vous devez spécifier le schéma HTTPS, https://, afin de fournir le niveau de protection recommandé. Les requêtes xCurl qui ne spécifient pas explicitement de schéma utilisent par défaut le schéma HTTPS.
xCurl n’effectue pas d’insertion automatique de jetons. Pour récupérer des jetons XBOX Live, votre titre doit appeler les API GRTS XUserGetTokenAndSignatureAsync ou XUserGetTokenAndSignatureUtf16Async pour récupérer les en-têtes d’autorisation et de signature, puis utiliser les options CURLOPT_HEADER, CURLOPT_HTTPHEADER ou CURLOPT_HEADERFUNCTION dans un appel à curl_easy_setopt pour définir les en-têtes avant d’effectuer la requête.

​
Considérations relatives à la mémoire et à la simultanéité

xCurl partage les mêmes limites de requêtes simultanées que celles qui s’appliquent à WinHttp. Les titres doivent limiter les requêtes simultanées à huit ou moins pour garantir que tous les appels fonctionnent correctement. Cette limite de simultanéité s’applique aux requêtes simultanées émises par xCurl, WinHttp et les API des XBOX services. xCurl utilise une mémoire tampon alternée (flip buffer) pour recevoir les données. Ce modèle lui permet d’offrir un meilleur débit en remplissant une deuxième mémoire tampon pendant que le titre lit la première. Toutefois, si le rappel de lecture prend trop de temps ou si curl_multi_perform n’est pas appelé assez fréquemment en mode multi, la mémoire noyau WinSock pourrait s’accumuler. Pour plus d’informations sur la mémoire noyau WinSock, consultez Considérations relatives à la mémoire des sockets.

​
Contrôle des allocations de xCurl

Par défaut, xCurl utilise le tas Windows, et ses allocations peuvent être suivies au moyen de XMemSetWin32HeapTrackingHooks. Sinon, des fonctions de mémoire peuvent être fournies au moment de l’initialisation, comme avec libCurl. En plus de curl_global_init_mem, xCurl fournit la fonction facultative xCurl_global_init_mem. Les rappels fournis à cette version de init sont semblables aux autres rappels de mémoire du Microsoft Game Development Kit (GDK) et fournissent plus d’informations que les rappels libCurl standard sur les données allouées.

​
Options prises en charge

Les options suivantes sont prises en charge avec les handles easy dans xCurl.
  • 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

​
Fonctionnalités non prises en charge

​
Sockets et fd_set

xCurl n’expose pas le socket sous-jacent utilisé pour le transport. Par conséquent, xCurl ne met en œuvre aucune option ni API qui serait utilisée pour des opérations sur les sockets. Cette limite supprime également la possibilité d’utiliser des fd_sets pour attendre l’arrivée de données au moyen de select et poll. Pour attendre l’arrivée de travail, utilisez curl_multi_wait et curl_multi_poll. Les API suivantes ne sont pas présentes dans xCurl
  • curl_easy_send
  • curl_easy_recv
  • curl_multi_socket
  • curl_multi_socket_action
  • curl_multi_socket_all
  • curl_multi_assign
  • curl_multi_fdset
Les options suivantes n’ont aucun effet et retournent l’erreur 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

L’interface CURL Share n’est pas mise en œuvre.

​
Mise en pause et reprise des transferts

Cette fonctionnalité n’est actuellement pas prise en charge. Le fait de retourner CURL_WRITEFUNC_PAUSE ou CURL_READFUNC_PAUSE à partir d’un rappel entraîne une opération abandonnée qui ne peut pas être reprise.

​
Voir aussi

API libCurl Configuration des services web dans l’Espace partenaires (article sous NDA) Fiddler sur les consoles XBOX One Vue d’ensemble des meilleures pratiques de sécurité des communications (article sous NDA)
Last modified on October 6, 2026