Skip to main content
Cet article décrit la bibliothèque xCurl, une implémentation des API libCurl conforme au Microsoft Game Development Kit (GDK). xCurl simplifie le développement de titres en respectant toutes les exigences et bonnes pratiques de sécurité sans nécessiter de logique ni de gestion particulière de la part du titre. Toutefois, elle ne prend pas en charge la communication WebSocket. Si vous devez implémenter une communication WebSocket, utilisez plutôt libHttpClient. xCurl diffère de libCurl en ce que xCurl est implémentée au-dessus de WinHttp et suit automatiquement les exigences et bonnes pratiques du Microsoft Game Development Kit (GDK), notamment 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 l’implémentation open source de libCurl, qu’il s’agisse des correctifs de bogues, des numéros de version ou d’autres éléments. Les développeurs peuvent utiliser xCurl pour conserver la même implémentation HTTP libCurl sur toutes les plateformes en ne modifiant qu’une inclusion d’en-tête et une liaison de bibliothèque. Plusieurs API libCurl ne sont pas implémentées dans xCurl, soit parce qu’elles sont rarement utilisées dans les scénarios de développement de jeux, soit parce qu’elles n’ont pas de fonctionnalité équivalente dans WinHttp vers laquelle elles pourraient être mappées. Les différences sont décrites plus loin dans cet article. xCurl s’appuie sur le 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 implémentations xCurl et WinHttp fonctionnent sur PC Windows et sur console XBOX sans aucune modification du code.

​
Support aux développeurs

xCurl repose sur WinHttp, et non sur libCurl, et fait partie du Microsoft Game Development Kit (GDK). Les demandes de support doivent être envoyées par les canaux de support recommandés pour les titres du Microsoft Game Development Kit (GDK), par exemple en contactant votre représentant Microsoft ou l’équipe de support aux développeurs via les forums des développeurs XBOX.

​
Ajouter xCurl à votre projet

Pour utiliser xCurl dans un jeu du Microsoft Game Development Kit (GDK) sur un PC Windows 10 ou une console XBOX, incluez les en-têtes et 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. Celui-ci lie la bibliothèque d’importation et inclut xCurl.dll dans la sortie de build.
  1. xCurl utilise un en-tête différent pour se distinguer de libCurl. Aux emplacements où curl.h serait inclus dans votre jeu, remplacez cet 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 différé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 aucune gestion supplémentaire 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 cours 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 renvoie HRESULT_FROM_WIN32(PROCESS_SUSPEND_RESUME), comme pour toute autre API GRTS, au cas où vous souhaiteriez traiter 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 au-delà des limites de suspension et de 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 différées jusqu’à la reprise et à l’initialisation du réseau qui s’ensuit. Ce délai garantit qu’elles démarrent dès que possible sans nécessiter de gestion supplémentaire de la part de votre titre.
Lorsque votre titre utilise l’interface multi de xCurl, il doit continuer à appeler curl_multi_perform, ainsi que, éventuellement, curl_multi_poll ou curl_multi_wait, lors de la suspension tant que des requêtes sont en cours. xCurl bloque la suspension jusqu’à ce que toutes les requêtes en cours soient terminées, et le fait de ne pas appeler curl_multi_perform peut entraîner l’expiration du délai de votre titre pendant la suspension. Nous recommandons de continuer à 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 via xCurl suivent les bonnes pratiques de sécurité des communications (article sous NDA). xCurl applique automatiquement tout épinglage de certificat particulier spécifié via 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 kits 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 d’offrir le niveau de protection recommandé. Pour les requêtes xCurl qui ne spécifient pas explicitement de schéma, le schéma HTTPS est déduit.
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 concurrence

xCurl partage les mêmes limitations de requêtes simultanées que WinHttp. Les titres doivent limiter les requêtes simultanées à huit au maximum pour garantir que tous les appels fonctionnent correctement. Cette limite de concurrence s’applique aux requêtes simultanées émises par xCurl, WinHttp et les API des services XBOX. xCurl utilise une mémoire tampon double (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ée assez fréquemment en mode multi, la mémoire noyau WinSock peut 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 via XMemSetWin32HeapTrackingHooks. Vous pouvez également fournir des fonctions de mémoire lors 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 similaires aux autres rappels de mémoire du Microsoft Game Development Kit (GDK) et fournissent davantage 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 n’implémente aucune option ni API qui serait utilisée pour des opérations sur les sockets. Cette limitation supprime également la possibilité d’utiliser des fd_sets pour attendre l’arrivée de données via 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 renvoient 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 implémentée.

​
Suspension et reprise des transferts

Cette fonctionnalité n’est actuellement pas prise en charge. Le renvoi de CURL_WRITEFUNC_PAUSE ou CURL_READFUNC_PAUSE à partir d’un rappel entraîne l’abandon de l’opération, 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 bonnes pratiques de sécurité des communications (article sous NDA)
Last modified on October 6, 2026