FltAllocateContext 関数 (fltkernel.h)
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 |