PKEY_AudioEndpoint_StableId

A propriedade PKEY_AudioEndpoint_StableId fornece um identificador opaco adicional para um ponto de extremidade de áudio. Windows tentativas de preservar esse identificador entre atualizações do sistema operacional e atualizações de driver de áudio.

A ID do ponto de extremidade comum retornada por IMMDevice::GetId não é estável. Uma atualização do sistema operacional ou uma atualização do driver de áudio pode fazer com que o mesmo periférico físico receba uma ID de ponto de extremidade diferente. Como resultado, um aplicativo não pode usar a ID do ponto de extremidade comum para acompanhar de forma confiável um ponto de extremidade de áudio físico. A propriedade PKEY_AudioEndpoint_StableId , quando disponível, pode ser usada para rastrear um ponto de extremidade de áudio físico. Um cenário de exemplo é um aplicativo de comunicação que se lembra do microfone ou alto-falante que o usuário selecionou e restaura essa seleção em uma sessão posterior.

O membro vt da estrutura PROPVARIANT é definido como VT_LPWSTR.

O membro pwszVal da estrutura PROPVARIANT aponta para uma cadeia de caracteres larga e terminada em nulo que contém o identificador estável para o dispositivo de ponto de extremidade de áudio. Se o ponto de extremidade não tiver uma ID estável, o valor da propriedade será VT_EMPTY. Nem todos os pontos de extremidade têm a garantia de ter uma ID estável.

Observações

Trate o valor da propriedade como uma cadeia de caracteres opaca, que diferencia maiúsculas de minúsculas e compare-o com diferenciação de maiúsculas de minúsculas. Não modifique, normalize, reconstrua ou analise o valor e não extraia ou dependa de nenhuma subcadeia de caracteres interna. O formato interno da cadeia de caracteres é um detalhe de implementação. Armazene o valor em cache apenas para identificar o mesmo ponto de extremidade novamente mais tarde.

Não trate a ID estável como um identificador imutável para todas as características do dispositivo. Outras propriedades de ponto de extremidade, por exemplo, o nome amigável e as características de formato, podem ser alteradas enquanto a ID estável permanece a mesma. Depois de resolver o dispositivo de uma ID estável armazenada em cache, consulte novamente as propriedades mutáveis das quais seu aplicativo depende.

A ID estável é mais durável do que a ID do ponto de extremidade comum, mas não é garantido que nunca mude. Windows tenta preservá-lo entre atualizações do sistema operacional e do driver de áudio. Windows' capacidade de preservar esse valor depende do comportamento do driver de áudio, do firmware periférico, do tipo de barramento (por exemplo, USB e Bluetooth) e das informações que o periférico expõe. Uma pequena porcentagem de periféricos pode receber uma ID estável diferente após uma atualização do sistema operacional ou do driver.

Um aplicativo deve lidar com cada um dos seguintes casos:

• O valor da propriedade é VT_EMPTY.
• A leitura do repositório de propriedades falha.
• Uma ID estável armazenada em cache não é mais resolvida para um ponto de extremidade por meio de IMMDeviceEnumerator::GetDevice.

Recuperando a ID estável

Para recuperar a ID estável para o ponto de extremidade selecionado pelo usuário, faça o seguinte:

1. Comece com uma interface IMMDevice para o ponto de extremidade selecionado.
2. Chame o método IMMDevice::OpenPropertyStore com o sinalizador STGM_READ.
3. Chame o método IPropertyStore::GetValue com a chave de propriedade PKEY_AudioEndpoint_StableId.
4. Se o membro vt do PROPVARIANT retornado for VT_LPWSTR, persista toda a cadeia de caracteres pwszVal .
5. Se a propriedade estiver indisponível ou não estiver VT_LPWSTR (por exemplo, em uma versão mais antiga do Windows ou quando o valor estiver VT_EMPTY), opcionalmente, você poderá voltar para IMMDevice::GetId. Observe que o valor de fallback é menos durável e pode ficar obsoleto após atualizações do sistema operacional ou do driver de áudio.

O exemplo a seguir recupera e persiste a 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);
        }
    }
}

Restaurando o dispositivo mais tarde

Para restaurar o dispositivo em uma sessão posterior, crie um objeto MMDeviceEnumerator chamando CoCreateInstance e, em seguida, passe a cadeia de caracteres stable-ID armazenada em cache como o argumento pwstrId para o método IMMDeviceEnumerator::GetDevice para recuperar a interface IMMDevice . Manipule o caso de falha no qual nenhum ponto de extremidade correspondente é encontrado.

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

Consulte também

Propriedades do ponto de extremidade de áudio

Propriedades de áudio principal

IMMDevice::OpenPropertyStore

IMMDeviceEnumerator::GetDevice

IMMDevice::GetId

Cadeias de caracteres da ID do ponto de extremidade