FltAllocateContext 関数 (fltkernel.h)

[アーティクル]
03/16/2024

FltAllocateContext ルーチンは、指定したコンテキスト型にコンテキスト構造を割り当てます。

構文

NTSTATUS FLTAPI FltAllocateContext(
  [in]  PFLT_FILTER      Filter,
  [in]  FLT_CONTEXT_TYPE ContextType,
  [in]  SIZE_T           ContextSize,
  [in]  POOL_TYPE        PoolType,
  [out] PFLT_CONTEXT     *ReturnedContext
);

パラメーター

[in] Filter

呼び出し元の不透明なフィルターポインター。このパラメーターは必須であり、 NULL にすることはできません。

[in] ContextType

割り当てるコンテキストの種類を示すFLT_CONTEXT_TYPE値。 ContextType には、次のいずれかを指定できます。

値	意味
FLT_VOLUME_CONTEXT (0x0001)	ボリュームコンテキストを割り当てます。
FLT_INSTANCE_CONTEXT (0x0002)	インスタンスコンテキストを割り当てます。
FLT_FILE_CONTEXT (0x0004)	ファイルコンテキストを割り当てます。
FLT_STREAM_CONTEXT (0x0008)	ストリームコンテキストを割り当てます。
FLT_STREAMHANDLE_CONTEXT (0x0010)	ストリームハンドルコンテキストを割り当てます。
FLT_TRANSACTION_CONTEXT (0x0020)	トランザクションコンテキストを割り当てます。
FLT_SECTION_CONTEXT (0x0040)	セクションコンテキストを割り当てます。 Windows 8 以降で使用できます。

[in] ContextSize

ミニフィルタードライバーによって定義されたコンテキストの部分のサイズ (バイト単位)。 0 より大きく、MAXUSHORT 以下である必要があります。固定サイズのコンテキストの場合、は、FLT_CONTEXT_REGISTRATION構造体で指定された Size 以下である必要があります。ミニフィルターは、コンテキストのこの部分を使用して、それ自体に固有のコンテキスト情報を維持します。 FltMgr は、コンテキスト構造のこの部分を不透明として扱います。このパラメーターは必須であり、0 にすることはできません。

[in] PoolType

割り当てるプールの種類。このパラメーターは必須であり、次のいずれかである必要があります。各種類の詳細については、「 POOL_TYPE 」を参照してください。詳細については、「解説」を参照してください。

値	意味
NonPagedPool	非ページシステムメモリ。 ContextType がFLT_VOLUME_CONTEXT場合、PoolType は NonPagedPool である必要があります。
PagedPool	ページング可能なシステムメモリ。
NonPagedPoolNx	非実行 (NX) 非ページプール。

[out] ReturnedContext

新しく割り当てられたコンテキストのアドレスを受け取る呼び出し元によって割り当てられた変数へのポインター。呼び出し元は、 FltReleaseContext を呼び出して、不要になったときにこのコンテキストを解放する必要があります。

戻り値

FltAllocateContext は、次のいずれかのSTATUS_SUCCESSまたは適切な NTSTATUS 値を返します。

リターンコード	説明
STATUS_FLT_CONTEXT_ALLOCATION_NOT_FOUND	指定した型のコンテキストの割り当て情報は、フィルター登録時に提供されませんでした。または、固定サイズのコンテキストの場合、要求された ContextSize は、指定した ContextType のFLT_CONTEXT_REGISTRATION構造体で指定されたサイズより大きくなります。
STATUS_FLT_DELETING_OBJECT	Filter パラメーターで指定されたミニフィルタードライバーが破棄されています。これはエラーコードです。
STATUS_INSUFFICIENT_RESOURCES	FltAllocateContext でプール割り当てエラーが発生しました。これはエラーコードです。
STATUS_INVALID_BUFFER_SIZE	ContextSize を MAXUSHORT より大きくすることはできません。これはエラーコードです。
STATUS_INVALID_PARAMETER	ContextType パラメーターまたは ContextSize パラメーターに無効な値が指定されました。これはエラーコードです。
STATUS_NOT_SUPPORTED	ファイルシステムでは、ストリームごとのコンテキストはサポートされていません。これはエラーコードです。

注釈

コンテキストの詳細については、「ミニフィルターコンテキストについて」を参照してください。

FltAllocateContext は 、指定したプールから指定した型のコンテキストを割り当てます。 Windows 11以降、ReturnedContext が指すメモリがゼロにするかどうかは、次のように異なります。

メモリは、可変サイズのコンテキストではゼロであることが保証されます。
メモリコンテンツは、呼び出し元によって提供されるコールバック関数によって割り当てられた固定サイズのコンテキストに対して実装定義されます。
それ以外の場合、ルックアサイドリストの動作のため、固定サイズのコンテキストではメモリをゼロにすることはできません。つまり、ルックアサイドリストから返されたエントリは、新しい割り当てではなく、以前にルックアサイドリストに解放されたメモリである場合、ゼロにされない可能性があります。

Windows 11する前に、返されるコンテキストの内容はゼロになりません。

PoolType を無効な値に設定すると、ルックアサイドリストがバイパスされるなどの予期しない動作が発生し、ルックアサイドリストのパフォーマンス上の利点が失われる可能性があります。 ContextAllocateCallback コールバック関数を持つコンテキストの場合、無効な PoolType による動作は実装に依存します。

コンテキストが割り当てられた後、次の表から適切な set-context ルーチンに ReturnedContext ポインターを渡すことによって、オブジェクトに設定できます。

コンテキストの種類	Set-Context ルーチン
FLT_FILE_CONTEXT	FltSetFileContext (Windows Vista 以降)
FLT_INSTANCE_CONTEXT	FltSetInstanceContext
FLT_SECTION_CONTEXT	FltCreateSectionForDataScan (Windows 8 以降)
FLT_STREAM_CONTEXT	FltSetStreamContext
FLT_STREAMHANDLE_CONTEXT	FltSetStreamHandleContext
FLT_TRANSACTION_CONTEXT	FltSetTransactionContext (Windows Vista 以降)
FLT_VOLUME_CONTEXT	FltSetVolumeContext

ミニフィルタードライバーが DriverEntry ルーチンから FltRegisterFilter を呼び出す場合は、使用する各コンテキストの種類を登録する必要があります。詳細については、「 FLT_CONTEXT_REGISTRATION 構造体の参照エントリ」および「コンテキスト型の登録」を参照してください。

FltAllocateContext は、ミニフィルタードライバーに固有のコンテキスト構造の部分の内容を初期化しません。

オブジェクトのコンテキストを取得するには、次の表から FltGetContexts または適切な get-context ルーチンを呼び出します。

コンテキストの種類	Get-Context ルーチン
FLT_FILE_CONTEXT	FltGetFileContext (Windows Vista 以降)
FLT_INSTANCE_CONTEXT	FltGetInstanceContext
FLT_SECTION_CONTEXT	FltGetSectionContext (Windows 8 以降)
FLT_STREAM_CONTEXT	FltGetStreamContext
FLT_STREAMHANDLE_CONTEXT	FltGetStreamHandleContext
FLT_TRANSACTION_CONTEXT	FltGetTransactionContext (Windows Vista 以降)
FLT_VOLUME_CONTEXT	FltGetVolumeContext

コンテキストは参照カウントされ、 FltAllocateContext から正常に戻った場合、 ReturnedContext によって指されるコンテキストは 1 の参照カウントを持つよう初期化されています。コンテキストは、参照カウントが 0 に達すると自動的に解放されます。コンテキストの参照カウントをインクリメントするには、 FltReferenceContext を呼び出します。

コンテキストの参照カウントを減らすには、 FltReleaseContext を呼び出します。

コンテキストは参照カウントされるため、通常は削除する必要はありません。コンテキストを明示的に削除するには、次の表から FltDeleteContext または適切な delete-context ルーチンを呼び出します。

コンテキストの種類	Delete-Context ルーチン
FLT_FILE_CONTEXT	FltDeleteFileContext (Windows Vista 以降)
FLT_INSTANCE_CONTEXT	FltDeleteInstanceContext
FLT_SECTION_CONTEXT	FltCloseSectionForDataScan (Windows 8 以降)
FLT_STREAM_CONTEXT	FltDeleteStreamContext
FLT_STREAMHANDLE_CONTEXT	FltDeleteStreamHandleContext
FLT_TRANSACTION_CONTEXT	FltDeleteTransactionContext (Windows Vista 以降)
FLT_VOLUME_CONTEXT	FltDeleteVolumeContext

要件

要件	値
対象プラットフォーム	ユニバーサル
Header	fltkernel.h (Fltkernel.h を含む)
Library	FltMgr.lib
[DLL]	Fltmgr.sys
IRQL	<= APC_LEVEL