> ## 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. # Détection de l'état d'initialisation du réseau > Détection de l'état d'initialisation du réseau ## Initialisation du réseau Utilisez cet article pour comprendre comment récupérer les informations de connectivité et d'initialisation du réseau dans les titres Microsoft Game Development Kit (GDK). Ces titres sont souvent lancés avant que les composants principaux du système d'exploitation et les services réseau ne soient en cours d'exécution. Par conséquent, appeler la plupart des API réseau et de sécurité, notamment `WinSock`, `WinHTTP`, `BCrypt`, `WinCrypt`, `schannel` et `IPHLPAPI`, trop tôt après le lancement du titre entraîne un comportement indéterminé. Ce comportement peut inclure des échecs inattendus, des valeurs de retour non initialisées, des pertes de paquets arbitraires, ainsi qu'une corruption de la mémoire et des plantages potentiels. Pour éviter ce comportement indéterminé, les titres Microsoft Game Development Kit (GDK) doivent utiliser les fonctions [XNetworkingGetConnectivityHint](/fr/reference/networking/xnetworking/functions/xnetworkinggetconnectivityhint) et [XNetworkingRegisterConnectivityHintChanged](/fr/reference/networking/xnetworking/functions/xnetworkingregisterconnectivityhintchanged). En particulier, le champ `XNetworkingConnectivityHint::networkInitialized` indique si le réseau est initialisé. Les titres doivent attendre que le champ `networkInitialized` soit `true` avant d'appeler les API réseau et de sécurité. De nombreuses bibliothèques d'intergiciels utilisent également en interne les API réseau et de sécurité ; même un intergiciel non lié au réseau peut utiliser la pile réseau pour la télémétrie ou le débogage. Consultez le fournisseur de l'intergiciel pour savoir quoi faire dans chaque cas. Si l'intergiciel lui-même n'attend pas l'initialisation du réseau, vous devrez peut-être retarder son chargement jusqu'à ce que le réseau soit initialisé. Plusieurs bibliothèques du Microsoft Game Development Kit (GDK), telles que [XSAPI](https://learn.microsoft.com/windows/uwp/xbox-live/xsapi-flat-c) et [Azure PlayFab Party](/fr/build/console-features/networking/game-mesh/playfab-party-intro-networking), exigent que vous attendiez l'initialisation du réseau avant de les utiliser. ## Séquencement de la pile HTTP `xCurl` et `libHttpClient` sont les seules bibliothèques HTTP couvertes par cette documentation qui gèrent automatiquement l'initialisation du réseau. Si votre titre utilise une autre pile HTTP, rendez la séquence de démarrage explicite. Voici un modèle sûr : 1. Interrogez l'indicateur de connectivité actuel ou inscrivez-vous aux modifications de connectivité. 2. Attendez que `XNetworkingConnectivityHint::networkInitialized` soit `true`. 3. Initialisez `WinSock` et toutes les autres dépendances réseau. 4. Accédez à l'état des certificats et configurez l'approbation. 5. Créez la pile HTTP et commencez à émettre des requêtes. La disponibilité du réseau doit passer en premier. Initialiser `WinSock`, l'état des certificats ou l'état HTTP trop tôt peut produire des échecs difficiles à diagnostiquer, car l'erreur visible apparaît souvent plus tard que la cause première. L'exemple suivant montre les premières étapes d'une séquence de démarrage d'une pile HTTP propre au titre. Il interroge directement `XNetworkingConnectivityHint` avant d'initialiser `WinSock`. ```cpp theme={null} HRESULT InitializeNetworkingDependencies() { XNetworkingConnectivityHint connectivityHint{}; HRESULT hr = XNetworkingGetConnectivityHint(&connectivityHint); if (FAILED(hr)) { return hr; } if (!connectivityHint.networkInitialized) { // Try again after your title receives a connectivity change notification. return E_PENDING; } WSADATA wsaData{}; int winsockResult = WSAStartup(MAKEWORD(2, 2), &wsaData); if (winsockResult != 0) { return HRESULT_FROM_WIN32(winsockResult); } return S_OK; } ``` Une fois ces étapes réussies, créez les objets de votre pile HTTP, puis appliquez toute configuration d'approbation propre à la pile avant d'émettre des requêtes. Pour les piles autres que Schannel, cela peut inclure le chargement du certificat de proxy requis par votre outil de débogage. ## Suspension et reprise De plus, les cycles de suspension/reprise du titre réinitialisent le champ `networkInitialized` à `false`. Lors de la suspension, les titres doivent libérer tous les handles de tous les composants réseau et de sécurité et cesser toutes les opérations réseau. Consultez la page de présentation de chaque API réseau pour plus d'informations sur les exigences de cette API lors de la suspension. Lors de la reprise, les titres doivent à nouveau attendre que le champ `networkInitialized` devienne `true` avant de tenter de rétablir les connexions et d'utiliser les API réseau ou de sécurité. Nous recommandons que le chemin d'initialisation du réseau lors de la reprise soit le même que celui du lancement initial du titre : lors de la reprise ou du lancement du titre, attendez que le réseau soit initialisé avant de démarrer votre code réseau. Les bibliothèques d'intergiciels qui ne gèrent pas la suspension/reprise, telles que GameChat2 et Azure PlayFab Party, doivent être nettoyées lors de la suspension et réinitialisées lors de la reprise, après avoir attendu l'initialisation du réseau. Partez du principe que toute pile HTTP autre que xCurl nécessite une gestion explicite du cycle de vie. Lors de la suspension ou de l'arrêt, cessez de mettre en file d'attente de nouvelles requêtes et annulez ou terminez le travail en cours. Détruisez les handles de requête, les sessions et les sockets qui ne doivent pas survivre à la suspension. Lors de la reprise, traitez l'initialisation du réseau comme un nouveau chemin d'initialisation. Attendez à nouveau `networkInitialized` avant de recréer l'état HTTP ou de réinscrire les écouteurs. Les conceptions basées sur un travail annulable et non bloquant sont plus faciles à défaire proprement lors de la suspension que les appels bloquants de longue durée. ## Test de l'initialisation du réseau L'initialisation du réseau prend généralement quelques secondes, aussi bien lors de la reprise que lors du lancement du titre, et varie selon le type de console et l'environnement réseau de l'utilisateur. Pendant le développement, l'initialisation du réseau est presque instantanée. Cela peut masquer des problèmes liés à divers éléments de votre titre qui n'attendent pas correctement l'initialisation du réseau. Pour tester les scénarios d'initialisation du réseau, utilisez `xbconfig NetworkInitDelayInSeconds=30` afin d'ajouter un délai arbitraire au processus d'initialisation du réseau. Lorsque vous utilisez ce paramètre, veillez à redémarrer complètement votre titre entre chaque test à l'aide de `xbapp terminate /full`. Redéfinissez `NetworkInitDelayInSeconds` sur `0` lorsque vous avez terminé les tests. Pour les piles HTTP qui créent leur propre état réseau, incluez au moins les scénarios suivants dans votre couverture de test : * Démarrage à froid * Suspension pendant que des requêtes sont actives * Reprise après une suspension propre * Quick Resume ou flux de restauration équivalents * Déconnexions du réseau autour des limites de suspension et de reprise ## Exemples de code d'initialisation du réseau L'exemple de code suivant montre comment interroger, de manière sûre en temps réel, si le réseau est initialisé. ```cpp theme={null} bool IsNetworkInitialized() { XNetworkingConnectivityHint connectivityHint; if (SUCCEEDED(XNetworkingGetConnectivityHint(&connectivityHint))) { return connectivityHint.networkInitialized; } return false; } ``` L'exemple de code suivant montre comment un titre peut se bloquer jusqu'à ce que le réseau soit initialisé. ```cpp theme={null} static void NetworkConnectivityHintChangedCallback( _In_ void* context, _In_ const XNetworkingConnectivityHint* connectivityHint ) { HANDLE networkInitializedEvent = static_cast(context); if (connectivityHint->networkInitialized) { (void)SetEvent(networkInitializedEvent); } } HRESULT EnsureNetworkInitialized() { HRESULT hr = S_OK; XNetworkingConnectivityHint connectivityHint; XTaskQueueHandle queue; hr = XTaskQueueCreate(XTaskQueueDispatchMode::Immediate, XTaskQueueDispatchMode::Immediate, &queue); if (SUCCEEDED(hr)) { // Use the new XNetworking APIs to check if the network is initialized. hr = XNetworkingGetConnectivityHint(&connectivityHint); if (SUCCEEDED(hr)) { if (!connectivityHint.networkInitialized) { // The network isn't initialized. Wait until the network becomes initialized. HANDLE networkInitializedEvent = CreateEvent(nullptr, TRUE, FALSE, nullptr); if (networkInitializedEvent != nullptr) { XTaskQueueRegistrationToken token; hr = XNetworkingRegisterConnectivityHintChanged(queue, networkInitializedEvent, NetworkConnectivityHintChangedCallback, &token); if (SUCCEEDED(hr)) { DWORD result = WaitForSingleObjectEx(networkInitializedEvent, INFINITE, FALSE); if (result != WAIT_OBJECT_0) { hr = HRESULT_FROM_WIN32(GetLastError()); } XNetworkingUnregisterConnectivityHintChanged(token, true); } CloseHandle(networkInitializedEvent); } else { hr = HRESULT_FROM_WIN32(GetLastError()); } } } XTaskQueueCloseHandle(queue); } return hr; } ``` ## Informations réseau Les informations réseau dans les titres Microsoft Game Development Kit (GDK) peuvent être récupérées à l'aide de l'API [XNetworkingGetConnectivityHint](/fr/reference/networking/xnetworking/functions/xnetworkinggetconnectivityhint). L'API [XNetworkingGetConnectivityHint](/fr/reference/networking/xnetworking/functions/xnetworkinggetconnectivityhint) retourne des informations à l'échelle de l'appareil sur les niveaux de connectivité réseau, les limites de données, les types de connectivité filaire ou sans fil, et indique si le réseau est initialisé. Il s'agit d'une API sûre en temps réel qui retourne immédiatement les informations actuelles. Vous pouvez écouter les modifications à l'aide des fonctions [XNetworkingRegisterConnectivityHintChanged](/fr/reference/networking/xnetworking/functions/xnetworkingregisterconnectivityhintchanged) et [XNetworkingUnregisterConnectivityHintChanged](/fr/reference/networking/xnetworking/functions/xnetworkingunregisterconnectivityhintchanged). L'exemple de code suivant montre comment utiliser la fonction [XNetworkingGetConnectivityHint](/fr/reference/networking/xnetworking/functions/xnetworkinggetconnectivityhint) pour interroger des informations sur l'état actuel du réseau. ```cpp theme={null} XNetworkingConnectivityHint connectivityHint; if (SUCCEEDED(XNetworkingGetConnectivityHint(&connectivityHint))) { printf(L"network initialized %u\n", connectivityHint.networkInitialized); printf(L"network connectivity level hint %u\n", connectivityHint.connectivityLevel); printf(L"network connectivity cost hint %u\n", connectivityHint.connectivityCost); printf(L"network approaching data limit %u\n", connectivityHint.approachingDataLimit); printf(L"network over data limit %u\n", connectivityHint.overDataLimit); printf(L"device is roaming %u\n", connectivityHint.roaming); switch (connectivityHint.ianaInterfaceType) { case IF_TYPE_ETHERNET_CSMACD: printf(L"network type is wired\n"); break; case IF_TYPE_IEEE80211: printf(L"network type is wireless\n"); break; case IF_TYPE_WWANPP: case IF_TYPE_WWANPP2: printf(L"network type is broadband\n"); break; default: printf(L"network type is unusually esoteric %u\n", connectivityHint.connectivityLevel); break; } } ``` ## Bonnes pratiques de connectivité réseau Les champs de la structure [XNetworkingConnectivityHint](/fr/reference/networking/xnetworking/structs/xnetworkingconnectivityhint) retournée, autres que le champ `XNetworkingConnectivityHint::networkInitialized`, sont des indicateurs. Il s'agit de la meilleure estimation de l'appareil quant à l'état actuel du réseau. Elle repose sur des heuristiques basées sur le trafic réseau observé sur l'appareil. L'état de `XNetworkingConnectivityLevelHint` représente une approximation générale du niveau réseau destinée à simplifier la logique de connectivité des titres. Les titres peuvent s'attendre à ce que `XNetworkingConnectivityLevelHint::None` reflète une déconnexion du support réseau et une absence générale de connectivité en régime stable, lorsque l'environnement réseau n'a pas changé depuis plusieurs minutes. Les autres états n'indiquent pas s'il existe une connectivité vers les points de terminaison spécifiques de votre titre. Par conséquent, nous recommandons, après avoir attendu l'initialisation du réseau, d'utiliser `WinSock` et/ou `WinHTTP` pour tenter d'établir une connexion à votre point de terminaison, quel que soit l'état du champ `XNetworkingConnectivityHint::connectivityLevelHint`. Si ces API échouent ultérieurement, nous vous recommandons d'utiliser alors l'API [XNetworkingGetConnectivityHint](/fr/reference/networking/xnetworking/functions/xnetworkinggetconnectivityhint) à des fins d'interface utilisateur et de rapports de diagnostic. Vous devez ensuite attendre une modification du niveau de connectivité réseau avant de réessayer. ## Récupération d'informations réseau avancées La plupart des titres Microsoft Game Development Kit (GDK) doivent utiliser l'API [XNetworkingGetConnectivityHint](/fr/reference/networking/xnetworking/functions/xnetworkinggetconnectivityhint) avec les API `WinSock` pour récupérer l'état du réseau et des informations réseau de base, telles que les adresses IP. Si vous avez besoin de plus d'informations, l'[API IP Helper](https://learn.microsoft.com/windows/desktop/IpHlp/ip-helper-start-page) de bas niveau est disponible dans le GDK. En général, utilisez l'API `IP Helper` dans le Microsoft Game Development Kit (GDK) de la même façon que dans un programme Win32. 1. Dans vos fichiers sources, ajoutez `#include ` après `#include `. 2. Effectuez l'édition de liens avec `XGamePlatform.lib` au lieu de le faire directement avec `Ws2_32.lib` et `Iphlpapi.lib`. Seules les API de la famille d'API `WINAPI\_PARTITION\_GAMES` fonctionnent dans les titres Microsoft Game Development Kit (GDK). Sur les consoles XBOX, certaines informations ne sont pas exactes lors de l'utilisation de l'API `IP Helper` en raison de l'abstraction sous-jacente de la plateforme. Cela comprend notamment les éléments suivants : * L'adresse MAC est toujours `AA-AA-AA-AA-AA-AA`. * Toutes les interfaces signalent toujours une interface filaire, quel que soit le type de connexion réseau sous-jacent. Le véritable type d'interface ne peut être récupéré qu'à partir de [XNetworkingGetConnectivityHint](/fr/reference/networking/xnetworking/functions/xnetworkinggetconnectivityhint). ## API de connectivité réseau non prises en charge Les API de connectivité réseau suivantes ne sont pas prises en charge pour les titres Microsoft Game Development Kit (GDK), qui doivent plutôt utiliser l'API [XNetworkingGetConnectivityHint](/fr/reference/networking/xnetworking/functions/xnetworkinggetconnectivityhint) pour déterminer la connectivité réseau. * [Espace de noms Windows.Networking.Connectivity](https://learn.microsoft.com/uwp/api/windows.networking.connectivity) * [Gestionnaire de listes de réseaux (Network List Manager)](https://learn.microsoft.com/windows/desktop/nla/portal) ## Voir aussi [XNetworkingGetConnectivityHint](/fr/reference/networking/xnetworking/functions/xnetworkinggetconnectivityhint) [XNetworkingRegisterConnectivityHintChanged](/fr/reference/networking/xnetworking/functions/xnetworkingregisterconnectivityhintchanged) [XNetworkingUnregisterConnectivityHintChanged](/fr/reference/networking/xnetworking/functions/xnetworkingunregisterconnectivityhintchanged) [Windows Sockets 2 (Winsock)](https://learn.microsoft.com/windows/desktop/WinSock/windows-sockets-start-page-2) [Services HTTP Windows (WinHTTP)](https://learn.microsoft.com/windows/desktop/winhttp/winhttp-start-page) [API IP Helper](https://learn.microsoft.com/windows/desktop/IpHlp/ip-helper-start-page) ## Related topics - [XR-052 Emplacement, itinérance et dépendances de l'état utilisateur et des sauvegardes de titre](/fr-CA/publishing/certification/xr/xr-052.md) - [XR052 Emplacement, itinérance et dépendances de l'état utilisateur et des sauvegardes du titre](/fr/publishing/certification/fma/xr-052.md) - [XR-052 État utilisateur et emplacement des sauvegardes de titre, itinérance et dépendances](/fr/publishing/certification/xr/xr-052.md) - [Compiler et exécuter votre premier titre console GDKX](/fr-CA/home/build-first-title/first-console-title-walkthrough.md) - [Exigences XBOX pour les jeux XBOX](/fr-CA/publishing/certification/xbox-requirements.md)