> ## 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.

# Vue d'ensemble de xCurl

> Vue d'ensemble de xCurl

Cet article décrit la bibliothèque `xCurl`, une implémentation des API [libCurl](https://curl.haxx.se/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](/fr/build/console-features/networking/web-requests/http-networking#libhttpclient).

`xCurl` diffère de `libCurl` en ce que `xCurl` est implémentée au-dessus de [WinHttp](/fr/build/console-features/networking/web-requests/intro-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](/fr/reference/system/xgameruntimeinit/functions/xgameruntimeinitialize) n'a pas été appelée.

Pour comprendre le fonctionnement des méthodes `xCurl`, consultez la documentation de l'[API libCurl](https://curl.haxx.se/libcurl/c/).

<Note>Les implémentations `xCurl` et `WinHttp` fonctionnent sur PC Windows et sur console XBOX sans aucune modification du code.</Note>

## 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.

```xml theme={null}
    <GDKExtLibNames>Xbox.xCurl.API</GDKExtLibNames>
```

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.

```cpp theme={null}
    #include <xCurl.h>
```

## 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.

<Note>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.</Note>

## 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)](/fr/build/game-principles/security/communication-security-overview). `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.

<Note>`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.</Note>

## 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](/fr/build/console-features/networking/game-mesh/winsock-intro-networking#SocketMemory).

### 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](https://curl.haxx.se/libcurl/c/curl_global_init_mem.html), `xCurl` fournit la fonction facultative [xCurl\_global\_init\_mem](/fr/reference/networking/xcurl/functions/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](https://curl.haxx.se/libcurl/c/)

[Configuration des services web dans l'Espace partenaires (article sous NDA)](/fr/services/xbox-services/fundamentals/s2s-auth-calls/custom-service-config/web-services/live-web-services)

[Fiddler sur les consoles XBOX One](/fr/build/console-features/networking/tools/fiddler-setup-networking)

[Vue d'ensemble des bonnes pratiques de sécurité des communications (article sous NDA)](/fr/build/game-principles/security/communication-security-overview)


## Related topics

- [Vue d'ensemble de XBOX Series X|S](/fr/paths/series-xs/overview.md)
- [Vue d'ensemble de l'accessibilité GDK](/fr/build/game-principles/accessibility/accessibility-overview.md)
- [Vue d'ensemble de Windows & ROG XBOX Ally](/fr/paths/windows/overview.md)
- [Vue d'ensemble de Godot et des moteurs communautaires](/fr/paths/community-engines/overview.md)
- [Vue d'ensemble de Play Anywhere (console + PC)](/fr/paths/play-anywhere/overview.md)