IMMNotificationClient
COM公式ドキュメント
IMMNotificationClient インターフェイスは、オーディオエンドポイントデバイスが追加または削除されたとき、エンドポイントデバイスの状態やプロパティが変化したとき、またはエンドポイントデバイスに割り当てられている既定のロールに変更があったときに通知を提供します。
メソッド 5
vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。
OnDeviceStateChanged メソッドは、オーディオエンドポイントデバイスの状態が変化したことを示します。
| pwstrDeviceId | LPWSTR | in | オーディオエンドポイントデバイスを識別するエンドポイント ID 文字列へのポインター。このパラメーターは、エンドポイント ID を含む、null で終端されたワイド文字列を指します。この文字列は呼び出しの間有効です。 |
| dwNewState | DEVICE_STATE | in | エンドポイントデバイスの新しい状態を指定します。このパラメーターの値は、次の DEVICE_STATE_XXX 定数のいずれかです。 |
戻り値
メソッドが成功した場合は S_OK を返します。失敗した場合はエラーコードを返します。
解説(Remarks)
OnDeviceStateChanged メソッドを実装するコード例については、Device Events を参照してください。
OnDeviceAdded メソッドは、新しいオーディオエンドポイントデバイスが追加されたことを示します。
| pwstrDeviceId | LPWSTR | in | オーディオエンドポイントデバイスを識別するエンドポイント ID 文字列へのポインター。このパラメーターは、エンドポイント ID を含む、null で終端されたワイド文字列を指します。この文字列は呼び出しの間有効です。 |
戻り値
メソッドが成功した場合は S_OK を返します。失敗した場合はエラーコードを返します。
解説(Remarks)
OnDeviceAdded メソッドを実装するコード例については、Device Events を参照してください。
OnDeviceRemoved メソッドは、オーディオエンドポイントデバイスが削除されたことを示します。
| pwstrDeviceId | LPWSTR | in | オーディオエンドポイントデバイスを識別するエンドポイント ID 文字列へのポインター。このパラメーターは、エンドポイント ID を含む、null で終端されたワイド文字列を指します。この文字列は呼び出しの間有効です。 |
戻り値
メソッドが成功した場合は S_OK を返します。失敗した場合はエラーコードを返します。
解説(Remarks)
OnDeviceRemoved メソッドを実装するコード例については、Device Events を参照してください。
OnDefaultDeviceChanged メソッドは、特定のデバイスロールに対する既定のオーディオエンドポイントデバイスが変更されたことをクライアントに通知します。
| flow | EDataFlow | in | エンドポイントデバイスのデータフロー方向。このパラメーターには、次の EDataFlow 列挙値のいずれかが設定されます。 eRender eCapture レンダリングデバイスのデータフロー方向は eRender です。キャプチャデバイスのデータフロー方向は eCapture です。 |
| role | ERole | in | オーディオエンドポイントデバイスのデバイスロール。このパラメーターには、次の ERole 列挙値のいずれかが設定されます。 eConsole eMultimedia eCommunications |
| pwstrDefaultDeviceId | LPWSTR | inoptional | オーディオエンドポイントデバイスを識別するエンドポイント ID 文字列へのポインター。このパラメーターは、エンドポイント ID を含む、null で終端されたワイド文字列を指します。この文字列は呼び出しの間有効です。特定のロールに対する既定のデバイスがユーザーによって削除または無効化され、そのロールを引き継げる他のデバイスが存在しない場合、pwstrDefaultDevice は NULL になります。 |
戻り値
メソッドが成功した場合は S_OK を返します。失敗した場合はエラーコードを返します。
解説(Remarks)
3 つの入力パラメーターは、新しい既定のオーディオエンドポイントデバイスのデータフロー方向、デバイスロール、およびエンドポイント ID 文字列を指定します。
Windows Vista では、MMDevice API はデバイスロールをサポートしますが、システム提供のユーザーインターフェイスプログラムはサポートしません。Windows Vista のユーザーインターフェイスでは、ユーザーはレンダリング用の既定のオーディオデバイスとキャプチャ用の既定のオーディオデバイスを選択できます。ユーザーが既定のレンダリングデバイスまたはキャプチャデバイスを変更すると、システムは 3 つすべてのデバイスロール(eConsole、eMultimedia、eCommunications)を新しいデバイスに割り当てます。したがって、ユーザーが既定のレンダリングデバイスまたはキャプチャデバイスを変更すると、システムはクライアントの OnDefaultDeviceChanged メソッドを 3 回、つまり 3 つのデバイスロールごとに 1 回呼び出します。
将来のバージョンの Windows では、ユーザーインターフェイスによってユーザーが個々のロールを異なるデバイスに割り当てられるようになる可能性があります。その場合、ユーザーが新しいレンダリングデバイスまたはキャプチャデバイスに対して 1 つまたは 2 つのデバイスロールの割り当てのみを変更すると、システムはクライアントの OnDefaultDeviceChanged メソッドを 1 回または 2 回のみ(つまり、変更されたロールごとに 1 回)呼び出します。OnDefaultDeviceChanged メソッドがロールの変更にどのように応答するかによって、Windows Vista で動作するように開発されたオーディオアプリケーションの動作は、将来のバージョンの Windows で実行したときに変化する可能性があります。詳細については、Device Roles in Windows Vista を参照してください。
OnDefaultDeviceChanged メソッドを実装するコード例については、Device Events を参照してください。
OnPropertyValueChanged メソッドは、オーディオエンドポイントデバイスに属するプロパティの値が変化したことを示します。
| pwstrDeviceId | LPWSTR | in | オーディオエンドポイントデバイスを識別するエンドポイント ID 文字列へのポインター。このパラメーターは、エンドポイント ID を含む、null で終端されたワイド文字列を指します。この文字列は呼び出しの間有効です。 |
| key | PROPERTYKEY | in | プロパティを指定する PROPERTYKEY 構造体。この構造体には、プロパティセットの GUID と、そのセット内のプロパティを識別するインデックスが含まれます。この構造体は値渡しされます。この構造体は呼び出しの間有効です。PROPERTYKEY の詳細については、Windows SDK のドキュメントを参照してください。 |
戻り値
メソッドが成功した場合は S_OK を返します。失敗した場合はエラーコードを返します。
解説(Remarks)
オーディオエンドポイントデバイスのプロパティの値を正常に変更する IPropertyStore::SetValue メソッドの呼び出しは、OnPropertyValueChanged の呼び出しを生成します。IPropertyStore::SetValue の詳細については、Windows SDK のドキュメントを参照してください。
クライアントは key パラメーターを使用して新しいプロパティ値を取得できます。プロパティキーを使用してエンドポイントデバイスのプロパティストアからプロパティ値を取得するコード例については、Device Properties を参照してください。
OnPropertyValueChanged メソッドを実装するコード例については、Device Events を参照してください。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)
HSP用 COM定義
#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。
#define global IID_IMMNotificationClient "{7991EEC9-7E89-4D85-8390-6C703CEC60C0}"
#usecom global IMMNotificationClient IID_IMMNotificationClient "{}"
#comfunc global IMMNotificationClient_OnDeviceStateChanged 3 wstr,int
#comfunc global IMMNotificationClient_OnDeviceAdded 4 wstr
#comfunc global IMMNotificationClient_OnDeviceRemoved 5 wstr
#comfunc global IMMNotificationClient_OnDefaultDeviceChanged 6 int,int,wstr
#comfunc global IMMNotificationClient_OnPropertyValueChanged 7 wstr,int
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。