FsRtlCheckOplock 函数 (ntifs.h)

项目
10/04/2023

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 参数指向的回调例程。

如果文件系统或筛选器驱动程序使用机会锁，则必须从任何可能导致机会锁中断的 I/O 操作调度例程调用 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)
Library	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= APC_LEVEL