Proprietà del dispositivo (API audio principali)

Durante il processo di enumerazione dei dispositivi endpoint audio, un'applicazione client può interrogare gli oggetti endpoint per le relative proprietà del dispositivo. Le proprietà del dispositivo vengono esposte nell'implementazione dell'API MMDevice dell'interfaccia IPropertyStore . Dato un riferimento all'interfaccia IMMDevice di un oggetto endpoint, un client può ottenere un riferimento all'archivio delle proprietà dell'oggetto endpoint chiamando il metodo IMMDevice::OpenPropertyStore.

I client possono leggere queste proprietà, ma non devono impostarli. I valori delle proprietà vengono archiviati come strutture PROPVARIANT .

Endpoint Manager imposta le proprietà di base del dispositivo per gli endpoint. Endpoint Manager è il componente Windows responsabile del rilevamento della presenza di dispositivi endpoint audio.

Ogni identificatore di proprietà PKEY_Xxx nell'elenco seguente è una costante di tipo PROPERTYKEY definita nel file di intestazione Functiondiscoverykeys_devpkey.h. Tutti i dispositivi endpoint audio hanno queste proprietà del dispositivo.

Proprietà	Descrizione
PKEY_DeviceInterface_FriendlyName	Nome descrittivo della scheda audio a cui è collegato il dispositivo endpoint (ad esempio, "Scheda audio XYZ").
PKEY_Device_DeviceDesc	Descrizione del dispositivo endpoint (ad esempio, "Altoparlanti").
PKEY_Device_FriendlyName	Nome descrittivo del dispositivo endpoint (ad esempio, "Altoparlanti (scheda audio XYZ)").
PKEY_Device_InstanceId	Archivia l'identificatore dell'istanza del dispositivo dell'endpoint audio. Il valore può anche essere aquirito tramite il metodo IMMDevice::GetId. Per altre informazioni su questa proprietà, vedere Stringhe ID endpoint e DEVPKEY_Device_InstanceId.
PKEY_Device_ContainerId	Archivia l'identificatore del contenitore del dispositivo PnP che implementa l'endpoint audio. Per altre informazioni su questa proprietà, vedere DEVPKEY_Device_ContainerId.

Alcuni dispositivi endpoint audio potrebbero avere proprietà aggiuntive che non vengono visualizzate nell'elenco precedente. Per altre informazioni sulle proprietà aggiuntive, vedere Proprietà dell'endpoint audio.

Per altre informazioni su PROPERTYKEY, vedere la documentazione di Windows Property System.

Nell'esempio di codice seguente vengono stampati i nomi visualizzati di tutti i dispositivi endpoint di rendering audio nel 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)
}

La macro FAILED nell'esempio di codice precedente è definita nel file di intestazione Winerror.h.

Nell'esempio di codice precedente il corpo del ciclo for nella funzione PrintEndpointNames chiama il metodo IMMDevice::GetId per ottenere la stringa ID endpoint per il dispositivo endpoint audio rappresentato dall'istanza dell'interfaccia IMMDevice . La stringa identifica in modo univoco il dispositivo rispetto a tutti gli altri dispositivi endpoint audio nel sistema. Un client può usare la stringa id endpoint per creare un'istanza del dispositivo endpoint audio in un secondo momento o in un processo diverso chiamando il metodo IMMDeviceEnumerator::GetDevice . I client devono considerare il contenuto della stringa id endpoint come opaca. Ovvero, i client non devono tentare di analizzare il contenuto della stringa per ottenere informazioni sul dispositivo. Il motivo è che il formato della stringa non è definito e potrebbe cambiare da un'implementazione dell'API MMDevice alla successiva.

I nomi descrittivi dei dispositivi e le stringhe ID endpoint ottenuti dalla funzione PrintEndpointNames nell'esempio di codice precedente sono identici ai nomi descrittivi dei dispositivi e alle stringhe ID endpoint fornite da DirectSound durante l'enumerazione del dispositivo. Per altre informazioni, vedere Eventi audio per applicazioni audio legacy.

Nell'esempio di codice precedente la funzione PrintEndpointNames chiama la funzione CoCreateInstance per creare un enumeratore per i dispositivi endpoint audio nel sistema. A meno che il programma chiamante chiamato in precedenza la funzione CoInitialize o CoInitializeEx per inizializzare la libreria COM, la chiamata CoCreateInstance avrà esito negativo. Per altre informazioni su CoCreateInstance, CoInitialize e CoInitializeEx, vedere la documentazione di Windows SDK.

Per altre informazioni sulle interfacce IMMDeviceEnumerator, IMMDeviceCollection e IMMDevice, vedere API MMDevice.

Argomenti correlati

Dispositivi endpoint audio