Detectar o status de inicialização da rede

Inicialização da rede

Use este artigo para entender como recuperar informações de conectividade e inicialização da rede em títulos do Microsoft Game Development Kit (GDK). Eles geralmente são iniciados antes que os componentes principais do sistema operacional e os serviços de rede estejam em execução. Como resultado, tentar chamar a maioria das APIs de rede e segurança, incluindo WinSock, WinHTTP, BCrypt, WinCrypt, schannel e IPHLPAPI, logo após a inicialização do título causa um comportamento indeterminado. Esse comportamento pode incluir falhas inesperadas, valores de retorno não inicializados, perda arbitrária de pacotes e possível corrupção de memória e falhas. Para evitar esse comportamento indeterminado, os títulos do Microsoft Game Development Kit (GDK) devem usar as funções XNetworkingGetConnectivityHint e XNetworkingRegisterConnectivityHintChanged. Em particular, o campo XNetworkingConnectivityHint::networkInitialized indica se a rede está inicializada. Os títulos devem aguardar até que o campo networkInitialized seja true antes de chamar as APIs de rede e segurança. Muitas bibliotecas de middleware também usam internamente as APIs de rede e segurança; até mesmo middlewares que não são de rede podem usar a pilha de rede para telemetria ou depuração. Consulte o fornecedor do middleware para saber o que fazer em cada caso. Se o próprio middleware não aguardar a inicialização da rede, talvez seja necessário adiar o carregamento do middleware até que a rede seja inicializada. Várias bibliotecas do Microsoft Game Development Kit (GDK), como XSAPI e Azure PlayFab Party, exigem que você aguarde a inicialização da rede antes de usá-las.

Sequenciamento da pilha HTTP

xCurl e libHttpClient são as únicas bibliotecas HTTP abordadas neste conjunto de documentos que gerenciam a inicialização da rede automaticamente. Se o seu título usar qualquer outra pilha HTTP, torne a sequência de inicialização explícita. Um padrão seguro é:

Consultar a dica de conectividade atual ou se registrar para alterações de conectividade.
Aguardar até que XNetworkingConnectivityHint::networkInitialized seja true.
Inicializar o WinSock e quaisquer outras dependências de rede.
Acessar o estado dos certificados e configurar a confiança.
Criar a pilha HTTP e começar a emitir solicitações.

A prontidão da rede deve vir primeiro. Inicializar o WinSock, o estado dos certificados ou o estado HTTP cedo demais pode produzir falhas difíceis de diagnosticar, porque o erro visível geralmente aparece depois da causa raiz. O exemplo a seguir mostra as primeiras etapas de uma sequência de inicialização de uma pilha HTTP de propriedade do título. Ele consulta XNetworkingConnectivityHint diretamente antes de inicializar o 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;
}

Depois que essas etapas forem bem-sucedidas, crie os objetos da sua pilha HTTP e aplique qualquer configuração de confiança específica da pilha antes de emitir solicitações. Para pilhas que não usam Schannel, isso pode incluir o carregamento do certificado de proxy exigido pela sua ferramenta de depuração.

Suspensão e retomada

Além disso, os ciclos de suspensão/retomada do título redefinem o campo networkInitialized para false. Na suspensão, os títulos devem limpar todos os identificadores de todos os componentes de rede e segurança e interromper todas as operações de rede. Confira a página de visão geral de cada API de rede para obter mais informações sobre os requisitos dessa API na suspensão. Na retomada, os títulos devem novamente aguardar que o campo networkInitialized se torne true antes de tentar restabelecer conexões e usar qualquer uma das APIs de rede ou segurança. Recomendamos que o caminho de inicialização da rede na retomada seja o mesmo que o caminho de inicialização do título: na retomada ou na inicialização do título, aguarde a inicialização da rede antes de iniciar seu código de rede. Bibliotecas de middleware que não reconhecem a suspensão/retomada, como GameChat2 e Azure PlayFab Party, devem ser limpas na suspensão e reinicializadas na retomada, após aguardar a inicialização da rede. Suponha que toda pilha HTTP diferente do xCurl exige tratamento explícito do ciclo de vida. Na suspensão ou no desligamento, pare de enfileirar novas solicitações e cancele ou conclua o trabalho em andamento. Destrua identificadores de solicitação, sessões e soquetes que não devem sobreviver à suspensão. Na retomada, trate a inicialização da rede como um novo caminho de inicialização. Aguarde networkInitialized novamente antes de recriar o estado HTTP ou registrar novamente os ouvintes. Designs baseados em trabalho cancelável e não bloqueante são mais fáceis de desfazer de forma limpa durante a suspensão do que chamadas bloqueantes de longa duração.

Testar a inicialização da rede

A inicialização da rede geralmente leva alguns segundos, tanto na retomada quanto na inicialização do título, e varia de acordo com o tipo de console e o ambiente de rede do usuário. Durante o desenvolvimento, a inicialização da rede é quase instantânea. Isso pode ocultar problemas em várias partes do seu título que não aguardam corretamente a inicialização da rede. Para testar cenários de inicialização da rede, use xbconfig NetworkInitDelayInSeconds=30 para adicionar um atraso arbitrário ao processo de inicialização da rede. Ao usar essa configuração, reinicie completamente o título entre cada teste usando xbapp terminate /full. Defina NetworkInitDelayInSeconds de volta para 0 ao concluir os testes. Para pilhas HTTP que criam seu próprio estado de rede, inclua pelo menos estes cenários na cobertura de testes:

Inicialização a frio
Suspensão enquanto há solicitações ativas
Retomada após uma suspensão limpa
Quick Resume ou fluxos de restauração equivalentes
Desconexões de rede próximas aos limites de suspensão e retomada

Exemplos de código de inicialização da rede

O exemplo de código a seguir mostra como sondar, de forma segura e em tempo real, se a rede está inicializada.

bool IsNetworkInitialized()
{
    XNetworkingConnectivityHint connectivityHint;
    if (SUCCEEDED(XNetworkingGetConnectivityHint(&connectivityHint)))
    {
        return connectivityHint.networkInitialized;
    }
    return false;
}

O exemplo de código a seguir mostra como um título pode bloquear até que a rede seja inicializada.

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;
}

Informações de rede

As informações de rede em títulos do Microsoft Game Development Kit (GDK) podem ser recuperadas com a API XNetworkingGetConnectivityHint. A API XNetworkingGetConnectivityHint retorna informações de todo o dispositivo sobre os níveis de conectividade de rede, limites de dados, tipos de conectividade com fio ou sem fio e se a rede está inicializada. É uma API segura em tempo real que retorna imediatamente as informações atuais. Você pode escutar as alterações com as funções XNetworkingRegisterConnectivityHintChanged e XNetworkingUnregisterConnectivityHintChanged. O exemplo de código a seguir mostra como usar a função XNetworkingGetConnectivityHint para consultar informações sobre o estado atual da rede.

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;
    }
}

Práticas recomendadas de conectividade de rede

Os campos da struct XNetworkingConnectivityHint retornada, exceto o campo XNetworkingConnectivityHint::networkInitialized, são dicas. Eles são a melhor estimativa do dispositivo sobre o estado atual da rede. Isso se baseia em heurísticas do tráfego de rede observado no dispositivo. O estado de XNetworkingConnectivityLevelHint representa uma aproximação geral do nível da rede para simplificar a lógica de conectividade dos títulos. Os títulos podem esperar que XNetworkingConnectivityLevelHint::None reflita a desconexão do meio de rede e a falta geral de conectividade em estado estável, quando o ambiente de rede não muda há vários minutos. Outros estados não representam se há conectividade com os pontos de extremidade específicos do seu título. Como resultado, recomendamos que, após aguardar a inicialização da rede, você use o WinSock e/ou o WinHTTP para tentar estabelecer uma conexão com seu ponto de extremidade, independentemente do estado do campo XNetworkingConnectivityHint::connectivityLevelHint. Se essas APIs falharem posteriormente, recomendamos que você use a API XNetworkingGetConnectivityHint para fins adicionais de interface do usuário e de relatórios de diagnóstico. Em seguida, você deve aguardar uma alteração no nível de conectividade da rede antes de tentar novamente.

Recuperar informações de rede avançadas

A maioria dos títulos do Microsoft Game Development Kit (GDK) deve usar a API XNetworkingGetConnectivityHint com as APIs do WinSock para recuperar o estado da rede e informações básicas de rede, como endereços IP. Se você precisar de mais informações, a API auxiliar de IP de baixo nível está disponível no GDK. Em geral, trabalhe com a API IP Helper no Microsoft Game Development Kit (GDK) da mesma forma que trabalharia com essa API em um programa Win32.

Nos seus arquivos de origem, use #include <iphlpapi.h> após #include <winsock2.h>.
Vincule a XGamePlatform.lib em vez de vincular diretamente a Ws2_32.lib e Iphlpapi.lib.

Somente as APIs da família de APIs WINAPI\_PARTITION\_GAMES funcionam em títulos do Microsoft Game Development Kit (GDK). Nos consoles XBOX, certas informações não são precisas ao usar a API IP Helper devido à abstração subjacente da plataforma. Isso inclui, entre outros, o seguinte:

O endereço MAC será sempre AA-AA-AA-AA-AA-AA.
Todas as interfaces sempre relatam uma interface com fio, independentemente do tipo de conexão de rede subjacente. O tipo real da interface só pode ser recuperado de XNetworkingGetConnectivityHint.

APIs de conectividade de rede sem suporte

As seguintes APIs de conectividade de rede não têm suporte para títulos do Microsoft Game Development Kit (GDK), que devem usar a API XNetworkingGetConnectivityHint para determinar a conectividade de rede.

Confira também

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

Porting

Build Paths

Inicialização da rede

Sequenciamento da pilha HTTP

Suspensão e retomada

Testar a inicialização da rede

Exemplos de código de inicialização da rede

Informações de rede

Práticas recomendadas de conectividade de rede

Recuperar informações de rede avançadas

APIs de conectividade de rede sem suporte

Confira também

​Inicialização da rede

​Sequenciamento da pilha HTTP

​Suspensão e retomada

​Testar a inicialização da rede

​Exemplos de código de inicialização da rede

​Informações de rede

​Práticas recomendadas de conectividade de rede

​Recuperar informações de rede avançadas

​APIs de conectividade de rede sem suporte

​Confira também

Inicialização da rede

Sequenciamento da pilha HTTP

Suspensão e retomada

Testar a inicialização da rede

Exemplos de código de inicialização da rede

Informações de rede

Práticas recomendadas de conectividade de rede

Recuperar informações de rede avançadas

APIs de conectividade de rede sem suporte

Confira também