Cihaz Özellikleri (Çekirdek Ses API'leri)

ses uç noktası cihazlarını listeleme işlemi sırasında, istemci uygulaması uç nokta nesnelerini cihaz özellikleri için sorgulayabilir. Cihaz özellikleri, IPropertyStore arabiriminin MMDevice API'sinin uygulamasında kullanıma sunulur. Bir uç nokta nesnesinin IMMDevice arabirimine başvuru verilip istemci, IMMDevice::OpenPropertyStore yöntemini çağırarak uç nokta nesnesinin özellik deposuna başvuru alabilir.

İstemciler bu özellikleri okuyabilir, ancak ayarlamamalıdır. Özellik değerleri PROPVARIANT yapıları olarak depolanır.

Uç nokta yöneticisi, uç noktalar için temel cihaz özelliklerini ayarlar. Uç nokta yöneticisi, ses uç noktası cihazlarının varlığını algılamaktan sorumlu olan Windows bileşenidir.

Aşağıdaki listedeki her PKEY_Xxx özellik tanımlayıcısı, Functiondiscoverykeys_devpkey.hüst bilgi dosyasında tanımlanan PROPERTYKEY türünde bir sabittir. Tüm ses uç noktası cihazları bu cihaz özelliklerine sahiptir.

Bazı ses uç noktası cihazlarının önceki listede görünmeyen ek özellikleri olabilir. Ek özellikler hakkında daha fazla bilgi için bkz. Ses Uç Noktası Özellikleri.

PROPERTYKEYhakkında daha fazla bilgi için Windows Özellik Sistemi belgelerine bakın.

Aşağıdaki kod örneği, sistemdeki tüm ses işleme uç noktası cihazlarının görünen adlarını yazdırır:

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

Yukarıdaki kod örneğindeki FAILED makro, Winerror.h üst bilgi dosyasında tanımlanmıştır.

Yukarıdaki kod örneğinde, PrintEndpointNames işlevindeki -loop gövdesinin, IMMDevice arabirim örneği tarafından temsil edilen ses uç noktası cihazı için uç nokta kimliği dizesi almak için IMMDevice::GetId yöntemini çağırır. Dize, cihazı sistemdeki diğer tüm ses uç noktası cihazlarıyla ilgili olarak benzersiz olarak tanımlar. İstemci, IMMDeviceEnumerator::GetDevice yöntemini çağırarak daha sonra veya farklı bir işlemde ses uç noktası cihazının bir örneğini oluşturmak için uç nokta kimliği dizesini kullanabilir. İstemciler uç nokta kimliği dizesinin içeriğini opak olarak ele almalıdır. Diğer bir ifadeyle, istemciler cihaz hakkında bilgi almak için dizenin içeriğini ayrıştırmaya çalışmamalıdır. Bunun nedeni, dize biçiminin tanımsız olması ve MMDevice API'sinin bir uygulamasından diğerine değişebileceğidir.

Önceki kod örneğinde PrintEndpointNames işlevi tarafından alınan kolay cihaz adları ve uç nokta kimliği dizeleri, cihaz numaralandırması sırasında DirectSound tarafından sağlanan kolay cihaz adları ve uç nokta kimliği dizeleriyle aynıdır. Daha fazla bilgi için bkz. Eski Ses Uygulamaları için Ses Olayları.

Yukarıdaki kod örneğinde PrintEndpointNames işlevi, CoCreateInstance işlevini çağırarak sistemdeki ses uç noktası cihazları için bir numaralandırıcı oluşturur. Çağıran program daha önce COM kitaplığını başlatmak için CoInitialize veya CoInitializeEx işlevini sürece CoCreateInstance çağrısı başarısız olur. coCreateInstance hakkında daha fazla bilgi için CoInitialize ve CoInitializeEx , Windows SDK belgelerine bakın.

IMMDeviceEnumerator, IMMDeviceCollectionve IMMDevice arabirimleri hakkında daha fazla bilgi için bkz. MMDevice API.

İlgili konular

Ses Uç Noktası Cihazları