FsRtlCheckOplockEx 函数 (ntifs.h)

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请求期间调用的,该请求指定创建选项参数中的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 开始。

指定 OplockIrp 参数中 IRP 定向到的文件或目录的父 (目录) 关联。

OPLOCK_FLAG_CLOSING_DELETE_ON_CLOSE (0x00000020)

支持从 Windows 8 开始。

指定 Irp 中指定的 I/O 操作是最初在其创建选项中设置FILE_DELETE_ON_CLOSE标志打开的句柄的IRP_MJ_CLEANUP。 如果 Irp 不是IRP_MJ_CLEANUP操作,则此标志无效。 指定此标志可能会导致机会锁中断。

支持从 Windows 8 开始。

指定删除该目录中的文件或链接时,在父目录中处理机会锁中断。 如果指定,则必须将此标志与OPLOCK_FLAG_PARENT_OBJECT结合使用。 当文件系统正在处理导致删除链接或文件的操作时,必须指定此标志。

[in, optional] Context

指向要传递给 CompletionRoutinePostIrpRoutine 参数指向的回调例程的调用方定义的上下文信息的指针。

[in, optional] CompletionRoutine

指向调用方提供的回调例程的指针。 如果机会锁中断正在进行中,则此例程在中断完成时调用。 此参数是可选的,可以为 NULL。 如果为 NULL,则调用方将进入等待状态,直到机会锁中断完成。

此例程声明如下:

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

此例程具有以下参数:

上下文

上下文信息指针,在 上下文 参数中传递给 FsRtlCheckOplockEx

Irp

指向 I/O 操作的 IRP 的指针。

[in, optional] PostIrpRoutine

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

此例程声明如下:

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

上下文

上下文信息指针,在 上下文 参数中传递给 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 包。 如果 CompletionRoutineNULL则 FsRtlCheckOplockEx 会在处理机会锁中断时阻止,而不是返回STATUS_PENDING。 STATUS_PENDING是一个成功代码。

注解

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

  • 如果 I/O 操作将导致机会锁中断,则会启动机会锁中断。
  • 如果 I/O 操作在机会性锁中断完成且指定 CompleteRoutine 中的完成例程之前无法继续, FsRtlCheckOplockEx 将返回STATUS_PENDING并调用 PostIrpRoutine 中指定的回调例程。 当确认机会锁中断时,将调用 CompletionRoutine 中的回调例程。
  • • 如果 I/O 操作无法继续,直到机会性锁中断完成且未指定 CompleteRoutine则 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

要求

   
最低受支持的客户端 FsRtlCheckOplockEx 例程从 Windows Vista 开始可用。
目标平台 通用
标头 ntifs.h (包括 Ntifs.h)
Library NtosKrnl.lib
DLL NtosKrnl.exe
IRQL <= APC_LEVEL

请参阅

FSCTL_OPBATCH_ACK_CLOSE_PENDING

FSCTL_OPLOCK_BREAK_ACKNOWLEDGE

FSCTL_OPLOCK_BREAK_ACK_NO_2

FSCTL_OPLOCK_BREAK_NOTIFY

FSCTL_REQUEST_BATCH_OPLOCK

FSCTL_REQUEST_FILTER_OPLOCK

FSCTL_REQUEST_OPLOCK_LEVEL_1

FSCTL_REQUEST_OPLOCK_LEVEL_2

FltCheckOplockEx

FsRtlCurrentBatchOplock

FsRtlInitializeOplock

FsRtlOplockFsctrl

FsRtlOplockIsFastIo 可能

FsRtlUninitializeOplock