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 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’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 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 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 :

Interrogez l’indicateur de connectivité actuel ou inscrivez-vous aux changements de connectivité.
Attendez que XNetworkingConnectivityHint::networkInitialized soit true.
Initialisez WinSock et toute autre dépendance 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. 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.

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

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

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 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. 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 changements au moyen des fonctions XNetworkingRegisterConnectivityHintChanged et XNetworkingUnregisterConnectivityHintChanged. L’exemple de code suivant montre comment utiliser la fonction XNetworkingGetConnectivityHint pour interroger les 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;
    }
}

Meilleures pratiques relatives à la connectivité réseau

Les champs de la structure 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 à 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 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 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, placez #include <iphlpapi.h> après #include <winsock2.h>.
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.

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 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 sur le réseau

Meilleures pratiques relatives à la 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 sur le réseau

​Meilleures pratiques relatives à la 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 sur le réseau

Meilleures pratiques relatives à la connectivité réseau

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

API de connectivité réseau non prises en charge

Voir aussi