Функция FltCbdqInitialize (fltkernel.h)

Статья
02/06/2025

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
      );

Кбрк

Указатель на очередь данных обратного вызова с отменой безопасности драйвера минифильтра. Эта очередь должна быть инициализирована путем вызова FltCbdqInitialize.

Кбр

Указатель на структуру данных обратного вызова, которую необходимо вставить в очередь.

InsertContext

Указатель сведений о контексте, переданный в качестве параметра InsertContext, FltCbdqInsertIo.

[in] CbdqRemoveIo

Указатель на подпрограмму обратного вызова, предоставленного вызывающим абонентом. Диспетчер фильтров вызывает эту подпрограмму, чтобы удалить указанную структуру данных обратного вызова из очереди. Эта подпрограмма объявлена следующим образом:

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

Кбрк

Кбр

Указатель на структуру данных обратного вызова, которую нужно удалить из очереди.

[in] CbdqPeekNextIo

Указатель на подпрограмму обратного вызова, предоставленного вызывающим абонентом. Диспетчер фильтров вызывает эту функцию, чтобы получить указатель на следующую операцию ввода-вывода, соответствующую PeekContext в очереди; или, если КбрNULL, чтобы получить указатель на первую соответствующую операцию ввода-вывода в очереди. Драйвер минифильтра полностью определяет значение PeekContext и определяет, когда операция ввода-вывода соответствует заданной 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
      );

Кбрк

Кбр

Указатель на структуру данных обратного вызова, помеченную позицией в очереди, чтобы начать поиск соответствия PeekContext. Если КбрNULL, поиск начинается в начале очереди.

PeekContext

Указатель сведений о контексте, переданный в качестве параметра PeekContext для FltCbdqRemoveNextIo.

[in] CbdqAcquire

Указатель на подпрограмму обратного вызова блокировки блокировки очереди, предоставленной вызывающим абонентом. Диспетчер фильтров вызывает эту подпрограмму, чтобы получить блокировку очереди перед попыткой вставки или удаления элемента из очереди. Эта подпрограмма объявлена следующим образом:

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

Кбрк

Irql

Указатель на системную переменную, которая получает текущий IRQL. Та же переменная передается соответствующей подпрограмме CbdqRelease.

[in] CbdqRelease

Указатель на подпрограмму обратного вызова блокировки блокировки очереди вызова очереди, предоставленной вызывающим абонентом. Диспетчер фильтров вызывает эту подпрограмму, чтобы освободить блокировку, полученную путем вызова соответствующей процедуры CbdqAcquire. Эта подпрограмма объявлена следующим образом:

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

Кбрк

Irql

Та же системная переменная, которая получила текущий IRQL, что и параметр Irql соответствующей подпрограмме CbdqAcquir e.

[in] CbdqCompleteCanceledIo

Указатель на подпрограмму отмены, предоставленной вызывающим абонентом. Диспетчер фильтров вызывает эту подпрограмму, чтобы сигнализировать драйверу минифильтра, чтобы завершить отмененную операцию ввода-вывода. Эта подпрограмма объявлена следующим образом:

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

Кбрк

Кбр

Указатель на структуру данных обратного вызова для отмененной операции ввода-вывода.

Возвращаемое значение

FltCbdqInitialize возвращает STATUS_SUCCESS или соответствующее значение NTSTATUS.

Замечания

Только что инициализированная очередь данных обратного вызова находится в состоянии включено, что означает, что элементы структуры данных обратного вызова можно вставить в очередь. Очередь может быть отключена путем вызова FltCbdqDisable и повторной обработки путем вызова FltCbdqEnable.

Драйверы минифильтра могут использовать FltCbdqxxx подпрограммы для реализации очереди данных обратного вызова для операций ввода-вывода на основе IRP. Используя эти подпрограммы, драйверы мини-фильтра могут сделать свои очереди отмененными; система прозрачно обрабатывает отмену ввода-вывода для драйверов мини-фильтра.

Подпрограммы FltCbdqXxx можно использовать только для операций ввода-вывода на основе IRP. Чтобы определить, представляет ли данная структура данных обратного вызова операцию ввода-вывода на основе IRP, используйте макрос FLT_IS_IRP_OPERATION.

Драйверы мини-фильтра могут использовать любую внутреннюю реализацию для очереди. Диспетчер фильтров взаимодействует с реализацией очереди минифильтратора исключительно с помощью набора подпрограмм диспетчера, предоставляемых FltCbdqInitialize.

Система автоматически блокирует и разблокирует очередь по мере необходимости. Минифильтры драйверов не реализуют блокировку внутри своих CbdqInsertIo, CbdqRemoveIoи КбркПеекNextIo подпрограммы.

Драйверы минифильтра могут использовать любой из примитивов синхронизации операционной системы в качестве механизма блокировки в КбркAcquire и КбркRelease подпрограмм, таких как блокировки спин-блокировки, объекта мьютексаили переменной ресурсов. Обратите внимание, что если драйвер мини-фильтра использует блокировку спина, а не мьютекс или ресурс для защиты очереди, он может вызывать FltCbdqXxx подпрограммы в IRQL <= DISPATCH_LEVEL. Если используется мьютекс или ресурс, драйвер минифильтра должен работать в IRQL <= APC_LEVEL при вызове любой из этих подпрограмм, кроме FltCbdqInitialize.

Драйвер минифильтра не управляет очередью напрямую. Вместо этого он вызывает FltCbdqInsertIo, FltCbdqRemoveIoи FltCbdqRemoveNextIo для добавления или удаления структуры данных обратного вызова. Эти подпрограммы, в свою очередь, вызывают функции обратного вызова, предоставляемые драйвером минифильтра для FltCbdqInitialize.

Драйверы минифильтра должны реализовать подпрограммы очереди следующим образом.

Подпрограмма Кбрк	Реализация
CbdqInsertIo	Вставьте указанную структуру данных обратного вызова в очередь.
CbdqRemoveIo	Удалите указанную структуру данных обратного вызова из очереди.
CbdqPeekNextIo	Эта подпрограмма должна позволить системе выполнять цикл по структурам данных обратного вызова с сопоставлением PeekContext в очереди. Кбр = CbdqPeekNextIo(Кбрк, NULL, PeekContext) должен возвращать первую соответствующую запись в очереди, и CbdqPeekNextIo(Cbdq, Кбр, PeekContext) должны возвращать следующую соответствующую запись после заданной структуры данных обратного вызова в очереди. Драйвер минифильтра полностью определяет значение PeekContext и определяет, когда структура данных обратного вызова соответствует значению PeekContext.
CbdqAcquire	Эта подпрограмма должна заблокировать очередь, чтобы к нему не могли получить доступ другие потоки. Драйверы мини-фильтра могут использовать любой механизм блокировки для блокировки очереди. Если драйвер минифильтра использует подпрограмму KeAcquireSpinLock, драйвер минифильтра может использовать расположение памяти, на которое указывает параметра Irql подпрограммы для хранения IRQL. В противном случае драйверы минифильтра могут игнорировать этот параметр.
CbdqRelease	Эта подпрограмма должна разблокировать очередь, созданную CbdqAcquire. Если драйвер минифильтра использовал блокировку спина и вернул значение IRQL в параметре IrqlCbdqAcquire, система передает это значение в параметре Irql CbdqRelease. Драйвер минифильтра может использовать IRQL для разблокировки блокировки спина путем вызова KeReleaseSpinLock. В противном случае драйверы минифильтра могут игнорировать параметр Irql.
CbdqCompleteCanceledIo	Эта подпрограмма должна завершить отмененную операцию ввода-вывода. Как правило, драйверы мини-фильтра могут просто вызывать FltCompletePendedPreOperation(Data, FLT_PREOP_COMPLETE, NULL). Драйверы минифильтра не нужно отменять структуру данных обратного вызова. Диспетчер фильтров автоматически вызывает КбркRemoveIo перед вызовом CbdqCompleteCanceledIo.