> ## 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. # Detectar o status de inicialização da rede > 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](/pt-BR/reference/networking/xnetworking/functions/xnetworkinggetconnectivityhint) e [XNetworkingRegisterConnectivityHintChanged](/pt-BR/reference/networking/xnetworking/functions/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](https://learn.microsoft.com/windows/uwp/xbox-live/xsapi-flat-c) e [Azure PlayFab Party](/pt-BR/build/console-features/networking/game-mesh/playfab-party-intro-networking), 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 é: 1. Consultar a dica de conectividade atual ou se registrar para alterações de conectividade. 2. Aguardar até que `XNetworkingConnectivityHint::networkInitialized` seja `true`. 3. Inicializar o `WinSock` e quaisquer outras dependências de rede. 4. Acessar o estado dos certificados e configurar a confiança. 5. 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`. ```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; } ``` 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. ```cpp theme={null} 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. ```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; } ``` ## 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](/pt-BR/reference/networking/xnetworking/functions/xnetworkinggetconnectivityhint). A API [XNetworkingGetConnectivityHint](/pt-BR/reference/networking/xnetworking/functions/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](/pt-BR/reference/networking/xnetworking/functions/xnetworkingregisterconnectivityhintchanged) e [XNetworkingUnregisterConnectivityHintChanged](/pt-BR/reference/networking/xnetworking/functions/xnetworkingunregisterconnectivityhintchanged). O exemplo de código a seguir mostra como usar a função [XNetworkingGetConnectivityHint](/pt-BR/reference/networking/xnetworking/functions/xnetworkinggetconnectivityhint) para consultar informações sobre o estado atual da rede. ```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; } } ``` ## Práticas recomendadas de conectividade de rede Os campos da struct [XNetworkingConnectivityHint](/pt-BR/reference/networking/xnetworking/structs/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](/pt-BR/reference/networking/xnetworking/functions/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](/pt-BR/reference/networking/xnetworking/functions/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](https://learn.microsoft.com/windows/desktop/IpHlp/ip-helper-start-page) 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. 1. Nos seus arquivos de origem, use `#include ` após `#include `. 2. 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](/pt-BR/reference/networking/xnetworking/functions/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](/pt-BR/reference/networking/xnetworking/functions/xnetworkinggetconnectivityhint) para determinar a conectividade de rede. * [Namespace Windows.Networking.Connectivity](https://learn.microsoft.com/uwp/api/windows.networking.connectivity) * [Gerenciador de Listas de Redes](https://learn.microsoft.com/windows/desktop/nla/portal) ## Confira também [XNetworkingGetConnectivityHint](/pt-BR/reference/networking/xnetworking/functions/xnetworkinggetconnectivityhint) [XNetworkingRegisterConnectivityHintChanged](/pt-BR/reference/networking/xnetworking/functions/xnetworkingregisterconnectivityhintchanged) [XNetworkingUnregisterConnectivityHintChanged](/pt-BR/reference/networking/xnetworking/functions/xnetworkingunregisterconnectivityhintchanged) [Windows Sockets 2 (Winsock)](https://learn.microsoft.com/windows/desktop/WinSock/windows-sockets-start-page-2) [Windows HTTP Services (WinHTTP)](https://learn.microsoft.com/windows/desktop/winhttp/winhttp-start-page) [API auxiliar de IP](https://learn.microsoft.com/windows/desktop/IpHlp/ip-helper-start-page) ## Related topics - [XR-074 Perda de conectividade com os serviços XBOX e de parceiros](/pt-BR/publishing/certification/xr/xr-074.md) - [Requisitos XBOX testados na certificação para jogos de console XBOX](/pt-BR/publishing/certification/console-cert-tested-requirements.md) - [Etapas do teste de validação de mídia](/pt-BR/publishing/game-publishing/concepts/certification/certification-media-validation-test-steps.md) - [Guia de BVT de console da certificação](/pt-BR/publishing/game-publishing/concepts/certification/certification-console-bvt-guide.md) - [Notas de versão do SDK C++ do PlayFab Multiplayer](/pt-BR/services/playfab/multiplayer/lobby/lobby-matchmaking-sdks/lobby-and-matchmaking-release-notes.md)