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

# MsQuic

> MsQuic

Cet article décrit comment utiliser [MsQuic](https://github.com/microsoft/msquic) avec le Microsoft Game Development Kit (GDK). MsQuic est une implémentation Microsoft du protocole [IETF QUIC](https://datatracker.ietf.org/wg/quic/about/). Elle est multiplateforme, écrite en C et conçue pour être une bibliothèque QUIC à usage général.

QUIC a été conçu à l'origine pour remplacer les scénarios qui utilisent « TLS sur TCP », comme HTTP. Les développeurs l'ont étendu pour en faire une couche de transport de données UDP à usage général, adaptée au multiplexage de messages de datagrammes non fiables en temps réel et de flux fiables de type TCP sur une seule connexion. Cette conception le rend particulièrement intéressant comme couche de transport client/serveur et comme base pour les flux de données de trafic de jeu en temps réel.

MsQuic est adapté aux titres GDK et est également disponible sur de nombreuses plateformes, notamment Windows Server, Linux (bureau et serveur), iOS, Android et macOS.

La [documentation de l'API MsQuic](https://github.com/microsoft/msquic/blob/main/docs/API.md) couvre de nombreux concepts importants de MsQuic et montre comment programmer avec la surface de l'API MsQuic.

## Fonctionnalités de QUIC

* Tous les paquets sont chiffrés et la négociation est authentifiée à l'aide de TLS 1.3.
* Flux parallèles de données d'application fiables et non fiables.
* Échange de données d'application dès le premier aller-retour (0-RTT).
* Contrôle de congestion et récupération des pertes améliorés.
* Résistance à un changement d'adresse IP ou de port du client.
* Équilibrage de charge sans état.
* Facilement extensible pour de nouvelles fonctionnalités et extensions.

## Implémentation de MsQuic

En plus d'être adapté aux titres GDK, MsQuic possède plusieurs fonctionnalités qui le distinguent des autres implémentations de QUIC :

* Optimisé pour le client et le serveur.
* Optimisé pour un débit maximal et une latence minimale.
* E/S asynchrones.
* Prise en charge de la mise à l'échelle côté réception (RSS).
* Prise en charge de la fusion des envois et réceptions UDP.

MsQuic implémente les RFC QUIC suivantes :

* [RFC 9000](https://datatracker.ietf.org/doc/html/rfc9000)
* [RFC 9001](https://datatracker.ietf.org/doc/html/rfc9001)
* [RFC 9002](https://datatracker.ietf.org/doc/html/rfc9002)

MsQuic implémente les brouillons d'extensions QUIC suivants :

* [Datagram](https://datatracker.ietf.org/doc/html/draft-ietf-quic-datagram)
* [Version Negotiation](https://datatracker.ietf.org/doc/html/draft-ietf-quic-version-negotiation)
* [Load Balancing](https://datatracker.ietf.org/doc/html/draft-ietf-quic-load-balancers)
* [ACK Frequency](https://datatracker.ietf.org/doc/html/draft-ietf-quic-ack-frequency)
* [Perf Testing](https://datatracker.ietf.org/doc/html/draft-banks-quic-performance)

## Obtention de MsQuic

Microsoft héberge MsQuic dans un dépôt GitHub open source. Vous devez obtenir MsQuic via l'une de ses versions officielles disponibles [ici](https://github.com/microsoft/msquic/blob/main/docs/Release.md). La prise en charge des consoles XBOX Series X|S a été ajoutée dans la version prerelease/1.9, mais nous vous recommandons d'utiliser la dernière version officielle lorsque cela est possible pour les titres GDK.

Vous trouverez des binaires MsQuic prégénérés pour une version donnée dans la section [Assets](https://github.com/microsoft/msquic/releases) de cette version. Toutes les variantes de build d'une version donnée de MsQuic sont entièrement compatibles entre elles. Bien que MsQuic s'efforce également de maintenir la rétrocompatibilité entre ses versions, consultez la documentation et les notes de publication de MsQuic pour connaître les attentes de compatibilité entre les différentes versions.

### Titres PC basés sur le GDK

Utilisez le binaire prégénéré `msquic_windows_x64_Release_openssl` pour les titres PC basés sur le GDK.

Les titres GDK sur PC s'exécutent en tant qu'applications Win32 x64 natives. Utilisez la version de MsQuic générée pour la plateforme x64. Sur PC, utilisez la version de MsQuic générée avec OpenSSL, car elle prend en charge toutes les versions de système d'exploitation prises en charge par le GDK. La version qui utilise Schannel ne prend en charge que Windows 11 et versions ultérieures.

### Titres console basés sur le GDK

Utilisez le binaire prégénéré `msquic_gamecore_console_x64_Release_schannel` pour les titres console basés sur le GDK.

MsQuic fournit une variante de build spéciale pour les titres basés sur le GDK sur les consoles XBOX. Cette variante limite MsQuic aux API de `WINAPI_PARTITION_GAMES` et lie MsQuic à `XGamePlatform.lib`. Pour utiliser cette variante de build, vous devez installer le XGDK d'octobre 2021 ou d'une version ultérieure. MsQuic utilise Schannel lors de la génération pour les titres console basés sur le GDK.

<a id="ClientServerAuthentication" />

## Authentification du client et du serveur

MsQuic utilise automatiquement les mêmes chemins d'authentification et de vérification que ceux utilisés pour les requêtes web HTTPS afin d'authentifier votre serveur. L'authentification du client doit suivre les bonnes pratiques décrites dans [Bonnes pratiques pour une communication client/serveur sécurisée (rubrique sous NDA)](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/game-principles/security/communication-security/communication-security-impl/gc-secure-game-mesh-impl#ClientAuthentication).

Dans MsQuic, sur le client comme sur le serveur, vous devez utiliser l'API [ConfigurationLoadCredential](https://github.com/microsoft/msquic/blob/main/docs/api/ConfigurationLoadCredential.md) avec une structure [QUIC\_CREDENTIAL\_CONFIG](https://github.com/microsoft/msquic/blob/main/docs/api/QUIC_CREDENTIAL_CONFIG.md) appropriée afin de configurer vos certificats. Toutes les suites de chiffrement incluses par défaut dans MsQuic sont considérées comme sécurisées, mais il est important de configurer correctement la façon dont MsQuic valide les certificats sur le client et sur le serveur pour garantir l'établissement d'un canal de communication sécurisé et authentifié.

Sur le serveur, pour utiliser l'authentification du client par jeton XSTS, vous devez spécifier les indicateurs `QUIC_CREDENTIAL_FLAG_REQUIRE_CLIENT_AUTHENTICATION`, `QUIC_CREDENTIAL_FLAG_INDICATE_CERTIFICATE_RECEIVED` et `QUIC_CREDENTIAL_FLAG_NO_CERTIFICATE_VALIDATION`. Lorsque vous spécifiez l'indicateur `QUIC_CREDENTIAL_FLAG_NO_CERTIFICATE_VALIDATION`, vous devez valider vous-même le certificat du client dans le rappel d'événement [QUIC\_CONNECTION\_EVENT\_PEER\_CERTIFICATE\_RECEIVED](https://github.com/microsoft/msquic/blob/main/docs/api/QUIC_CONNECTION_EVENT.md#quic_connection_event_peer_certificate_received), comme décrit dans la section [Bonnes pratiques pour une communication client/serveur sécurisée (rubrique sous NDA)](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/game-principles/security/communication-security/communication-security-impl/gc-secure-game-mesh-impl#ClientAuthentication).

De plus, sur le serveur, vous devez fournir un certificat correctement rattaché à une racine afin de permettre au client d'authentifier votre serveur, comme vous le feriez pour un serveur web HTTPS.

Sur le client, vous ne devez *jamais* spécifier l'indicateur `QUIC_CREDENTIAL_FLAG_NO_CERTIFICATE_VALIDATION`, car le comportement par défaut de MsQuic pour l'authentification du serveur est le moyen le plus simple et le plus sûr de valider l'identité. Pour l'authentification du client par jeton XSTS, spécifiez plutôt l'indicateur `QUIC_CREDENTIAL_FLAG_CLIENT` ainsi que le certificat généré par votre serveur, comme décrit dans la section [Bonnes pratiques pour une communication client/serveur sécurisée (rubrique sous NDA)](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/game-principles/security/communication-security/communication-security-impl/gc-secure-game-mesh-impl#ClientAuthentication). Nous vous recommandons de fournir le certificat du client en spécifiant le mode `QUIC_CREDENTIAL_TYPE_CERTIFICATE_CONTEXT` et en utilisant des API telles que [CertCreateContext](https://learn.microsoft.com/windows/win32/api/wincrypt/nf-wincrypt-certcreatecontext) pour générer le contexte directement à partir des données de réponse de votre requête web.

## Initialisation du réseau

MsQuic ne gère pas automatiquement l'[initialisation du réseau](/fr/build/console-features/networking/initialization-connectivity-networking) pour les titres GDK. Attendez que le réseau soit initialisé après le lancement de votre titre et après chaque reprise avant d'initialiser MsQuic à l'aide de [MsQuicOpenVersion](https://github.com/microsoft/msquic/blob/main/docs/api/MsQuicOpenVersion.md) ou [MsQuicOpen](https://github.com/microsoft/msquic/blob/main/docs/api/MsQuicOpen.md).

<a id="SuspendResume" />

## Suspension et reprise

Inscrivez-vous aux événements de suspension et de reprise à l'aide de `RegisterAppStateChangeNotification`. Lors de la suspension, fermez tous les flux ouverts, puis fermez MsQuic. Ensuite, lors de la reprise, attendez l'initialisation du réseau, puis rouvrez MsQuic.

Pour fermer rapidement tous les flux MsQuic dans le délai de suspension, appelez [StreamShutdown](https://github.com/microsoft/msquic/blob/main/docs/api/StreamShutdown.md) pour chaque flux ouvert avec les indicateurs `QUIC_STREAM_SHUTDOWN_FLAG_ABORT` et `QUIC_STREAM_SHUTDOWN_FLAG_IMMEDIATE`. Cet appel déclenche immédiatement un événement `QUIC_STREAM_EVENT_SHUTDOWN_COMPLETE`. À ce stade, vous pouvez appeler [StreamClose](https://github.com/microsoft/msquic/blob/main/docs/api/StreamClose.md) en toute sécurité pour fermer le flux. Une fois tous les flux d'une connexion donnée fermés, appelez [ConnectionShutdown](https://github.com/microsoft/msquic/blob/main/docs/api/ConnectionShutdown.md) avec l'indicateur `QUIC_CONNECTION_SHUTDOWN_FLAG_SILENT`, puis [ConnectionClose](https://github.com/microsoft/msquic/blob/main/docs/api/ConnectionClose.md). Après avoir fermé toutes les connexions, appelez [RegistrationClose](https://github.com/microsoft/msquic/blob/main/docs/api/RegistrationClose.md) et [ConfigurationClose](https://github.com/microsoft/msquic/blob/main/docs/api/ConfigurationClose.md) pour les inscriptions et configurations restantes, puis [MsQuicClose](https://github.com/microsoft/msquic/blob/main/docs/api/MsQuicClose.md).

## Port préféré

Utilisez le [port multijoueur UDP local préféré](/fr/build/console-features/networking/game-mesh/preferred-local-udp-multiplayer-port-networking) pour le trafic de jeu principal dans les titres GDK. Définissez ce port dans MsQuic à l'aide de la fonction [SetParam](https://github.com/microsoft/msquic/blob/main/docs/api/SetParam.md) avec le paramètre `QUIC_PARAM_CONN_LOCAL_ADDRESS` sur un handle d'objet de connexion avant d'appeler [ConnectionStart](https://github.com/microsoft/msquic/blob/main/docs/api/ConnectionStart.md).

Lorsque vous définissez `QUIC_PARAM_CONN_LOCAL_ADDRESS`, spécifiez la famille `AF_UNSPEC` pour autoriser les sockets double pile IPv4 et IPv6. L'exemple suivant montre comment définir le port préféré lorsque `MsQuicCallTable` est retourné par [MsQuicOpen](https://github.com/microsoft/msquic/blob/main/docs/api/MsQuicOpen.md) et que `MsQuicConnectionHandle` est retourné par [ConnectionOpen](https://github.com/microsoft/msquic/blob/main/docs/api/ConnectionOpen.md).

```text theme={null}
uint16_t preferredPort;
if (SUCCEEDED(XNetworkingQueryPreferredLocalUdpMultiplayerPort(&preferredPort)))
{
    QUIC_ADDR localAddress = {};
    localAddress.si_family = AF_UNSPEC;
    localAddress.Ipv4.sin_port = htons(preferredPort);

    QUIC_STATUS status = MsQuicCallTable->SetParam(
        MsQuicConnectionHandle,
        QUIC_PARAM_LEVEL_CONNECTION,
        QUIC_PARAM_CONN_LOCAL_ADDRESS,
        sizeof(localAddress),
        &localAddress);
}
```

## Considérations relatives à la mémoire

L'implémentation performante de MsQuic permet de transférer de grandes quantités de données vers et depuis votre titre GDK. En complément des [considérations relatives à la mémoire de WinSock](/fr/build/console-features/networking/game-mesh/winsock-intro-networking#SocketMemory), lorsque vous utilisez MsQuic, suivez ces bonnes pratiques pour réduire la consommation de mémoire par le noyau :

Les titres GDK doivent réduire au minimum le temps d'exécution dans le rappel. MsQuic n'utilise pas de threads distincts pour l'exécution du protocole et les appels vers l'application. Par conséquent, tout retard important dans le rappel retarde le protocole et augmente la consommation de mémoire requise par le noyau. Tout travail ou temps de traitement important que le titre doit effectuer doit se faire sur son propre thread.

Les titres GDK doivent gérer efficacement leurs mémoires tampons d'envoi afin de réduire l'utilisation de la mémoire du noyau. Pour plus d'informations, consultez [Send buffering in MsQuic](https://github.com/microsoft/msquic/blob/main/docs/Streams.md#send-buffering) pour découvrir comment MsQuic permet à votre titre de contrôler ce comportement.

Nous vous recommandons vivement d'utiliser des réceptions asynchrones avec MsQuic pour garantir que les données reçues sont transférées efficacement vers les mémoires tampons en mode utilisateur. [Receiving in MsQuic](https://github.com/microsoft/msquic/blob/main/docs/Streams.md#receiving) fournit des détails supplémentaires sur la gestion des réceptions asynchrones. De plus, n'utilisez pas la fonctionnalité d'acceptation partielle des données dans les clients GDK MsQuic afin de réduire la quantité de mémoire du noyau consommée.

## Voir aussi

[MsQuic](https://github.com/microsoft/msquic)

[Documentation de l'API MsQuic](https://github.com/microsoft/msquic/blob/main/docs/API.md)

[Versions de MsQuic](https://github.com/microsoft/msquic/blob/main/docs/Release.md)

[Documentation sur la génération de MsQuic](https://github.com/microsoft/msquic/blob/main/docs/BUILD.md)

[Exemple de serveur PlayFab MsQuic Echo](https://github.com/microsoft/Xbox-GDK-Samples/tree/main/Samples/Live/MsQuicEcho)


## Related topics

- [MsQuic](/build/console-features/networking/game-mesh/msquic-intro-networking.md)
- [Game Mesh](/build/console-features/networking/game-mesh/game-mesh-toc.md)
- [Networking on XBOX consoles with the GDK](/build/console-features/networking/index.md)
- [Game mesh networking for XBOX titles](/build/console-features/networking/game-mesh/index.md)
- [XBOX 游戏的 Game mesh 网络](/zh-CN/build/console-features/networking/game-mesh/index.md)