ISimpleAudioVolume
COM公式ドキュメント
ISimpleAudioVolume インターフェースは、クライアントがオーディオセッションのマスター音量レベルを制御できるようにします。
メソッド 4
vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。
SetMasterVolume メソッドは、オーディオセッションのマスター音量レベルを設定します。
| fLevel | FLOAT | in | 新しいマスター音量レベル。有効な音量レベルは 0.0 から 1.0 の範囲です。 |
| EventContext | GUID* | in | イベントコンテキスト GUID へのポインター。このメソッドの呼び出しによって音量変更イベントが生成された場合、セッションマネージャーは、セッションマネージャーに IAudioSessionEvents インターフェースを登録しているすべてのクライアントに通知を送信します。セッションマネージャーは、各通知に EventContext ポインターの値を含めます。通知を受け取ったクライアントは、EventContext の値を調べることで、そのイベントの発生元が自身であるか他のクライアントであるかを判別できます。この仕組みは、クライアントがセッション内のすべてのクライアントの間で一意となる値をこのパラメーターに選択することに依存します。呼び出し元がこのパラメーターに NULL ポインターを指定した場合、クライアントの通知メソッドは NULL のコンテキストポインターを受け取ります。 |
戻り値
メソッドが成功した場合は S_OK を返します。失敗した場合の戻り値には、以下の表に示す値が含まれますが、これらに限定されません。
| Return code | Description |
|---|---|
| パラメーター fLevel が 0.0 から 1.0 の範囲にありません。 | |
| オーディオエンドポイントデバイスが取り外されたか、オーディオハードウェアまたは関連するハードウェアリソースが再構成、無効化、削除、その他の理由で使用できなくなりました。 | |
| Windows オーディオサービスが実行されていません。 |
解説(Remarks)
このメソッドは、呼び出しによってセッションの音量レベルが変化した場合にのみ音量変更イベントを生成します。たとえば、呼び出し時の音量レベルが 0.4 で、呼び出しによって音量レベルを 0.4 に設定した場合、イベントは生成されません。
GetMasterVolume メソッドは、オーディオセッションのクライアント音量レベルを取得します。
| pfLevel | FLOAT* | out | メソッドがクライアント音量レベルを書き込む float 変数へのポインター。音量レベルは 0.0 から 1.0 の範囲の値です。 |
戻り値
メソッドが成功した場合は S_OK を返します。失敗した場合の戻り値には、以下の表に示す値が含まれますが、これらに限定されません。
| Return code | Description |
|---|---|
| パラメーター pfLevel が NULL です。 | |
| オーディオエンドポイントデバイスが取り外されたか、オーディオハードウェアまたは関連するハードウェアリソースが再構成、無効化、削除、その他の理由で使用できなくなりました。 | |
| Windows オーディオサービスが実行されていません。 |
解説(Remarks)
このメソッドは、セッションのクライアント音量レベルを取得します。これは、クライアントが以前の ISimpleAudioVolume::SetMasterVolume メソッドの呼び出しで設定した音量レベルです。
SetMute メソッドは、オーディオセッションのミュート状態を設定します。
| bMute | BOOL | in | 新しいミュート状態。TRUE はミュートを有効にします。FALSE はミュートを無効にします。 |
| EventContext | GUID* | in | イベントコンテキスト GUID へのポインター。このメソッドの呼び出しによって音量変更イベントが生成された場合、セッションマネージャーは、セッションマネージャーに IAudioSessionEvents インターフェースを登録しているすべてのクライアントに通知を送信します。セッションマネージャーは、各通知に EventContext ポインターの値を含めます。通知を受け取ったクライアントは、EventContext の値を調べることで、そのイベントの発生元が自身であるか他のクライアントであるかを判別できます。この仕組みは、クライアントがセッション内のすべてのクライアントの間で一意となる値をこのパラメーターに選択することに依存します。呼び出し元がこのパラメーターに NULL ポインターを指定した場合、クライアントの通知メソッドは NULL のコンテキストポインターを受け取ります。 |
戻り値
メソッドが成功した場合は S_OK を返します。失敗した場合の戻り値には、以下の表に示す値が含まれますが、これらに限定されません。
| Return code | Description |
|---|---|
| オーディオエンドポイントデバイスが取り外されたか、オーディオハードウェアまたは関連するハードウェアリソースが再構成、無効化、削除、その他の理由で使用できなくなりました。 | |
| Windows オーディオサービスが実行されていません。 |
解説(Remarks)
このメソッドは、呼び出しによってセッションのミュート状態が無効から有効へ、または有効から無効へ変化した場合にのみ音量変更イベントを生成します。たとえば、呼び出し時にミュートが有効で、呼び出しによってミュートを有効にした場合、イベントは生成されません。
このメソッドは、オーディオセッション内のすべてのチャネルに同じミュート状態を適用します。エンドポイントデバイスは、常にセッション内のすべてのチャネルに対して均一にミュートを適用します。個々のチャネルのミュート状態を設定するための IChannelAudioVolume メソッドは存在しません。
クライアントは、SimpleAudioVolume::GetMute メソッドを呼び出すことで、オーディオセッションのミュート状態を取得できます。
GetMute メソッドは、オーディオセッションの現在のミュート状態を取得します。
| pbMute | BOOL* | out | メソッドがミュート状態を書き込む BOOL 変数へのポインター。TRUE はミュートが有効であることを示します。FALSE はミュートが無効であることを示します。 |
戻り値
メソッドが成功した場合は S_OK を返します。失敗した場合の戻り値には、以下の表に示す値が含まれますが、これらに限定されません。
| Return code | Description |
|---|---|
| パラメーター pbMute が NULL です。 | |
| オーディオエンドポイントデバイスが取り外されたか、オーディオハードウェアまたは関連するハードウェアリソースが再構成、無効化、削除、その他の理由で使用できなくなりました。 | |
| Windows オーディオサービスが実行されていません。 |
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)
HSP用 COM定義
#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。
#define global IID_ISimpleAudioVolume "{87CE5498-68D6-44E5-9215-6DA47EF883D8}" #usecom global ISimpleAudioVolume IID_ISimpleAudioVolume "{}" #comfunc global ISimpleAudioVolume_SetMasterVolume 3 float,var #comfunc global ISimpleAudioVolume_GetMasterVolume 4 var #comfunc global ISimpleAudioVolume_SetMute 5 int,var #comfunc global ISimpleAudioVolume_GetMute 6 var ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。#define global IID_ISimpleAudioVolume "{87CE5498-68D6-44E5-9215-6DA47EF883D8}" #usecom global ISimpleAudioVolume IID_ISimpleAudioVolume "{}" #comfunc global ISimpleAudioVolume_SetMasterVolume 3 float,sptr #comfunc global ISimpleAudioVolume_GetMasterVolume 4 sptr #comfunc global ISimpleAudioVolume_SetMute 5 int,sptr #comfunc global ISimpleAudioVolume_GetMute 6 sptr ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。