Propriedades do dispositivo (APIs de áudio principais)

Durante o processo de enumeração de dispositivos de ponto de extremidade de áudio , um aplicativo cliente pode interrogar os objetos de ponto de extremidade para suas propriedades de dispositivo. As propriedades do dispositivo são expostas na implementação da API MMDevice da interfaceIPropertyStore. Dada uma referência à interface IMMDevice de um objeto de ponto de extremidade, um cliente pode obter uma referência ao armazenamento de propriedades do objeto de ponto de extremidade chamando o IMMDevice::OpenPropertyStore método.

Os clientes podem ler essas propriedades, mas não devem defini-las. Os valores de propriedade são armazenados como estruturas de PROPVARIANT.

O gerenciador de pontos de extremidade define as propriedades básicas do dispositivo para pontos de extremidade. O gerenciador de pontos finais é o componente do Windows responsável por detetar a presença de dispositivos de ponto de extremidade de áudio.

Cada identificador de propriedade PKEY_Xxx na lista a seguir é uma constante do tipo PROPERTYKEY que é definida no arquivo de cabeçalho Functiondiscoverykeys_devpkey.h. Todos os dispositivos de ponto final de áudio têm essas propriedades de dispositivo.

Alguns dispositivos de ponto de extremidade de áudio podem ter propriedades adicionais que não aparecem na lista anterior. Para obter mais informações sobre propriedades adicionais, consulte Audio Endpoint Properties.

Para obter mais informações sobre PROPERTYKEY, consulte a documentação do Windows Property System.

O exemplo de código a seguir imprime os nomes de exibição de todos os dispositivos de ponto de extremidade de renderização de áudio no sistema:

//-----------------------------------------------------------
// This function enumerates all active (plugged in) audio
// rendering endpoint devices. It prints the friendly name
// and endpoint ID string of each endpoint device.
//-----------------------------------------------------------
#define EXIT_ON_ERROR(hres)  \
              if (FAILED(hres)) { goto Exit; }
#define SAFE_RELEASE(punk)  \
              if ((punk) != NULL)  \
                { (punk)->Release(); (punk) = NULL; }

const CLSID CLSID_MMDeviceEnumerator = __uuidof(MMDeviceEnumerator);
const IID IID_IMMDeviceEnumerator = __uuidof(IMMDeviceEnumerator);

void PrintEndpointNames()
{
    HRESULT hr = S_OK;
    IMMDeviceEnumerator *pEnumerator = NULL;
    IMMDeviceCollection *pCollection = NULL;
    IMMDevice *pEndpoint = NULL;
    IPropertyStore *pProps = NULL;
    LPWSTR pwszID = NULL;

    hr = CoCreateInstance(
           CLSID_MMDeviceEnumerator, NULL,
           CLSCTX_ALL, IID_IMMDeviceEnumerator,
           (void**)&pEnumerator);
    EXIT_ON_ERROR(hr)

    hr = pEnumerator->EnumAudioEndpoints(
                        eRender, DEVICE_STATE_ACTIVE,
                        &pCollection);
    EXIT_ON_ERROR(hr)

    UINT  count;
    hr = pCollection->GetCount(&count);
    EXIT_ON_ERROR(hr)

    if (count == 0)
    {
        printf("No endpoints found.\n");
    }

    // Each loop prints the name of an endpoint device.
    for (ULONG i = 0; i < count; i++)
    {
        // Get pointer to endpoint number i.
        hr = pCollection->Item(i, &pEndpoint);
        EXIT_ON_ERROR(hr)

        // Get the endpoint ID string.
        hr = pEndpoint->GetId(&pwszID);
        EXIT_ON_ERROR(hr)
        
        hr = pEndpoint->OpenPropertyStore(
                          STGM_READ, &pProps);
        EXIT_ON_ERROR(hr)

        PROPVARIANT varName;
        // Initialize container for property value.
        PropVariantInit(&varName);

        // Get the endpoint's friendly-name property.
        hr = pProps->GetValue(
                       PKEY_Device_FriendlyName, &varName);
        EXIT_ON_ERROR(hr)

        // GetValue succeeds and returns S_OK if PKEY_Device_FriendlyName is not found.
        // In this case vartName.vt is set to VT_EMPTY.      
        if (varName.vt != VT_EMPTY)
        {
            // Print endpoint friendly name and endpoint ID.
            printf("Endpoint %d: \"%S\" (%S)\n", 
                    i, varName.pwszVal, pwszID);
        }

        CoTaskMemFree(pwszID);
        pwszID = NULL;
        PropVariantClear(&varName);
        SAFE_RELEASE(pProps)
        SAFE_RELEASE(pEndpoint)
    }
    SAFE_RELEASE(pEnumerator)
    SAFE_RELEASE(pCollection)
    return;

Exit:
    printf("Error!\n");
    CoTaskMemFree(pwszID);
    SAFE_RELEASE(pEnumerator)
    SAFE_RELEASE(pCollection)
    SAFE_RELEASE(pEndpoint)
    SAFE_RELEASE(pProps)
}

A macro FAILED no exemplo de código anterior é definida no arquivo de cabeçalho Winerror.h.

No exemplo de código anterior, o para-loop body na função PrintEndpointNames chama o IMMDevice::GetId método para obter a cadeia de caracteres de ID de ponto de extremidade para o dispositivo de ponto de extremidade de áudio que é representado pela instância de interface de IMMDevice. A cadeia de caracteres identifica exclusivamente o dispositivo em relação a todos os outros dispositivos de ponto final de áudio no sistema. Um cliente pode usar a cadeia de caracteres de ID de ponto de extremidade para criar uma instância do dispositivo de ponto de extremidade de áudio em um momento posterior ou em um processo diferente, chamando o IMMDeviceEnumerator::GetDevice método. Os clientes devem tratar o conteúdo da cadeia de caracteres de ID do ponto de extremidade como opaco. Ou seja, os clientes não devem tentar analisar o conteúdo da cadeia de caracteres para obter informações sobre o dispositivo. O motivo é que o formato da cadeia de caracteres é indefinido e pode mudar de uma implementação da API MMDevice para a próxima.

Os nomes de dispositivo amigáveis e cadeias de caracteres de ID de ponto de extremidade que são obtidos pela função PrintEndpointNames no exemplo de código anterior são idênticos aos nomes de dispositivo amigável e cadeias de caracteres de ID de ponto de extremidade que são fornecidos pelo DirectSound durante a enumeração de dispositivo. Para obter mais informações, consulte eventos de áudio para aplicativos de áudio herdados.

No exemplo de código anterior, a função PrintEndpointNames chama a função CoCreateInstance para criar um enumerador para os dispositivos de ponto de extremidade de áudio no sistema. A menos que o programa de chamada chamado anteriormente o CoInitialize ou função CoInitializeEx para inicializar a biblioteca COM, a chamada CoCreateInstance falhará. Para obter mais informações sobre CoCreateInstance , CoInitializee CoInitializeEx, consulte a documentação do SDK do Windows.

Para obter mais informações sobre o IMMDeviceEnumerator, IMMDeviceCollectione interfaces IMMDevice, consulte MMDevice API.

Tópicos relacionados

dispositivos de ponto final de áudio