XUserGetLocalId

아티클
05/10/2023

사용자의 고유한 게임 세션 ID를 검색합니다.

구문

HRESULT XUserGetLocalId(  
         XUserHandle user,  
         XUserLocalId* userLocalId  
)

매개 변수

user _In_
형식: XUserHandle

로컬 ID를 검색할 사용자에 대한 핸들입니다.

userLocalId _Out_
형식: XUserLocalId*

사용자의 고유한 게임 세션 ID를 포함합니다.

반환 값

형식: HRESULT

HRESULT 성공 또는 오류 코드입니다.
오류 코드 목록은 오류 코드를 참조하세요.

비고

특정 사용자의 사용자 ID를 검색하려면 XUserGetId를 호출합니다.

특정 사용자의 상태를 검색하려면 XUserGetState를 호출합니다.

특정 사용자의 연령 그룹을 검색하려면 XUserGetAgeGroup을 호출합니다.

XUserLocalId는 게이밍 세션 내에서 사용자를 고유하게 식별합니다. XUserHandle가 중복되면, 두 핸들 모두 동일한 XUserLocalId를 유지 관리합니다. 게이밍 세션이 종료되면 동일한 사용자가 다음 세션 중에 다른 XUserLocalId를 가질 수 있습니다. 이러한 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;
}