FltCheckOplock 関数 (fltkernel.h)

[アーティクル]
08/07/2023

ミニフィルタードライバーは FltCheckOplock を呼び出して、IRP ベースのファイル I/O 操作のコールバックデータ構造をファイルの現在の日和見ロック (oplock) 状態と同期します。

構文

FLT_PREOP_CALLBACK_STATUS FLTAPI FltCheckOplock(
  [in]           POPLOCK                                 Oplock,
  [in]           PFLT_CALLBACK_DATA                      CallbackData,
  [in, optional] PVOID                                   Context,
  [in, optional] PFLTOPLOCK_WAIT_COMPLETE_ROUTINE        WaitCompletionRoutine,
  [in, optional] PFLTOPLOCK_PREPOST_CALLBACKDATA_ROUTINE PrePostCallbackDataRoutine
);

パラメーター

[in] Oplock

ファイルの不透明な oplock ポインター。このポインターは、 FltInitializeOplock の以前の呼び出しによって初期化されている必要があります。

[in] CallbackData

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

[in, optional] Context

WaitCompletionRoutine および PrePostCallbackDataRoutine が指すコールバックルーチンに渡される呼び出し元定義のコンテキスト情報へのポインター。フィルターマネージャーは、この情報を不透明として扱います。

[in, optional] WaitCompletionRoutine

呼び出し元が指定したコールバックルーチンへのポインター。 oplock の中断が進行中の場合、フィルターマネージャーは、oplock の中断が完了したときにこのルーチンを呼び出します。このパラメーターは省略可能であり、 NULL にすることができます。 NULL の場合、呼び出し元は oplock ブレークが完了するまで待機状態になります。

このルーチンは、次のように宣言されます。

typedef VOID
(*PFLTOPLOCK_WAIT_COMPLETE_ROUTINE) (
      IN PFLT_CALLBACK_DATA CallbackData,
      IN PVOID Context
      );

このルーチンには、次のパラメーターがあります。

CallbackData

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

Context

Context パラメーターで FltCheckOplock に渡されたコンテキスト情報ポインター。

[in, optional] PrePostCallbackDataRoutine

I/O 操作が作業キューにポストされた場合に呼び出される呼び出し元が指定したコールバックルーチンへのポインター。このパラメーターは省略可能であり、 NULL にすることができます。

このルーチンは、次のように宣言されます。

typedef VOID
(*PFLTOPLOCK_PREPOST_CALLBACKDATA_ROUTINE) (
      IN PFLT_CALLBACK_DATA CallbackData,
      IN PVOID Context
      );

CallbackData

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

Context

Context パラメーターで FltCheckOplock に渡されたコンテキスト情報ポインター。

戻り値

FltCheckOplock は、次のFLT_PREOP_CALLBACK_STATUS コードのいずれかを返します。

リターンコード	説明
FLT_PREOP_COMPLETE	FltCheckOplock でプール割り当てエラーが発生したか、 FsRtlCheckOplock 関数の呼び出しでエラーが返されました。 FltCheckOplock は、FLT_CALLBACK_DATA コールバックデータ構造の IoStatus メンバーのIO_STATUS_BLOCK構造体の Status メンバーにエラーコードを設定します。 CallbackData パラメーターは、このFLT_CALLBACK_DATAを指します。
FLT_PREOP_PENDING	oplock の中断が開始されたため、フィルターマネージャーは I/O 操作を作業キューにポストしました。 I/O 操作は、 CallbackData パラメーターが指すコールバックデータによって表されます。
FLT_PREOP_SUCCESS_WITH_CALLBACK	I/O 操作はすぐに実行されました。この操作が create-options パラメーターでFILE_COMPLETE_IF_OPLOCKED指定された作成操作である場合、操作が直ちに実行された場合でも、実際には oplock の中断が進行中である可能性があることに注意してください。これが状況かどうかを判断するために、呼び出し元は、FLT_CALLBACK_DATAコールバックデータ構造の IoStatus メンバーのIO_STATUS_BLOCK構造体の Status メンバーに状態をチェックする必要があります。

注釈

ミニフィルタードライバーは 、FltCheckOplock を呼び出して、IRP ベースの I/O 操作を、次の条件に従ってファイルの現在の oplock 状態と同期します。

I/O 操作によって oplock が中断する場合、oplock の中断が開始されます。
oplock の中断が完了するまで I/O 操作を続行できない場合、 FltCheckOplock は FLT_PREOP_PENDINGを返し、 PrePostCallbackDataRoutine パラメーターが指すコールバックルーチンを呼び出します。

ミニフィルタードライバーで oplocks を使用する場合は、oplock の中断を引き起こす可能性がある I/O 操作に対して、任意の事前操作コールバック (PFLT_PRE_OPERATION_CALLBACK) ルーチンから FltCheckOplock を呼び出す必要があります。この規則は、次の種類の I/O 操作に適用されます。これらの操作によって oplock の中断が発生する可能性があるためです。

IRP_MJ_CLEANUP

IRP_MJ_CREATE

IRP_MJ_FILE_SYSTEM_CONTROL

IRP_MJ_FLUSH_BUFFERS

IRP_MJ_LOCK_CONTROL

IRP_MJ_READ

IRP_MJ_SET_INFORMATION

IRP_MJ_WRITE

I/O 操作は、IRP ベースの I/O 操作である必要があります。特定のコールバックデータ構造が IRP ベースの I/O 操作を表すかどうかを確認するには、 FLT_IS_IRP_OPERATION マクロを使用します。

ミニフィルターは、WaitCompletionRoutine で指定されたコールバック内で FltCheckOplock を再度呼び出してはなりません。これにより、 FltCheckOplock が返される前に oplock パッケージが完了コールバックを呼び出すと、デッドロック状態が発生する可能性があります。

日和見ロックの詳細については、Microsoft Windows SDKドキュメントを参照してください。