FsRtlCheckOplockEx 函数（ntifs.h）

项目
12/20/2024

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的行为。标志参数具有以下选项：

价值	意义
OPLOCK_FLAG_COMPLETE_IF_OPLOCKED（0x00000001）	指定允许机会锁中断继续，而不阻止或挂起导致操作锁中断的操作。
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 在处理IRP_MJ_CREATE请求期间调用，该请求指定创建选项参数中的FILE_OPEN_REQUIRING_OPLOCK标志。 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 参数中传递给 FsRtlCheckOplockEx的上下文信息指针。
Irp	指向 I/O 操作的 IRP 的指针。

[in, optional] PostIrpRoutine

指向调用方提供的回调例程的指针，如果 I/O 操作发布到工作队列，则调用该例程。此参数是可选的，可以是 NULL。

此例程声明如下：

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

此例程具有以下参数：

参数	描述
上下文	在 Context 参数中传递给 FsRtlCheckOplockEx的上下文信息指针。
Irp	指向 I/O 操作的 IRP 的指针。

返回值

FsRtlCheckOplockEx 返回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 包。如果 CompletionRoutine 为 NULL，则在处理 oplock 中断时，此例程将阻止，而不是返回STATUS_PENDING。 STATUS_PENDING是成功的代码。

言论

FsRtlCheckOplockEx 根据以下条件将 I/O 操作的 IRP 与文件的当前机会锁状态同步：

如果 I/O 操作将导致机会锁中断，则会启动机会锁中断。
如果 I/O 操作在机会锁中断完成并且指定了 CompletionRoutine 中的完成例程之前无法继续，FsRtlCheckOplockEx 返回STATUS_PENDING并调用在 postIrpRoutine中指定的回调例程。确认机会锁定中断后，将调用 CompletionRoutine 中的回调例程。
如果 I/O 操作在机会性锁中断完成并且 未指定 completionRoutine 之前无法继续，则在确认机会锁中断之前，FsRtlCheckOplockEx 将不会返回。

仅当指定了 CompletionRoutine 时，才应指定 PostIrpRoutine。

如果文件系统或筛选器驱动程序使用机会锁，则它必须从任何可能导致机会锁中断的调度例程中调用 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 文档。

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

要求

要求	价值
最低支持的客户端	Windows Vista
目标平台	普遍
标头	ntifs.h （include Ntifs.h）
库	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= APC_LEVEL