FsRtlCheckOplockEx2 関数 (ntifs.h)

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

FsRtlCheckOplockEx2 は 、ファイル I/O 操作の IRP を、ファイルの現在の日和見ロック (oplock) 状態と同期します。

構文

NTSTATUS FsRtlCheckOplockEx2(
  [in]           POPLOCK                       Oplock,
  [in]           PIRP                          Irp,
  [in]           ULONG                         Flags,
  [in]           ULONG                         FlagsEx2,
  [in, optional] PVOID                         CompletionRoutineContext,
  [in, optional] POPLOCK_WAIT_COMPLETE_ROUTINE CompletionRoutine,
  [in, optional] POPLOCK_FS_PREPOST_IRP        PostIrpRoutine,
  [in]           ULONGLONG                     Timeout,
  [in, optional] PVOID                         NotifyContext,
  [in, optional] POPLOCK_NOTIFY_ROUTINE        NotifyRoutine
);

パラメーター

[in] Oplock

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

[in] Irp

要求された I/O 操作を宣言する IRP へのポインター。

[in] Flags

関連付けられたファイル I/O 操作のビットマスク。ファイルシステムまたはフィルタードライバーは、 FsRtlCheckOplockEx2 の動作を指定するビットを設定します。 フラグ には、次のオプションがあります。

フラグ値	意味
OPLOCK_FLAG_COMPLETE_IF_OPLOCKED (0x00000001)	oplock 中断の原因となった操作をブロックまたは保留中にせずに、oplock の中断を続行することを許可するように指定します。
OPLOCK_FLAG_OPLOCK_KEY_CHECK_ONLY (0x00000002)	FsRtlCheckOplockEx2 は、Irp パラメーターが指す IRP に関連付けられているFILE_OBJECTの oplock キーに対してのみチェックするように指定します。 FsRtlCheckOplockEx2 は、IRP でキーが指定されている場合は、キーを追加する必要があります。他の oplock 処理は行われません。つまり、oplock の中断は発生しません。 Windows 7 以降でサポートされています。
OPLOCK_FLAG_BACK_OUT_ATOMIC_OPLOCK (0x00000004)	FsRtlCheckOplockEx2 が FsRtlOplockFsctrl ルーチンの呼び出しによって以前に設定されていた状態を元に戻す必要があることを指定します。 FsRtlOplockFsctrl は、create options パラメーターでFILE_OPEN_REQUIRING_OPLOCK フラグを指定するIRP_MJ_CREATE要求の処理中に呼び出されます。通常、OPLOCK_FLAG_BACK_OUT_ATOMIC_OPLOCK フラグは、以前に失敗したときにこのような作成要求の最終処理で使用されます。 Windows 7 以降でサポートされています。
OPLOCK_FLAG_IGNORE_OPLOCK_KEYS (0x00000008)	oplock キーに関係なく、すべての oplock の中断を続行することを許可するように指定します。 Windows 7 以降でサポートされています。
OPLOCK_FLAG_PARENT_OBJECT (0x00000010)	Oplock が Irp パラメーターの IRP の転送先となるファイルまたはディレクトリの親 (ディレクトリ) に関連付けられていることを指定します。 Windows 8 以降でサポートされています。
OPLOCK_FLAG_CLOSING_DELETE_ON_CLOSE (0x00000020)	Irp で指定された I/O 操作が、作成オプションで設定されたFILE_DELETE_ON_CLOSE フラグで最初に開かれたハンドルのIRP_MJ_CLEANUPであることを指定します。 Irp がIRP_MJ_CLEANUP操作でない場合、このフラグは無効です。このフラグを指定すると、oplock の中断が発生する可能性があります。 Windows 8 以降でサポートされています。
OPLOCK_FLAG_REMOVING_FILE_OR_LINK (0x00000040)	そのディレクトリ内のファイルまたはリンクを削除するときに、親ディレクトリで oplock の中断を処理することを指定します。指定した場合、このフラグを OPLOCK_FLAG_PARENT_OBJECT と組み合わせる必要があります。このフラグは、ファイル・システムがリンクまたはファイルの除去を行う操作を処理する場合に指定する必要があります。 Windows 8 以降でサポートされています。

[in] FlagsEx2

予約;は 0 に設定する必要があります。

[in, optional] CompletionRoutineContext

CompletionRoutine パラメーターが指すコールバックルーチンに渡される呼び出し元定義コンテキスト情報へのポインター。このパラメーターは省略可能であり、 NULL にすることができます。

[in, optional] CompletionRoutine

呼び出し元が指定したコールバックルーチンへのポインター。 oplock の中断が進行中の場合、このルーチンは、中断が完了したときに呼び出されます。このパラメーターは省略可能であり、 NULL にすることができます。 NULL の場合、FsRtlCheckOpLockEx2 は同期的に動作し、呼び出し元は oplock の中断が完了するまで待機状態になります。

CompletionRoutine は次のように宣言されています。

typedef VOID
(*POPLOCK_WAIT_COMPLETE_ROUTINE) (
      IN PVOID Context,
      IN PIRP Irp
      );

CompletionRoutine には、次のパラメーターがあります。

Context: Context パラメーターで FsRtlCheckOplockEx2 に渡されたコンテキスト情報ポインター。
Irp: I/O 操作の IRP へのポインター。

[in, optional] PostIrpRoutine

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

PostIrpRoutine は次のように宣言されています。

typedef VOID
(*POPLOCK_FS_PREPOST_IRP) (
      IN PVOID Context,
      IN PIRP Irp
      );

PostIrpRoutine には、次のパラメーターがあります。

コンテキスト。これは、Context パラメーターで FsRtlCheckOplockEx2 に渡されたコンテキスト情報ポインターです。
Irp: I/O 操作の IRP へのポインター。

[in] Timeout

0 以外の場合は、oplock の中断が完了するまで待機するために呼び出し元のスレッドをブロックするために使用されるイベントを待機するタイムアウト (ミリ秒単位) を指定します。この値は、次の条件の両方が true の場合を除き無視されます。 CompletionRoutine は NULL で 、NotifyRoutine は NULL ではありません。

[in, optional] NotifyContext

NotifyRoutineパラメーターが指すコールバックルーチンに渡されるOPLOCK_NOTIFY_PARAMS構造体へのポインター。このパラメーターは省略可能であり、 NULL にすることができます。

[in, optional] NotifyRoutine

oplock 状態通知のために呼び出される呼び出し元から指定されたコールバックルーチンへのポインター。このパラメーターは省略可能であり、 NULL にすることができます。

NotifyRoutine は次のように宣言されています。

typedef NTSTATUS
(*POPLOCK_NOTIFY_ROUTINE) (
      IN POPLOCK_NOTIFY_PARAMS NotifyParams
      );

NotifyRoutine には、次のパラメーターがあります。

NotifyParams。これは、FsRtlCheckOplockEx2 に渡される NotifyContext パラメーターに設定されます。

戻り値

FsRtlCheckOplockEx2 は、次のいずれかのSTATUS_SUCCESSまたは適切な NTSTATUS コードを返します。

リターンコード	説明
STATUS_CANCELLED	IRP が取り消されました。 STATUS_CANCELLEDはエラーコードです。
STATUS_CANNOT_BREAK_OPLOCK	oplock ブレークを実行できません。 IRP はIRP_MJ_CREATE要求です。 FILE_OPEN_REQUIRING_OPLOCK操作の create options パラメーターで指定され、許可された oplock があります。
STATUS_OPLOCK_BREAK_IN_PROGRESS	oplock の中断が進行中です。 IRP はIRP_MJ_CREATE要求であり、FILE_COMPLETE_IF_OPLOCKED操作の create options パラメーターで指定されました。 STATUS_OPLOCK_BREAK_IN_PROGRESSは、OPLOCK_FLAG_COMPLETE_IF_OPLOCKEDが設定され、oplock が壊れている場合に返される成功コードです。
STATUS_PENDING	oplock の中断が進行中であり、IRP の制御が oplock パッケージに渡されました。 CompletionRoutine が NULL の場合、FsRtlCheckOplockEx2 は、oplock の中断がSTATUS_PENDINGを返すのではなく処理される間にブロックします。 STATUS_PENDINGは成功コードです。

注釈

ミニフィルターは、 FsRtlCheckOplockEx2 の代わりに FltCheckOplockEx を呼び出す必要があります。

FsRtlCheckOplockEx2 は、I/O 操作の IRP を、次の条件に従ってファイルの現在の oplock 状態と同期します。

I/O 操作によって oplock が中断する場合、oplock の中断が開始されます。
Oplock の中断が完了し 、CompletionRoutine の完了ルーチンが指定されるまで I/O 操作を続行できない場合、 FsRtlCheckOplockEx2 はSTATUS_PENDINGを返し、 PostIrpRoutine で指定されたコールバックルーチンを呼び出します。 oplock の中断が確認されると、 CompletionRoutine のコールバックルーチンが呼び出されます。
操作ロックの中断が完了するまで I/O 操作を続行できず、 CompletionRoutine が指定されていない場合、呼び出し元のスレッドはブロックされ、 FsRtlCheckOplockEx2 は oplock の中断が完了したときにのみを返します。

呼び出し元のスレッドがブロックされ、NotifyRoutine が NULL でない場合は、NotifyParams に設定されている次の理由のいずれかまたはすべてについて NotifyRoutine が呼び出されます。

OPLOCK_NOTIFY_BREAK_WAIT_INTERIM_TIMEOUT
OPLOCK_NOTIFY_BREAK_WAIT_TERMINATED

上記のいずれかの理由で NotifyRoutine の呼び出しが発生するのは 、CompletionRoutine が NULL で、呼び出し元のスレッドが中断の完了を待機するのをブロックする必要がある場合のみです。

NotifyRoutine が理由OPLOCK_NOTIFY_BREAK_WAIT_INTERIM_TIMEOUTで呼び出された場合、待機が何らかの理由で終了または完了した場合 (決して実行されない可能性がある) 場合、OPLOCK_NOTIFY_BREAK_WAIT_TERMINATED理由で常に呼び出されます。

FsRtlCheckOplockEx2 は 、NotifyRoutine によって返されるOPLOCK_NOTIFY_BREAK_WAIT_INTERIM_TIMEOUTおよびOPLOCK_NOTIFY_BREAK_WAIT_TERMINATED状態コードを無視します。

PostIrpRoutine は、CompletionRoutine が指定されている場合にのみ指定する必要があります。 PostIrpRoutine が NULL でない場合は、待機中の Irp キューに何かをキューに入れる前に呼び出されます。

OPLOCK_FLAG_PARENT_OBJECT フラグが Flags で指定されている場合、 FsRtlCheckOplockEx2 は既存の親 oplock を無条件に中断します。つまり、 Irp の主要なコードは考慮されません。

ファイルシステムが oplocks を使用する場合は、oplock の中断を引き起こす可能性がある I/O 操作のディスパッチルーチンから FsRtlCheckOplockEx2 を呼び出す必要があります。この規則は、次の種類の I/O 操作に適用されます。これらの操作によって oplock の中断が発生する可能性があるためです。