네트워크 초기화 상태 감지

아티클
05/09/2023

이 항목을 사용하여 Microsoft GDK(Game Development Kit) 타이틀에서 네트워크 연결 및 초기화 정보를 검색하는 방법을 이해하세요. 주로 핵심 OS 구성 요소와 네트워킹 서비스가 실행되기 전에 시작됩니다. 그 결과 타이틀이 시작된 지 얼마 지나지 않아 WinSock, WinHTTP, BCrypt, WinCrypt, schannel 및 IPHLPAPI을(를) 포함한 대부분의 네트워킹과 보안 API를 호출하려고 시도하면 불확실한 동작이 발생합니다. 이 동작에는 예기치 않은 실패, 초기화되지 않은 반환 값, 임의의 패킷 손실, 잠재적인 메모리 손상 및 충돌이 포함될 수 있습니다.

이러한 불확실한 동작을 방지하려면 Microsoft GDK(게임 개발 키트) 타이틀에서 XNetworkingGetConnectivityHint 및 XNetworkingRegisterConnectivityHintChanged 함수를 사용해야 합니다. 특히 XNetworkingConnectivityHint::networkInitialized 필드는 네트워크 초기화 여부를 나타냅니다. 타이틀은 networkInitialized 필드가 true가 될 때까지 기다린 다음 네트워킹 및 보안 API를 호출해야 합니다.

또한 많은 미들웨어 라이브러리는 내부적으로 네트워킹 및 보안 API를 사용합니다. 네트워킹이 아닌 미들웨어도 원격 측정 또는 디버깅을 위해 네트워크 스택을 사용할 수 있습니다. 각 인스턴스에서 해야 하는 작업은 미들웨어 공급자에게 문의하세요. 미들웨어가 자체적으로 네트워크 초기화를 대기하지 않는다면, 네트워크가 초기화될 때까지 미들웨어 로딩을 연기해야 할 수도 있습니다. XSAPI 및 Azure PlayFab 파티와 같은 Microsoft GDK(게임 개발 키트)에 있는 여러 라이브러리를 사용하려면 네트워크가 초기화될 때까지 기다려야 합니다.

일시 중단 및 재개

또한 타이틀 일시 중지/재개 주기는 networkInitialized 필드를 false로 재설정합니다. 일시 중지하면 타이틀이 모든 네트워크 및 보안 구성 요소에 대한 핸들 일체를 정리하고 모든 네트워크 작업을 중지합니다. 일시 중단 시 해당 API의 요구 사항에 대한 자세한 내용은 각 네트워킹 API의 개요 페이지를 참조하세요. 재개하면 타이틀은 networkInitialized 필드가 true가 될 때까지 다시 기다린 다음 연결 재설정을 시도하고 네트워킹 또는 보안 API를 사용해야 합니다. 재개 네트워크 초기화 경로는 초기 타이틀 실행 경로와 동일할 것을 권장합니다. 재개 시 또는 타이틀 실행 시 네트워크 코드를 시작하기 전에 네트워크가 초기화될 때까지 기다리세요. XSAPI, GameChat2, Azure PlayFab 파티와 같은 suspend/resume을 모르는 미들웨어 라이브러리는 네트워크 초기화 후에는 대기 시 또는 다시 초기화할 때 정리해야 합니다.

네트워크 초기화 테스트

네트워크 초기화는 일반적으로 재개 및 타이틀 실행 시 몇 초 정도 걸리며, 본체 유형과 사용자의 네트워크 환경에 따라 달라집니다. 개발 과정에서 네트워크 초기화는 거의 즉시 완료됩니다. 이렇게 하면 네트워크가 초기화될 때까지 기다리지 않은 타이틀의 여러 부분에서 발생하는 문제를 숨길 수 있습니다. 네트워크 초기화 시나리오 테스트를 위해, xbconfig NetworkInitDelayInSeconds=30을 이용해 임의의 지연 시간을 네트워크 초기화 프로세스에 추가합니다. 이 설정을 사용할 때는 xbapp terminate /full을(를) 이용해 테스트가 끝날 때마다 타이틀을 완전히 다시 시작해야 합니다. 테스트가 끝나면 NetworkInitDelayInSeconds을(를) 다시 0으로 설정해야 합니다.

네트워크 초기화 코드 예제

다음 코드 예제는 네트워크 초기화 여부를 실시간으로 안전하게 폴링하는 방법을 보여 줍니다.


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

다음 코드 예제는 네트워크가 초기화될 때까지 타이틀을 차단하는 방법을 보여 줍니다.

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

네트워크 정보

Microsoft GDK(게임 개발 키트) 타이틀의 네트워크 정보는 XNetworkingGetConnectivityHint API를 사용하여 검색할 수 있습니다.

XNetworkingGetConnectivityHint API는 장치 전반의 정보 네트워크 연결 수준, 데이터 제한, 유선 대 무선 연결 유형, 네트워크 초기화 여부를 반환합니다. 이것은 현재 정보를 즉시 반환하는 안전한 실시간 API입니다. XNetworkingRegisterConnectivityHintChanged 및 XNetworkingUnregisterConnectivityHintChanged 기능을 사용하여 변경 내용을 수신할 수 있습니다.

다음 코드 예제는 XNetworkingGetConnectivityHint 함수를 사용하여 현재 네트워크 상태 관련 정보를 쿼리하는 방법을 보여 줍니다.


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

네트워크 연결 모범 사례

반환된 XNetworkingConnectivityHint 구조체에 있는 필드 중 XNetworkingConnectivityHint::networkInitialized 이외의 필드는 힌트입니다. 디바이스가 네트워크의 현재 상태를 최대한 추측한 것입니다. 이는 디바이스에서 관찰된 네트워크 트래픽 추론을 바탕으로 합니다.

XNetworkingConnectivityLevelHint 상태는 타이틀 연결 논리를 간소화하는 일반적인 네트워크 수준 근사치를 나타냅니다. 타이틀은 네트워크 환경이 몇 분간 변경되지 않은 안정 상태에서 일반적인 연결 부족뿐 아니라 네트워크 매체 연결 끊김이 XNetworkingConnectivityLevelHint::None에 반영될 것으로 기대할 수 있습니다. 기타 상태는 특정 타이틀 끝점에 연결되어 있는지 여부를 나타내지 않습니다.

결과적으로 네트워크 초기화가 끝날 때까지 기다린 다음, WinSock 및/또는 WinHTTP를 이용해 XNetworkingConnectivityHint::connectivityLevelHint 필드 상태와 상관없이 끝점과의 연결을 형성하는 것이 좋습니다. 이러한 API가 나중에 실패한다면, 추가 UI 및 진단 보고에는 XNetworkingGetConnectivityHint API를 사용하는 것이 좋습니다. 그런 다음 네트워크 연결 수준이 변경될 때까지 기다린 후 다시 시도해야 합니다.

고급 네트워크 정보 검색

대부분의 Microsoft GDK(게임 개발 키트) 타이틀에서는 XNetworkingGetConnectivityHint API와 WinSock API를 함께 사용해 네트워크 관련 상태와 IP 주소 등의 기본 네트워크 정보를 검색해야 합니다. 자세한 정보가 필요하다면 GDK에서 하위 수준 IP 도우미 API를 이용하세요.

일반적으로 Win32 프로그램에서 이 API를 사용하는 것과 같은 방식으로 Microsoft GDK(게임 개발 키트)에서 IP Helper API를 사용합니다.