> ## 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 en une couche de transport de données UDP à usage général, adaptée au multiplexage de messages 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 offert pour une multitude de 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 d'API de MsQuic.

## Fonctionnalités de QUIC

* Tous les paquets sont chiffrés et l'établissement de la liaison est authentifié au moyen 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 la congestion et récupération des pertes améliorés.
* Résiste à un changement de l'adresse IP ou du 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ée aux titres GDK, MsQuic possède plusieurs fonctionnalités qui la distinguent des autres implémentations de QUIC :

* Optimisée pour le client et le serveur.
* Optimisée 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 du regroupement 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 extensions provisoires (drafts) QUIC suivantes :

* [Datagramme](https://datatracker.ietf.org/doc/html/draft-ietf-quic-datagram)
* [Négociation de version](https://datatracker.ietf.org/doc/html/draft-ietf-quic-version-negotiation)
* [Équilibrage de charge](https://datatracker.ietf.org/doc/html/draft-ietf-quic-load-balancers)
* [Fréquence des ACK](https://datatracker.ietf.org/doc/html/draft-ietf-quic-ack-frequency)
* [Tests de performance](https://datatracker.ietf.org/doc/html/draft-banks-quic-performance)

## Obtention de MsQuic

Microsoft héberge MsQuic dans un référentiel GitHub à code source ouvert. Vous devriez obtenir MsQuic au moyen de l'une de ses versions officielles, disponibles [ici](https://github.com/microsoft/msquic/blob/main/docs/Release.md). La prise en charge de la console XBOX Series X|S a été ajoutée dans la préversion prerelease/1.9, mais nous vous recommandons d'utiliser la dernière version officielle lorsque c'est possible pour les titres GDK.

Vous trouverez des fichiers 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 tente également de maintenir la rétrocompatibilité entre ses versions, consultez la documentation et les notes de version de MsQuic pour connaître les attentes en matière de compatibilité entre les différentes versions.

### Titres PC basés sur le GDK

Utilisez le fichier 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 du système d'exploitation que le GDK prend en charge. La version qui utilise Schannel ne prend en charge que Windows 11 et les versions ultérieures.

### Titres de console basés sur le GDK

Utilisez le fichier binaire prégénéré `msquic_gamecore_console_x64_Release_schannel` pour les titres de 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 fait en sorte que MsQuic soit lié à `XGamePlatform.lib`. Pour utiliser cette variante de build, vous devez installer le XGDK de la version d'octobre 2021 ou d'une version ultérieure. MsQuic utilise Schannel lors de la génération pour les titres de 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 pratiques exemplaires décrites dans [pratiques exemplaires 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 [pratiques exemplaires 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 enraciné afin de permettre au client d'authentifier votre serveur, tout 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 la façon la plus simple et la plus sécurisée de valider l'identité. Pour l'authentification du client par jeton XSTS, vous devez plutôt spécifier l'indicateur `QUIC_CREDENTIAL_FLAG_CLIENT` avec le certificat généré par votre serveur, comme décrit dans la section [pratiques exemplaires 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 recommandons de fournir le certificat du client en spécifiant le mode `QUIC_CREDENTIAL_TYPE_CERTIFICATE_CONTEXT` et en utilisant des API comme [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-CA/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 de [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 moment, 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 que tous les flux d'une connexion donnée sont 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-CA/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 permettre l'utilisation de 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 des volumes de données élevés vers et depuis votre titre GDK. En complément des [considérations relatives à la mémoire de WinSock](/fr-CA/build/console-features/networking/game-mesh/winsock-intro-networking#SocketMemory), suivez ces pratiques exemplaires lorsque vous utilisez MsQuic afin de réduire au minimum 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 ascendants vers l'application. Par conséquent, tout délai 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 fortement d'utiliser des réceptions asynchrones avec MsQuic afin de 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 au minimum 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)