FltCheckOplock 函数 (fltkernel.h)

项目
08/07/2023

微筛选器驱动程序调用 FltCheckOplock 以将基于 IRP 的文件 I/O 操作的回调数据结构与文件的当前机会锁同步 (oplock) 状态。

语法

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

参数

[in] Oplock

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

[in] CallbackData

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

[in, optional] Context

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

[in, optional] WaitCompletionRoutine

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

此例程声明如下：

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

此例程具有以下参数：

CallbackData

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

上下文

在 Context 参数中传递到 FltCheckOplock 的上下文信息指针。

[in, optional] PrePostCallbackDataRoutine

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

此例程声明如下：

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

CallbackData

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

上下文

在 Context 参数中传递到 FltCheckOplock 的上下文信息指针。

返回值

FltCheckOplock 返回以下FLT_PREOP_CALLBACK_STATUS代码之一：

返回代码	说明
FLT_PREOP_COMPLETE	FltCheckOplock 遇到池分配失败，或者对 FsRtlCheckOplock 函数的调用返回错误。 FltCheckOplock 将在 FLT_CALLBACK_DATA 回调数据结构的 IoStatus 成员的 IO_STATUS_BLOCK 结构的 Status 成员中设置错误代码。 CallbackData 参数指向此FLT_CALLBACK_DATA。
FLT_PREOP_PENDING	启动 oplock 中断，导致筛选器管理器将 I/O 操作发布到工作队列。 I/O 操作由 CallbackData 参数指向的回调数据表示。
FLT_PREOP_SUCCESS_WITH_CALLBACK	I/O 操作已立即执行。请注意，如果此操作是在 create-options 参数中指定FILE_COMPLETE_IF_OPLOCKED的创建操作，则即使立即执行该操作，实际上也可能存在 oplock 中断。若要确定是否是这种情况，调用方应在FLT_CALLBACK_DATA回调数据结构的 IoStatus 成员的 IO_STATUS_BLOCK 结构的 Status 成员中检查状态。

注解

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

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

如果微筛选器驱动程序使用 oplock，则必须从任何预操作回调 (调用 FltCheckOplock，PFLT_PRE_OPERATION_CALLBACK) 可能导致 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

I/O 操作必须是基于 IRP 的 I/O 操作。若要确定给定的回调数据结构是否表示基于 IRP 的 I/O 操作，请使用 FLT_IS_IRP_OPERATION 宏。

微筛选器不得在 WaitCompletionRoutine 中指定的回调中再次调用 FltCheckOplock。如果 oplock 包在 FltCheckOplock 返回之前调用完成回调，则这样做可能会导致死锁情况。

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