XUserLocalId

아티클
05/09/2023

사용자의 게임 세션 ID를 지정합니다.

구문

typedef struct XUserLocalId {  
    uint64_t value;  
} XUserLocalId

멤버

value
형식: uint64_t

사용자의 게임 세션 ID입니다.

비고

XUserLocalId는 게이밍 세션 내에서 사용자를 고유하게 식별합니다. XUserHandle가 중복되면, 두 핸들 모두 동일한 XUserLocalId를 유지 관리합니다. 게이밍 세션이 종료되면 동일한 사용자가 다음 세션 중에 다른 XUserLocalId를 가질 수 있습니다. 이러한 ID를 게임 세션 전반에서 사용자를 식별하는 용도로 사용해선 안 됩니다. ID는 개별 게임 세션에서만 유효합니다.

“null” XUserLocalId는 XUserNullUserLocalId 값과 같습니다.

다음 콜백 함수 및 함수는 XUserLocalId 구조 또는 이에 관한 포인터를 인수로 취합니다.

XUserChangeEventCallback: 사용자 변경 이벤트에 대한 콜백 함수입니다.
XUserDefaultAudioEndpointUtf16ChangedCallback: 사용자의 기본 오디오 끝점이 변경되면 호출되는 콜백입니다.
XUserFindUserByLocalId: 특정 로컬 사용자 ID를 이용해 사용자에 대한 핸들을 검색하는 함수입니다.
XUserGetDefaultAudioEndpointUtf16: 특정 사용자에 대한 기본 오디오 끝점을 검색하는 함수입니다.
XUserGetLocalId: 사용자의 고유 게임 세션 ID를 검색하는 함수입니다.

다음 예제에서는 XUserLocalId 구조를 사용하여 사용자의 기본 오디오 끝점을 검색하는 방법을 보여줍니다.

HRESULT GetAudioDeviceAssociation(
    IMMDeviceEnumerator* audioDeviceEnumerator,
    XUserLocalId user,
    XUserDefaultAudioEndpointKind defaultAudioEndpointKind,
    _Outptr_result_maybenull_ IMMDevice** endpoint)
{
    wchar_t audioDeviceId[XUserAudioEndpointMaxUtf16Count];
    RETURN_IF_FAILED_WITH_EXPECTED(XUserGetDefaultAudioEndpointUtf16(user, defaultAudioEndpointKind, std::size(audioDeviceId), audioDeviceId, nullptr), E_NOTFOUND);

    return audioDeviceEnumerator->GetDevice(audioDeviceId, endpoint);
}

HRESULT GetAudioAssociations()
{
    Mwrl::ComPtr<IMMDeviceEnumerator> audioDeviceEnumerator;

    RETURN_IF_FAILED(CoCreateInstance(
        __uuidof(MMDeviceEnumerator),
        nullptr,
        CLSCTX_ALL,
        __uuidof(IMMDeviceEnumerator),
        (void**)&audioDeviceEnumerator));

    XUserLocalId userLocalId;
    RETURN_IF_FAILED(XUserGetLocalId(_handle.get(), &userLocalId));

    {
        wil::unique_cotaskmem_string id;
        Mwrl::ComPtr<IMMDevice> device;
        if (SUCCEEDED(GetAudioDeviceAssociation(audioDeviceEnumerator.Get(), userLocalId, XUserDefaultAudioEndpointKind::CommunicationRender, &device)))
        {
            RETURN_IF_FAILED(device->GetId(&id));
        }
        appLog.AddLog("Preferred render communication device id: %S\n", id.get());
    }

    {
        wil::unique_cotaskmem_string id;
        Mwrl::ComPtr<IMMDevice> device;
        if (SUCCEEDED(GetAudioDeviceAssociation(audioDeviceEnumerator.Get(), userLocalId, XUserDefaultAudioEndpointKind::CommunicationCapture, &device)))
        {
            RETURN_IF_FAILED(device->GetId(&id));
        }
        appLog.AddLog("Preferred capture communication device id: %S\n", id.get());
    }

    return S_OK;
}