Share via

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

  • Статья

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.

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

Кбрюк

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

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

Кбрюк

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

Cbd

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

PeekContext

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

[in] CbdqAcquire

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

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

Кбрюк

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

Irql

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

[in] CbdqRelease

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

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

Кбрюк

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

Irql

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

[in] CbdqCompleteCanceledIo

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

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

Кбрюк

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

Cbd

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

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

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

Комментарии

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

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

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

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

При необходимости система автоматически блокирует и разблокирует очередь. Драйверы минифильтра не реализуют блокировку внутри процедур CbdqInsertIo, CbdqRemoveIo и CbdqPeekNextIo .

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

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

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

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

Требования

Требование Значение
Целевая платформа Универсальное
Верхняя часть fltkernel.h (включая Fltkernel.h)
IRQL Любой уровень

См. также раздел

FLT_CALLBACK_DATA

FLT_CALLBACK_DATA_QUEUE

FLT_IS_IRP_OPERATION

FltCbdqDisable

FltCbdqEnable

FltCbdqInsertIo

FltCbdqRemoveIo

FltCbdqRemoveNextIo

FltCompletePendedPreOperation

KeAcquireSpinLock

KeReleaseSpinLock