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

Статья
08/07/2023

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

Синтаксис

NTSTATUS FLTAPI FltAllocateCallbackData(
  [in]           PFLT_INSTANCE      Instance,
  [in, optional] PFILE_OBJECT       FileObject,
  [out]          PFLT_CALLBACK_DATA *RetNewCallbackData
);

Параметры

[in] Instance

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

[in, optional] FileObject

Указатель на объект файла, используемый в операции ввода-вывода. Этот параметр является необязательным и может иметь значение NULL.

[out] RetNewCallbackData

Указатель на переменную, выделенную вызывающим объектом, которая получает адрес новой структуры данных обратного вызова (FLT_CALLBACK_DATA).

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

FltAllocateCallbackData возвращает STATUS_SUCCESS или соответствующее значение NTSTATUS, например следующее:

Код возврата	Описание
STATUS_INSUFFICIENT_RESOURCES	FltAllocateCallbackData столкнулся с ошибкой выделения пула при попытке выделить структуру данных обратного вызова. Это код ошибки.

Драйвер минифильтра может вызывать FltAllocateCallbackData , чтобы выделить структуру данных обратного вызова (FLT_CALLBACK_DATA) для операции ввода-вывода, инициированной драйвером минифильтра.

Примечание Подпрограмма FltAllocateCallbackData не выделяет всю память, которая может потребоваться для последующего запроса ввода-вывода. Если запрос ввода-вывода, например FltPerformSynchronousIo или FltPerformAsynchronousIo, требует дополнительной памяти для определенной структуры, запрос может столкнуться с выделением памяти. Чтобы избежать этой потенциальной проблемы, можно использовать подпрограмму FltAllocateCallbackDataEx , предварительно наделив память для дополнительных структур, которые будут использоваться в запросе ввода-вывода. Если возникает проблема с выделением памяти для структуры RetNewCallbackData или дополнительных необходимых структур, ее можно решить в точке выделения данных обратного вызова.

Структуры данных обратного вызова выделяются из непагированного пула.

После инициализации параметров структуры данных обратного вызова, возвращаемой FltAllocateCallbackData, вызывающий объект инициирует операцию ввода-вывода, передав структуру FltPerformSynchronousIo или FltPerformAsynchronousIo. Эти подпрограммы отправляют операцию ввода-вывода только в экземпляры драйвера минифильтра, подключенные под инициирующим экземпляром (указанный в параметре Instance ), и в файловую систему. Драйверы минифильтра, подключенные над указанным экземпляром, не получают операцию ввода-вывода.

Драйверы минифильтра могут инициировать только операции ввода-вывода на основе IRP. Они не могут инициировать операции обратного вызова быстрого ввода-вывода или фильтра файловой системы (FSFilter).

Драйверы минифильтра должны использовать FltAllocateCallbackData, FltPerformAsynchronousIo и FltPerformSynchronousIo только для операций ввода-вывода, для которых нельзя использовать такие подпрограммы:

FltClose

FltCreateFile

FltQueryVolumeInformation

FltReadFile

FltSetVolumeInformation

FltTagFile

FltUntagFile

FltWriteFile

Если структура данных обратного вызова, выделенная FltAllocateCallbackData , больше не нужна, вызывающий объект отвечает за ее освобождение путем вызова FltFreeCallbackData.

Требования

Требование	Значение
Целевая платформа	Универсальное
Верхняя часть	fltkernel.h (включая Fltkernel.h)
Библиотека	FltMgr.lib
IRQL	<= APC_LEVEL