fltCbdqInitialize 函数 (fltkernel.h)

项目
08/07/2023

FltCbdqInitialize 初始化微筛选器驱动程序的回调数据队列调度表。

语法

NTSTATUS FLTAPI FltCbdqInitialize(
  [in]      PFLT_INSTANCE                                 Instance,
  [in, out] PFLT_CALLBACK_DATA_QUEUE                      Cbdq,
  [in]      PFLT_CALLBACK_DATA_QUEUE_INSERT_IO            CbdqInsertIo,
  [in]      PFLT_CALLBACK_DATA_QUEUE_REMOVE_IO            CbdqRemoveIo,
  [in]      PFLT_CALLBACK_DATA_QUEUE_PEEK_NEXT_IO         CbdqPeekNextIo,
  [in]      PFLT_CALLBACK_DATA_QUEUE_ACQUIRE              CbdqAcquire,
  [in]      PFLT_CALLBACK_DATA_QUEUE_RELEASE              CbdqRelease,
  [in]      PFLT_CALLBACK_DATA_QUEUE_COMPLETE_CANCELED_IO CbdqCompleteCanceledIo
);

参数

[in] Instance

要初始化其回调数据队列的实例的不透明实例指针。

[in, out] Cbdq

指向微筛选器驱动程序分配的回调数据队列的指针。

[in] CbdqInsertIo

指向调用方提供的插入回调例程的指针。筛选器管理器调用此例程以将指定的回调数据结构插入队列中。此例程的声明如下：

typedef NTSTATUS
(*PFLT_CALLBACK_DATA_QUEUE_INSERT_IO)(
      _Inout_ PFLT_CALLBACK_DATA_QUEUE Cbdq,
      _In_ PFLT_CALLBACK_DATA Cbd,
      _In_opt_ PVOID InsertContext
      );

Cbdq

指向微筛选器驱动程序的取消安全回调数据队列的指针。此队列必须已通过调用 FltCbdqInitialize 进行初始化。

Cbd

指向要插入队列的回调数据结构的指针。

InsertContext

作为 InsertContext 参数传递给 FltCbdqInsertIo 的上下文信息指针。

[in] CbdqRemoveIo

指向调用方提供的删除回调例程的指针。筛选器管理器调用此例程以从队列中删除指定的回调数据结构。此例程的声明如下：

typedef VOID
(*PFLT_CALLBACK_DATA_QUEUE_REMOVE_IO)(
      _Inout_ PFLT_CALLBACK_DATA_QUEUE Cbdq,
      _In_ PFLT_CALLBACK_DATA Cbd
      );

Cbdq

指向微筛选器驱动程序的取消安全回调数据队列的指针。此队列必须已通过调用 FltCbdqInitialize 进行初始化。

Cbd

指向要从队列中删除的回调数据结构的指针。

[in] CbdqPeekNextIo

指向调用方提供的速览回调例程的指针。筛选器管理器调用此函数以获取指向队列中与 PeekContext 匹配的下一个 I/O 操作的指针;或者，如果 Cbd 为 NULL，则获取指向队列中第一个匹配 I/O 操作的指针。微筛选器驱动程序完全定义 PeekContext 的含义，并定义 I/O 操作何时与给定 的 PeekContext 匹配。此例程的声明如下：

typedef PFLT_CALLBACK_DATA
(*PFLT_CALLBACK_DATA_QUEUE_PEEK_NEXT_IO)(
      _In_ PFLT_CALLBACK_DATA_QUEUE Cbdq,
      _In_opt_ PFLT_CALLBACK_DATA Cbd,
      _In_opt_ PVOID PeekContext
      );

Cbdq

指向微筛选器驱动程序的取消安全回调数据队列的指针。此队列必须已通过调用 FltCbdqInitialize 进行初始化。

Cbd

指向回调数据结构的指针，该结构标记队列中要开始搜索 与 PeekContext 的匹配项的位置。如果 Cbd 为 NULL，则搜索从队列的头开始。

PeekContext

作为 PeekContext 参数传递给 FltCbdqRemoveNextIo 的上下文信息指针。

[in] CbdqAcquire

指向调用方提供的获取队列锁回调例程的指针。在尝试在队列中插入或删除项之前，筛选器管理器调用此例程来获取队列上的锁。此例程的声明如下：

typedef VOID
(*PFLT_CALLBACK_DATA_QUEUE_ACQUIRE)(
      _Inout_ PFLT_CALLBACK_DATA_QUEUE Cbdq,
      _Out_opt_ PKIRQL Irql
      );

Cbdq

指向微筛选器驱动程序的取消安全回调数据队列的指针。此队列必须已通过调用 FltCbdqInitialize 进行初始化。

Irql

指向接收当前 IRQL 的系统提供的变量的指针。将同一变量传递给相应的 CbdqRelease 例程。

[in] CbdqRelease

指向调用方提供的释放队列锁回调例程的指针。筛选器管理器调用此例程以释放它通过调用相应的 CbdqAcquire 例程获取的锁。此例程的声明如下：

typedef VOID
(*PFLT_CALLBACK_DATA_QUEUE_RELEASE)(
      _Inout_ PFLT_CALLBACK_DATA_QUEUE Cbdq,
      _In_opt_ KIRQL Irql
      );

Cbdq

指向微筛选器驱动程序的取消安全回调数据队列的指针。此队列必须已通过调用 FltCbdqInitialize 进行初始化。

Irql

系统提供的同一变量，该变量接收当前 IRQL 作为相应 CbdqAcquire 例程的 Irql 参数。

[in] CbdqCompleteCanceledIo

指向调用方提供的取消例程的指针。筛选器管理器调用此例程以向微筛选器驱动程序发出信号，以完成取消的 I/O 操作。此例程的声明如下：

typedef VOID
(*PFLT_CALLBACK_DATA_QUEUE_COMPLETE_CANCELED_IO)(
      _Inout_ PFLT_CALLBACK_DATA_QUEUE Cbdq,
      _Inout_ PFLT_CALLBACK_DATA Cbd
      );

Cbdq

指向微筛选器驱动程序的取消安全回调数据队列的指针。此队列必须已通过调用 FltCbdqInitialize 进行初始化。

Cbd

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

返回值

FltCbdqInitialize 返回STATUS_SUCCESS或适当的 NTSTATUS 值。

注解

新初始化的回调数据队列处于启用状态，这意味着可以将回调数据结构项插入队列中。可以通过调用 FltCbdqDisable 来禁用队列，并通过调用 FltCbdqEnable 重新启用队列。

微筛选器驱动程序可以使用 FltCbdqXxx 例程为基于 IRP 的 I/O 操作实现回调数据队列。通过使用这些例程，微筛选器驱动程序可以使其队列取消安全;系统以透明方式处理微筛选器驱动程序的 I/O 取消。

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

微筛选器驱动程序可以使用队列的任何内部实现。筛选器管理器仅通过 FltCbdqInitialize 提供的一组调度例程与微筛选器驱动程序的队列实现进行交互。

系统根据需要自动锁定和解锁队列。微筛选器驱动程序不会在其 CbdqInsertIo、 CbdqRemoveIo 和 CbdqPeekNextIo 例程中实现任何锁定。

微筛选器驱动程序可以使用操作系统的任何同步基元作为其 CbdqAcquire 和 CbdqRelease 例程中的锁定机制，例如旋转锁、互斥对象或资源变量。请注意，如果微筛选器驱动程序使用旋转锁而不是互斥锁或资源来保护队列，它可以在 IRQL <= DISPATCH_LEVEL调用 FltCbdqXxx 例程。如果使用互斥体或资源，则在调用除 FltCbdqInitialize 之外的任何例程时，微筛选器驱动程序必须在 IRQL <= APC_LEVEL 运行。

微筛选器驱动程序不会直接操作队列。相反，它调用 FltCbdqInsertIo、 FltCbdqRemoveIo 和 FltCbdqRemoveNextIo 来添加或删除回调数据结构。这些例程依次调用微筛选器驱动程序提供给 FltCbdqInitialize 的回调函数。

微筛选器驱动程序应按如下所示实现队列例程。

Cbdq 例程	实现
CbdqInsertIo	将指定的回调数据结构插入队列中。
CbdqRemoveIo	从队列中删除指定的回调数据结构。
CbdqPeekNextIo	此例程应允许系统循环访问队列中具有匹配的 PeekContext 的回调数据结构。 Cbd = CbdqPeekNextIo (Cbdq、NULL、PeekContext) 应返回队列中的第一个匹配项，CbdqPeekNextIo (Cbdq、PeekContext) 应返回队列中给定回调数据结构之后的下一个匹配条目。微筛选器驱动程序完全定义 PeekContext 的含义，并定义回调数据结构何时与 PeekContext 值匹配。
CbdqAcquire	此例程应锁定队列，以便其他线程无法访问它。微筛选器驱动程序可以使用任何锁定机制来锁定队列。如果微筛选器驱动程序使用 KeAcquireSpinLock 例程，则微筛选器驱动程序可以使用例程的 Irql 参数指向的内存位置来存储 IRQL。否则，微筛选器驱动程序可以忽略该参数。
CbdqRelease	此例程应解锁 CbdqAcquire 创建的队列。如果微筛选器驱动程序使用自旋锁并返回 CbdqAcquire 的 Irql 参数中的 IRQL 值，则系统会在 CbdqRelease 的 Irql 参数中传递该值。微筛选器驱动程序可以使用 IRQL 通过调用 KeReleaseSpinLock 来解锁旋转锁。否则，微筛选器驱动程序可以忽略 Irql 参数。
CbdqCompleteCanceledIo	此例程应完成已取消的 I/O 操作。通常，微筛选器驱动程序只能调用 FltCompletePendedPreOperation (Data、FLT_PREOP_COMPLETE、 NULL) 。微筛选器驱动程序不需要取消回调数据结构的排队 -- 筛选器管理器在调用 CbdqCompleteCanceledIo 之前会自动调用队列的 CbdqRemoveIo。