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 et 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 et Azure PlayFab Party, 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 :

Interrogez l’indicateur de connectivité actuel ou inscrivez-vous aux modifications de connectivité.
Attendez que XNetworkingConnectivityHint::networkInitialized soit true.
Initialisez WinSock et toutes les autres dépendances réseau.
Accédez à l’état des certificats et configurez l’approbation.
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.

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

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

static
void
NetworkConnectivityHintChangedCallback(
    _In_ void* context,
    _In_ const XNetworkingConnectivityHint* connectivityHint
    )
{
    HANDLE networkInitializedEvent = static_cast<HANDLE>(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. L’API 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 et XNetworkingUnregisterConnectivityHintChanged. L’exemple de code suivant montre comment utiliser la fonction XNetworkingGetConnectivityHint pour interroger des informations sur l’état actuel du réseau.

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

Dans vos fichiers sources, ajoutez #include <iphlpapi.h> après #include <winsock2.h>.
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.

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 pour déterminer la connectivité réseau.

Voir aussi

XNetworkingGetConnectivityHint XNetworkingRegisterConnectivityHintChanged XNetworkingUnregisterConnectivityHintChanged Windows Sockets 2 (Winsock) Services HTTP Windows (WinHTTP) API IP Helper

Introduction

Onboarding & Access

Setup & Install

Build Your First Title

Initialisation du réseau

Séquencement de la pile HTTP

Suspension et reprise

Test de l’initialisation du réseau

Exemples de code d’initialisation du réseau

Informations réseau

Bonnes pratiques de connectivité réseau

Récupération d’informations réseau avancées

API de connectivité réseau non prises en charge

Voir aussi

​Initialisation du réseau

​Séquencement de la pile HTTP

​Suspension et reprise

​Test de l’initialisation du réseau

​Exemples de code d’initialisation du réseau

​Informations réseau

​Bonnes pratiques de connectivité réseau

​Récupération d’informations réseau avancées

​API de connectivité réseau non prises en charge

​Voir aussi

Initialisation du réseau

Séquencement de la pile HTTP

Suspension et reprise

Test de l’initialisation du réseau

Exemples de code d’initialisation du réseau

Informations réseau

Bonnes pratiques de connectivité réseau

Récupération d’informations réseau avancées

API de connectivité réseau non prises en charge

Voir aussi