PKEY_AudioEndpoint_StableId

A propriedade PKEY_AudioEndpoint_StableId fornece um identificador adicional e opaco para um endpoint áudio. O Windows tenta preservar este identificador entre atualizações do sistema operativo e atualizações de drivers de áudio.

O ID de endpoint comum que é devolvido por IMMDevice::GetId não é estável. Uma atualização do sistema operativo ou de um driver de áudio pode fazer com que o mesmo periférico físico seja atribuído a um ID de endpoint diferente. Como resultado, uma aplicação não pode usar o ID de endpoint comum para rastrear de forma fiável um endpoint áudio físico. A propriedade PKEY_AudioEndpoint_StableId , quando disponível, pode ser usada para rastrear um endpoint áudio físico. Um exemplo de cenário é uma aplicação de comunicações que se lembra do microfone ou altifalante que o utilizador selecionou e restaura essa seleção numa sessão posterior.

O membro vt da estrutura PROPVARIANT está definido como VT_LPWSTR.

O membro pwszVal da estrutura PROPVARIANT aponta para uma cadeia de caracteres largos, terminada por nulos, que contém o identificador estável do dispositivo endpoint de áudio. Se o endpoint não tiver ID estável, o valor da propriedade é VT_EMPTY. Nem todos os endpoints têm garantia de ter um ID estável.

Remarks

Trate o valor da propriedade como uma cadeia opaca e sensível a maiúsculas minúsculas, e compare-a de forma sensível a maiúsculas minúsculas. Não modifique, normalize, reconstrua ou analise o valor, e não extraia nem confie em qualquer subcadeia interna. O formato interno da cadeia é um detalhe de implementação. Cache o valor apenas para identificar o mesmo endpoint mais tarde.

Não trate o ID estável como um identificador imutável para todas as características do dispositivo. Outras propriedades do endpoint — por exemplo, o nome amigável e as características do formato — podem mudar enquanto o ID de estabilidade se mantém igual. Depois de resolver o dispositivo a partir de um ID estável em cache, volte a consultar quaisquer propriedades mutáveis de que a sua aplicação dependa.

O ID estável é mais durável do que o ID de endpoint comum, mas não é garantido que nunca mude. O Windows tenta preservá-lo através das atualizações do sistema operativo e dos drivers de áudio. A capacidade do Windows de preservar este valor depende do comportamento do driver de áudio, do firmware do periférico, do tipo de barramento (por exemplo, USB e Bluetooth) e da informação que o periférico expõe. Uma pequena percentagem de periféricos pode receber um ID estável diferente após uma atualização do sistema operativo ou do driver.

Uma aplicação deve tratar de cada um dos seguintes casos:

• O valor da propriedade é VT_EMPTY.
• A leitura do armazenamento imobiliário falha.
• Um ID estável em cache já não resolve para um endpoint através do IMMDeviceEnumerator::GetDevice.

Recuperação do ID do estábulo

Para recuperar o ID estável do endpoint selecionado pelo utilizador, faça o seguinte:

1. Comece com uma interface IMMDevice para o endpoint selecionado.
2. Chame o método IMMDevice::OpenPropertyStore com a flag STGM_READ.
3. Chame o método IPropertyStore::GetValue com a chave de propriedade PKEY_AudioEndpoint_StableId.
4. Se o membro vt do PROPVARIANT devolvido for VT_LPWSTR, persista toda a cadeia pwszVal .
5. Se a propriedade não estiver disponível ou não estiver VT_LPWSTR (por exemplo, numa versão mais antiga do Windows, ou quando o valor for VT_EMPTY), pode opcionalmente recorrer ao IMMDevice::GetId. Note que o valor de recurso é menos durável e pode tornar-se obsoleto após atualizações do sistema operativo ou dos drivers de áudio.

O exemplo seguinte recupera e mantém o ID estável.

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

Restauração do dispositivo posteriormente

Para restaurar o dispositivo numa sessão posterior, crie um objeto MMDeviceEnumerator chamando o CoCreateInstance e depois passe a string stable-ID em cache como argumento pwstrId para o método IMMDeviceEnumerator::GetDevice para recuperar a interface IMMDevice . Trate do caso de falha em que não seja encontrado um endpoint correspondente.

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

Ver também

Propriedades do Endpoint de Áudio

Propriedades Principais do Áudio

IMMDevice::OpenPropertyStore

IMMDeviceEnumerator::GetDevice

IMMDevice::GetId

Cadeias de ID de Endpoint