Apparaateigenschappen (Core Audio-API's)

Tijdens het proces van het inventariseren van audio-eindpuntapparaten kan een clienttoepassing de eindpuntobjecten voor hun apparaateigenschappen ondervragen. De apparaateigenschappen worden weergegeven in de implementatie van de IPropertyStore-interface van de MMDevice-API. Gezien een verwijzing naar de IMMDevice-interface van een eindpuntobject, kan een client een verwijzing verkrijgen naar het eigenschappenarchief van het eindpuntobject door de methode IMMDevice::OpenPropertyStore aan te roepen.

Clients kunnen deze eigenschappen lezen, maar mogen ze niet instellen. Eigenschapswaarden worden opgeslagen als PROPVARIANT-structuren .

De eindpuntbeheerder stelt de basiseigenschappen van het apparaat voor eindpunten in. Endpoint Manager is het Windows-onderdeel dat verantwoordelijk is voor het detecteren van de aanwezigheid van audio-eindpuntapparaten.

Elke PKEY_Xxx eigenschaps-id in de volgende lijst is een constante van het type PROPERTYKEY die is gedefinieerd in het headerbestand Functiondiscoverykeys_devpkey.h. Alle audio-eindpuntapparaten hebben deze apparaateigenschappen.

Vastgoed	Description
PKEY_DeviceInterface_FriendlyName	De beschrijvende naam van de audioadapter waaraan het eindpuntapparaat is gekoppeld (bijvoorbeeld 'XYZ-audioadapter').
PKEY_Device_DeviceDesc	De apparaatbeschrijving van het eindpuntapparaat (bijvoorbeeld 'Sprekers').
PKEY_Device_FriendlyName	De beschrijvende naam van het eindpuntapparaat (bijvoorbeeld 'Luidsprekers (XYZ-audioadapter)').
PKEY_Device_InstanceId	Slaat de exemplaar-id van het audio-eindpuntapparaat op. De waarde kan ook worden verkregen via de methode IMMDevice::GetId . Zie Eindpunt-id-tekenreeksen en DEVPKEY_Device_InstanceId voor meer informatie over deze eigenschap.
PKEY_Device_ContainerId	Slaat de container-id op van het PnP-apparaat dat het audio-eindpunt implementeert. Zie DEVPKEY_Device_ContainerId voor meer informatie over deze eigenschap.

Sommige audio-eindpuntapparaten hebben mogelijk extra eigenschappen die niet worden weergegeven in de voorgaande lijst. Zie Eigenschappen van audio-eindpunt voor meer informatie over aanvullende eigenschappen.

Zie de documentatie van het Windows Property System voor meer informatie over PROPERTYKEY.

In het volgende codevoorbeeld worden de weergavenamen van alle audiorenderingseindpunten in het systeem afgedrukt:

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

De macro FAILED in het voorgaande codevoorbeeld is gedefinieerd in het headerbestand Winerror.h.

In het voorgaande codevoorbeeld roept de for-looptekst in de functie PrintEndpointNames de methode IMMDevice::GetId aan om de eindpunt-id-tekenreeks te verkrijgen voor het audio-eindpuntapparaat dat wordt vertegenwoordigd door het exemplaar van de IMMDevice-interface . De tekenreeks identificeert het apparaat op unieke wijze met betrekking tot alle andere audio-eindpuntapparaten in het systeem. Een client kan de eindpunt-id-tekenreeks gebruiken om op een later tijdstip of in een ander proces een exemplaar van het audio-eindpuntapparaat te maken door de methode IMMDeviceEnumerator::GetDevice aan te roepen. Clients moeten de inhoud van de eindpunt-id-tekenreeks behandelen als ondoorzichtig. Dat wil gezegd, clients mogen niet proberen de inhoud van de tekenreeks te parseren om informatie over het apparaat te verkrijgen. De reden hiervoor is dat de tekenreeksindeling niet is gedefinieerd en kan veranderen van de ene implementatie van de MMDevice-API naar de volgende.

De beschrijvende apparaatnamen en eindpunt-id-tekenreeksen die worden verkregen door de functie PrintEndpointNames in het voorgaande codevoorbeeld, zijn identiek aan de beschrijvende apparaatnamen en eindpunt-id-tekenreeksen die door DirectSound worden geleverd tijdens de opsomming van het apparaat. Zie Audio-gebeurtenissen voor verouderde audiotoepassingen voor meer informatie.

In het voorgaande codevoorbeeld roept de functie PrintEndpointNames de functie CoCreateInstance aan om een enumerator te maken voor de audio-eindpuntapparaten in het systeem. Tenzij het aanroepende programma eerder de functie CoInitialize of CoInitializeEx heeft aangeroepen om de COM-bibliotheek te initialiseren, mislukt de aanroep CoCreateInstance . Zie de Windows SDK-documentatie voor meer informatie over CoCreateInstance, CoInitialize en CoInitializeEx.

Zie MMDevice-API voor meer informatie over de IMMDeviceEnumerator-, IMMDeviceCollection- en IMMDevice-interfaces.

Verwante onderwerpen

Audio-eindpuntapparaten