FsRtlCheckOplockEx2 函数（ntifs.h）

项目
12/21/2024

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

指向文件的不透明不透明锁结构的指针。此指针必须由上一次调用来初始化 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 在处理IRP_MJ_CREATE请求期间调用，该请求指定创建选项参数中的FILE_OPEN_REQUIRING_OPLOCK标志。 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

保留;必须设置为零。

[in, optional] CompletionRoutineContext

指向要传递给 CompletionRoutine 参数指向的回调例程的调用方定义的上下文信息的指针。此参数是可选的，可以 NULL。

[in, optional] CompletionRoutine

指向调用方提供的回调例程的指针。如果操作锁中断正在进行中，则当中断完成时将调用此例程。此参数是可选的，可以 NULL。如果它 NULL，FsRtlCheckOpLockEx2 同步运行，则将调用方置于等待状态，直到操作锁中断完成。

CompletionRoutine 声明如下：

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

CompletionRoutine 具有以下参数：

上下文：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，它是 Context 参数中传递给 FsRtlCheckOplockEx2的上下文信息指针。
Irp：指向 I/O 操作的 IRP 的指针。

[in] Timeout

如果为非零，则指定超时（以毫秒为单位）等待用于阻止调用方线程的事件，以便等待 oplock 中断完成。除非满足以下两个条件，否则将忽略此值：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请求。在操作的 create options 参数中指定了FILE_OPEN_REQUIRING_OPLOCK，并且有一个授予的 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 包。如果 CompletionRoutineNULL，则在处理 oplock 中断时 FsRtlCheckOplockEx2 块，而不是返回STATUS_PENDING。 STATUS_PENDING是成功的代码。

言论

微型筛选器应调用 FltCheckOplockEx 而不是 FsRtlCheckOplockEx2。

FsRtlCheckOplockEx2 根据以下条件将 I/O 操作的 IRP 与文件的当前 oplock 状态同步：

如果 I/O 操作将导致 oplock 中断，则会启动 oplock 中断。
如果 I/O 操作在操作锁中断完成并且指定了 CompletionRoutine 中的完成例程之前无法继续，FsRtlCheckOplockEx2 返回STATUS_PENDING并调用在 postIrpRoutine中指定的回调例程。确认 oplock 中断后，将调用 CompletionRoutine 中的回调例程。
如果 I/O 操作在操作锁中断完成且未指定 CompletionRoutine 之前无法继续，则调用方线程将被阻止，并且仅当 oplock 中断完成时，FsRtlCheckOplockEx2 才会返回。

如果调用方线程被阻止，并且 NotifyRoutine 未 NULL，NotifyRoutine 将出于在 NotifyParams中设置的任何或全部原因调用 NotifyRoutine：