ホーム › Media.Audio › IPart

IPart

COM

📘 Microsoft Learn (日本語) · English

IIDae2de0e4-5bca-4f2d-aa46-5d13f8fdb3a9継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

IPart インターフェイスは、デバイストポロジ内のパート(コネクタまたはサブユニット)を表します。

メソッド 13

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

vtbl 3 HRESULT GetName(LPWSTR* ppwstrName)

GetName メソッドは、このパートのフレンドリ名を取得します。

ppwstrName

LPWSTR*

out

このパートのフレンドリ名を格納する null 終端のワイド文字列のアドレスを、メソッドが書き込むポインタ変数へのポインタです。メソッドが文字列用のストレージを割り当てます。呼び出し側は、不要になったときに CoTaskMemFree 関数を呼び出してストレージを解放する責任があります。GetName の呼び出しが失敗した場合、*ppwstrName は NULL になります。CoTaskMemFree の詳細については、Windows SDK のドキュメントを参照してください。

戻り値

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

戻り値コード	説明
E_POINTER	ポインタ ppwstrName が NULL です。

vtbl 4 HRESULT GetLocalId(DWORD* pnId)

GetLocalId メソッドは、このパートのローカル ID を取得します。

pnId

DWORD*

out

このパートのローカル ID を、メソッドが書き込む UINT 変数へのポインタです。

戻り値

戻り値コード	説明
E_POINTER	ポインタ pnId が NULL です。

解説(Remarks)

パートオブジェクトへのポインタを持っている場合、このメソッドを呼び出してそのパートのローカル ID を取得できます。ローカル ID は、デバイストポロジ内のすべてのパートの中でパートを一意に識別する番号です。

IAudioInputSelector::GetSelection および IAudioOutputSelector::GetSelection メソッドは、接続されているパートのローカル ID を取得します。IAudioInputSelector::SetSelection および IAudioOutputSelector::SetSelection メソッドは、ローカル ID で識別されるパートに接続された入力または出力を選択します。IDeviceTopology::GetPartById メソッドは、ローカル ID で識別されるパートを取得します。

GetLocalId メソッドを使用するコード例については、次のトピックを参照してください。

vtbl 5 HRESULT GetGlobalId(LPWSTR* ppwstrGlobalId)

GetGlobalId メソッドは、このパートのグローバル ID を取得します。

ppwstrGlobalId

LPWSTR*

out

グローバル ID を格納する null 終端のワイド文字列のアドレスを、メソッドが書き込むポインタ変数へのポインタです。メソッドが文字列用のストレージを割り当てます。呼び出し側は、不要になったときに CoTaskMemFree 関数を呼び出してストレージを解放する責任があります。GetGlobalId の呼び出しが失敗した場合、*ppwstrGlobalId は NULL になります。CoTaskMemFree の詳細については、Windows SDK のドキュメントを参照してください。

戻り値

戻り値コード	説明
E_POINTER	ポインタ ppwstrGlobalId が NULL です。
E_OUTOFMEMORY	メモリ不足です。

解説(Remarks)

グローバル ID は、システム内のすべてのデバイストポロジ内のすべてのパートの中で、パートを一意に識別する文字列です。クライアントはこの文字列を不透明なものとして扱う必要があります。つまり、クライアントはパートに関する情報を取得するために文字列の内容を解析しないようにしてください。理由は、文字列の形式が未定義であり、DeviceTopology API の実装によって変わる可能性があるためです。

vtbl 6 HRESULT GetPartType(PartType* pPartType)

GetPartType メソッドは、このパートのパートタイプを取得します。

pPartType

PartType*

out

パートタイプを、メソッドが書き込む PartType 変数へのポインタです。パートタイプは、パートがコネクタかサブユニットかを示す次の PartType 列挙値のいずれかです。

Connector

Subunit

戻り値

戻り値コード	説明
E_POINTER	ポインタ pPartType が NULL です。

解説(Remarks)

このメソッドを使用するコード例については、Device Topologies の SelectCaptureDevice 関数の実装を参照してください。

vtbl 7 HRESULT GetSubType(GUID* pSubType)

GetSubType メソッドは、このパートのパートサブタイプを取得します。

pSubType

GUID*

out

このパートのサブタイプ GUID を、メソッドが書き込む GUID 変数へのポインタです。

戻り値

戻り値コード	説明
E_POINTER	ポインタ pSubType が NULL です。

解説(Remarks)

このメソッドは通常、ヘッダーファイル Ksmedia.h の KSNODETYPE_Xxx GUID 値のいずれかを取得しますが、一部のカスタムドライバは他の GUID 値を提供する場合があります。KSNODETYPE_Xxx GUID の詳細については、Windows DDK のドキュメントを参照してください。

IPart Interface で説明されているように、パートはコネクタまたはサブユニットのいずれかになります。

コネクタであるパートの場合、このメソッドはドライバがコネクタに割り当てたピンカテゴリ GUID を取得します。ピンカテゴリ GUID の例を次に示します。

KSNODETYPE_ANALOG_CONNECTOR。コネクタがマイクやスピーカーなどのアナログデバイスとの間のデータパスの一部である場合。
KSNODETYPE_SPDIF_INTERFACE。コネクタが S/PDIF ポートとの間のデータパスの一部である場合。

詳細については、Windows DDK のドキュメントのピンカテゴリプロパティ KSPROPERTY_PIN_CATEGORY の説明を参照してください。

サブユニットであるパートの場合、このメソッドはサブユニットが実行するストリーム処理機能を示すサブタイプ GUID を取得します。たとえば、音量制御サブユニットの場合、このメソッドは GUID 値 KSNODETYPE_VOLUME を取得します。

次の表は、サブユニットに対して GetSubType メソッドで取得できるサブタイプ GUID の一部を示しています。

サブタイプ GUID	制御インターフェイス	必須または省略可能
KSNODETYPE_3D_EFFECTS	IAudioChannelConfig	省略可能
KSNODETYPE_AGC	IAudioAutoGainControl	必須
KSNODETYPE_DAC	IAudioChannelConfig	省略可能
KSNODETYPE_DEMUX	IAudioOutputSelector	必須
KSNODETYPE_DEV_SPECIFIC	IDeviceSpecificProperty	必須
KSNODETYPE_LOUDNESS	IAudioLoudness	必須
KSNODETYPE_MUTE	IAudioMute	必須
KSNODETYPE_MUX	IAudioInputSelector	必須
KSNODETYPE_PEAKMETER	IAudioPeakMeter	必須
KSNODETYPE_PROLOGIC_DECODER	IAudioChannelConfig	省略可能
KSNODETYPE_TONE	IAudioBass IAudioMidrange IAudioTreble	省略可能省略可能省略可能
KSNODETYPE_VOLUME	IAudioChannelConfig IAudioVolumeLevel	省略可能必須

上記の表で、中央の列は、左の列で指定されたサブタイプのサブユニットがサポートする制御インターフェイスを示しています。右の列は、そのサブユニットによる制御インターフェイスのサポートが必須か省略可能かを示します。サポートが必須の場合、アプリケーションは指定されたサブタイプのサブユニットが制御インターフェイスをサポートしていることに依存できます。サポートが省略可能の場合、指定されたサブタイプのサブユニットは制御インターフェイスをサポートすることもしないこともあります。

上記の表の制御インターフェイスは、サブユニットのプロパティへの便利なアクセス手段を提供します。ただし、一部のサブユニットには対応する制御インターフェイスが存在しないプロパティがあります。アプリケーションは、IKsControl インターフェイスを通じてこれらのプロパティにアクセスできます。詳細については、Using the IKsControl Interface to Access Audio Properties を参照してください。

vtbl 8 HRESULT GetControlInterfaceCount(DWORD* pCount)

GetControlInterfaceCount メソッドは、このパートがサポートする制御インターフェイスの数を取得します。

pCount

DWORD*

out

このパートの制御インターフェイスの数を、メソッドが書き込む UINT 変数へのポインタです。

戻り値

戻り値コード	説明
E_POINTER	ポインタ pCount が NULL です。

vtbl 9 HRESULT GetControlInterface(DWORD nIndex, IControlInterface** ppInterfaceDesc)

GetControlInterface メソッドは、このパートがサポートしている場合、指定された制御インターフェイスへの参照を取得します。

nIndex	DWORD	in	制御インターフェイス番号です。パートが n 個の制御インターフェイスをサポートする場合、制御インターフェイスには 0 から n– 1 までの番号が付けられます。
ppInterfaceDesc	IControlInterface**	out	指定されたオーディオ機能の IControlInterface インターフェイスのアドレスを、メソッドが書き込むポインタ変数へのポインタです。このメソッドを通じて、呼び出し側はインターフェイスへのカウント付き参照を取得します。呼び出し側は、不要になったときにインターフェイスの Release メソッドを呼び出してインターフェイスを解放する責任があります。GetControlInterface の呼び出しが失敗した場合、ppFunction は NULL* になります。

戻り値

戻り値コード	説明
E_POINTER	ポインタ ppFunction が NULL です。
E_INVALIDARG	パラメータ nIndex が範囲外です。
E_NOTFOUND	パートに制御インターフェイスがありません。

vtbl 10 HRESULT EnumPartsIncoming(IPartsList** ppParts)

EnumPartsIncoming メソッドは、すべての受信パート、つまりこのパートより上流のデータパス上に存在するパートのリストを取得します。

ppParts

IPartsList**

out

このパートの直上流にあるパートのリストをカプセル化する IPartsList インターフェイスのアドレスを、メソッドが書き込むポインタ変数へのポインタです。このメソッドを通じて、呼び出し側はインターフェイスへのカウント付き参照を取得します。呼び出し側は、不要になったときにインターフェイスの Release メソッドを呼び出してインターフェイスを解放する責任があります。EnumPartsIncoming の呼び出しが失敗した場合、*ppParts は NULL になります。

戻り値

戻り値コード	説明
E_POINTER	ポインタ ppParts が NULL です。
E_NOTFOUND	このパートには上流パートへのリンクがありません。
E_OUTOFMEMORY	メモリ不足です。

解説(Remarks)

クライアントアプリケーションは、トラバースの各ステップでこのメソッドを繰り返し呼び出して現在のパートの直上流にあるパートのリストを取得することにより、オーディオデータフローの方向とは逆向きにデバイストポロジをトラバースできます。

このパートに上流パートへのリンクがない場合、メソッドはエラーコード E_NOTFOUND を返し、パートリストを作成しません(*ppParts は NULL です)。たとえば、IPart インターフェイスがデバイストポロジにデータが入るコネクタを表す場合、メソッドはこのエラーコードを返します。

vtbl 11 HRESULT EnumPartsOutgoing(IPartsList** ppParts)

EnumPartsOutgoing メソッドは、すべての送信パート、つまりこのパートより下流のデータパス上に存在するパートのリストを取得します。

ppParts

IPartsList**

out

このパートの直下流にあるパートのリストをカプセル化する IPartsList インターフェイスのアドレスを、メソッドが書き込むポインタ変数へのポインタです。このメソッドを通じて、呼び出し側はインターフェイスへのカウント付き参照を取得します。呼び出し側は、不要になったときにインターフェイスの Release メソッドを呼び出してインターフェイスを解放する責任があります。EnumPartsOutgoing の呼び出しが失敗した場合、*ppParts は NULL になります。

戻り値

戻り値コード	説明
E_POINTER	ポインタ ppParts が NULL です。
E_NOTFOUND	このパートには下流パートへのリンクがありません。
E_OUTOFMEMORY	メモリ不足です。

解説(Remarks)

クライアントアプリケーションは、トラバースの各ステップでこのメソッドを繰り返し呼び出して現在のパートの直下流にあるパートのリストを取得することにより、オーディオデータフローの方向にデバイストポロジをトラバースできます。

このパートに下流パートへのリンクがない場合、メソッドはエラーコード E_NOTFOUND を返し、パートリストを作成しません(*ppParts は NULL です)。たとえば、IPart インターフェイスがデバイストポロジからデータが出るコネクタを表す場合、メソッドはこのエラーコードを返します。

EnumPartsOutgoing メソッドを使用するコード例については、Device Topologies の SelectCaptureDevice 関数の実装を参照してください。

vtbl 12 HRESULT GetTopologyObject(IDeviceTopology** ppTopology)

GetTopologyObject メソッドは、このパートを含むデバイストポロジオブジェクトの IDeviceTopology インターフェイスへの参照を取得します。

ppTopology

IDeviceTopology**

out

デバイストポロジオブジェクトの IDeviceTopology インターフェイスのアドレスを、メソッドが書き込むポインタ変数へのポインタです。呼び出し側は、このメソッドからインターフェイスへのカウント付き参照を取得します。このメソッドを通じて、呼び出し側はインターフェイスへのカウント付き参照を取得します。呼び出し側は、不要になったときにインターフェイスの Release メソッドを呼び出してインターフェイスを解放する責任があります。GetTopologyObject の呼び出しが失敗した場合、*ppTopology は NULL になります。

戻り値

戻り値コード	説明
E_POINTER	ポインタ ppTopology が NULL です。

解説(Remarks)

このメソッドを使用するコード例については、次のトピックを参照してください。

vtbl 13 HRESULT Activate(DWORD dwClsContext, GUID* refiid, void** ppvObject)

Activate メソッドは、コネクタまたはサブユニット上で機能固有のインターフェイスをアクティブ化します。

dwClsContext

DWORD

新しく作成されたオブジェクトを管理するコードが実行される実行コンテキストです。呼び出し側は、このパラメータを 1 つ以上の CLSCTX 列挙値のビットごとの OR に設定することでコンテキストを制限できます。クライアントは CLSCTX_ALL を指定することで、コンテキスト制限を課さないようにできます。CLSCTX の詳細については、Windows SDK のドキュメントを参照してください。

refiid

GUID*

要求される制御機能のインターフェイス ID です。クライアントはこのパラメータを次の REFIID 値のいずれかに設定する必要があります。

IID_IAudioAutoGainControl

IID_IAudioBass

IID_IAudioChannelConfig

IID_IAudioInputSelector

IID_IAudioLoudness

IID_IAudioMidrange

IID_IAudioMute

IID_IAudioOutputSelector

IID_IAudioPeakMeter

IID_IAudioTreble

IID_IAudioVolumeLevel

IID_IDeviceSpecificProperty

IID_IKsFormatSupport

IID_IKsJackDescription

IID_IKsJackDescription2

詳細については、「解説」を参照してください。

ppvObject

void**

outoptional

パラメータ refiid で指定されたインターフェイスのアドレスを、メソッドが書き込むポインタ変数へのポインタです。このメソッドを通じて、呼び出し側はインターフェイスへのカウント付き参照を取得します。呼び出し側は、不要になったときにインターフェイスの Release メソッドを呼び出してインターフェイスを解放する責任があります。Activate の呼び出しが失敗した場合、*ppObject は NULL になります。

戻り値

戻り値コード	説明
E_INVALIDARG	dwClsContext の CLSCTX_INPROC_SERVER ビットがゼロです。
E_POINTER	ポインタ ppvObject が NULL です。
E_NOINTERFACE	パートオブジェクトが要求されたインターフェイスをサポートしていません。

解説(Remarks)

Activate メソッドは、次の機能固有の制御インターフェイスをサポートします。

パートの機能固有の制御インターフェイスのインターフェイス ID を取得するには、パートの IControlInterface::GetIID メソッドを呼び出します。機能固有の制御インターフェイス型のインターフェイス ID を取得するには、__uuidof 演算子を使用します。たとえば、IAudioAutoGainControl のインターフェイス ID は次のように定義されます。


const IID IID_IAudioAutoGainControl  __uuidof(IAudioAutoGainControl)

__uuidof 演算子の詳細については、Windows SDK のドキュメントを参照してください。

vtbl 14 HRESULT RegisterControlChangeCallback(GUID* riid, IControlChangeNotify* pNotify)

RegisterControlChangeCallback メソッドは、このパートの状態変化の通知を受け取るためにクライアントが実装する IControlChangeNotify インターフェイスを登録します。

riid	GUID*	in	制御変化を監視する対象となる機能固有の制御インターフェイスです。詳細については、「解説」を参照してください。
pNotify	IControlChangeNotify*	in	クライアントの IControlChangeNotify インターフェイスへのポインタです。メソッドが成功すると、クライアントの IControlChangeNotify インターフェイスの AddRef メソッドを呼び出します。

戻り値

戻り値コード	説明
E_INVALIDARG	パラメータ riid が有効な制御インターフェイス識別子ではありません。
E_POINTER	ポインタ pNotify が NULL です。

解説(Remarks)

パラメータ riid を次の GUID 値のいずれかに設定します。

IID_IAudioAutoGainControl
IID_IAudioBass
IID_IAudioChannelConfig
IID_IAudioInputSelector
IID_IAudioLoudness
IID_IAudioMidrange
IID_IAudioMute
IID_IAudioOutputSelector
IID_IAudioPeakMeter
IID_IAudioTreble
IID_IAudioVolumeLevel
IID_IDeviceSpecificProperty
IID_IKsFormatSupport
IID_IKsJackDescription

パートの機能固有の制御インターフェイスのインターフェイス ID を取得するには、パートの IControlInterface::GetIID メソッドを呼び出します。機能固有の制御インターフェイス型のインターフェイス ID を取得するには、__uuidof 演算子を使用します。たとえば、IAudioAutoGainControl のインターフェイス ID は次のように定義されます。


const IID IID_IAudioAutoGainControl  __uuidof(IAudioAutoGainControl)

__uuidof 演算子の詳細については、Windows SDK のドキュメントを参照してください。

クライアントは、IControlChangeNotify インターフェイスへの最後の参照を解放する前に、IPart::UnregisterControlChangeCallback メソッドを呼び出してインターフェイスの登録を解除する必要があります。そうしないと、アプリケーションは IControlChangeNotify オブジェクトと IPart オブジェクトが保持するリソースをリークします。RegisterControlChangeCallback はクライアントの IControlChangeNotify::AddRef メソッドを呼び出し、UnregisterControlChangeCallback は IControlChangeNotify::Release メソッドを呼び出すことに注意してください。クライアントが誤って UnregisterControlChangeCallback を呼び出す前に IControlChangeNotify インターフェイスへの参照を解放すると、IPart オブジェクトは IControlChangeNotify インターフェイスへの参照を決して解放しません。たとえば、不適切に設計された IControlChangeNotify 実装は、IControlChangeNotify オブジェクトのデストラクタから UnregisterControlChangeCallback を呼び出す場合があります。この場合、IPart オブジェクトが IControlChangeNotify インターフェイスへの参照を解放するまでクライアントは UnregisterControlChangeCallback を呼び出さず、クライアントが UnregisterControlChangeCallback を呼び出すまで IPart オブジェクトは IControlChangeNotify インターフェイスへの参照を解放しません。AddRef および Release メソッドの詳細については、Windows SDK のドキュメントの IUnknown インターフェイスの説明を参照してください。

vtbl 15 HRESULT UnregisterControlChangeCallback(IControlChangeNotify* pNotify)

UnregisterControlChangeCallback メソッドは、クライアントが以前に IPart::RegisterControlChangeCallback メソッドの呼び出しによって登録した IControlChangeNotify インターフェイスの登録を削除します。

pNotify

IControlChangeNotify*

登録を削除する対象の IControlChangeNotify インターフェイスへのポインタです。クライアントは、以前の IPart::RegisterControlChangeCallback メソッドの呼び出しで、この同じインターフェイスポインタをパートオブジェクトに渡しました。UnregisterControlChangeCallback メソッドが成功すると、クライアントの IControlChangeNotify インターフェイスの Release メソッドを呼び出します。

戻り値

戻り値コード	説明
E_INVALIDARG	ポインタ pNotify が NULL です。
E_NOTFOUND	インターフェイスインスタンス *pNotify は現在登録されていません。

解説(Remarks)

クライアントは、IControlChangeNotify インターフェイスへの最後の参照を解放する前に、UnregisterControlChangeCallback を呼び出してインターフェイスの登録を解除する必要があります。そうしないと、アプリケーションは IControlChangeNotify オブジェクトと IPart オブジェクトが保持するリソースをリークします。IPart::RegisterControlChangeCallback メソッドはクライアントの IControlChangeNotify::AddRef メソッドを呼び出し、UnregisterControlChangeCallback は IControlChangeNotify::Release メソッドを呼び出すことに注意してください。クライアントが誤って UnregisterControlChangeCallback を呼び出す前に IControlChangeNotify インターフェイスへの参照を解放すると、IPart オブジェクトは IControlChangeNotify インターフェイスへの参照を決して解放しません。たとえば、不適切に設計された IControlChangeNotify 実装は、IControlChangeNotify オブジェクトのデストラクタから UnregisterControlChangeCallback を呼び出す場合があります。この場合、IPart オブジェクトが IControlChangeNotify インターフェイスへの参照を解放するまでクライアントは UnregisterControlChangeCallback を呼び出さず、クライアントが UnregisterControlChangeCallback を呼び出すまで IPart オブジェクトは IControlChangeNotify インターフェイスへの参照を解放しません。AddRef および Release メソッドの詳細については、Windows SDK のドキュメントの IUnknown インターフェイスの説明を参照してください。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_IPart "{AE2DE0E4-5BCA-4F2D-AA46-5D13F8FDB3A9}"
#usecom global IPart IID_IPart "{}"
#comfunc global IPart_GetName                          3 var
#comfunc global IPart_GetLocalId                       4 var
#comfunc global IPart_GetGlobalId                      5 var
#comfunc global IPart_GetPartType                      6 var
#comfunc global IPart_GetSubType                       7 var
#comfunc global IPart_GetControlInterfaceCount         8 var
#comfunc global IPart_GetControlInterface              9 int,sptr
#comfunc global IPart_EnumPartsIncoming                10 sptr
#comfunc global IPart_EnumPartsOutgoing                11 sptr
#comfunc global IPart_GetTopologyObject                12 sptr
#comfunc global IPart_Activate                         13 int,var,sptr
#comfunc global IPart_RegisterControlChangeCallback    14 var,sptr
#comfunc global IPart_UnregisterControlChangeCallback  15 sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IPart "{AE2DE0E4-5BCA-4F2D-AA46-5D13F8FDB3A9}"
#usecom global IPart IID_IPart "{}"
#comfunc global IPart_GetName                          3 sptr
#comfunc global IPart_GetLocalId                       4 sptr
#comfunc global IPart_GetGlobalId                      5 sptr
#comfunc global IPart_GetPartType                      6 sptr
#comfunc global IPart_GetSubType                       7 sptr
#comfunc global IPart_GetControlInterfaceCount         8 sptr
#comfunc global IPart_GetControlInterface              9 int,sptr
#comfunc global IPart_EnumPartsIncoming                10 sptr
#comfunc global IPart_EnumPartsOutgoing                11 sptr
#comfunc global IPart_GetTopologyObject                12 sptr
#comfunc global IPart_Activate                         13 int,sptr,sptr
#comfunc global IPart_RegisterControlChangeCallback    14 sptr,sptr
#comfunc global IPart_UnregisterControlChangeCallback  15 sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。