ホーム › Media.Audio › IChannelAudioVolume

IChannelAudioVolume

COM

📘 Microsoft Learn (日本語) · English

IID1c158861-b533-4b30-b1cf-e853e51c59b8継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

IChannelAudioVolume インターフェイスを使用すると、クライアントはストリームが属するオーディオセッション内のすべてのチャネルの音量レベルを制御および監視できます。

メソッド 5

vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。

vtbl 3 HRESULT GetChannelCount(DWORD* pdwCount)

GetChannelCount メソッドは、オーディオセッションのストリーム形式に含まれるチャネル数を取得します。

pdwCount

DWORD*

out

メソッドがチャネル数を書き込む UINT32 変数へのポインター。

戻り値

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

戻り値	説明
E_POINTER	パラメーター pdwCount が NULL です。
AUDCLNT_E_DEVICE_INVALIDATED	オーディオエンドポイントデバイスが取り外されたか、オーディオハードウェアまたは関連するハードウェアリソースが再構成、無効化、削除、またはその他の理由で使用できなくなりました。
AUDCLNT_E_SERVICE_NOT_RUNNING	Windows オーディオサービスが実行されていません。

解説(Remarks)

IChannelAudioVolume インターフェイスの他のメソッドを呼び出す前に、このメソッドを呼び出してオーディオセッション内のチャネル数を取得してください。

vtbl 4 HRESULT SetChannelVolume(DWORD dwIndex, FLOAT fLevel, GUID* EventContext)

SetChannelVolume メソッドは、オーディオセッション内の指定されたチャネルの音量レベルを設定します。

dwIndex	DWORD	in	チャネル番号。オーディオセッションのストリーム形式に N 個のチャネルがある場合、チャネルは 0 から N– 1 までの番号が付けられます。チャネル数を取得するには、IChannelAudioVolume::GetChannelCount メソッドを呼び出します。
fLevel	FLOAT	in	チャネルの音量レベル。有効な音量レベルの範囲は 0.0 から 1.0 です。
EventContext	GUID*	in	イベントコンテキスト GUID へのポインター。このメソッドの呼び出しによってチャネル音量変更イベントが生成される場合、セッションマネージャーは、IAudioSessionEvents インターフェイスをセッションマネージャーに登録したすべてのクライアントに通知を送信します。セッションマネージャーは、各通知に EventContext ポインター値を含めます。通知を受信すると、クライアントは EventContext 値を検査することで、自身または別のクライアントがイベントの発生元であるかどうかを判断できます。この仕組みは、クライアントがセッション内のすべてのクライアントの中で一意となる値をこのパラメーターに選択することに依存します。呼び出し元がこのパラメーターに NULL ポインターを指定した場合、クライアントの通知メソッドは NULL コンテキストポインターを受け取ります。

戻り値

戻り値	説明
E_INVALIDARG	パラメーター dwIndex に無効なチャネル番号が設定されているか、パラメーター fLevel が 0.0 から 1.0 の範囲にありません。
AUDCLNT_E_DEVICE_INVALIDATED	オーディオエンドポイントデバイスが取り外されたか、オーディオハードウェアまたは関連するハードウェアリソースが再構成、無効化、削除、またはその他の理由で使用できなくなりました。
AUDCLNT_E_SERVICE_NOT_RUNNING	Windows オーディオサービスが実行されていません。

解説(Remarks)

このメソッドは成功した場合、新しいチャネル音量レベルが以前のチャネル音量レベルと値が異なるかどうかにかかわらず、チャネル音量変更イベントを生成します。

vtbl 5 HRESULT GetChannelVolume(DWORD dwIndex, FLOAT* pfLevel)

GetChannelVolume メソッドは、オーディオセッション内の指定されたチャネルの音量レベルを取得します。

dwIndex	DWORD	in	チャネル番号。オーディオセッションのストリーム形式に N 個のチャネルがある場合、チャネルは 0 から N– 1 までの番号が付けられます。チャネル数を取得するには、IChannelAudioVolume::GetChannelCount メソッドを呼び出します。
pfLevel	FLOAT*	out	メソッドが指定されたチャネルの音量レベルを書き込む float 変数へのポインター。音量レベルの範囲は 0.0 から 1.0 です。

戻り値

戻り値	説明
E_INVALIDARG	パラメーター dwIndex に無効なチャネル番号が設定されています。
E_POINTER	パラメーター pfLevel が NULL です。
AUDCLNT_E_DEVICE_INVALIDATED	オーディオエンドポイントデバイスが取り外されたか、オーディオハードウェアまたは関連するハードウェアリソースが再構成、無効化、削除、またはその他の理由で使用できなくなりました。
AUDCLNT_E_SERVICE_NOT_RUNNING	Windows オーディオサービスが実行されていません。

解説(Remarks)

クライアントは、IChannelAudioVolume::SetAllVolumes メソッドまたは IChannelAudioVolume::SetChannelVolume メソッドを呼び出して、オーディオセッション内のチャネルごとの音量レベルを設定できます。

vtbl 6 HRESULT SetAllVolumes(DWORD dwCount, FLOAT* pfVolumes, GUID* EventContext)

SetAllVolumes メソッドは、オーディオセッション内のすべてのチャネルの個別の音量レベルを設定します。

dwCount	DWORD	in	pfVolumes 配列の要素数。このパラメーターは、オーディオセッションのストリーム形式のチャネル数と等しくなければなりません。チャネル数を取得するには、IChannelAudioVolume::GetChannelCount メソッドを呼び出します。
pfVolumes	FLOAT*	in	オーディオセッション内のチャネルの音量レベルの配列へのポインター。pfVolumes 配列の要素数は dwCount パラメーターで指定します。呼び出し元は、各チャネルの音量レベルを、チャネル番号に一致するインデックスの配列要素に書き込みます。オーディオセッションのストリーム形式に N 個のチャネルがある場合、チャネルは 0 から N– 1 までの番号が付けられます。有効な音量レベルの範囲は 0.0 から 1.0 です。
EventContext	GUID*	in	イベントコンテキスト GUID へのポインター。このメソッドの呼び出しによってチャネル音量変更イベントが生成される場合、セッションマネージャーは、IAudioSessionEvents インターフェイスをセッションマネージャーに登録したすべてのクライアントに通知を送信します。セッションマネージャーは、各通知に EventContext ポインター値を含めます。通知を受信すると、クライアントは EventContext 値を検査することで、自身または別のクライアントがイベントの発生元であるかどうかを判断できます。この仕組みは、クライアントがセッション内のすべてのクライアントの中で一意となる値をこのパラメーターに選択することに依存します。呼び出し元がこのパラメーターに NULL ポインターを指定した場合、クライアントの通知メソッドは NULL コンテキストポインターを受け取ります。

戻り値

戻り値	説明
E_INVALIDARG	パラメーター dwCount がオーディオセッションのストリーム形式のチャネル数と等しくないか、pfVolumes 配列要素の値が 0.0 から 1.0 の範囲にありません。
E_POINTER	パラメーター pfVolumes が NULL です。
AUDCLNT_E_DEVICE_INVALIDATED	オーディオエンドポイントデバイスが取り外されたか、オーディオハードウェアまたは関連するハードウェアリソースが再構成、無効化、削除、またはその他の理由で使用できなくなりました。
AUDCLNT_E_SERVICE_NOT_RUNNING	Windows オーディオサービスが実行されていません。

解説(Remarks)

このメソッドは成功した場合、新しいチャネル音量レベルのいずれかが以前のチャネル音量レベルと値が異なるかどうかにかかわらず、チャネル音量変更イベントを生成します。

vtbl 7 HRESULT GetAllVolumes(DWORD dwCount, FLOAT* pfVolumes)

GetAllVolumes メソッドは、オーディオセッション内のすべてのチャネルの音量レベルを取得します。

dwCount	DWORD	in	pfVolumes 配列の要素数。dwCount パラメーターは、オーディオセッションのストリーム形式のチャネル数と等しくなければなりません。チャネル数を取得するには、IChannelAudioVolume::GetChannelCount メソッドを呼び出します。
pfVolumes	FLOAT*	out	オーディオセッション内のチャネルの音量レベルの配列へのポインター。このパラメーターは、メソッドが各チャネルの音量レベルを書き込む呼び出し元が割り当てた float 配列を指します。音量レベルの範囲は 0.0 から 1.0 です。

戻り値

戻り値	説明
E_INVALIDARG	パラメーター dwCount がオーディオセッションのストリーム形式のチャネル数と等しくありません。
E_POINTER	パラメーター pfVolumes が NULL です。
AUDCLNT_E_DEVICE_INVALIDATED	オーディオエンドポイントデバイスが取り外されたか、オーディオハードウェアまたは関連するハードウェアリソースが再構成、無効化、削除、またはその他の理由で使用できなくなりました。
AUDCLNT_E_SERVICE_NOT_RUNNING	Windows オーディオサービスが実行されていません。

解説(Remarks)

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

HSP用 COM定義

#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。

出力引数:

#define global IID_IChannelAudioVolume "{1C158861-B533-4B30-B1CF-E853E51C59B8}"
#usecom global IChannelAudioVolume IID_IChannelAudioVolume "{}"
#comfunc global IChannelAudioVolume_GetChannelCount   3 var
#comfunc global IChannelAudioVolume_SetChannelVolume  4 int,float,var
#comfunc global IChannelAudioVolume_GetChannelVolume  5 int,var
#comfunc global IChannelAudioVolume_SetAllVolumes     6 int,var,var
#comfunc global IChannelAudioVolume_GetAllVolumes     7 int,var
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。#define global IID_IChannelAudioVolume "{1C158861-B533-4B30-B1CF-E853E51C59B8}"
#usecom global IChannelAudioVolume IID_IChannelAudioVolume "{}"
#comfunc global IChannelAudioVolume_GetChannelCount   3 sptr
#comfunc global IChannelAudioVolume_SetChannelVolume  4 int,float,sptr
#comfunc global IChannelAudioVolume_GetChannelVolume  5 int,sptr
#comfunc global IChannelAudioVolume_SetAllVolumes     6 int,sptr,sptr
#comfunc global IChannelAudioVolume_GetAllVolumes     7 int,sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。