XUserGetDefaultAudioEndpointUtf16

Article
2025-04-28

Retrieves the default audio endpoint for a specific user.

Syntax

HRESULT XUserGetDefaultAudioEndpointUtf16(  
         XUserLocalId user,  
         XUserDefaultAudioEndpointKind defaultAudioEndpointKind,  
         size_t endpointIdUtf16Count,  
         wchar_t* endpointIdUtf16,  
         size_t* endpointIdUtf16Used  
)

Parameters

user
Type: XUserLocalId
The local ID of the user to get the default audio endpoint for.

defaultAudioEndpointKind
Type: XUserDefaultAudioEndpointKind
An enumeration value that specifies whether the user's default audio endpoint renders or captures audio.

endpointIdUtf16Count
Type: size_t
The wchar_t count of the buffer that the endpointIdUtf16 parameter points to. Pass XUserAudioEndpointMaxUtf16Count.

endpointIdUtf16 _Out_writes_to_(endpointIdUtf16Count,endpointIdUtf16Used)
Type: wchar_t
Contains the ID of the user's default audio endpoint.

endpointIdUtf16Used _Out_opt_
Type: size_t*

Contains the actual wchar_t count of the ID that the endpointIdUtf16 parameter returns.

Return value

Type: HRESULT

Returns S_OK if successful; otherwise, returns an error code. For a list of error codes, see Error Codes.

Remarks

Note

This function isn't safe to call on a time-sensitive thread. For more information, see Time-sensitive threads.

The XUserGetDefaultAudioEndpointUtf16 function takes an XUserDefaultAudioEndpointKind enumeration as an argument.

The XUserDefaultAudioEndpointUtf16ChangedCallback callback function invokes when the default audio endpoint for a specific user changes.

To register to receive a callback when the default audio endpoint changes, call XUserRegisterForDefaultAudioEndpointUtf16Changed.

To un-register to receive a callback when the default audio endpoint changes, call XUserUnregisterForDefaultAudioEndpointUtf16Changed.

The following example demonstrates how to retrieve the default audio endpoint for a user.

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

Requirements

Header: XUser.h

Library: xgameruntime.lib

Supported platforms: Windows, Xbox One family consoles and Xbox Series consoles

Share via