FltCheckOplockEx 函数（fltkernel.h）

微型筛选器驱动程序调用 FltCheckOplockEx 例程，以同步基于 IRP 的 I/O作的回调数据结构，该作具有文件的当前机会锁（oplock）状态。

Syntax

FLT_PREOP_CALLBACK_STATUS FLTAPI FltCheckOplockEx(
  [in]           POPLOCK                                 Oplock,
  [in]           PFLT_CALLBACK_DATA                      CallbackData,
  [in]           ULONG                                   Flags,
  [in, optional] PVOID                                   Context,
  [in, optional] PFLTOPLOCK_WAIT_COMPLETE_ROUTINE        WaitCompletionRoutine,
  [in, optional] PFLTOPLOCK_PREPOST_CALLBACKDATA_ROUTINE PrePostCallbackDataRoutine
);

Parameters

[in] Oplock

文件的不透明不透明不透明指针。此指针必须由之前对 FltInitializeOplock 的调用进行初始化。

[in] CallbackData

指向 I/O作 FLT_CALLBACK_DATA 结构的回调数据的指针。

[in] Flags

关联的文件 I/O 操作的位掩码。微型筛选器驱动程序设置位以指定 FltCheckOplockEx 的行为。标志可以是以下一个或多个值。

Flag	Description
OPLOCK_FLAG_COMPLETE_IF_OPLOCKED（0x00000001）	允许机会锁中断继续，而不会阻止或挂起导致操作锁中断的操作。
OPLOCK_FLAG_OPLOCK_KEY_CHECK_ONLY（0x00000002）	指定 FltCheckOplockEx 应仅检查与 I/O作关联的FILE_OBJECT上的机会锁键。此 I/O作由 CallbackData 参数指向的回调数据表示。如果 I/O作中提供了密钥，则 FltCheckOplockEx 必须添加密钥。没有发生其他 oplock 处理;也就是说，不会发生机会锁中断。
OPLOCK_FLAG_BACK_OUT_ATOMIC_OPLOCK（0x00000004）	指定 FsRtlCheckOplockEx 应还原以前通过调用 FltOplockFsctrl 例程设置的任何状态。处理IRP_MJ_CREATE请求时调用 FltOplockFsctrl。此IRP_MJ_CREATE请求指定 create options 参数中的FILE_OPEN_REQUIRING_OPLOCK标志。 OPLOCK_FLAG_BACK_OUT_ATOMIC_OPLOCK标志通常用于以前失败时此类创建请求的最终处理。
OPLOCK_FLAG_IGNORE_OPLOCK_KEYS（0x00000008）	允许所有机会锁中断继续进行，而不考虑机会锁键。

[in, optional] Context

指向要传递给 WaitCompletionRoutine 和 PrePostCallbackDataRoutine 指向的回调例程的调用方定义的上下文信息的指针。筛选器管理器将此信息视为不透明。

[in, optional] WaitCompletionRoutine

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

此例程声明如下：

typedef VOID
(*PFLTOPLOCK_WAIT_COMPLETE_ROUTINE) (
      IN PFLT_CALLBACK_DATA CallbackData,
      IN PVOID Context
      );

此例程具有以下参数：

CallbackData 是指向 I/O作的回调数据结构的指针。调用 WaitCompleteRoutine 时，IoStatus 子结构可能会填充失败状态（例如STATUS_CANCELLED）。应检查此状态并做出适当的反应。
Context 是上下文信息指针，在 Context 参数中传递给 FltCheckOplockEx。

[in, optional] PrePostCallbackDataRoutine

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

此例程声明如下：

typedef VOID
(*PFLTOPLOCK_PREPOST_CALLBACKDATA_ROUTINE) (
      IN PFLT_CALLBACK_DATA CallbackData,
      IN PVOID Context
      );

CallbackData 是指向 I/O作的回调数据结构的指针。
Context 是上下文信息指针，在 Context 参数中传递给 FltCheckOplockEx。

返回值

FltCheckOplockEx 返回以下FLT_PREOP_CALLBACK_STATUS代码之一：

返回代码	Description
FLT_PREOP_COMPLETE	FltCheckOplockEx 遇到池分配失败，或者对 FsRtlCheckOplockEx 函数的调用返回了错误。 FltCheckOplockEx 在FLT_CALLBACK_DATA回调数据结构的 IoStatus 成员IO_STATUS_BLOCK结构的状态成员中设置错误代码。 CallbackData 参数指向此FLT_CALLBACK_DATA结构。
FLT_PREOP_PENDING	已启动操作锁中断，这导致筛选器管理器将 I/O 操作发布到工作队列。 I/O作由 CallbackData 参数指向的回调数据表示。
FLT_PREOP_SUCCESS_WITH_CALLBACK	CallbackData 参数指向的回调数据未插入，并且 I/O作会立即执行。请注意，如果在 Flags 参数中指定的调用方OPLOCK_FLAG_COMPLETE_IF_OPLOCKED，则即使 I/O作未插入，oplock 中断实际上也可能正在进行中。若要确定这种情况是否为这种情况，调用方应检查FLT_CALLBACK_DATA回调数据结构的 ioStatus 成员IO_STATUS_BLOCK结构的状态成员中的STATUS_OPLOCK_BREAK_IN_PROGRESS。

Remarks

微型筛选器驱动程序调用 FltCheckOplockEx ，以便根据以下条件将基于 IRP 的 I/O作与文件的当前 oplock 状态同步：

如果 I/O 操作将导致 oplock 中断，则会启动 oplock 中断。
如果 I/O作在 oplock 中断完成之前无法继续， FltCheckOplockEx 将返回FLT_PREOP_PENDING并调用 PrePostCallbackDataRoutine 参数指向的回调例程。
如果微型筛选器驱动程序使用 oplocks，则它必须从任何预作回调（PFLT_PRE_OPERATION_CALLBACK）例程调用 FltCheckOplockEx，以便执行可能导致 oplock 中断的 I/O作。此规则适用于以下类型的 I/O 操作，因为这些操作可能会导致 oplock 中断：
- 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
- IRP_MJ_ACQUIRE_FOR_SECTION_SYNCHRONIZATION