FwpsFlowAssociateContext0 関数 (fwpsk.h)

[アーティクル]
08/07/2023

FwpsFlowAssociateContext0 関数は、引き出しドライバー定義コンテキストをデータフローに関連付けます。

メモFwpsFlowAssociateContext0 は、 FwpsFlowAssociateContext の特定のバージョンです。詳細については、「 WFP Version-Independent 名と特定のバージョンの Windows を対象とする」を参照してください。

構文

NTSTATUS FwpsFlowAssociateContext0(
  [in] UINT64 flowId,
  [in] UINT16 layerId,
  [in] UINT32 calloutId,
  [in] UINT64 flowContext
);

パラメーター

[in] flowId

コンテキストを関連付けるデータフローを指定するランタイム識別子。データフローの実行時識別子は、吹き出しドライバーの classifyFn 吹き出し関数に渡されたFWPS_METADATA_FIELD_FLOW_HANDLEメタデータ値を介して引き出しドライバーに提供されます。

[in] layerId

コンテキストが関連付けられているフィルターレイヤーの実行時識別子。コンテキストは、指定されたフィルターレイヤーにのみ関連付けられます。詳細については、「ランタイムフィルターレイヤー識別子」を参照してください。

[in] calloutId

フィルターエンジン内の吹き出しの実行時識別子。この識別子は、吹き出しドライバーが呼び出し線をフィルターエンジンに登録するために FwpsCalloutRegister0、 FwpsCalloutRegister1、または FwpsCalloutRegister2 関数を呼び出したときに返されました。

[in] flowContext

データフローに関連付ける引き出しドライバー定義コンテキスト。このパラメーターは 0 にすることはできません。このコンテキストは、フィルターエンジンに対して不透明です。

戻り値

FwpsFlowAssociateContext0 関数は、次の NTSTATUS コードのいずれかを返します。

リターンコード	説明
STATUS_SUCCESS	コンテキストがデータフローに正常に関連付けられました。
STATUS_INVALID PARAMETER	flowContext パラメーターが NULL であるか、calloutID パラメーターで指定された吹き出しに flowDeleteFn が登録されていません。
STATUS_OBJECT_NAME_EXISTS	コンテキストは既にデータフローに関連付けられています。この場合、コールアウトドライバーは、まず FwpsFlowRemoveContext0 関数を呼び出して既存のコンテキストを削除してから、FwpsFlowAssociateContext0 関数をもう一度呼び出して、新しいコンテキストをデータフローに関連付ける必要があります。
その他の状態コード	エラーが発生しました。

解説

データフローをフィルター処理する場合、吹き出しドライバーは FwpsFlowAssociateContext0 関数を呼び出して、コンテキストをデータフローに関連付けることができます。その後、このコンテキストを使用して、フィルターエンジンによる呼び出し間のドライバー固有のデータまたは状態情報を、そのデータフローの吹き出しの classifyFn 吹き出し関数に保持できます。

フィルターエンジンには、flowDeleteFn 吹き出し関数を登録した layerId パラメーターによって識別されるレイヤーに引き出しが存在する必要があります。それ以外の場合、 FwpsFlowAssociateContext0 関数の呼び出しはSTATUS_INVALID_PARAMETERを返します。フィルターエンジンは、フローが終了したときに flowDeleteFn 吹き出し関数を呼び出して、吹き出しドライバーがフローに関連付けられているコンテキストをクリーンできるようにします。

同じフローに対して FwpsFlowAssociateContext0 を複数回呼び出すことができます。呼び出しごとに、異なる吹き出しと別のコンテキスト (追加された吹き出しごとに 1 つのコンテキスト) を指定する必要があります。

FwpsFlowAssociateContext0 関数は、1 つのコンテキストを 1 つの追加された吹き出しに関連付けます。

複数のコンテキストをフローに関連付けることができます。ただし、各コンテキストは異なる吹き出しに関連付ける必要があります。新しい吹き出しは、前の吹き出しと同じレイヤー、または別のレイヤーに配置できます。

詳細とサンプルコードについては、「コンテキストをData Flowに関連付ける」および「Windows フィルタリングプラットフォームのサンプル」を参照してください。

要件

要件	値
サポートされている最小のクライアント	Windows Vista 以降で使用できます。
対象プラットフォーム	ユニバーサル
Header	fwpsk.h (Fwpsk.h を含む)
Library	Fwpkclnt.lib
IRQL	<= DISPATCH_LEVEL