デバイスのプロパティ (コア オーディオ API)

オーディオ エンドポイント デバイス列挙するプロセス中に、クライアント アプリケーションは、デバイスのプロパティに対してエンドポイント オブジェクトを問い合えることができます。 デバイス プロパティは、MMDevice API の IPropertyStore インターフェイスの実装で公開されます。 エンドポイント オブジェクトの IMMDevice インターフェイスへの参照を指定すると、クライアントは、IMMDevice::OpenPropertyStore メソッドを呼び出すことによって、エンドポイント オブジェクトのプロパティ ストアへの参照を取得できます。

クライアントはこれらのプロパティを読み取ることができますが、設定しないでください。 プロパティ値は PROPVARIANT 構造体 格納されます。

エンドポイント マネージャーは、エンドポイントの基本的なデバイス プロパティを設定します。 エンドポイント マネージャーは、オーディオ エンドポイント デバイスの存在を検出する Windows コンポーネントです。

次の一覧の各 PKEY_Xxx プロパティ識別子は、ヘッダー ファイル Functiondiscoverykeys_devpkey.hで定義されている PROPERTYKEY 型の定数です。 すべてのオーディオ エンドポイント デバイスには、これらのデバイス プロパティがあります。

一部のオーディオ エンドポイント デバイスには、前の一覧に表示されない追加のプロパティがある場合があります。 その他のプロパティの詳細については、「Audio Endpoint Properties」を参照してください。

PROPERTYKEY の詳細については、Windows プロパティ システムのドキュメントを参照してください。

次のコード例では、システム内のすべてのオーディオ レンダリング エンドポイント デバイスの表示名を出力します。

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

前のコード例の FAILED マクロは、ヘッダー ファイル Winerror.h で定義されています。

前のコード例では、PrintEndpointNames 関数 -loop 本文のは、IMMDevice::GetId メソッドを呼び出して、IMMDevice インターフェイス インスタンスによって表されるオーディオ エンドポイント デバイスの エンドポイント ID 文字列 を取得します。 この文字列は、システム内の他のすべてのオーディオ エンドポイント デバイスに関してデバイスを一意に識別します。 クライアントは、エンドポイント ID 文字列を使用して、後で、または別のプロセスで、IMMDeviceEnumerator::GetDevice メソッドを呼び出すことによって、オーディオ エンドポイント デバイスのインスタンスを作成できます。 クライアントは、エンドポイント ID 文字列の内容を不透明として扱う必要があります。 つまり、クライアントは文字列の内容を解析してデバイスに関する情報を取得しないでください。 その理由は、文字列形式が未定義であり、MMDevice API の実装から次の実装に変わる可能性があるためです。

前のコード例の PrintEndpointNames 関数によって取得されるフレンドリ デバイス名とエンドポイント ID 文字列は、デバイスの列挙中に DirectSound によって提供されるフレンドリ デバイス名とエンドポイント ID 文字列と同じです。 詳細については、「レガシ オーディオ アプリケーション のオーディオ イベントをする」を参照してください。

前のコード例では、PrintEndpointNames 関数は、CoCreateInstance 関数を呼び出して、システム内のオーディオ エンドポイント デバイスの列挙子を作成します。 呼び出し元のプログラムが以前に com ライブラリを初期化するために CoInitialize または CoInitializeEx 関数を呼び出していない限り、CoCreateInstance 呼び出しは失敗します。 CoCreateInstance、CoInitialize、および CoInitializeEx の詳細については、Windows SDK のドキュメントを参照してください。

IMMDeviceEnumerator、IMMDeviceCollection、および IMMDevice インターフェイス の詳細については、「MMDevice API」を参照してください。

関連トピック

オーディオ エンドポイント デバイスの を する