FltCreateSectionForDataScan 関数 (fltkernel.h)
FltCreateSectionForDataScan ルーチンは、ファイルのセクション オブジェクトを作成します。 フィルター マネージャーは、必要に応じて、作成されたセクションと I/O を同期できます。
構文
NTSTATUS FLTAPI FltCreateSectionForDataScan(
[in] PFLT_INSTANCE Instance,
[in] PFILE_OBJECT FileObject,
[in] PFLT_CONTEXT SectionContext,
[in] ACCESS_MASK DesiredAccess,
[in, optional] POBJECT_ATTRIBUTES ObjectAttributes,
[in, optional] PLARGE_INTEGER MaximumSize,
[in] ULONG SectionPageProtection,
[in] ULONG AllocationAttributes,
[in] ULONG Flags,
[out] PHANDLE SectionHandle,
[out] PVOID *SectionObject,
[out, optional] PLARGE_INTEGER SectionFileSize
);
パラメーター
[in] Instance
コンテキストを取得するミニフィルター ドライバー インスタンスの不透明なインスタンス ポインター。
[in] FileObject
開いているファイルのファイル オブジェクト。 セクション オブジェクトは、指定されたファイルによってサポートされます。 このパラメーターは必須であり、NULL にすることはできません。
[in] SectionContext
以前に割り当てられたセクション コンテキストへのポインター。
[in] DesiredAccess
セクション オブジェクトのアクセスの種類を、次の ACCESS_MASK フラグの 1 つ以上として指定します。
| フラグ | 呼び出し元が |
|---|---|
| SECTION_MAP_READ | セクションのビューを読み取る。 |
| SECTION_MAP_WRITE | セクションのビューを書き込みます。 |
| SECTION_QUERY | セクションに関する情報をセクション オブジェクトに照会します。 ドライバーは、このフラグを設定する必要があります。 |
| SECTION_ALL_ACCESS | 前のフラグによって定義されたすべてのアクションと、STANDARD_RIGHTS_REQUIREDによって定義されたアクション。 STANDARD_RIGHTS_REQUIREDの詳細については、「 ACCESS_MASK」を参照してください。 |
[in, optional] ObjectAttributes
オブジェクト名とその他の属性を指定する省略可能な OBJECT_ATTRIBUTES 構造体へのポインター。 InitializeObjectAttributes マクロを使用して、この構造体を初期化します。
[in, optional] MaximumSize
このパラメーターは将来使用するために予約されています。
[in] SectionPageProtection
セクションの各ページに配置する保護。 次のいずれかの値を指定します。 このパラメーターは必須であり、0 にすることはできません。
| フラグ | 説明 |
|---|---|
| PAGE_READONLY | コミットされたページ領域への読み取り専用アクセスを有効にします。 コミットされたリージョンに書き込もうとすると、アクセス違反が発生します。 システムが読み取り専用アクセスと実行アクセスを区別する場合、コミットされたリージョンでコードを実行しようとすると、アクセス違反が発生します。 |
| PAGE_READWRITE | コミットされたページ領域への読み取りと書き込みの両方のアクセスを有効にします。 |
[in] AllocationAttributes
SEC_XXX フラグのビットマスクによって、セクションの割り当て属性が決まります。 次の値のうち 1 つ以上を指定します。 このパラメーターは必須であり、0 にすることはできません。
| フラグ | 説明 |
|---|---|
| SEC_COMMIT | セクションのすべてのページに対して、メモリまたはディスク上のページング ファイルに物理ストレージを割り当てます。 これが既定の設定です。 このフラグは必須であり、省略できないことに注意してください。 |
| SEC_FILE | FileObject パラメーターで指定されたファイルは、マップされたファイルです。 |
[in] Flags
このパラメーターは将来使用するために予約されています。
[out] SectionHandle
セクションへの不透明なハンドルを受け取る呼び出し元によって割り当てられた変数へのポインター。 既定では、セクション ハンドルはユーザー ハンドルです。 呼び出し元がカーネル ハンドルを必要とする場合は、OBJ_KERNEL_HANDLE フラグが設定された ObjectAttributes パラメーター内の初期化されたOBJECT_ATTRIBUTES構造体へのポインターを渡す必要があります。
[out] SectionObject
セクション オブジェクトへの不透明なポインターを受け取る呼び出し元によって割り当てられた変数へのポインター。
[out, optional] SectionFileSize
セクション オブジェクトの作成時にファイルのサイズ (バイト単位) を受け取る呼び出し元によって割り当てられた変数へのポインター。 このパラメーターは省略可能であり、NULL にすることができます。
戻り値
FltCreateSectionForDataScan は 、次のいずれかのSTATUS_SUCCESSまたは適切な NTSTATUS 値を返します。
| リターン コード | 説明 |
|---|---|
| STATUS_END_OF_FILE | FileObject パラメーターで指定されたファイルのサイズは 0 です。 |
| STATUS_FILE_LOCK_CONFLICT | FileObject パラメーターで指定されたファイルはロックされています。 |
| STATUS_INSUFFICIENT_RESOURCES | FltCreateSectionForDataScan で プール割り当てエラーが発生しました。 |
| STATUS_INVALID_FILE_FOR_SECTION | FileObject パラメーターで指定されたファイルは、セクションをサポートしていません。 |
| STATUS_INVALID_PARAMETER | ミニフィルターは登録されていません。 |
| STATUS_INVALID_PARAMETER_8 | SectionPageProtection パラメーターに指定された値が無効です。 |
| STATUS_INVALID_PARAMETER_9 | 呼び出し元が AllocationAttributes パラメーターに無効な値を指定しました。 |
| STATUS_NOT_SUPPORTED | このインスタンスにアタッチされているボリュームは、セクション コンテキストをサポートしていません。 |
| STATUS_PRIVILEGE_NOT_HELD | 呼び出し元には、 DesiredAccess パラメーターで指定されたアクセス権を持つセクション オブジェクトを作成するために必要な特権がありませんでした。 |
| STATUS_FILE_IS_A_DIRECTORY | FileObject パラメーターで指定されたファイルはディレクトリです。 |
| STATUS_FLT_CONTEXT_ALREADY_DEFINED | Instance で指定されたフィルター インスタンスには、ストリーム用の開いているセクションが既に存在します。 ストリームごとに 1 つのセクションのみがサポートされるため、インスタンスごとに 1 つのセクションがサポートされます。 |
注釈
FltCreateSectionForDataScan を呼び出す前に、ミニフィルターで FltRegisterForDataScan を呼び出して、データ スキャン用のボリュームを最初に登録する必要があります。 他のフィルター コンテキスト要素と同様に、 SectionContext は 最初に FltAllocateContext で割り当てられます。
FltCreateSectionForDataScan は、FltCreateSectionForDataScan が呼び出されるスレッドのプロセス ハンドル テーブルに、オブジェクト (SectionHandle) へのハンドルを挿入します。
ハンドルには、ユーザー ハンドルまたはカーネル ハンドルのいずれかを指定できます。 ObjectAttributes が指すOBJECT_ATTRIBUTES構造体に設定OBJ_KERNEL_HANDLEを使用して作成されたハンドルはカーネル ハンドルであり、カーネル モードからのみアクセスできます。 OBJ_KERNEL_HANDLE フラグなしで作成されたハンドルは、ユーザー またはカーネル モードからアクセスできるユーザー ハンドルです。 フィルターを使用すると、ユーザー ハンドルを作成し、処理のためにユーザー モード アプリケーションに渡すことができます。 たとえば、ウイルス スキャン エンジンは、ユーザー モード アプリケーションに存在し、ファイル システム フィルターからユーザー ハンドルをフィードできます。
セクションを開いたままにして現在のファイル I/O と互換性がない状況が発生する場合があります。 特に、キャッシュ消去をトリガーするファイル I/O は、開いているセクションが原因でキャッシュの消去が禁止されている場合、キャッシュの一貫性を低下させる可能性があります。 ミニフィルターは、これらのイベントの通知にオプションのコールバック ルーチンを提供できます。 ミニフィルター ドライバーは、これらの通知を受信する PFLT_SECTION_CONFLICT_NOTIFICATION_CALLBACK を実装します。 FLT_REGISTRATIONの SectionNotificationCallbackメンバーがミニ フィルターの登録時にこのコールバック ルーチンに設定されている場合、競合通知が有効になります。 通知を受信すると、セクションを閉じて、競合する I/O 操作を続行できます。
注意
セクション通知コールバックは、 FltCreateSectionForDataScan が 返される前に発生する可能性があります。 ミニフィルターは、コールバックを受け取り、 SectionHandle と SectionObject がまだ有効でないケースを処理できる必要があります。
このルーチンによって作成されたセクション オブジェクトが不要になった場合は、ZwClose ルーチンを呼び出してセクション オブジェクトのハンドル (SectionHandle) を閉じ、ObDereferenceObject ルーチンを呼び出してセクション オブジェクト自体 (SectionObject) を逆参照してください。
マップされたセクションとメモリのビューの作成の概要については、「 セクション オブジェクトとビュー」を参照してください。 また、Microsoft Windows SDKの CreateFileMapping ルーチンのドキュメントも参照してください。
重要
ミニフィルターは、 FltCreateSectionForDataScan に渡されたセクション コンテキストを明示的に削除することはできません。 セクション コンテキストが FltCreateSectionForDataScan に渡された後は、FltDeleteContext を呼び出さないでください。 この場合、 FltCloseSectionForDataScan を呼び出すことによって、セクション コンテキストの割り当てが解除され、ストリームから削除されます。
一般に、セクションは読み取り専用として作成する必要があります。 特に、読み取り専用ファイルがトランザクション内にあり、ミニフィルターで読み取り専用セクションが作成されない場合、セクションへの書き込みは破棄され、トランザクションの一部として含まれません。
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows 8 |
| 対象プラットフォーム | ユニバーサル |
| Header | fltkernel.h (Fltkernel.h を含む) |
| Library | FltMgr.lib |
| IRQL | <= APC_LEVEL |