Properti Perangkat (API Audio Inti)

  • Artikel

Selama proses menghitung perangkat titik akhir audio, aplikasi klien dapat menginterogasi objek titik akhir untuk properti perangkat mereka. Properti perangkat diekspos dalam implementasi MMDevice API dari antarmuka IPropertyStore. Mengingat referensi ke antarmuka IMMDevice dari objek titik akhir, klien dapat memperoleh referensi ke penyimpanan properti objek titik akhir dengan memanggil metode IMMDevice::OpenPropertyStore.

Klien dapat membaca properti ini, tetapi tidak boleh mengaturnya. Nilai properti disimpan sebagai struktur PROPVARIANT .

Manajer titik akhir mengatur properti perangkat dasar untuk titik akhir. Manajer titik akhir adalah komponen Windows yang bertanggung jawab untuk mendeteksi keberadaan perangkat titik akhir audio.

Setiap pengidentifikasi properti PKEY_Xxx dalam daftar berikut adalah konstanta jenis PROPERTYKEY yang ditentukan dalam file header Functiondiscoverykeys_devpkey.h. Semua perangkat titik akhir audio memiliki properti perangkat ini.

Properti Deskripsi
PKEY_DeviceInterface_FriendlyName Nama adaptor audio yang mudah diingat tempat perangkat titik akhir dilampirkan (misalnya, "Adapter Audio XYZ").
PKEY_Device_DeviceDesc Deskripsi perangkat perangkat titik akhir (misalnya, "Speaker").
PKEY_Device_FriendlyName Nama perangkat titik akhir yang mudah diingat (misalnya, "Speaker (Adaptor Audio XYZ)").
PKEY_Device_InstanceId Menyimpan pengidentifikasi instans perangkat titik akhir audio. Nilai juga dapat diminta melalui metode IMMDevice::GetId . Untuk informasi selengkapnya tentang properti ini, lihat String ID Titik Akhir dan DEVPKEY_Device_InstanceId.
PKEY_Device_ContainerId Menyimpan pengidentifikasi kontainer perangkat PnP yang mengimplementasikan titik akhir audio. Untuk informasi selengkapnya tentang properti ini, lihat DEVPKEY_Device_ContainerId.

Beberapa perangkat titik akhir audio mungkin memiliki properti tambahan yang tidak muncul di daftar sebelumnya. Untuk informasi selengkapnya tentang properti tambahan, lihat Properti Titik Akhir Audio.

Untuk informasi selengkapnya tentang PROPERTYKEY, lihat dokumentasi Sistem Properti Windows.

Contoh kode berikut mencetak nama tampilan semua perangkat titik akhir penyajian audio dalam sistem:

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

Makro GAGAL dalam contoh kode sebelumnya didefinisikan dalam file header Winerror.h.

Dalam contoh kode sebelumnya, isi for-loop dalam fungsi PrintEndpointNames memanggil metode IMMDevice::GetId untuk mendapatkan string ID titik akhir untuk perangkat titik akhir audio yang diwakili oleh instans antarmuka IMMDevice . String secara unik mengidentifikasi perangkat sehubungan dengan semua perangkat titik akhir audio lainnya dalam sistem. Klien dapat menggunakan string ID titik akhir untuk membuat instans perangkat titik akhir audio di lain waktu atau dalam proses yang berbeda dengan memanggil metode IMMDeviceEnumerator::GetDevice. Klien harus memperlakukan konten string ID titik akhir sebagai buram. Artinya, klien tidak boleh mencoba mengurai konten string untuk mendapatkan informasi tentang perangkat. Alasannya adalah bahwa format string tidak ditentukan dan mungkin berubah dari satu implementasi MMDevice API ke yang berikutnya.

Nama perangkat yang ramah dan string ID titik akhir yang diperoleh oleh fungsi PrintEndpointNames dalam contoh kode sebelumnya identik dengan nama perangkat yang ramah dan string ID titik akhir yang disediakan oleh DirectSound selama enumerasi perangkat. Untuk informasi selengkapnya, lihat Peristiwa Audio untuk Aplikasi Audio Warisan.

Dalam contoh kode sebelumnya, fungsi PrintEndpointNames memanggil fungsi CoCreateInstance untuk membuat enumerator untuk perangkat titik akhir audio dalam sistem. Kecuali program panggilan sebelumnya disebut fungsi CoInitialize atau CoInitializeEx untuk menginisialisasi pustaka COM, panggilan CoCreateInstance akan gagal. Untuk informasi selengkapnya tentang CoCreateInstance, CoInitialize, dan CoInitializeEx, lihat dokumentasi Windows SDK.

Untuk informasi selengkapnya tentang antarmuka IMMDeviceEnumerator, IMMDeviceCollection, dan IMMDevice , lihat MMDevice API.

Perangkat Titik Akhir Audio