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请求期间调用的,该请求在 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 |
另请参阅
FSCTL_OPBATCH_ACK_CLOSE_PENDING