FsRtlCheckOplock 函数（ntifs.h）

项目
12/21/2024

FsRtlCheckOplock 例程将文件 I/O 操作的 IRP 与文件的当前机会锁（oplock）状态同步。

语法

NTSTATUS FsRtlCheckOplock(
  [in]           POPLOCK                       Oplock,
  [in]           PIRP                          Irp,
  [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, optional] Context

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

[in, optional] CompletionRoutine

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

此例程声明如下：

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

此例程具有以下参数：

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

[in, optional] PostIrpRoutine

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

此例程声明如下：

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

此例程具有以下参数：

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

返回值

FsRtlCheckOplock 例程返回STATUS_SUCCESS或相应的 NTSTATUS 代码，例如以下代码之一：

返回代码	描述
STATUS_CANCELLED	IRP 已取消。 STATUS_CANCELLED是错误代码。
STATUS_CANNOT_BREAK_OPLOCK	如果 IRP 是IRP_MJ_CREATE且FILE_OPEN_REQUIRING_OPLOCK位于 IRP 的 CreateOptions 中，则例程不会启动现有机会锁的中断，但失败并STATUS_CANNOT_BREAK_OPLOCK。
STATUS_OPLOCK_BREAK_IN_PROGRESS	机会锁中断正在进行中。 IRP 是一个IRP_MJ_CREATE请求，FILE_COMPLETE_IF_OPLOCKED是在操作的 create options 参数中指定的。 STATUS_OPLOCK_BREAK_IN_PROGRESS是成功的代码。
STATUS_PENDING	已启动机会锁中断，并且 IRP 的控制已传递到 oplock 包。如果 CompletionRoutine 为 NULL，则在处理 oplock 中断时，此例程将阻止，而不是返回STATUS_PENDING。 STATUS_PENDING是成功的代码。

言论

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

如果 I/O 操作将导致机会锁中断，则会启动机会锁中断。
如果 I/O 操作在机会锁中断完成之前无法继续，FsRtlCheckOplock 返回STATUS_PENDING并调用 PostIrpRoutine 参数指向的回调例程。

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

有关机会锁的详细信息，请参阅 Windows SDK 文档。

微型筛选器应调用 FltCheckOplock，而不是 FsRtlCheckOplock。

要求

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