FsRtlCheckOplockEx 函数 (ntifs.h)

项目
02/29/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 的行为。 Flags 参数具有以下选项：

值	含义
OPLOCK_FLAG_COMPLETE_IF_OPLOCKED (0x00000001)	指定允许机会性锁中断继续进行而不阻止或挂起导致 oplock 中断的操作。
OPLOCK_FLAG_OPLOCK_KEY_CHECK_ONLY (0x00000002)	从 Windows 7 开始受支持。指定 FsRtlCheckOplockEx 应仅对与 Irp 参数指向的 IRP 关联的FILE_OBJECT上的机会锁键检查。然后，如果 IRP 中提供了密钥，则 FsRtlCheckOplockEx 必须添加密钥。不会发生其他 oplock 处理;也就是说，不会发生机会性锁中断。
OPLOCK_FLAG_BACK_OUT_ATOMIC_OPLOCK (0x00000004)	从 Windows 7 开始受支持。指定 FsRtlCheckOplockEx 应还原之前通过调用 FsRtlOplockFsctrl 例程设置的任何状态。 FsRtlOplockFsctrl 是在处理IRP_MJ_CREATE请求期间调用的，该请求在 create options 参数中指定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请求。 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，则此例程将在处理 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 操作。此规则适用于以下类型的 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 (包括 Ntifs.h)
Library	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= APC_LEVEL