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

Статья
02/06/2025

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

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

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

FltClose

FltCreateFile

FltQueryVolumeInformation

FltReadFile

FltSetVolumeInformation

FltTagFile

FltUntagFile

FltWriteFile

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

Требования

Требование	Ценность
целевая платформа	Всеобщий
заголовка	fltkernel.h (include Fltkernel.h)
библиотеки	FltMgr.lib
IRQL	<= APC_LEVEL