IGraphConfig

COM

IID03a1eb8e-32bf-4245-8502-114d08a9cb88継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

Filter Graph Manager は、動的なグラフ構築をサポートするために IGraphConfig を公開します。

メソッド 10

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

vtbl 3 HRESULT Reconnect(IPin* pOutputPin, IPin* pInputPin, AM_MEDIA_TYPE* pmtFirstConnection, IBaseFilter* pUsingFilter, HANDLE hAbortEvent, DWORD dwFlags)

Reconnect メソッドは、2 つのピン間で動的な再接続を実行します。

pOutputPin	IPin*	in	出力ピンの IPin インターフェイスへのポインター。NULL を指定できますが、その場合 pInputPin は NULL であってはなりません。
pInputPin	IPin*	in	入力ピンの IPin インターフェイスへのポインター。NULL を指定できますが、その場合 pOutputPin は NULL であってはなりません。
pmtFirstConnection	AM_MEDIA_TYPE*	in	再接続中に行われる最初のピン接続のメディアタイプを指定する AM_MEDIA_TYPE 構造体へのポインター。このパラメーターが NULL の場合、最初の接続は任意のメディアタイプを持つことができます。
pUsingFilter	IBaseFilter*	in	再接続で使用するオプションのフィルターへのポインター。フィルターはすでにグラフ内に存在している必要があります。NULL を指定できます。
hAbortEvent	HANDLE	in	イベントへのハンドル。呼び出し元がデータ処理スレッドの 1 つから呼び出しているフィルターの場合、このパラメーターは、フィルターが停止状態になったときにシグナル状態になるイベントへのハンドルにする必要があります。それ以外の場合、このパラメーターは NULL にできます。詳細については、「解説」を参照してください。
dwFlags	DWORD	in	再接続の実行方法を指定する、AM_GRAPH_CONFIG_RECONNECT_FLAGS 列挙型のフラグの組み合わせ。

戻り値

成功した場合は S_OK を返します。それ以外の場合は、次のいずれかの値、またはここに記載されていない他の値のエラーコードを返します。

戻り値	説明
E_INVALIDARG	無効な引数です。(たとえば、pInputPin と pOutputPin の両方が NULL である場合など。)
E_NOINTERFACE	入力ピンが IPinConnection をサポートしていません。
VFW_E_CANNOT_CONNECT	フィルターを接続できません。
VFW_E_STATE_CHANGED	フィルターの状態が変化しました。操作を完了できません。

解説(Remarks)

一方のピンのみを指定した場合、メソッドはもう一方のピンを検索します。ただし、既定では、IFilterGraph::AddFilter メソッドによってグラフに追加されたフィルターに到達すると、検索は失敗します。この動作を上書きするには、IGraphConfig::SetFilterFlags を呼び出し、そのフィルターに AM_FILTER_FLAGS_REMOVABLE フラグを設定します。

再接続プロセスには複数のステップが含まれ、そのほとんどはこのメソッド内で処理されます。

まず、メソッドを呼び出す前に、再構成されるパスに沿ったデータの流れを必ずブロックしてください。アプリケーションは、これを行うために IPinFlowControl::Block メソッドを呼び出す必要があります。呼び出し元がアプリケーションではなくフィルターの場合は、フィルターが内部でデータフローを制御できる可能性があります。
指定された出力ピンと入力ピンは、再接続の開始点と終了点を定義します。入力ピンは IPinConnection インターフェイスをサポートしている必要があります。これらのピンのいずれかを指定しないままにした場合 (NULL パラメーターを渡した場合)、メソッドはフィルターグラフを検索して再接続の候補ピンを見つけます。(入力ピンを見つけるには出力ピンから下流方向に検索し、出力ピンを見つけるには入力ピンから上流方向に検索します。)
メソッドは、(内部的に IGraphConfig::PushThroughData を呼び出すことで)保留中のデータをフィルターグラフを通じて送り出します。
グラフに挿入するフィルターを指定した場合、メソッドは開始出力ピンをそのフィルターの入力ピンに接続し、フィルターの出力ピンを最終的な入力ピンに接続します。フィルターを指定しない場合、メソッドは単に出力ピンを入力ピンに接続します。いずれの場合も、メソッドは接続を完了するために必要な変換フィルターを挿入します。(ただし、適切なフラグを設定することでこの動作を上書きできます。詳細については、dwFlags パラメーターの説明を参照してください。)
最後に、メソッドは新しいフィルターを実行状態にします。データフローを再開するかどうかは呼び出し元に委ねられます。アプリケーションは、フラグを指定せずに IPinFlowControl::Block を呼び出すことでこれを行えます。

フィルターが自身のデータ処理スレッドの 1 つでこのメソッドを呼び出すと、デッドロックが発生する可能性があります。メソッドはフィルターグラフのロックを取得しますが、これにより IMediaFilter::Stop の呼び出しを受け取ったフィルターが停止できなくなる場合があります。この状況を防ぐため、メソッドはフィルターが提供するイベントオブジェクトへのハンドルを受け取ります。フィルターは、Stop メソッドの呼び出しを受け取った場合、そのイベントをシグナル状態にする必要があります。

vtbl 4 HRESULT Reconfigure(IGraphConfigCallback* pCallback, void* pvContext, DWORD dwFlags, HANDLE hAbortEvent)

Reconfigure メソッドは、フィルターグラフをロックし、アプリケーションまたはフィルター内のコールバック関数を呼び出して動的な再構成を実行します。

pCallback	IGraphConfigCallback*	in	アプリケーションまたはフィルター上の IGraphConfigCallback コールバックインターフェイスへのポインター。
pvContext	void*	in	コールバックルーチンに渡される PVOID 型の変数へのポインター。
dwFlags	DWORD	in	コールバックルーチンに渡される、アプリケーション定義のフラグ。
hAbortEvent	HANDLE	in	イベントへのハンドル。呼び出し元がデータ処理スレッドの 1 つから呼び出しているフィルターの場合、このパラメーターは、フィルターが停止状態になったときにシグナル状態になるイベントへのハンドルにする必要があります。それ以外の場合、このパラメーターは NULL にできます。詳細については、「解説」を参照してください。

戻り値

成功した場合は S_OK を、それ以外の場合はエラーコードを返します。考えられるエラーには、メソッドがフィルターグラフのロックを取得できなかった場合の VFW_E_WRONG_STATE、コールバックルーチンが返した HRESULT、またはグラフがフィルターを実行状態にできなかったことを示すエラーコードなどがあります。

解説(Remarks)

このメソッドは、アプリケーションまたはフィルターが特殊な動的グラフ構築を実装できるように提供されています。ただし、ほとんどの場合は IGraphConfig::Reconnect メソッドで十分であり、実装の詳細のほとんどを処理してくれるため、そちらを優先すべきです。

このメソッドを呼び出す前に、必要に応じてストリームをブロックし、データをグラフを通じて送り出してください(IPinFlowControl::Block および IGraphConfig::PushThroughData を参照)。コールバックメソッドが成功すると、IGraphConfig::Reconfigure はすべてのフィルターを実行状態にしようとします。(その後、呼び出し元はデータフローのブロックを解除する必要があります。)それ以外の場合は、コールバックメソッドが返したエラーコードをそのまま返します。

vtbl 5 HRESULT AddFilterToCache(IBaseFilter* pFilter)

AddFilterToCache メソッドは、フィルターをフィルターキャッシュに追加します。

pFilter

IBaseFilter*

フィルターの IBaseFilter インターフェイスへのポインター。

戻り値

次のいずれかの HRESULT 値を返します。

戻り値	説明
E_FAIL	失敗しました。
E_POINTER	NULL ポインター引数です。
S_FALSE	フィルターは既にキャッシュ内にあります。
S_OK	フィルターがキャッシュに追加されました。

解説(Remarks)

このメソッドを呼び出す前に、フィルターのすべてのピンを切断する必要があります。そうしないとメソッドは失敗します。フィルターがフィルターグラフ内にある場合、このメソッドはそれを削除します。また、フィルターがまだ停止状態でない場合は、このメソッドがフィルターを停止状態にします。

vtbl 6 HRESULT EnumCacheFilter(IEnumFilters** pEnum)

EnumCacheFilter メソッドは、フィルターキャッシュ内のフィルターを列挙します。

pEnum

IEnumFilters**

out

フィルター列挙子上の IEnumFilters インターフェイスへのポインターを受け取ります。呼び出し元はこのインターフェイスを解放する必要があります。

戻り値

次のいずれかの HRESULT 値を返します。

戻り値	説明
E_OUTOFMEMORY	必要なメモリの割り当てに失敗しました。
E_POINTER	NULL ポインター引数です。
S_OK	成功しました。

vtbl 7 HRESULT RemoveFilterFromCache(IBaseFilter* pFilter)

RemoveFilterFromCache メソッドは、フィルターをフィルターキャッシュから削除します。

pFilter

IBaseFilter*

キャッシュから削除するフィルターの IBaseFilter インターフェイスへのポインター。

戻り値

次のいずれかの HRESULT 値を返します。

戻り値	説明
E_POINTER	NULL ポインター引数です。
S_FALSE	フィルターはキャッシュ内にありませんでした。
S_OK	フィルターがキャッシュから正常に削除されました。

vtbl 8 HRESULT GetStartTime(LONGLONG* prtStart)

GetStartTime メソッドは、フィルターグラフが最後に実行状態にされたときに使用された基準時間を取得します。

prtStart

LONGLONG*

out

開始時間を受け取ります。

戻り値

次のいずれかの HRESULT 値を返します。

戻り値	説明
S_OK	成功しました。
VFW_E_WRONG_STATE	フィルターグラフが実行状態ではありません。

解説(Remarks)

フィルターグラフは現在実行状態である必要があります。そうでない場合、このメソッドは失敗します。

vtbl 9 HRESULT PushThroughData(IPin* pOutputPin, IPinConnection* pConnection, HANDLE hEventAbort)

PushThroughData メソッドは、フィルターグラフを通じて指定されたピンまでデータを送り出します。

pOutputPin	IPin*	in	フィルターグラフ内の出力ピンの IPin インターフェイスへのポインター。
pConnection	IPinConnection*	in	フィルターグラフ内の入力ピンの IPinConnection インターフェイスへのポインター。このパラメーターは NULL にできます。
hEventAbort	HANDLE	in	イベントへのハンドル。呼び出し元がデータ処理スレッドの 1 つから呼び出しているフィルターの場合、このパラメーターは、フィルターが停止状態になったときにシグナル状態になるイベントへのハンドルにする必要があります。それ以外の場合、このパラメーターは NULL にできます。詳細については、「解説」を参照してください。

戻り値

成功した場合は S_OK を返します。それ以外の場合は、次のいずれかの値、またはここに記載されていない他の値のエラーコードを返します。

戻り値	説明
E_OUTOFMEMORY	必要なメモリの割り当てに失敗しました。
VFW_E_NOT_FOUND	候補となる入力ピンが見つかりませんでした。
VFW_E_STATE_CHANGED	操作中にフィルターの状態が変化しました。

解説(Remarks)

このメソッドは、指定された出力ピンから指定された入力ピンまで、保留中のデータを送り出します。オプションで、入力ピンを指定しないままにして、メソッドにフィルターグラフから最適な候補を検索させることもできます。データを送り出しているスレッドからこのメソッドを呼び出さないでください。

vtbl 10 HRESULT SetFilterFlags(IBaseFilter* pFilter, DWORD dwFlags)

SetFilterFlags メソッドは、フィルターの構成情報を設定します。

pFilter

IBaseFilter*

フィルターグラフ内のフィルターの IBaseFilter インターフェイスへのポインター。

dwFlags

DWORD

新しい構成フラグを指定する値。次のいずれかの値である必要があります。

値	説明
ゼロ	フラグは設定されていません。
AM_FILTER_FLAGS_REMOVABLE	動的な再接続中にフィルターを削除できます。詳細については、「解説」を参照してください。

戻り値

次のいずれかの HRESULT 値を返します。

戻り値	説明
E_POINTER	NULL ポインター引数です。
E_INVALIDARG	無効な引数です。
S_OK	成功しました。
VFW_E_NOT_IN_GRAPH	フィルターがグラフ内にありません。

解説(Remarks)

AM_FILTER_FLAGS_REMOVABLE フラグは、IGraphConfig::Reconnect メソッドの動作を変更します。Reconnect メソッドは、2 つのピン間で動的な再接続を実行します。呼び出し元が一方のピンを指定し、もう一方のピンを指定しないままにした場合、Reconnect は指定されたピンから上流または下流を検索して適切な一致を見つけます。ただし、既定では、IFilterGraph::AddFilter メソッドによってグラフに追加されたフィルターに到達すると、検索は失敗します。この動作を上書きするには、SetFilterFlags を呼び出し、そのフィルターに AM_FILTER_FLAGS_REMOVABLE フラグを設定します。

vtbl 11 HRESULT GetFilterFlags(IBaseFilter* pFilter, DWORD* pdwFlags)

GetFilterFlags メソッドは、フィルターの構成情報を取得します。

pFilter	IBaseFilter*	in	フィルターグラフ内のフィルターの IBaseFilter インターフェイスへのポインター。
pdwFlags	DWORD*	out	現在の構成フラグを受け取ります。

戻り値

次のいずれかの HRESULT 値を返します。

戻り値	説明
E_POINTER	Null ポインター引数です。
S_OK	成功しました。
VFW_E_NOT_IN_GRAPH	フィルターがグラフ内にありません。

vtbl 12 HRESULT RemoveFilterEx(IBaseFilter* pFilter, DWORD Flags)

RemoveFilterEx メソッドは、フィルターをフィルターグラフから削除します。

pFilter	IBaseFilter*	in	グラフから削除するフィルターの IBaseFilter インターフェイスへのポインター。
Flags	DWORD	in	REM_FILTER_FLAGS 列挙型のフラグの組み合わせ。

戻り値

成功した場合は S_OK を、失敗した場合はその原因を示す HRESULT 値を返します。

解説(Remarks)

このメソッドは、メソッドの動作を指定するフラグを受け取ることで、IFilterGraph::RemoveFilter メソッドを拡張します。このフラグにより、アプリケーションはピンを自動的に切断することなくフィルターを削除できるようになり、接続されたフィルターのグループを新しいグラフに移動する際のパフォーマンスが向上します。

既定では、このメソッドはフィルターをグラフから削除する前に切断します。フィルターを接続したままにするには、REMFILTERF_LEAVECONNECTED フラグを使用します。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_IGraphConfig "{03A1EB8E-32BF-4245-8502-114D08A9CB88}"
#usecom global IGraphConfig IID_IGraphConfig "{}"
#comfunc global IGraphConfig_Reconnect              3 sptr,sptr,var,sptr,sptr,int
#comfunc global IGraphConfig_Reconfigure            4 sptr,sptr,int,sptr
#comfunc global IGraphConfig_AddFilterToCache       5 sptr
#comfunc global IGraphConfig_EnumCacheFilter        6 sptr
#comfunc global IGraphConfig_RemoveFilterFromCache  7 sptr
#comfunc global IGraphConfig_GetStartTime           8 var
#comfunc global IGraphConfig_PushThroughData        9 sptr,sptr,sptr
#comfunc global IGraphConfig_SetFilterFlags         10 sptr,int
#comfunc global IGraphConfig_GetFilterFlags         11 sptr,var
#comfunc global IGraphConfig_RemoveFilterEx         12 sptr,int
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IGraphConfig "{03A1EB8E-32BF-4245-8502-114D08A9CB88}"
#usecom global IGraphConfig IID_IGraphConfig "{}"
#comfunc global IGraphConfig_Reconnect              3 sptr,sptr,sptr,sptr,sptr,int
#comfunc global IGraphConfig_Reconfigure            4 sptr,sptr,int,sptr
#comfunc global IGraphConfig_AddFilterToCache       5 sptr
#comfunc global IGraphConfig_EnumCacheFilter        6 sptr
#comfunc global IGraphConfig_RemoveFilterFromCache  7 sptr
#comfunc global IGraphConfig_GetStartTime           8 sptr
#comfunc global IGraphConfig_PushThroughData        9 sptr,sptr,sptr
#comfunc global IGraphConfig_SetFilterFlags         10 sptr,int
#comfunc global IGraphConfig_GetFilterFlags         11 sptr,sptr
#comfunc global IGraphConfig_RemoveFilterEx         12 sptr,int
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。