> ## 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 mise en œuvre 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 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](/fr-CA/build/console-features/networking/web-requests/http-networking#libhttpclient).

`xCurl` diffère de `libCurl` en ce sens que `xCurl` est mise en œuvre par-dessus [WinHttp](/fr-CA/build/console-features/networking/web-requests/intro-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](/fr-CA/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 mises en œuvre de `xCurl` et de `WinHttp` fonctionnent sur PC Windows et sur console XBOX sans aucune modification du code.</Note>

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

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

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.

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

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

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

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

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

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

[Vue d'ensemble des meilleures pratiques de sécurité des communications (article sous NDA)](/fr-CA/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)