IMMDeviceEnumerator

IMMDeviceEnumerator インターフェイスは、マルチメディアデバイスリソースを列挙するためのメソッドを提供します。

EnumAudioEndpoints メソッドは、指定された条件を満たすオーディオエンドポイントデバイスのコレクションを生成します。

メソッドが成功した場合は S_OK を返します。失敗した場合、戻り値には次の表に示す値が含まれますが、これらに限定されません。

たとえば、次の呼び出しは、現在アクティブな(存在し、かつ無効化されていない)すべてのオーディオレンダリングエンドポイントデバイスを列挙します。

  hr = pDevEnum->EnumAudioEndpoints(
                   eRender, DEVICE_STATE_ACTIVE,
                   &pEndpoints);

上記のコードフラグメントでは、変数 hr は HRESULT 型、pDevEnum は IMMDeviceEnumerator インターフェイスへのポインター、pEndpoints は IMMDeviceCollection インターフェイスへのポインターです。

例

EnumAudioEndpoints メソッドを呼び出すコード例については、Device Properties を参照してください。

GetDefaultAudioEndpoint メソッドは、指定されたデータフロー方向とロールに対する既定のオーディオエンドポイントを取得します。

メソッドが成功した場合は S_OK を返します。失敗した場合、戻り値には次の表に示す値が含まれますが、これらに限定されません。

メモ

Windows Vista では、MMDevice API はデバイスロールをサポートしていますが、システム提供のユーザーインターフェイスプログラムはサポートしていません。Windows Vista のユーザーインターフェイスでは、ユーザーはレンダリング用の既定オーディオデバイスとキャプチャ用の既定オーディオデバイスを選択できます。ユーザーが既定のレンダリングデバイスまたはキャプチャデバイスを変更すると、システムは 3 つのデバイスロール(eConsole、eMultimedia、eCommunications)すべてをそのデバイスに割り当てます。したがって、GetDefaultAudioEndpoint は、role パラメーターで示されるロールに関係なく、常に既定のレンダリングデバイスまたはキャプチャデバイスを選択します。将来のバージョンの Windows では、ユーザーインターフェイスによってユーザーが個々のロールを異なるデバイスに割り当てられるようになる可能性があります。その場合、GetDefaultAudioEndpoint によるレンダリングデバイスまたはキャプチャデバイスの選択は role パラメーターに依存する可能性があります。したがって、Windows Vista で動作するように開発されたオーディオアプリケーションの動作は、将来のバージョンの Windows で実行したときに変わる可能性があります。詳細については、Device Roles in Windows Vista を参照してください。

このメソッドは、指定されたデータフロー方向(レンダリングまたはキャプチャ)とロールに対する既定のエンドポイントデバイスを取得します。たとえば、クライアントは次の呼び出しを行うことで、既定のコンソール再生デバイスを取得できます。

  hr = pDevEnum->GetDefaultAudioEndpoint(
                   eRender, eConsole, &pDeviceOut);

上記のコードフラグメントでは、変数 hr は HRESULT 型、pDevEnum は IMMDeviceEnumerator インターフェイスへのポインター、pDeviceOut は IMMDevice インターフェイスへのポインターです。

Windows システムには、デスクトップスピーカー、高音質ヘッドホン、デスクトップマイク、スピーカーとマイク付きのヘッドセット、高音質マルチチャネルスピーカーなど、さまざまなオーディオエンドポイントデバイスの組み合わせが含まれる場合があります。ユーザーは、これらのデバイスに適切なロールを割り当てることができます。たとえば、音声通信ストリームを管理するアプリケーションは、GetDefaultAudioEndpoint を呼び出して、そのロールに指定されたレンダリングデバイスとキャプチャデバイスを識別できます。

レンダリングデバイスまたはキャプチャデバイスが 1 つしか使用できない場合、システムは常に 3 つのレンダリングロールまたはキャプチャロールすべてをそのデバイスに割り当てます。指定されたロールに対するレンダリングデバイスまたはキャプチャデバイスの検出にメソッドが失敗した場合、それはレンダリングデバイスまたはキャプチャデバイスがまったく使用できないことを意味します。使用可能なデバイスがない場合、メソッドは *ppEndpoint = NULL を設定し、ERROR_NOT_FOUND を返します。

GetDefaultAudioEndpoint メソッドを呼び出すコード例については、次のトピックを参照してください。

• Rendering a Stream
• Audio Events for Legacy Audio Applications

GetDevice メソッドは、エンドポイント ID 文字列で識別されるオーディオエンドポイントデバイスを取得します。

メソッドが成功した場合は S_OK を返します。失敗した場合、戻り値には次の表に示す値が含まれますが、これらに限定されません。

2 つのプログラムが 2 つの異なるプロセスで実行されており、両方が同じオーディオエンドポイントデバイスにアクセスする必要がある場合、一方のプログラムがデバイスの IMMDevice インターフェイスをもう一方のプログラムに単純に渡すことはできません。ただし、これらのプログラムは次の手順に従うことで同じデバイスにアクセスできます。

1. 最初のプログラムが最初のプロセスで IMMDevice::GetId メソッドを呼び出し、デバイスを識別するエンドポイント ID 文字列を取得します。
2. 最初のプログラムが、そのエンドポイント ID 文字列をプロセス境界を越えて 2 番目のプログラムに渡します。
3. 2 番目のプロセスでデバイスの IMMDevice インターフェイスへの参照を取得するために、2 番目のプログラムがエンドポイント ID 文字列を指定して GetDevice を呼び出します。

• Endpoint ID Strings
• Audio Events for Legacy Audio Applications

• Device Properties
• Device Events
• Using the IKsControl Interface to Access Audio Properties

RegisterEndpointNotificationCallback メソッドは、クライアントの通知コールバックインターフェイスを登録します。

メソッドが成功した場合は S_OK を返します。失敗した場合、戻り値には次の表に示す値が含まれますが、これらに限定されません。

このメソッドは、エンドポイントデバイスのロール、状態、存在、またはプロパティが変化したときにシステムから呼び出される IMMNotificationClient インターフェイスを登録します。呼び出し元は IMMNotificationClient インターフェイスを実装します。

通知が不要になったとき、クライアントは IMMDeviceEnumerator::UnregisterEndpointNotificationCallback メソッドを呼び出して通知を終了できます。

クライアントは、RegisterEndpointNotificationCallback の呼び出し後、かつ UnregisterEndpointNotificationCallback を呼び出す前に、IMMNotificationClient オブジェクトが解放されないようにする必要があります。これらのメソッドは、クライアントの IMMNotificationClient::AddRef および IMMNotificationClient::Release の実装を呼び出しません。クライアントは IMMNotificationClient オブジェクトの参照カウントを維持する責任があります。クライアントは、RegisterEndpointNotificationCallback の呼び出しが成功した場合はカウントをインクリメントし、UnregisterEndpointNotificationCallback を呼び出した後にのみ最後の参照を解放するか、または UnregisterEndpointNotificationCallback が呼び出される前にオブジェクトが削除されないようにするための何らかの別のメカニズムを実装する必要があります。そうしないと、アプリケーションは IMMNotificationClient および同じコンテナー内に実装されているその他のオブジェクトが保持するリソースをリークします。

AddRef および Release メソッドの詳細については、Windows SDK ドキュメントの IUnknown インターフェイスに関する説明を参照してください。

UnregisterEndpointNotificationCallback メソッドは、クライアントが以前に IMMDeviceEnumerator::RegisterEndpointNotificationCallback メソッドの呼び出しで登録した通知インターフェイスの登録を削除します。

メソッドが成功した場合は S_OK を返します。失敗した場合、戻り値には次の表に示す値が含まれますが、これらに限定されません。

クライアントは、RegisterEndpointNotificationCallback の呼び出し後、かつ UnregisterEndpointNotificationCallback を呼び出す前に、IMMNotificationClient オブジェクトが解放されないようにする必要があります。これらのメソッドは、クライアントの IMMNotificationClient::AddRef および IMMNotificationClient::Release の実装を呼び出しません。クライアントは IMMNotificationClient オブジェクトの参照カウントを維持する責任があります。クライアントは、RegisterEndpointNotificationCallback の呼び出しが成功した場合はカウントをインクリメントし、UnregisterEndpointNotificationCallback を呼び出した後にのみ最後の参照を解放するか、または UnregisterEndpointNotificationCallback が呼び出される前にオブジェクトが削除されないようにするための何らかの別のメカニズムを実装する必要があります。そうしないと、アプリケーションは IMMNotificationClient および同じコンテナー内に実装されているその他のオブジェクトが保持するリソースをリークします。

AddRef および Release メソッドの詳細については、Windows SDK ドキュメントの IUnknown インターフェイスに関する説明を参照してください。