FsRtlCheckOplockEx 関数 (ntifs.h)

[アーティクル]
10/04/2023

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

構文

NTSTATUS FsRtlCheckOplockEx(
  [in]           POPLOCK                       Oplock,
  [in]           PIRP                          Irp,
  [in]           ULONG                         Flags,
  [in, optional] PVOID                         Context,
  [in, optional] POPLOCK_WAIT_COMPLETE_ROUTINE CompletionRoutine,
  [in, optional] POPLOCK_FS_PREPOST_IRP        PostIrpRoutine
);

パラメーター

[in] Oplock

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

[in] Irp

I/O 操作の IRP へのポインター。

[in] Flags

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

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

[in, optional] Context

CompletionRoutine パラメーターと PostIrpRoutine パラメーターが指すコールバックルーチンに渡される呼び出し元定義コンテキスト情報へのポインター。

[in, optional] CompletionRoutine

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

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

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

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

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

[in, optional] PostIrpRoutine

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

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

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

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

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

戻り値

FsRtlCheckOplockEx は 、次のいずれかの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	日和見ロックの中断が進行中です。 IRP はIRP_MJ_CREATE要求であり、FILE_COMPLETE_IF_OPLOCKED操作の create options パラメーターで指定されました。 STATUS_OPLOCK_BREAK_IN_PROGRESSは、OPLOCK_FLAG_COMPLETE_IF_OPLOCKEDが設定され、日和見ロックが解除された場合に返される成功コードです。
STATUS_PENDING	日和見ロックの中断が開始され、IRP の制御が oplock パッケージに渡されました。 CompletionRoutine が NULL の場合、このルーチンは、STATUS_PENDINGを返すのではなく、oplock 中断の処理中にブロックされます。 STATUS_PENDINGは成功コードです。

注釈

FsRtlCheckOplockEx は、次の条件に従って、I/O 操作の IRP をファイルの現在の日和見ロック状態と同期します。

I/O 操作によって日和見ロックが中断する場合、日和見ロックの中断が開始されます。
日和見ロック中断が完了し、 CompletionRoutine の完了ルーチンが指定されるまで I/O 操作を続行できない場合、 FsRtlCheckOplockEx はSTATUS_PENDINGを返し、 PostIrpRoutine で指定されたコールバックルーチンを呼び出します。日和見ロックの中断が確認されると、 CompletionRoutine のコールバックルーチンが呼び出されます。
日和見ロックの中断が完了し 、CompletionRoutine が指定されない限り、I/O 操作を続行できない場合、日和見ロックの中断が確認されるまで FsRtlCheckOplockEx は戻りません。

PostIrpRoutine は、CompletionRoutine が指定されている場合にのみ指定する必要があります。

ファイルシステムまたはフィルタードライバーが日和見ロックを使用する場合は、日和見的なロックの中断を引き起こす可能性がある I/O 操作のディスパッチルーチンから FsRtlCheckOplockEx を呼び出す必要があります。この規則は、次の種類の I/O 操作に適用されます。これらの操作は、日和見ロックの中断を引き起こす可能性があるためです。

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

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

ミニフィルターでは、 FsRtlCheckOplockEx ではなく FltCheckOplockEx を呼び出す必要があります。

要件

要件	値
サポートされている最小のクライアント	Windows Vista
対象プラットフォーム	ユニバーサル
Header	ntifs.h (Ntifs.h を含む)
Library	NtosKrnl.lib
[DLL]	NtosKrnl.exe
IRQL	<= APC_LEVEL