PKEY_AudioEndpoint_StableId

La propiedad PKEY_AudioEndpoint_StableId proporciona un identificador opaco adicional para un punto de conexión de audio. Windows intenta conservar este identificador en las actualizaciones del sistema operativo y las actualizaciones de controladores de audio.

El identificador de punto de conexión normal devuelto por IMMDevice::GetId no es estable. Una actualización del sistema operativo o una actualización del controlador de audio puede hacer que se asigne un mismo periférico físico a un identificador de punto de conexión diferente. Como resultado, una aplicación no puede usar el identificador de punto de conexión normal para realizar un seguimiento confiable de un punto de conexión de audio físico. La propiedad PKEY_AudioEndpoint_StableId , cuando está disponible, se puede usar para realizar un seguimiento de un punto de conexión de audio físico. Un escenario de ejemplo es una aplicación de comunicaciones que recuerda el micrófono o el altavoz que el usuario seleccionó y restaura esa selección en una sesión posterior.

El miembro vt de la estructura PROPVARIANT se establece en VT_LPWSTR.

El miembro pwszVal de la estructura PROPVARIANT apunta a una cadena de caracteres anchos terminada en NULL que contiene el identificador estable del dispositivo de punto de conexión de audio. Si el punto de conexión no tiene ningún identificador estable, el valor de la propiedad es VT_EMPTY. No se garantiza que todos los puntos de conexión tengan un identificador estable.

Observaciones

Trate el valor de la propiedad como una cadena opaca, con distinción entre mayúsculas y minúsculas y compárela con distinción entre mayúsculas y minúsculas. No modifique, normalice, reconstruya ni analice el valor y no extraiga ni dependa de ninguna subcadena interna. El formato interno de la cadena es un detalle de implementación. Almacene en caché el valor solo para identificar el mismo punto de conexión de nuevo más adelante.

No trate el identificador estable como un identificador inmutable para todas las características del dispositivo. Otras propiedades del punto de conexión (por ejemplo, el nombre descriptivo y las características de formato) pueden cambiar mientras el identificador estable permanece igual. Después de resolver el dispositivo desde un identificador estable almacenado en caché, vuelva a consultar las propiedades mutables de las que depende la aplicación.

El identificador estable es más duradero que el identificador de punto de conexión normal, pero no se garantiza que nunca cambie. Windows intenta conservarlo en las actualizaciones del sistema operativo y del controlador de audio. Windows capacidad de conservar este valor depende del comportamiento del controlador de audio, el firmware periférico, el tipo de bus (por ejemplo, USB y Bluetooth) y la información que expone el periférico. Un pequeño porcentaje de periféricos puede recibir un identificador estable diferente después de una actualización del sistema operativo o del controlador.

Una aplicación debe controlar cada uno de los casos siguientes:

• El valor de la propiedad es VT_EMPTY.
• Se produce un error en la lectura del almacén de propiedades.
• Un identificador estable almacenado en caché ya no se resuelve en un punto de conexión a través de IMMDeviceEnumerator::GetDevice.

Recuperación del identificador estable

Para recuperar el identificador estable del punto de conexión seleccionado por el usuario, haga lo siguiente:

1. Comience con una interfaz IMMDevice para el punto de conexión seleccionado.
2. Llame al método IMMDevice::OpenPropertyStore con la marca STGM_READ.
3. Llame al método IPropertyStore::GetValue con la clave de propiedad PKEY_AudioEndpoint_StableId.
4. Si el miembro vt del PROPVARIANT devuelto es VT_LPWSTR, conserve toda la cadena pwszVal .
5. Si la propiedad no está disponible o no está VT_LPWSTR (por ejemplo, en una versión anterior de Windows o cuando el valor es VT_EMPTY), puede revertir opcionalmente a IMMDevice::GetId. Tenga en cuenta que el valor de reserva es menos duradero y puede quedar obsoleto después de las actualizaciones del sistema operativo o del controlador de audio.

En el ejemplo siguiente se recupera y se conserva el identificador estable.

wil::unique_cotaskmem_string deviceId;
wil::com_ptr_nothrow<IPropertyStore> propertyStore;
if (SUCCEEDED(userSelectedEndpoint->OpenPropertyStore(STGM_READ, &propertyStore)))
{
    wil::unique_prop_variant var;
    if (SUCCEEDED(propertyStore->GetValue(PKEY_AudioEndpoint_StableId, &var)))
    {
        if (var.vt == VT_LPWSTR)
        {
            deviceId.reset(var.release().pwszVal);
        }
    }
}

Restauración del dispositivo más adelante

Para restaurar el dispositivo en una sesión posterior, cree un objeto MMDeviceEnumerator llamando a CoCreateInstance y, a continuación, pase la cadena de id. estable almacenada en caché como argumento pwstrId al método IMMDeviceEnumerator::GetDevice para devolver la interfaz IMMDevice . Controle el caso de error en el que no se encuentra ningún punto de conexión coincidente.

HRESULT GetUserAudioEndpoint(_In_ PCWSTR endpointStableId, _COM_Outptr_ IMMDevice** userSelectedEndpoint)
{
    *userSelectedEndpoint = nullptr;
    wil::com_ptr_nothrow<IMMDeviceEnumerator> enumerator;
    RETURN_IF_FAILED(CoCreateInstance(__uuidof(MMDeviceEnumerator), nullptr, CLSCTX_ALL, IID_PPV_ARGS(&enumerator)));
    RETURN_IF_FAILED(enumerator->GetDevice(endpointStableId, userSelectedEndpoint));
    return S_OK;
}

Requirements

Véase también

Propiedades del punto de conexión de audio

Propiedades principales de audio

IMMDevice::OpenPropertyStore

IMMDeviceEnumerator::GetDevice

IMMDevice::GetId

Cadenas de id. de punto de conexión