IDeviceTopology
COM公式ドキュメント
IDeviceTopology インターフェイスは、オーディオデバイスのトポロジーへのアクセスを提供します。
メソッド 7
vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。
GetConnectorCount メソッドは、device-topology オブジェクト内のコネクタの数を取得します。
| pCount | DWORD* | out | コネクタ数(デバイストポロジー内のコネクタの数)を書き込む UINT ポインター変数へのポインター。 |
戻り値
メソッドが成功した場合は S_OK を返します。失敗した場合、返される可能性のあるコードには、次の表に示す値が含まれますが、これらに限定されません。
| 戻り値のコード | 説明 |
|---|---|
| ポインター pCount が NULL です。 |
GetConnector メソッドは、コネクタ番号で指定されたコネクタを取得します。
| nIndex | DWORD | in | コネクタ番号。デバイストポロジーに n 個のコネクタが含まれる場合、コネクタには 0 から n − 1 までの番号が付けられます。デバイストポロジー内のコネクタの数を取得するには、IDeviceTopology::GetConnectorCount メソッドを呼び出します。 |
| ppConnector | IConnector** | out | コネクタオブジェクトの IConnector インターフェイスのアドレスを書き込むポインター変数へのポインター。このメソッドを通じて、呼び出し元はインターフェイスへの参照カウント付き参照を取得します。呼び出し元は、インターフェイスが不要になったときに、そのインターフェイスの Release メソッドを呼び出して解放する責任があります。GetConnector の呼び出しが失敗した場合、*ppConnector は NULL になります。 |
戻り値
メソッドが成功した場合は S_OK を返します。失敗した場合、返される可能性のあるコードには、次の表に示す値が含まれますが、これらに限定されません。
| 戻り値のコード | 説明 |
|---|---|
| パラメーター nIndex が範囲外です。 | |
| ポインター ppConnector が NULL です。 |
解説(Remarks)
GetConnector メソッドを呼び出すコード例については、Device Topologies の GetHardwareDeviceTopology および SelectCaptureDevice 関数の実装を参照してください。
GetSubunitCount メソッドは、デバイストポロジー内のサブユニットの数を取得します。
| pCount | DWORD* | out | サブユニット数(デバイストポロジー内のサブユニットの数)を書き込む UINT 変数へのポインター。 |
戻り値
メソッドが成功した場合は S_OK を返します。失敗した場合、返される可能性のあるコードには、次の表に示す値が含まれますが、これらに限定されません。
| 戻り値のコード | 説明 |
|---|---|
| ポインター pCount が NULL です。 |
GetSubunit メソッドは、サブユニット番号で指定されたサブユニットを取得します。
| nIndex | DWORD | in | サブユニット番号。デバイストポロジーに n 個のサブユニットが含まれる場合、サブユニットには 0 から n − 1 までの番号が付けられます。デバイストポロジー内のサブユニットの数を取得するには、IDeviceTopology::GetSubunitCount メソッドを呼び出します。 |
| ppSubunit | ISubunit** | out | サブユニットオブジェクトの ISubunit インターフェイスのアドレスを書き込むポインター変数へのポインター。このメソッドを通じて、呼び出し元はインターフェイスへの参照カウント付き参照を取得します。呼び出し元は、インターフェイスが不要になったときに、そのインターフェイスの Release メソッドを呼び出して解放する責任があります。GetSubunit の呼び出しが失敗した場合、*ppSubunit は NULL になります。 |
戻り値
メソッドが成功した場合は S_OK を返します。失敗した場合、返される可能性のあるコードには、次の表に示す値が含まれますが、これらに限定されません。
| 戻り値のコード | 説明 |
|---|---|
| パラメーター nIndex が範囲外です。 | |
| ポインター ppSubunit が NULL です。 |
GetPartById メソッドは、ローカル ID で識別されるパートを取得します。
| nId | DWORD | in | 取得するパート。このパラメーターはパートのローカル ID です。詳細については、「解説」を参照してください。 |
| ppPart | IPart** | out | nId で識別されるパートオブジェクトの IPart インターフェイスのアドレスを書き込むポインター変数へのポインター。このメソッドを通じて、呼び出し元はインターフェイスへの参照カウント付き参照を取得します。呼び出し元は、インターフェイスが不要になったときに、そのインターフェイスの Release メソッドを呼び出して解放する責任があります。GetPartById の呼び出しが失敗した場合、*ppPart は NULL になります。 |
戻り値
メソッドが成功した場合は S_OK を返します。失敗した場合、返される可能性のあるコードには、次の表に示す値が含まれますが、これらに限定されません。
| 戻り値のコード | 説明 |
|---|---|
| パラメーター nId が有効なローカル ID ではありません。 | |
| ポインター ppPart が NULL です。 |
解説(Remarks)
ローカル ID は、デバイストポロジー内のすべてのパートの中でパートを一意に識別する番号です。IAudioInputSelector::GetSelection および IAudioOutputSelector::GetSelection メソッドは、接続されたパートのローカル ID を取得します。IAudioInputSelector::SetSelection および IAudioOutputSelector::SetSelection メソッドは、ローカル ID で識別されるパートに接続された入力または出力を選択します。パートオブジェクトへのポインターがある場合は、IPart::GetLocalId メソッドを呼び出してパートのローカル ID を取得できます。
GetDeviceId メソッドは、device-topology オブジェクトによって表されるデバイスのデバイス識別子を取得します。
| ppwstrDeviceId | LPWSTR* | out | デバイス識別子を含む null 終端のワイド文字列のアドレスを書き込むポインター変数へのポインター。メソッドが文字列用のストレージを割り当てます。呼び出し元は、そのストレージが不要になったときに、CoTaskMemFree 関数を呼び出して解放する責任があります。GetDeviceId の呼び出しが失敗した場合、*ppwstrDeviceId は NULL になります。CoTaskMemFree の詳細については、Windows SDK のドキュメントを参照してください。 |
戻り値
メソッドが成功した場合は S_OK を返します。失敗した場合、返される可能性のあるコードには、次の表に示す値が含まれますが、これらに限定されません。
| 戻り値のコード | 説明 |
|---|---|
|
ポインター ppwstrDeviceId が NULL です。 |
| メモリ不足です。 |
解説(Remarks)
このメソッドで取得したデバイス識別子は、IMMDeviceEnumerator::GetDevice メソッドの入力パラメーターとして使用できます。
GetDeviceId メソッドを使用するコード例については、Using the IKsControl Interface to Access Audio Properties を参照してください。
GetSignalPath メソッドは、2 つのパートを結ぶシグナルパス内のパートの一覧を、そのパスが存在する場合に取得します。
| pIPartFrom | IPart* | in | 「from」パートへのポインター。このパラメーターは、シグナルパスの始点にあるパートの IPart インターフェイスへのポインターです。 |
| pIPartTo | IPart* | in | 「to」パートへのポインター。このパラメーターは、シグナルパスの終点にあるパートの IPart インターフェイスへのポインターです。 |
| bRejectMixedPaths | BOOL | in | 混合データを含むパスを拒否するかどうかを指定します。bRejectMixedPaths が TRUE(0 以外)の場合、メソッドはミキサー(すなわち、2 つ以上の入力信号を加算する処理ノード)を含むデータパスを無視します。FALSE の場合、メソッドはパスにミキサーが含まれるかどうかにかかわらず、「from」パートと「to」パートを接続するパスを見つけようとします。 |
| ppParts | IPartsList** | out | IPartsList インターフェイスインスタンスのアドレスを書き込むポインター変数へのポインター。このインターフェイスは、「from」パートと「to」パートを接続するシグナルパス内のパートの一覧をカプセル化します。このメソッドを通じて、呼び出し元はインターフェイスへの参照カウント付き参照を取得します。呼び出し元は、インターフェイスが不要になったときに、そのインターフェイスの Release メソッドを呼び出して解放する責任があります。GetSignalPath の呼び出しが失敗した場合、*ppParts は NULL になります。 |
戻り値
メソッドが成功した場合は S_OK を返します。失敗した場合、返される可能性のあるコードには、次の表に示す値が含まれますが、これらに限定されません。
| 戻り値のコード | 説明 |
|---|---|
| パラメーター pIPartFrom、pIPartTo、または ppParts が NULL です。 | |
| 2 つのパートを結ぶパスが見つかりませんでした。 | |
| パラメーター pIPartFrom または pIPartTo が有効な IPart インターフェイスを指していません。 | |
| メモリ不足です。 |
解説(Remarks)
このメソッドは、指定されたシグナルパスに沿って存在するパートの一覧を含む IPartsList インターフェイスインスタンスを作成します。パート一覧内のパートは、シグナルパス内での相対的な位置に従って順序付けられます。「to」パートが一覧の最初の項目で、「from」パートが一覧の最後の項目です。
一覧に n 個のパートが含まれる場合、「to」パートと「from」パートは、それぞれ一覧のインデックス 0 と n − 1 で識別されます。パート一覧内のパートの数を取得するには、IPartsList::GetCount メソッドを呼び出します。インデックスでパートを取得するには、IPartsList::GetPart メソッドを呼び出します。
シグナルパス内のパートは、すべて同じデバイストポロジーに属している必要があります。パスがデバイストポロジー間の境界をまたぐことはできません。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)
HSP用 COM定義
#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。
#define global IID_IDeviceTopology "{2A07407E-6497-4A18-9787-32F79BD0D98F}" #usecom global IDeviceTopology IID_IDeviceTopology "{}" #comfunc global IDeviceTopology_GetConnectorCount 3 var #comfunc global IDeviceTopology_GetConnector 4 int,sptr #comfunc global IDeviceTopology_GetSubunitCount 5 var #comfunc global IDeviceTopology_GetSubunit 6 int,sptr #comfunc global IDeviceTopology_GetPartById 7 int,sptr #comfunc global IDeviceTopology_GetDeviceId 8 var #comfunc global IDeviceTopology_GetSignalPath 9 sptr,sptr,int,sptr ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。 ; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IDeviceTopology "{2A07407E-6497-4A18-9787-32F79BD0D98F}" #usecom global IDeviceTopology IID_IDeviceTopology "{}" #comfunc global IDeviceTopology_GetConnectorCount 3 sptr #comfunc global IDeviceTopology_GetConnector 4 int,sptr #comfunc global IDeviceTopology_GetSubunitCount 5 sptr #comfunc global IDeviceTopology_GetSubunit 6 int,sptr #comfunc global IDeviceTopology_GetPartById 7 int,sptr #comfunc global IDeviceTopology_GetDeviceId 8 sptr #comfunc global IDeviceTopology_GetSignalPath 9 sptr,sptr,int,sptr ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。 ; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。