> ## 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 réseau dans les titres du Microsoft Game Development Kit (GDK). Ceux-ci sont souvent lancés avant que les composants principaux du système d'exploitation et les services réseau soient en cours d'exécution. Par conséquent, tenter d'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 que des corruptions de mémoire et des plantages potentiels. Pour éviter ce comportement indéterminé, les titres du Microsoft Game Development Kit (GDK) doivent utiliser les fonctions [XNetworkingGetConnectivityHint](/fr-CA/reference/networking/xnetworking/functions/xnetworkinggetconnectivityhint) et [XNetworkingRegisterConnectivityHintChanged](/fr-CA/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'intergiciel utilisent aussi les API réseau et de sécurité à l'interne; 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), comme [XSAPI](https://learn.microsoft.com/windows/uwp/xbox-live/xsapi-flat-c) et [Azure PlayFab Party](/fr-CA/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 dans 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 changements de connectivité. 2. Attendez que `XNetworkingConnectivityHint::networkInitialized` soit `true`. 3. Initialisez `WinSock` et toute autre dépendance 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. Démarrer `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 gérée par le titre. Il interroge directement `XNetworkingConnectivityHint` avant de démarrer `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 et de reprise du titre réinitialisent le champ `networkInitialized` à `false`. Lors de la suspension, les titres doivent nettoyer tous les descripteurs de tous les composants réseau et de sécurité et cesser toutes les opérations réseau. Consultez la page de vue d'ensemble 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 de 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 à la reprise soit le même que celui du lancement initial du titre : à la reprise ou au lancement du titre, attendez que le réseau soit initialisé avant de démarrer votre code réseau. Les bibliothèques d'intergiciel qui ne tiennent pas compte de la suspension et de la reprise, comme 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. Supposez que chaque pile HTTP autre que xCurl exige une gestion explicite du cycle de vie. Lors de la suspension ou de l'arrêt, cessez de mettre de nouvelles requêtes en file d'attente et annulez ou videz le travail en cours. Détruisez les descripteurs de requête, les sessions et les sockets qui ne doivent pas survivre à la suspension. Lors de la reprise, traitez le démarrage du réseau comme un nouveau chemin d'initialisation. Attendez de nouveau `networkInitialized` avant de recréer l'état HTTP ou de réinscrire les écouteurs. Les conceptions fondées sur un travail annulable et non bloquant sont plus faciles à défaire proprement pendant la suspension que les appels bloquants de longue durée. ## Test de l'initialisation du réseau L'initialisation du réseau prend habituellement quelques secondes, tant à la reprise qu'au 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 à diverses parties 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` pour 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 au moyen de `xbapp terminate /full`. Remettez `NetworkInitDelayInSeconds` à `0` lorsque vous avez terminé les tests. Pour les piles HTTP qui créent leur propre état réseau, incluez au moins ces scénarios 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 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 vérifier par interrogation, de façon 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 pourrait 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 sur le réseau Les informations sur le réseau dans les titres du Microsoft Game Development Kit (GDK) peuvent être récupérées au moyen de l'API [XNetworkingGetConnectivityHint](/fr-CA/reference/networking/xnetworking/functions/xnetworkinggetconnectivityhint). L'API [XNetworkingGetConnectivityHint](/fr-CA/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 changements au moyen des fonctions [XNetworkingRegisterConnectivityHintChanged](/fr-CA/reference/networking/xnetworking/functions/xnetworkingregisterconnectivityhintchanged) et [XNetworkingUnregisterConnectivityHintChanged](/fr-CA/reference/networking/xnetworking/functions/xnetworkingunregisterconnectivityhintchanged). L'exemple de code suivant montre comment utiliser la fonction [XNetworkingGetConnectivityHint](/fr-CA/reference/networking/xnetworking/functions/xnetworkinggetconnectivityhint) pour interroger les 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; } } ``` ## Meilleures pratiques relatives à la connectivité réseau Les champs de la structure [XNetworkingConnectivityHint](/fr-CA/reference/networking/xnetworking/structs/xnetworkingconnectivityhint) retournée, autres que le champ `XNetworkingConnectivityHint::networkInitialized`, sont des indicateurs. Ils représentent la meilleure estimation possible de l'appareil quant à l'état actuel du réseau. Cette estimation repose sur des heuristiques fondé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 précis de votre titre. Par conséquent, nous recommandons qu'après avoir attendu l'initialisation du réseau, vous utilisiez `WinSock` 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 par la suite, nous recommandons d'utiliser l'API [XNetworkingGetConnectivityHint](/fr-CA/reference/networking/xnetworking/functions/xnetworkinggetconnectivityhint) à des fins d'interface utilisateur et de rapports de diagnostic. Vous devez ensuite attendre un changement du niveau de connectivité réseau avant de réessayer. ## Récupération d'informations réseau avancées La plupart des titres du Microsoft Game Development Kit (GDK) doivent utiliser l'API [XNetworkingGetConnectivityHint](/fr-CA/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 comme 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, placez `#include ` après `#include `. 2. Effectuez l'édition des liens avec `XGamePlatform.lib` plutôt que directement avec `Ws2_32.lib` et `Iphlpapi.lib`. Seules les API de la famille d'API `WINAPI\_PARTITION\_GAMES` fonctionnent dans les titres du Microsoft Game Development Kit (GDK). Sur les consoles XBOX, certaines informations ne sont pas exactes lorsque vous utilisez l'API `IP Helper`, en raison de l'abstraction sous-jacente de la plateforme. Cela comprend notamment ce qui suit : * L'adresse MAC sera 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'au moyen de [XNetworkingGetConnectivityHint](/fr-CA/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 du Microsoft Game Development Kit (GDK), qui doivent plutôt utiliser l'API [XNetworkingGetConnectivityHint](/fr-CA/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-CA/reference/networking/xnetworking/functions/xnetworkinggetconnectivityhint) [XNetworkingRegisterConnectivityHintChanged](/fr-CA/reference/networking/xnetworking/functions/xnetworkingregisterconnectivityhintchanged) [XNetworkingUnregisterConnectivityHintChanged](/fr-CA/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)