IControlInterface
COM公式ドキュメント
IControlInterface インターフェイスは、デバイストポロジー内のパート(コネクターまたはサブユニット)上のコントロールインターフェイスを表します。クライアントは、IPart::GetControlInterface メソッドを呼び出すことで、パートの IControlInterface インターフェイスへの参照を取得します。
メソッド 2
vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。
GetName メソッドは、コントロールインターフェイスがカプセル化するオーディオ機能のフレンドリ名を取得します。
| ppwstrName | LPWSTR* | out | メソッドがフレンドリ名を含む null 終端のワイド文字列のアドレスを書き込む先の、文字列ポインターへのポインター。メソッドが文字列用のストレージを割り当てます。呼び出し側は、ストレージが不要になった時点で CoTaskMemFree 関数を呼び出して解放する責任があります。GetName の呼び出しが失敗した場合、*ppwstrName は NULL になります。CoTaskMemFree の詳細については、Windows SDK のドキュメントを参照してください。 |
戻り値
メソッドが成功した場合は S_OK を返します。失敗した場合の戻り値には、次の表に示す値が含まれますが、これらに限定されません。
| 戻り値 | 説明 |
|---|---|
| ポインター ppwstrName が NULL です。 | |
| メモリ不足です。 |
解説(Remarks)
フレンドリ名の例として、IAudioPeakMeter インターフェイスを持つサブユニットには「peak meter」というフレンドリ名が付けられている場合があります。
GetIID メソッドは、パートの機能固有のコントロールインターフェイスのインターフェイス ID を取得します。
| pIID | GUID* | out | メソッドがパートの機能固有のコントロールインターフェイスのインターフェイス ID を書き込む先の、GUID 変数へのポインター。詳細については、「解説」を参照してください。 |
戻り値
メソッドが成功した場合は S_OK を返します。失敗した場合の戻り値には、次の表に示す値が含まれますが、これらに限定されません。
| 戻り値 | 説明 |
|---|---|
| ポインター pIID が NULL です。 |
解説(Remarks)
パート(コネクターまたはサブユニット)を表すオブジェクトには、2 つのコントロールインターフェイスがあります。1 つ目は汎用のコントロールインターフェイス IControlInterface で、すべての種類のコントロールに共通するメソッドを備えています。2 つ目は機能固有のコントロールインターフェイスで、特定の種類のコントロールに適用されるメソッドを備えています。GetIID メソッドは、2 つ目のコントロールインターフェイスのインターフェイス ID を取得します。クライアントは、このインターフェイス ID を IPart::Activate メソッドに渡すことで、パートの機能固有インターフェイスのインスタンスを作成できます。
メソッドは、次の表に示す機能固有のインターフェイス ID のいずれかを取得します。
| インターフェイス ID | インターフェイス名 |
|---|---|
| IID_IAudioAutoGainControl | IAudioAutoGainControl |
| IID_IAudioBass | IAudioBass |
| IID_IAudioChannelConfig | IAudioChannelConfig |
| IID_IAudioInputSelector | IAudioInputSelector |
| IID_IAudioLoudness | IAudioLoudness |
| IID_IAudioMidrange | IAudioMidrange |
| IID_IAudioMute | IAudioMute |
| IID_IAudioOutputSelector | IAudioOutputSelector |
| IID_IAudioPeakMeter | IAudioPeakMeter |
| IID_IAudioTreble | IAudioTreble |
| IID_IAudioVolumeLevel | IAudioVolumeLevel |
| IID_IDeviceSpecificProperty | IDeviceSpecificProperty |
| IID_IKsFormatSupport | IKsFormatSupport |
| IID_IKsJackDescription | IKsJackDescription |
インターフェイスのインターフェイス ID を取得するには、__uuidof 演算子を使用します。たとえば、IAudioAutoGainControl インターフェイスのインターフェイス ID は次のように定義されます。
const IID IID_IAudioAutoGainControl __uuidof(IAudioAutoGainControl)
__uuidof 演算子の詳細については、Windows SDK のドキュメントを参照してください。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)
HSP用 COM定義
#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。
#define global IID_IControlInterface "{45D37C3F-5140-444A-AE24-400789F3CBF3}" #usecom global IControlInterface IID_IControlInterface "{}" #comfunc global IControlInterface_GetName 3 var #comfunc global IControlInterface_GetIID 4 var ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。#define global IID_IControlInterface "{45D37C3F-5140-444A-AE24-400789F3CBF3}" #usecom global IControlInterface IID_IControlInterface "{}" #comfunc global IControlInterface_GetName 3 sptr #comfunc global IControlInterface_GetIID 4 sptr ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。