IAudioEndpointVolume
COM公式ドキュメント
IAudioEndpointVolume インターフェースは、オーディオエンドポイントデバイスとの間で入出力されるオーディオストリームの音量コントロールを表します。
メソッド 18
vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。
RegisterControlChangeNotify メソッドは、クライアントの通知コールバックインターフェースを登録します。
| pNotify | IAudioEndpointVolumeCallback* | in | クライアントが通知コールバック用に登録する IAudioEndpointVolumeCallback インターフェースへのポインター。RegisterControlChangeNotify メソッドが成功すると、クライアントの IAudioEndpointVolumeCallback インターフェースの AddRef メソッドが呼び出されます。 |
戻り値
メソッドが成功した場合は S_OK を返します。失敗した場合、返される可能性のあるリターンコードには、次の表に示す値が含まれますが、これらに限定されません。
| リターンコード | 説明 |
|---|---|
| パラメーター pNotify が NULL です。 |
解説(Remarks)
このメソッドは、エンドポイントの音量レベルまたはミュート状態が変化したときにシステムから呼び出される IAudioEndpointVolumeCallback インターフェースを登録します。IAudioEndpointVolumeCallback インターフェースは呼び出し側が実装します。
通知が不要になった場合、クライアントは IAudioEndpointVolume::UnregisterControlChangeNotify メソッドを呼び出して通知を終了できます。
クライアントは、IAudioEndpointVolumeCallback インターフェースへの最後の参照を解放する前に、UnregisterControlChangeNotify を呼び出してインターフェースの登録を解除する必要があります。そうしないと、アプリケーションは IAudioEndpointVolumeCallback オブジェクトおよび IAudioEndpointVolume オブジェクトが保持しているリソースをリークします。RegisterControlChangeNotify はクライアントの IAudioEndpointVolumeCallback::AddRef メソッドを呼び出し、UnregisterControlChangeNotify は IAudioEndpointVolumeCallback::Release メソッドを呼び出す点に注意してください。クライアントが誤って UnregisterControlChangeNotify を呼び出す前に IAudioEndpointVolumeCallback インターフェースへの参照を解放してしまうと、IAudioEndpointVolume オブジェクトは IAudioEndpointVolumeCallback インターフェースへの参照を決して解放しません。たとえば、設計の不適切な IAudioEndpointVolumeCallback 実装では、IAudioEndpointVolumeCallback オブジェクトのデストラクターから UnregisterControlChangeNotify を呼び出すことがあります。この場合、クライアントは IAudioEndpointVolume オブジェクトが IAudioEndpointVolumeCallback インターフェースへの参照を解放するまで UnregisterControlChangeNotify を呼び出さず、IAudioEndpointVolume オブジェクトはクライアントが UnregisterControlChangeNotify を呼び出すまで IAudioEndpointVolumeCallback インターフェースへの参照を解放しません。AddRef および Release メソッドの詳細については、Windows SDK ドキュメントの IUnknown インターフェースの説明を参照してください。
さらに、クライアントは IAudioEndpointVolume オブジェクトへの最後の参照を解放する前に UnregisterControlChangeNotify を呼び出す必要があります。そうしないと、オブジェクトは登録情報を保持するために割り当てたストレージをリークします。通知インターフェースの登録後、クライアントは IAudioEndpointVolume オブジェクトが存在する間に限り通知を受け取り続けます。
RegisterControlChangeNotify を呼び出すコード例については、Endpoint Volume Controls を参照してください。
UnregisterControlChangeNotify メソッドは、以前の IAudioEndpointVolume::RegisterControlChangeNotify メソッドの呼び出しで登録したクライアントの通知コールバックインターフェースの登録を削除します。
| pNotify | IAudioEndpointVolumeCallback* | in | クライアントの IAudioEndpointVolumeCallback インターフェースへのポインター。クライアントは、以前の IAudioEndpointVolume::RegisterControlChangeNotify メソッドの呼び出しで、これと同じインターフェースポインターをエンドポイントボリュームオブジェクトに渡しています。UnregisterControlChangeNotify メソッドが成功すると、クライアントの IAudioEndpointVolumeCallback インターフェースの Release メソッドが呼び出されます。 |
戻り値
メソッドが成功した場合は S_OK を返します。失敗した場合、返される可能性のあるリターンコードには、次の表に示す値が含まれますが、これらに限定されません。
| リターンコード | 説明 |
|---|---|
| パラメーター pNotify が NULL です。 |
解説(Remarks)
クライアントは、IAudioEndpointVolumeCallback インターフェースへの最後の参照を解放する前に、UnregisterControlChangeNotify を呼び出してインターフェースの登録を解除する必要があります。そうしないと、アプリケーションは IAudioEndpointVolumeCallback オブジェクトおよび IAudioEndpointVolume オブジェクトが保持しているリソースをリークします。IAudioEndpointVolume::RegisterControlChangeNotify メソッドはクライアントの IAudioEndpointVolumeCallback::AddRef メソッドを呼び出し、UnregisterControlChangeNotify は IAudioEndpointVolumeCallback::Release メソッドを呼び出す点に注意してください。クライアントが誤って UnregisterControlChangeNotify を呼び出す前に IAudioEndpointVolumeCallback インターフェースへの参照を解放してしまうと、IAudioEndpointVolume オブジェクトは IAudioEndpointVolumeCallback インターフェースへの参照を決して解放しません。たとえば、設計の不適切な IAudioEndpointVolumeCallback 実装では、IAudioEndpointVolumeCallback オブジェクトのデストラクターから UnregisterControlChangeNotify を呼び出すことがあります。この場合、クライアントは IAudioEndpointVolume オブジェクトが IAudioEndpointVolumeCallback インターフェースへの参照を解放するまで UnregisterControlChangeNotify を呼び出さず、IAudioEndpointVolume オブジェクトはクライアントが UnregisterControlChangeNotify を呼び出すまで IAudioEndpointVolumeCallback インターフェースへの参照を解放しません。AddRef および Release メソッドの詳細については、Windows SDK ドキュメントの IUnknown インターフェースの説明を参照してください。
UnregisterControlChangeNotify を呼び出すコード例については、Endpoint Volume Controls を参照してください。
GetChannelCount メソッドは、オーディオエンドポイントデバイスに入出力されるオーディオストリームのチャネル数を取得します。
| pnChannelCount | DWORD* | out | メソッドがチャネル数を書き込む UINT 変数へのポインター。 |
戻り値
メソッドが成功した場合は S_OK を返します。失敗した場合、返される可能性のあるリターンコードには、次の表に示す値が含まれますが、これらに限定されません。
| リターンコード | 説明 |
|---|---|
| パラメーター pnChannelCount が NULL です。 |
SetMasterVolumeLevel メソッドは、オーディオエンドポイントデバイスに入出力されるオーディオストリームのマスター音量レベルをデシベル単位で設定します。
| fLevelDB | FLOAT | in | 新しいマスター音量レベル(デシベル単位)。このメソッドで設定できる音量レベルの範囲と粒度を取得するには、IAudioEndpointVolume::GetVolumeRange メソッドを呼び出します。 |
| pguidEventContext | GUID* | in | IAudioEndpointVolumeCallback::OnNotify メソッドのコンテキスト値。このパラメーターはイベントコンテキスト GUID を指します。SetMasterVolumeLevel の呼び出しによってエンドポイントの音量レベルが変更されると、そのエンドポイントに IAudioEndpointVolumeCallback インターフェースを登録しているすべてのクライアントに通知が送られます。クライアントは OnNotify メソッドの実装内でイベントコンテキスト GUID を調べることで、音量変更イベントの発生源が自分自身か他のクライアントかを判別できます。呼び出し側がこのパラメーターに NULL ポインターを指定した場合、通知ルーチンはコンテキスト GUID 値 GUID_NULL を受け取ります。 |
戻り値
メソッドが成功した場合は S_OK を返します。失敗した場合、返される可能性のあるリターンコードには、次の表に示す値が含まれますが、これらに限定されません。
| リターンコード | 説明 |
|---|---|
| パラメーター fLevelDB がデバイスでサポートされる音量範囲の外にあります。 | |
| メモリ不足です。 |
解説(Remarks)
音量レベル fLevelDB が IAudioEndpointVolume::GetVolumeRange メソッドによって報告される音量範囲の外にある場合、SetMasterVolumeLevel の呼び出しは失敗し、エラーコード E_INVALIDARG を返します。
SetMasterVolumeLevelScalar メソッドは、オーディオエンドポイントデバイスに入出力されるオーディオストリームのマスター音量レベルを設定します。音量レベルは、0.0 ～ 1.0 の範囲の正規化されたオーディオテーパー値で表されます。
| fLevel | FLOAT | in | 新しいマスター音量レベル。レベルは 0.0 ～ 1.0 の範囲の正規化された値で表されます。 |
| pguidEventContext | GUID* | in | IAudioEndpointVolumeCallback::OnNotify メソッドのコンテキスト値。このパラメーターはイベントコンテキスト GUID を指します。SetMasterVolumeLevelScalar の呼び出しによってエンドポイントの音量レベルが変更されると、そのエンドポイントに IAudioEndpointVolumeCallback インターフェースを登録しているすべてのクライアントに通知が送られます。クライアントは OnNotify メソッドの実装内でイベントコンテキスト GUID を調べることで、音量変更イベントの発生源が自分自身か他のクライアントかを判別できます。呼び出し側がこのパラメーターに NULL ポインターを指定した場合、通知ルーチンはコンテキスト GUID 値 GUID_NULL を受け取ります。 |
戻り値
メソッドが成功した場合は S_OK を返します。失敗した場合、返される可能性のあるリターンコードには、次の表に示す値が含まれますが、これらに限定されません。
| リターンコード | 説明 |
|---|---|
| パラメーター fLevel が 0.0 ～ 1.0 の範囲外です。 | |
| メモリ不足です。 |
解説(Remarks)
音量レベルは 0.0 ～ 1.0 の範囲に正規化されており、0.0 が最小音量レベル、1.0 が最大レベルです。この範囲内では、正規化された音量レベルと信号振幅の減衰との関係は、非線形のオーディオテーパーカーブで表されます。このカーブの形状は将来のバージョンの Windows で変更される可能性があることに注意してください。オーディオテーパーカーブの詳細については、Audio-Tapered Volume Controls を参照してください。
このメソッドに渡される正規化された音量レベルは、アプリケーションウィンドウやオンスクリーンディスプレイにおける音量コントロールの位置を表すのに適しています。
SetMasterVolumeLevelScalar を呼び出すコード例については、Endpoint Volume Controls を参照してください。
GetMasterVolumeLevel メソッドは、オーディオエンドポイントデバイスに入出力されるオーディオストリームのマスター音量レベルをデシベル単位で取得します。
| pfLevelDB | FLOAT* | out | マスター音量レベルへのポインター。このパラメーターは、メソッドが音量レベルをデシベル単位で書き込む float 変数を指します。このメソッドで取得される音量レベルの範囲を取得するには、IAudioEndpointVolume::GetVolumeRange メソッドを呼び出します。 |
戻り値
メソッドが成功した場合は S_OK を返します。失敗した場合、返される可能性のあるリターンコードには、次の表に示す値が含まれますが、これらに限定されません。
| リターンコード | 説明 |
|---|---|
| パラメーター pfLevelDB が NULL です。 |
GetMasterVolumeLevelScalar メソッドは、オーディオエンドポイントデバイスに入出力されるオーディオストリームのマスター音量レベルを取得します。音量レベルは、0.0 ～ 1.0 の範囲の正規化されたオーディオテーパー値で表されます。
| pfLevel | FLOAT* | out | マスター音量レベルへのポインター。このパラメーターは、メソッドが音量レベルを書き込む float 変数を指します。レベルは 0.0 ～ 1.0 の範囲の正規化された値で表されます。 |
戻り値
メソッドが成功した場合は S_OK を返します。失敗した場合、返される可能性のあるリターンコードには、次の表に示す値が含まれますが、これらに限定されません。
| リターンコード | 説明 |
|---|---|
| パラメーター pfLevel が NULL です。 |
解説(Remarks)
音量レベルは 0.0 ～ 1.0 の範囲に正規化されており、0.0 が最小音量レベル、1.0 が最大レベルです。この範囲内では、正規化された音量レベルと信号振幅の減衰との関係は、非線形のオーディオテーパーカーブで表されます。このカーブの形状は将来のバージョンの Windows で変更される可能性があることに注意してください。オーディオテーパーカーブの詳細については、Audio-Tapered Volume Controls を参照してください。
このメソッドで取得される正規化された音量レベルは、アプリケーションウィンドウやオンスクリーンディスプレイにおける音量コントロールの位置を表すのに適しています。
GetMasterVolumeLevelScalar を呼び出すコード例については、Endpoint Volume Controls を参照してください。
SetChannelVolumeLevel メソッドは、オーディオエンドポイントデバイスに入出力されるオーディオストリームの指定したチャネルの音量レベルをデシベル単位で設定します。
| nChannel | DWORD | in | チャネル番号。オーディオストリームに n 個のチャネルが含まれる場合、チャネルには 0 から n– 1 の番号が付けられます。チャネル数を取得するには、IAudioEndpointVolume::GetChannelCount メソッドを呼び出します。 |
| fLevelDB | FLOAT | in | 新しい音量レベル(デシベル単位)。このメソッドで設定できる音量レベルの範囲と粒度を取得するには、IAudioEndpointVolume::GetVolumeRange メソッドを呼び出します。 |
| pguidEventContext | GUID* | in | IAudioEndpointVolumeCallback::OnNotify メソッドのコンテキスト値。このパラメーターはイベントコンテキスト GUID を指します。SetChannelVolumeLevel の呼び出しによってエンドポイントの音量レベルが変更されると、そのエンドポイントに IAudioEndpointVolumeCallback インターフェースを登録しているすべてのクライアントに通知が送られます。クライアントは OnNotify メソッドの実装内でイベントコンテキスト GUID を調べることで、音量変更イベントの発生源が自分自身か他のクライアントかを判別できます。呼び出し側がこのパラメーターに NULL ポインターを指定した場合、通知ルーチンはコンテキスト GUID 値 GUID_NULL を受け取ります。 |
戻り値
メソッドが成功した場合は S_OK を返します。失敗した場合、返される可能性のあるリターンコードには、次の表に示す値が含まれますが、これらに限定されません。
| リターンコード | 説明 |
|---|---|
| パラメーター nChannel がストリームのチャネル数以上であるか、パラメーター fLevelDB がデバイスでサポートされる音量範囲の外にあります。 | |
| メモリ不足です。 |
解説(Remarks)
音量レベル fLevelDB が IAudioEndpointVolume::GetVolumeRange メソッドによって報告される音量範囲の外にある場合、SetChannelVolumeLevel の呼び出しは失敗し、エラーコード E_INVALIDARG を返します。
SetChannelVolumeLevelScalar メソッドは、オーディオエンドポイントデバイスに入出力されるオーディオストリームの指定したチャネルの、正規化されたオーディオテーパー音量レベルを設定します。
| nChannel | DWORD | in | チャネル番号。オーディオストリームに n 個のチャネルが含まれる場合、チャネルには 0 から n– 1 の番号が付けられます。チャネル数を取得するには、IAudioEndpointVolume::GetChannelCount メソッドを呼び出します。 |
| fLevel | FLOAT | in | 音量レベル。音量レベルは 0.0 ～ 1.0 の範囲の正規化された値で表されます。 |
| pguidEventContext | GUID* | in | IAudioEndpointVolumeCallback::OnNotify メソッドのコンテキスト値。このパラメーターはイベントコンテキスト GUID を指します。SetChannelVolumeLevelScalar の呼び出しによってエンドポイントの音量レベルが変更されると、そのエンドポイントに IAudioEndpointVolumeCallback インターフェースを登録しているすべてのクライアントに通知が送られます。クライアントは OnNotify メソッドの実装内でイベントコンテキスト GUID を調べることで、音量変更イベントの発生源が自分自身か他のクライアントかを判別できます。呼び出し側がこのパラメーターに NULL ポインターを指定した場合、通知ルーチンはコンテキスト GUID 値 GUID_NULL を受け取ります。 |
戻り値
メソッドが成功した場合は S_OK を返します。失敗した場合、返される可能性のあるリターンコードには、次の表に示す値が含まれますが、これらに限定されません。
| リターンコード | 説明 |
|---|---|
| パラメーター nChannel がストリームのチャネル数以上であるか、パラメーター fLevel が 0.0 ～ 1.0 の範囲外です。 | |
| メモリ不足です。 |
解説(Remarks)
音量レベルは 0.0 ～ 1.0 の範囲に正規化されており、0.0 が最小音量レベル、1.0 が最大レベルです。この範囲内では、正規化された音量レベルと信号振幅の減衰との関係は、非線形のオーディオテーパーカーブで表されます。このカーブの形状は将来のバージョンの Windows で変更される可能性があることに注意してください。オーディオテーパーカーブの詳細については、Audio-Tapered Volume Controls を参照してください。
このメソッドに渡される正規化された音量レベルは、アプリケーションウィンドウやオンスクリーンディスプレイにおける音量コントロールの位置を表すのに適しています。
GetChannelVolumeLevel メソッドは、オーディオエンドポイントデバイスに入出力されるオーディオストリームの指定したチャネルの音量レベルをデシベル単位で取得します。
| nChannel | DWORD | in | チャネル番号。オーディオストリームに n 個のチャネルがある場合、チャネルには 0 から n– 1 の番号が付けられます。ストリームのチャネル数を取得するには、IAudioEndpointVolume::GetChannelCount メソッドを呼び出します。 |
| pfLevelDB | FLOAT* | out | メソッドが音量レベルをデシベル単位で書き込む float 変数へのポインター。このメソッドで取得される音量レベルの範囲を取得するには、IAudioEndpointVolume::GetVolumeRange メソッドを呼び出します。 |
戻り値
メソッドが成功した場合は S_OK を返します。失敗した場合、返される可能性のあるリターンコードには、次の表に示す値が含まれますが、これらに限定されません。
| リターンコード | 説明 |
|---|---|
| パラメーター nChannel がストリームのチャネル数以上です。 | |
| パラメーター pfLevelDB が NULL です。 |
GetChannelVolumeLevelScalar メソッドは、オーディオエンドポイントデバイスに入出力されるオーディオストリームの指定したチャネルの、正規化されたオーディオテーパー音量レベルを取得します。
| nChannel | DWORD | in | チャネル番号。オーディオストリームに n 個のチャネルが含まれる場合、チャネルには 0 から n– 1 の番号が付けられます。チャネル数を取得するには、IAudioEndpointVolume::GetChannelCount メソッドを呼び出します。 |
| pfLevel | FLOAT* | out | メソッドが音量レベルを書き込む float 変数へのポインター。レベルは 0.0 ～ 1.0 の範囲の正規化された値で表されます。 |
戻り値
メソッドが成功した場合は S_OK を返します。失敗した場合、返される可能性のあるリターンコードには、次の表に示す値が含まれますが、これらに限定されません。
| リターンコード | 説明 |
|---|---|
| パラメーター nChannel がストリームのチャネル数以上です。 | |
| パラメーター pfLevel が NULL です。 |
解説(Remarks)
音量レベルは 0.0 ～ 1.0 の範囲に正規化されており、0.0 が最小音量レベル、1.0 が最大レベルです。この範囲内では、正規化された音量レベルと信号振幅の減衰との関係は、非線形のオーディオテーパーカーブで表されます。このカーブの形状は将来のバージョンの Windows で変更される可能性があることに注意してください。オーディオテーパーカーブの詳細については、Audio-Tapered Volume Controls を参照してください。
このメソッドで取得される正規化された音量レベルは、アプリケーションウィンドウやオンスクリーンディスプレイにおける音量コントロールの位置を表すのに適しています。
SetMute メソッドは、オーディオエンドポイントデバイスに入出力されるオーディオストリームのミュート状態を設定します。
| bMute | BOOL | in | 新しいミュート状態。bMute が TRUE の場合、メソッドはストリームをミュートします。FALSE の場合、メソッドはミュートを解除します。 |
| pguidEventContext | GUID* | in | IAudioEndpointVolumeCallback::OnNotify メソッドのコンテキスト値。このパラメーターはイベントコンテキスト GUID を指します。SetMute の呼び出しによってエンドポイントのミュート状態が変更されると、そのエンドポイントに IAudioEndpointVolumeCallback インターフェースを登録しているすべてのクライアントに通知が送られます。クライアントは OnNotify メソッドの実装内でイベントコンテキスト GUID を調べることで、コントロール変更イベントの発生源が自分自身か他のクライアントかを判別できます。呼び出し側がこのパラメーターに NULL ポインターを指定した場合、通知ルーチンはコンテキスト GUID 値 GUID_NULL を受け取ります。 |
戻り値
メソッドが成功してミュート状態が変化した場合、メソッドは S_OK を返します。メソッドが成功し、新しいミュート状態が以前のミュート状態と同じ場合、メソッドは S_FALSE を返します。メソッドが失敗した場合、返される可能性のあるリターンコードには、次の表に示す値が含まれますが、これらに限定されません。
| リターンコード | 説明 |
|---|---|
| メモリ不足です。 |
解説(Remarks)
SetMute を呼び出すコード例については、Endpoint Volume Controls を参照してください。
GetMute メソッドは、オーディオエンドポイントデバイスに入出力されるオーディオストリームのミュート状態を取得します。
| pbMute | BOOL* | out | メソッドがミュート状態を書き込む BOOL 変数へのポインター。*pbMute が TRUE の場合、ストリームはミュートされています。FALSE の場合、ストリームはミュートされていません。 |
戻り値
メソッドが成功した場合は S_OK を返します。失敗した場合、返される可能性のあるリターンコードには、次の表に示す値が含まれますが、これらに限定されません。
| リターンコード | 説明 |
|---|---|
| パラメーター pbMute が NULL です。 |
解説(Remarks)
GetMute を呼び出すコード例については、Endpoint Volume Controls を参照してください。
GetVolumeStepInfo メソッドは、音量範囲における現在のステップに関する情報を取得します。
| pnStep | DWORD* | out | メソッドが現在のステップインデックスを書き込む UINT 変数へのポインター。このインデックスは 0 から *pStepCount– 1 の範囲の値であり、0 が最小音量レベル、*pStepCount– 1 が最大レベルを表します。 |
| pnStepCount | DWORD* | out | メソッドが音量範囲のステップ数を書き込む UINT 変数へのポインター。この数は、IAudioEndpointVolume インターフェースインスタンスの有効期間中、一定に保たれます。 |
戻り値
メソッドが成功した場合は S_OK を返します。失敗した場合、返される可能性のあるリターンコードには、次の表に示す値が含まれますが、これらに限定されません。
| リターンコード | 説明 |
|---|---|
| パラメーター pnStep と pnStepCount の両方が NULL です。 |
解説(Remarks)
このメソッドは、オーディオエンドポイントデバイスに入出力されるオーディオストリームの音量レベルを、離散的な音量レベルの範囲におけるインデックスすなわち「ステップ」として表します。出力値 *pnStepCount はその範囲のステップ数です。出力値 *pnStep は現在の音量レベルのステップインデックスです。ステップ数を n = *pnStepCount とすると、ステップインデックス *pnStep は 0(最小音量)から n – 1(最大音量)までの値を取り得ます。
0 から n – 1 の範囲において、隣接するステップ間の各区間は、線形の信号振幅でもデシベルでも、必ずしも均一な音量増分を表すとは限りません。Windows Vista では、GetVolumeStepInfo はインデックスと音量レベル(信号振幅)の関係をオーディオテーパーカーブとして定義しています。このカーブの形状は将来のバージョンの Windows で変更される可能性があることに注意してください。オーディオテーパーカーブの詳細については、Audio-Tapered Volume Controls を参照してください。
オーディオアプリケーションは、IAudioEndpointVolume::VolumeStepUp および IAudioEndpointVolume::VolumeStepDown メソッドを呼び出して、音量レベルを 1 区間分増減できます。いずれのメソッドも、まずオーディオテーパーカーブ上の次のポイントに対応する理想的な音量レベルを計算します。次に、その理想レベルに最も近い近似となるエンドポイント音量設定を選択します。エンドポイント音量設定の範囲と粒度を取得するには、IEndpointVolume::GetVolumeRange メソッドを呼び出します。オーディオエンドポイントデバイスがハードウェア音量コントロールを実装している場合、GetVolumeRange はハードウェアの音量設定を記述します。それ以外の場合、EndpointVolume API はエンドポイント音量コントロールをソフトウェアで実装し、GetVolumeRange はソフトウェアで実装されたコントロールの音量設定を記述します。
VolumeStepUp メソッドは、オーディオエンドポイントデバイスに入出力されるオーディオストリームの音量レベルを 1 ステップ増加させます。
| pguidEventContext | GUID* | in | IAudioEndpointVolumeCallback::OnNotify メソッドのコンテキスト値。このパラメーターはイベントコンテキスト GUID を指します。VolumeStepUp の呼び出しによってエンドポイントの音量レベルが変更されると、そのエンドポイントに IAudioEndpointVolumeCallback インターフェースを登録しているすべてのクライアントに通知が送られます。クライアントは OnNotify メソッドの実装内でイベントコンテキスト GUID を調べることで、音量変更イベントの発生源が自分自身か他のクライアントかを判別できます。呼び出し側がこのパラメーターに NULL ポインターを指定した場合、クライアントの通知メソッドは NULL コンテキストポインターを受け取ります。 |
戻り値
メソッドが成功した場合は S_OK を返します。失敗した場合、返される可能性のあるリターンコードには、次の表に示す値が含まれますが、これらに限定されません。
| リターンコード | 説明 |
|---|---|
| メモリ不足です。 |
解説(Remarks)
現在の音量ステップと音量範囲の合計ステップ数を取得するには、IAudioEndpointVolume::GetVolumeStepInfo メソッドを呼び出します。
音量レベルがすでに音量範囲の最高ステップにある場合、VolumeStepUp の呼び出しは何も行わず、ステータスコード S_OK を返します。
隣接するステップ間の各区間は、線形の信号振幅でもデシベルでも、必ずしも均一な音量増分を表すとは限りません。Windows Vista では、VolumeStepUp はステップインデックスと音量レベル(信号振幅)の関係をオーディオテーパーカーブとして定義しています。このカーブの形状は将来のバージョンの Windows で変更される可能性があることに注意してください。オーディオテーパーカーブの詳細については、Audio-Tapered Volume Controls を参照してください。
VolumeStepDown メソッドは、オーディオエンドポイントデバイスに入出力されるオーディオストリームの音量レベルを 1 ステップ減少させます。
| pguidEventContext | GUID* | in | IAudioEndpointVolumeCallback::OnNotify メソッドのコンテキスト値。このパラメーターはイベントコンテキスト GUID を指します。VolumeStepDown の呼び出しによってエンドポイントの音量レベルが変更されると、そのエンドポイントに IAudioEndpointVolumeCallback インターフェースを登録しているすべてのクライアントに通知が送られます。クライアントは OnNotify メソッドの実装内でイベントコンテキスト GUID を調べることで、音量変更イベントの発生源が自分自身か他のクライアントかを判別できます。呼び出し側がこのパラメーターに NULL ポインターを指定した場合、クライアントの通知メソッドは NULL コンテキストポインターを受け取ります。 |
戻り値
メソッドが成功した場合は S_OK を返します。失敗した場合、返される可能性のあるリターンコードには、次の表に示す値が含まれますが、これらに限定されません。
| リターンコード | 説明 |
|---|---|
| メモリ不足です。 |
解説(Remarks)
現在の音量ステップと音量範囲の合計ステップ数を取得するには、IAudioEndpointVolume::GetVolumeStepInfo メソッドを呼び出します。
音量レベルがすでに音量範囲の最低ステップにある場合、VolumeStepDown の呼び出しは何も行わず、ステータスコード S_OK を返します。
隣接するステップ間の各区間は、線形の信号振幅でもデシベルでも、必ずしも均一な音量増分を表すとは限りません。Windows Vista では、VolumeStepDown はステップインデックスと音量レベル(信号振幅)の関係をオーディオテーパーカーブとして定義しています。このカーブの形状は将来のバージョンの Windows で変更される可能性があることに注意してください。オーディオテーパーカーブの詳細については、Audio-Tapered Volume Controls を参照してください。
QueryHardwareSupport メソッドは、オーディオエンドポイントデバイスに対して、ハードウェアでサポートされている機能を照会します。(IAudioEndpointVolume.QueryHardwareSupport)
| pdwHardwareSupportMask | DWORD* | out | メソッドがハードウェアサポートマスクを書き込む DWORD 変数へのポインター。このマスクは、オーディオエンドポイントデバイスのハードウェア機能を示します。メソッドはこのマスクを 0、または 1 つ以上の ENDPOINT_HARDWARE_SUPPORT_XXX 定数のビット単位 OR の組み合わせに設定します。 |
戻り値
メソッドが成功した場合は S_OK を返します。失敗した場合、返される可能性のあるリターンコードには、次の表に示す値が含まれますが、これらに限定されません。
| リターンコード | 説明 |
|---|---|
| パラメーター pdwHardwareSupportMask が NULL です。 |
解説(Remarks)
このメソッドは、オーディオエンドポイントデバイスが次の機能をハードウェアで実装しているかどうかを示します。
- 音量コントロール
- ミュートコントロール
- ピークメーター
GetVolumeRange メソッドは、オーディオエンドポイントデバイスに入出力されるオーディオストリームの音量範囲をデシベル単位で取得します。
| pflVolumeMindB | FLOAT* | out | 最小音量レベルへのポインター。このパラメーターは、メソッドが最小音量レベルをデシベル単位で書き込む float 変数を指します。この値は、IAudioEndpointVolume インターフェースインスタンスの有効期間中、一定に保たれます。 |
| pflVolumeMaxdB | FLOAT* | out | 最大音量レベルへのポインター。このパラメーターは、メソッドが最大音量レベルをデシベル単位で書き込む float 変数を指します。この値は、IAudioEndpointVolume インターフェースインスタンスの有効期間中、一定に保たれます。 |
| pflVolumeIncrementdB | FLOAT* | out | 音量増分へのポインター。このパラメーターは、メソッドが音量増分をデシベル単位で書き込む float 変数を指します。この増分は、IAudioEndpointVolume インターフェースインスタンスの有効期間中、一定に保たれます。 |
戻り値
メソッドが成功した場合は S_OK を返します。失敗した場合、返される可能性のあるリターンコードには、次の表に示す値が含まれますが、これらに限定されません。
| リターンコード | 説明 |
|---|---|
| パラメーター pfLevelMinDB、pfLevelMaxDB、または pfVolumeIncrementDB が NULL です。 |
解説(Remarks)
vmin = *pfLevelMinDB から vmax = *pfLevelMaxDB までの音量範囲は、サイズ vinc = *pfVolumeIncrementDB の n 個の均一な区間に分割されます。ここで、
n = (vmax – vmin) / vinc です。
vmin、vmax、vinc の値はデシベル単位で測定されます。クライアントは、vmin から vmax までの範囲にある n + 1 個の離散値のいずれかに音量レベルを設定できます。
IAudioEndpointVolume::SetChannelVolumeLevel および IAudioEndpointVolume::SetMasterVolumeLevel メソッドは、vmin から vmax までの範囲の音量レベルのみを受け付けます。呼び出し側がこの範囲外の音量レベルを指定すると、メソッドは失敗して E_INVALIDARG を返します。呼び出し側が音量範囲内の 2 つのステップの間に位置する音量レベルを指定した場合、メソッドは要求された音量レベルに最も近いステップにエンドポイントの音量レベルを設定し、S_OK を返します。ただし、その後の IAudioEndpointVolume::GetChannelVolumeLevel または IAudioEndpointVolume::GetMasterVolumeLevel の呼び出しでは、ステップ値ではなく、直前の SetChannelVolumeLevel または SetMasterVolumeLevel の呼び出しで要求された音量レベルが取得されます。
音量コントロールがハードウェアで実装されている場合、GetVolumeRange はハードウェア音量設定の範囲と粒度を記述します。これに対して、IEndpointVolume::GetVolumeStepInfo メソッドが報告するステップは、IEndpointVolume::VolumeStepDown および IEndpointVolume::VolumeStepUp メソッドによってソフトウェアで計算されるオーディオテーパーカーブ上のポイントに対応します。いずれのメソッドも、まずカーブ上の次のポイントに対応する理想的な音量レベルを計算します。次に、その理想レベルに最も近い近似となるハードウェア音量設定を選択します。オーディオテーパーカーブの詳細については、Audio-Tapered Volume Controls を参照してください。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)
HSP用 COM定義
#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。
#define global IID_IAudioEndpointVolume "{5CDF2C82-841E-4546-9722-0CF74078229A}" #usecom global IAudioEndpointVolume IID_IAudioEndpointVolume "{}" #comfunc global IAudioEndpointVolume_RegisterControlChangeNotify 3 sptr #comfunc global IAudioEndpointVolume_UnregisterControlChangeNotify 4 sptr #comfunc global IAudioEndpointVolume_GetChannelCount 5 var #comfunc global IAudioEndpointVolume_SetMasterVolumeLevel 6 float,var #comfunc global IAudioEndpointVolume_SetMasterVolumeLevelScalar 7 float,var #comfunc global IAudioEndpointVolume_GetMasterVolumeLevel 8 var #comfunc global IAudioEndpointVolume_GetMasterVolumeLevelScalar 9 var #comfunc global IAudioEndpointVolume_SetChannelVolumeLevel 10 int,float,var #comfunc global IAudioEndpointVolume_SetChannelVolumeLevelScalar 11 int,float,var #comfunc global IAudioEndpointVolume_GetChannelVolumeLevel 12 int,var #comfunc global IAudioEndpointVolume_GetChannelVolumeLevelScalar 13 int,var #comfunc global IAudioEndpointVolume_SetMute 14 int,var #comfunc global IAudioEndpointVolume_GetMute 15 var #comfunc global IAudioEndpointVolume_GetVolumeStepInfo 16 var,var #comfunc global IAudioEndpointVolume_VolumeStepUp 17 var #comfunc global IAudioEndpointVolume_VolumeStepDown 18 var #comfunc global IAudioEndpointVolume_QueryHardwareSupport 19 var #comfunc global IAudioEndpointVolume_GetVolumeRange 20 var,var,var ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。 ; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IAudioEndpointVolume "{5CDF2C82-841E-4546-9722-0CF74078229A}" #usecom global IAudioEndpointVolume IID_IAudioEndpointVolume "{}" #comfunc global IAudioEndpointVolume_RegisterControlChangeNotify 3 sptr #comfunc global IAudioEndpointVolume_UnregisterControlChangeNotify 4 sptr #comfunc global IAudioEndpointVolume_GetChannelCount 5 sptr #comfunc global IAudioEndpointVolume_SetMasterVolumeLevel 6 float,sptr #comfunc global IAudioEndpointVolume_SetMasterVolumeLevelScalar 7 float,sptr #comfunc global IAudioEndpointVolume_GetMasterVolumeLevel 8 sptr #comfunc global IAudioEndpointVolume_GetMasterVolumeLevelScalar 9 sptr #comfunc global IAudioEndpointVolume_SetChannelVolumeLevel 10 int,float,sptr #comfunc global IAudioEndpointVolume_SetChannelVolumeLevelScalar 11 int,float,sptr #comfunc global IAudioEndpointVolume_GetChannelVolumeLevel 12 int,sptr #comfunc global IAudioEndpointVolume_GetChannelVolumeLevelScalar 13 int,sptr #comfunc global IAudioEndpointVolume_SetMute 14 int,sptr #comfunc global IAudioEndpointVolume_GetMute 15 sptr #comfunc global IAudioEndpointVolume_GetVolumeStepInfo 16 sptr,sptr #comfunc global IAudioEndpointVolume_VolumeStepUp 17 sptr #comfunc global IAudioEndpointVolume_VolumeStepDown 18 sptr #comfunc global IAudioEndpointVolume_QueryHardwareSupport 19 sptr #comfunc global IAudioEndpointVolume_GetVolumeRange 20 sptr,sptr,sptr ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。 ; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。