Enhetsegenskaper (Kärnljud-API:er)

Under processen med att räkna upp ljudslutpunktsenheterkan ett klientprogram fråga slutpunktsobjekten om deras enhetsegenskaper. Enhetsegenskaperna exponeras i MMEnhets-API:ets implementering av gränssnittet IPropertyStore. Med en referens till IMMDevice--gränssnittet för ett slutpunktsobjekt kan en klient hämta en referens till slutpunktsobjektets egenskapsarkiv genom att anropa metoden IMMDevice::OpenPropertyStore.

Klienter kan läsa dessa egenskaper, men bör inte ange dem. Egenskapsvärden lagras som PROPVARIANT- strukturer.

Slutpunktshanteraren anger de grundläggande enhetsegenskaperna för slutpunkter. Slutpunktshanteraren är Den Windows-komponent som ansvarar för att identifiera förekomsten av ljudslutpunktsenheter.

Varje PKEY_Xxx egenskapsidentifierare i följande lista är en konstant av typen PROPERTYKEY som definieras i rubrikfilen Functiondiscoverykeys_devpkey.h. Alla ljudslutpunktsenheter har dessa enhetsegenskaper.

Egenskap	Beskrivning
PKEY_DeviceInterface_FriendlyName	Det egna namnet på det ljudkort som slutpunktsenheten är ansluten till (till exempel "XYZ-ljudadapter").
PKEY_Device_DeviceDesc	Enhetsbeskrivningen för slutpunktsenheten (till exempel "Talare").
PKEY_Device_FriendlyName	Det egna namnet på slutpunktsenheten (till exempel "Högtalare (XYZ-ljudadapter)").
PKEY_Device_InstanceId	Lagrar ljudslutpunkten enhetsinstansidentifierare. Värdet kan också hämtas via IMMDevice::GetId-metod. Mer information om den här egenskapen finns i Endpoint ID Strings and DEVPKEY_Device_InstanceId.
PKEY_Device_ContainerId	Lagrar containeridentifierare för PnP-enheten som implementerar ljudslutpunkten. Mer information om den här egenskapen finns i DEVPKEY_Device_ContainerId.

Vissa ljudslutpunktsenheter kan ha ytterligare egenskaper som inte visas i föregående lista. Mer information om ytterligare egenskaper finns i Ljudslutpunktsegenskaper.

Mer information om PROPERTYKEYfinns i dokumentationen Windows Property System.

Följande kodexempel skriver ut visningsnamnen för alla slutpunktsenheter för ljudåtergivning i systemet:

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

Makrot FAILED i föregående kodexempel definieras i huvudfilen Winerror.h.

I föregående kodexempel anropar för-loop-brödtexten i funktionen PrintEndpointNames metoden IMMDevice::GetId för att hämta slutpunkts-ID-strängen för ljudslutpunktsenheten som representeras av IMMDevice gränssnittsinstans. Strängen identifierar enheten unikt med avseende på alla andra ljudslutpunktsenheter i systemet. En klient kan använda slutpunkts-ID-strängen för att skapa en instans av ljudslutpunktsenheten vid ett senare tillfälle eller i en annan process genom att anropa metoden IMMDeviceEnumerator::GetDevice. Klienter bör behandla innehållet i slutpunkts-ID-strängen som ogenomskinlig. Klienter bör alltså inte försöka parsa innehållet i strängen för att hämta information om enheten. Anledningen är att strängformatet är odefinierat och kan ändras från en implementering av MMDevice API till nästa.

De egna enhetsnamnen och slutpunkts-ID-strängarna som hämtas av funktionen PrintEndpointNames i föregående kodexempel är identiska med de egna enhetsnamn och slutpunkts-ID-strängar som tillhandahålls av DirectSound under enhetsuppräkning. Mer information finns i Ljudhändelser för äldre ljudprogram.

I föregående kodexempel anropar funktionen PrintEndpointNames funktionen CoCreateInstance för att skapa en uppräknare för ljudslutpunktsenheterna i systemet. Om inte det anropande programmet tidigare anropade antingen funktionen CoInitialize eller CoInitializeEx för att initiera COM-biblioteket misslyckas CoCreateInstance--anropet. Mer information om CoCreateInstance, CoInitializeoch CoInitializeExfinns i Windows SDK-dokumentationen.

Mer information om IMMDeviceEnumerator, IMMDeviceCollectionoch IMMDevice-gränssnitt finns i MMDevice API.

Relaterade ämnen

ljudslutpunktsenheter