PFLT_PRE_OPERATION_CALLBACK コールバック関数 (fltkernel.h)

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

ミニフィルタードライバーの PFLT_PRE_OPERATION_CALLBACK ルーチンは、I/O 操作の操作前処理を実行します。

構文

PFLT_PRE_OPERATION_CALLBACK PfltPreOperationCallback;

FLT_PREOP_CALLBACK_STATUS PfltPreOperationCallback(
  [in, out] PFLT_CALLBACK_DATA Data,
  [in]      PCFLT_RELATED_OBJECTS FltObjects,
  [out]     PVOID *CompletionContext
)
{...}

パラメーター

[in, out] Data

I/O 操作のコールバックデータ (FLT_CALLBACK_DATA) 構造体へのポインター。

[in] FltObjects

現在 の I /O 要求に関連するオブジェクトの不透明なポインターを含むFLT_RELATED_OBJECTS構造体へのポインター。

[out] CompletionContext

このコールバックルーチンがFLT_PREOP_SUCCESS_WITH_CALLBACKまたはFLT_PREOP_SYNCHRONIZEを返す場合、このパラメーターは、対応する操作後コールバックルーチンに渡される省略可能なコンテキストポインターです。それ以外の場合は NULL にする必要があります。

戻り値

このコールバックルーチンは、次のいずれかのFLT_PREOP_CALLBACK_STATUS値を返します。

リターンコード	説明
FLT_PREOP_COMPLETE	ミニフィルターは I/O 操作を完了しています。詳細については、「解説」を参照してください。
FLT_PREOP_DISALLOW_FASTIO	操作は高速 I/O 操作であり、ミニフィルターでは高速 I/O パスをこの操作に使用できません。詳細については、「解説」を参照してください。
FLT_PREOP_PENDING	ミニフィルターは I/O 操作をペンドし、操作はまだ保留中です。詳細については、「解説」を参照してください。
FLT_PREOP_SUCCESS_NO_CALLBACK	ミニフィルターは、さらに処理するために FltMgr に I/O 操作を返しています。この場合、 FltMgr は、I/O の完了中にミニフィルタードライバーの操作後コールバックが存在する場合は呼び出しません。
FLT_PREOP_SUCCESS_WITH_CALLBACK	ミニフィルターは、さらに処理するために FltMgr に I/O 操作を返しています。この場合、 FltMgr は I/O の完了時にミニフィルターの操作後コールバックを呼び出します。
FLT_PREOP_SYNCHRONIZE	ミニフィルターは、後続の処理のために FltMgr に I/O 操作を返しますが、操作は完了していません。詳細については、「解説」を参照してください。
FLT_PREOP_DISALLOW_FSFILTER_IO	ミニフィルターは、高速 QueryOpen 操作を禁止し、操作を低速パスに強制しています。これにより、I/O マネージャーはファイルのオープン/クエリ/クローズを実行して要求を処理します。ミニフィルタードライバーは、QueryOpen の場合にのみこの状態を返す必要があります。

注釈

詳細については、「操作前コールバックルーチンの記述」を参照してください。

ミニフィルターの操作前コールバックルーチンは、1 つ以上の種類の I/O 操作を処理します。 (このコールバックルーチンは、レガシフィルターモデルのディスパッチルーチンに似ています)。

ミニフィルターは、コールバックルーチンのエントリポイントを FLT_REGISTRATION 構造体の OperationRegistration 配列に格納することで、特定の種類の I/O 操作の事前操作コールバックルーチンを登録します。ミニフィルターは、DriverEntry ルーチンで FltRegisterFilter にパラメーターとしてこの構造体を渡します。ミニフィルターは、操作後のコールバック (PFLT_POST_OPERATION_CALLBACK) ルーチンを登録せずに、特定の種類の I/O 操作に対して操作前コールバックルーチンを登録できます。その逆も同様です。

ミニフィルタードライバーの操作前または操作後のコールバックルーチンは、操作のコールバックデータ構造の内容を変更できます。その場合は、コールバックデータ構造の IoStatus フィールドの内容が変更されていない限り、FltSetCallbackDataDirty を呼び出す必要があります。

このジェネリックコールバックルーチンの IRQL は、その特定の IO パスに依存します。現在の IRQL を知る必要がある場合は、 KeGetCurrentIRQL を迅速かつ安価に呼び出すことができます。 IRQL の詳細については、「操作前コールバックルーチンの記述」を参照してください。

ファイルシステムは、ファイルの末尾にある書き込み操作と読み取り操作を、基になるファイルストレージデバイスのセクターサイズの倍数に切り上げます。読み取り前または書き込み前の操作を処理する場合、バッファーを割り当ててスワップするフィルターでは、割り当てられたバッファーのサイズを、関連付けられているデバイスのセクターサイズの倍数に丸める必要があります。そうでない場合、基になるファイルシステムから転送されるデータの長さは、バッファーの割り当てられた長さを超えます。バッファーのスワップの詳細については、「 SwapBuffers Minifilter サンプル」を参照してください。

Windows 8以降、CompletionContext は、操作の結果に基づいて有効なコンテキスト値を定義するFlt_CompletionContext_Outptr注釈を使用します。 CompletionContext の注釈を含むコールバックの使用例を次に 示します。

FLT_PREOP_CALLBACK_STATUS
SwapPreReadBuffers(
    _Inout_ PFLT_CALLBACK_DATA Data,
    _In_ PCFLT_RELATED_OBJECTS FltObjects,
    _Flt_CompletionContext_Outptr_ PVOID *CompletionContext
    );

FLT_PREOP_COMPLETEを返す

このルーチンがFLT_PREOP_COMPLETEを返す場合は、コールバックデータ構造の IoStatus.Status フィールドを、I/O 操作の最終的な NTSTATUS 値に設定する必要があります。この NTSTATUS 値をSTATUS_PENDINGすることはできません。クリーンアップ操作または終了操作の場合、クリーンアップ操作と終了操作は失敗しないため、STATUS_PENDING以外の成功 NTSTATUS 値である必要があります。

このルーチンがFLT_PREOP_COMPLETEを返す場合、 FltMgr は、ドライバースタックまたはファイルシステムの呼び出し元の下のミニフィルタードライバーに I/O 操作を送信しません。この場合、 FltMgr は、ドライバースタック内の呼び出し元の上にあるミニフィルタードライバーの操作後コールバックルーチンのみを呼び出します。

FLT_PREOP_DISALLOW_FASTIOを返す

このルーチンがFLT_PREOP_DISALLOW_FASTIOを返す場合は、FltMgr によってこのフィールドが自動的にSTATUS_FLT_DISALLOW_FAST_IOに設定されるため、コールバックデータ構造の IoStatus.Status フィールドを設定しないでください。

FLT_PREOP_DISALLOW_FASTIOは、高速 I/O 操作の場合にのみ返すことができます。特定のコールバックデータ構造が高速 I/O 操作を表しているかどうかを判断するには、 FLT_IS_FASTIO_OPERATION マクロを使用します。

このルーチンがFLT_PREOP_DISALLOW_FASTIOを返す場合、 FltMgr は高速 I/O 操作をドライバースタック内の呼び出し元の下のミニフィルタードライバーやファイルシステムに送信しません。この場合、 FltMgr は、ドライバースタック内の呼び出し元の上にあるミニフィルタードライバーの操作後コールバックルーチンのみを呼び出します。

FLT_PREOP_PENDINGを返す

FLT_PREOP_PENDINGは、IRP ベースの I/O 操作のみをペンで処理できるため、IRP ベースの I/O 操作に対してのみ返すことができます。特定のコールバックデータ構造が IRP ベースの I/O 操作を表すかどうかを確認するには、 FLT_IS_IRP_OPERATION マクロを使用します。

このルーチンがFLT_PREOP_PENDINGを返す場合、ミニフィルタードライバーが FltCompletePendedPreOperation を呼び出すまで、FltMgr は I/O 操作をさらに処理しません。

FLT_PREOP_SYNCHRONIZE が返される場合

ミニフィルターの操作前コールバックルーチンがFLT_PREOP_SYNCHRONIZEを返す場合、ミニフィルターは操作に対応する操作後コールバックを登録している必要があります。このルーチンがFLT_PREOP_SYNCHRONIZEを返すと、 FltMgr は IRQL <= APC_LEVEL で現在のスレッドのコンテキストでミニフィルターの操作後コールバックを呼び出します。

FLT_PREOP_SYNCHRONIZEは、IRP ベースの I/O 操作に対してのみ返す必要があります。 IRP ベースの操作ではない I/O 操作に対して返された場合、 FltMgr は、この戻り値をFLT_PREOP_SUCCESS_WITH_CALLBACKしたかのように扱います。

これらの操作は FltMgr によって既に同期されているため、ミニフィルタードライバーは作成操作のFLT_PREOP_SYNCHRONIZEを返さないでください。

ミニフィルターは、非同期の読み取りおよび書き込み操作のFLT_PREOP_SYNCHRONIZEを返すことはありません。これにより、ミニフィルタードライバーとシステムパフォーマンスの両方が著しく低下する可能性があります。

要件

要件	値
サポートされている最小のクライアント	Microsoft Windows 2000 Update Rollup 1 for SP4、Windows XP SP2、Windows Server 2003 SP1、およびそれ以降の Windows オペレーティングシステム。
対象プラットフォーム	デスクトップ
Header	fltkernel.h (FltKernel.h を含む)
IRQL	「解説」セクションを参照してください