FltAllocateExtraCreateParameter 関数 (fltkernel.h)

[アーティクル]
02/26/2024

FltAllocateExtraCreateParameter ルーチンは、ユーザー定義の追加の create パラメーター (ECP) コンテキスト構造用にページングされたメモリプールを割り当て、その構造体へのポインターを生成します。

構文

NTSTATUS FLTAPI FltAllocateExtraCreateParameter(
  [in]           PFLT_FILTER                                    Filter,
  [in]           LPCGUID                                        EcpType,
  [in]           ULONG                                          SizeOfContext,
  [in]           FSRTL_ALLOCATE_ECP_FLAGS                       Flags,
  [in, optional] PFSRTL_EXTRA_CREATE_PARAMETER_CLEANUP_CALLBACK CleanupCallback,
  [in]           ULONG                                          PoolTag,
  [out]          PVOID                                          *EcpContext
);

パラメーター

[in] Filter

ミニフィルタードライバーの不透明なフィルターポインター。このポインターはミニフィルタードライバーを一意に識別し、ミニフィルタードライバーが読み込まれる限り一定のままになります。

[in] EcpType

ECP コンテキスト構造の型を示すユーザー定義 GUID へのポインター。詳細については、「ドライバーでの GUID の使用」を参照してください。

[in] SizeOfContext

ユーザー定義コンテキスト構造のサイズ (バイト単位)。

[in] Flags

プール割り当てオプションを定義します。次に、一覧に示されている 1 つ以上のフラグ値をビットごとの OR 操作を使用して Flags パラメーターと組み合わせた場合にプールを割り当てる方法について説明します。

FSRTL_ALLOCATE_ECP_FLAG_NONPAGED_POOL - ページ以外のプールが割り当てられます。このフラグ値を使用しない場合は、ページプールが割り当てられます。
FSRTL_ALLOCATE_ECPLIST_FLAG_CHARGE_QUOTA - このルーチンによって割り当てられたすべてのプールは、現在のプロセスのメモリクォータに対して課金されます。

複数のフラグを使用すると、使用されるフラグ値に関連付けられているすべての効果が発生します。

[in, optional] CleanupCallback

PFSRTL_EXTRA_CREATE_PARAMETER_CLEANUP_CALLBACK型のミニフィルター定義クリーンアップコールバックルーチンへのオプションのポインター。クリーンアップコールバックルーチンは、( FltAllocateExtraCreateParameter ルーチンによって作成された) ECP 構造体が削除されると呼び出されます。クリーンアップコールバックルーチンが適用されない場合は、このパラメーターを NULL に 設定します。

[in] PoolTag

割り当てられたメモリのプールタグを指定します。詳細については、ExAllocatePoolWithTag の Tag パラメーターを参照してください。

[out] EcpContext

割り当てられた ECP コンテキスト構造体へのポインターを受け取ります。ルーチンが十分なプールの割り当てに失敗した場合、 *EcpContext は NULL になり、ルーチンは状態コードSTATUS_INSUFFICIENT_RESOURCESを返します。

戻り値

FltAllocateExtraCreateParameter は、次のいずれかの値を返すことができます。

リターンコード	説明
STATUS_INSUFFICIENT_RESOURCES	FltAllocateExtraCreateParameter が ECP 構造体に十分なメモリを割り当てることができませんでした。この場合、 EcpContext は NULL になります。
STATUS_SUCCESS	ECP 構造体が正常に割り当てられました。この場合、割り当てられた構造体へのポインターが EcpContext パラメーターで返されます。

注釈

既定では、 FltAllocateExtraCreateParameter ルーチンは、ユーザー定義の ECP コンテキスト構造にページメモリプールを割り当てます。上記のようにFSRTL_ALLOCATE_ECP_FLAG_NONPAGED_POOLビットマスクを使用すると、ページ化されていないメモリプールが割り当てられます。このプールが割り当てられ、ECP コンテキスト構造が初期化されると、 FltInsertExtraCreateParameter ルーチンを使用して ECP コンテキスト構造 (ECP リスト要素) を ECP リスト構造 (ECP リスト) に挿入します。

FltAllocateExtraCreateParameter ルーチンによって割り当てられたメモリプールは、オペレーティングシステムによって自動的に解放されません。このメモリプールは、最終的に次のいずれかの方法を使用して解放する必要があります。

FltRemoveExtraCreateParameter ルーチンを呼び出して ECP リストから ECP コンテキスト構造を削除し、FltFreeExtraCreateParameter ルーチンを呼び出して ECP コンテキスト構造自体を解放します。 ECP リストは存在したままです。
FltFreeExtraCreateParameterList ルーチンを呼び出します。これにより、リスト要素 (ECP コンテキスト構造体) を含む ECP リストが解放されます。 ECP リストが破棄されます。

ただし、ファイルシステムまたはファイルシステムフィルタードライバーが、IRP_MJ_CREATE要求の処理中に既存または新しく作成されたECP_LISTに ECP をアタッチした場合、IRP が完了すると、この ECP は自動的にクリーンアップされます。その結果、フィルタードライバーは、動的に追加される ECP をクリーンする必要はありません。これにより、フィルタードライバーの ECP を再解析ポイント間で適切に伝達できます。つまり、複数のIRP_MJ_CREATE要求を生成する必要があるプロセスです。