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

Статья
11/16/2023

FltReadFileEx считывает данные из открытого файла, потока или устройства. Эта функция расширяет fltReadFile , чтобы разрешить необязательное использование MDL для чтения данных вместо сопоставленного адреса буфера.

Синтаксис

NTSTATUS FLTAPI FltReadFileEx(
  [in]            PFLT_INSTANCE                    InitiatingInstance,
  [in]            PFILE_OBJECT                     FileObject,
  [in, optional]  PLARGE_INTEGER                   ByteOffset,
  [in]            ULONG                            Length,
  [out]           PVOID                            Buffer,
  [in]            FLT_IO_OPERATION_FLAGS           Flags,
  [out, optional] PULONG                           BytesRead,
  [in, optional]  PFLT_COMPLETED_ASYNC_IO_CALLBACK CallbackRoutine,
  [in, optional]  PVOID                            CallbackContext,
  [in, optional]  PULONG                           Key,
  [in, optional]  PMDL                             Mdl
);

Параметры

[in] InitiatingInstance

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

[in] FileObject

Указатель на FILE_OBJECT для файла, из который считываются данные. Этот файловый объект должен быть открыт в данный момент. Вызов FltReadFileEx , когда файловый объект еще не открыт или больше не открыт (например, в процедуре обратного вызова перед созданием или после очистки), приводит к тому, что система будет использовать ASSERT в проверенной сборке. Этот параметр является обязательным и не может иметь значение NULL.

[in, optional] ByteOffset

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

Если указан параметр ByteOffset , операции ввода-вывода выполняются с таким смещением независимо от текущего значения поля CurrentByteOffset объекта файла.

Если файл был открыт для синхронного ввода-вывода (FO_SYNCHRONOUS_IO задано в поле Флаги файлового объекта), вызывающий объект может задать для Параметра ByteOffset-LowPart> значение FILE_USE_FILE_POINTER_POSITION а для ByteOffset-HighPart значение -1, чтобы операции ввода-вывода> выполнялись в поле CurrentByteOffset объекта файла.
Если файл не был открыт для синхронного ввода-вывода, использование FILE_USE_FILE_POINTER_POSITION является ошибкой.

Если параметр ByteOffset не указан:

Если файл не был открыт для синхронного ввода-вывода, это ошибка.
В противном случае операции ввода-вывода выполняются в объекте CurrentByteOffset файла.

Если объект файла был открыт для синхронного ввода-вывода, поле CurrentByteOffset обновляется, если вызывающий объект не передает флаг FLTFL_IO_OPERATION_DO_NOT_UPDATE_BYTE_OFFSET.

Примечание. В этом случае файловая система по-прежнему обновляет CurrentByteOffset . Диспетчер фильтров сохраняет значение CurrentByteOffset перед отправкой ввода-вывода вниз стека и восстанавливает его при возврате ввода-вывода. С точки зрения вызывающего объекта FltReadFileEx (и фильтров на больших высотах) CurrrentByteOffset не обновляется. Но фильтры под вызывающим объектом видят обновленное значение CurrentByteOffset в обратных вызовах после чтения и записи.

Если файловый объект не был открыт для синхронного ввода-вывода, поле CurrentByteOffset не обновляется независимо от состояния параметра ByteOffset .

[in] Length

Размер (в байтах) буфера, на который указывает параметр Buffer .

[out] Buffer

Указатель на буфер, выделенный вызывающим объектом, который получает данные, считываемые из файла. Если MDL предоставляется в Mdl, буфер должен иметь значение NULL.

[in] Flags

Битовая маска флагов, указывающая тип выполняемой операции чтения.

Flag	Значение
FLTFL_IO_OPERATION_DO_NOT_UPDATE_BYTE_OFFSET	Драйверы минифильтра могут задать этот флаг, чтобы указать, что FltReadFile не должен обновлять поле Объекта файла CurrentByteOffset .
FLTFL_IO_OPERATION_NON_CACHED	Драйверы минифильтра могут задать этот флаг для указания некэшированного чтения, даже если файловый объект не был открыт с FILE_NO_INTERMEDIATE_BUFFERING.
FLTFL_IO_OPERATION_PAGING	Драйверы минифильтра могут задать этот флаг, чтобы указать чтение подкачки.
FLTFL_IO_OPERATION_SYNCHRONOUS_PAGING	Драйверы минифильтра могут задать этот флаг для указания синхронного чтения ввода-вывода подкачки. Драйверы минифильтра, устанавливающие этот флаг, также должны установить флаг FLTFL_IO_OPERATION_PAGING. Доступно, начиная с Windows Vista.

[out, optional] BytesRead

Указатель на переменную, выделенную вызывающим объектом, которая получает количество байтов, считанных из файла. Если CallbackRoutine не имеет значение NULL, этот параметр игнорируется. В противном случае этот параметр является необязательным и может иметь значение NULL.

[in, optional] CallbackRoutine

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

[in, optional] CallbackContext

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

[in, optional] Key

Необязательный ключ, связанный с блокировкой диапазона байтов.

[in, optional] Mdl

Необязательный MDL, описывающий память, в которой считываются данные. Если буфер предоставляется в буфере , то Mdl должен иметь значение NULL.

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

FltReadFileEx возвращает значение NTSTATUS, возвращенное файловой системой.

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

FltReadFileEx выполняет некэшированные ввод-вывод, если выполняется одно из следующих значений:

Вызывающий объект задает флаг FLTFL_IO_OPERATION_NON_CACHED в параметре Flags .
Файловый объект был открыт для ввода-вывода без кэширования. Обычно это делается путем указания флага FILE_NO_INTERMEDIATE_BUFFERING CreateOptions в предыдущем вызове FltCreateFile, FltCreateFileEx или ZwCreateFile.

Некэшированные операции ввода-вывода накладывают следующие ограничения на значения параметров, передаваемые в FltReadFileEx:

Буфер, на который указывает параметр Buffer , должен быть выровнен в соответствии с требованиями к выравниванию базового запоминающего устройства. Чтобы выделить такой выровненный буфер, вызовите Метод FltAllocatePoolAlignedWithTag.
Смещение байтов, на которое указывает параметр ByteOffset , должно быть неотрицательным, кратным размеру сектора тома.
Длина, указанная в параметре Length , должна быть неогрегативной, кратной размеру сектора тома.

Если предпринята попытка чтения за пределами конца файла, Функция FltReadFileEx возвращает ошибку.

Если значение параметра CallbackRoutine не равно NULL, операция чтения выполняется асинхронно.

Если значение параметра CallbackRoutine равно NULL, операция чтения выполняется синхронно. То есть FltReadFileEx ожидает завершения операции чтения перед возвратом. Это верно, даже если объект файла, на который указывает FileObject , был открыт для асинхронного ввода-вывода.

Если несколько потоков вызывают FltReadFileEx для одного и того же объекта файла, а файловый объект был открыт для синхронного ввода-вывода, диспетчер фильтров не пытается сериализовать операции ввода-вывода в файле. В этом отношении FltReadFileEx отличается от ZwReadFile.

Параметр Mdl предоставляется в качестве удобства, если минифильтр уже имеет доступный MDL. MDL используется напрямую, и можно избежать дополнительного шага сопоставления адреса для буфера .

Требования

Требование	Значение
Минимальная версия клиента	Windows 8
Целевая платформа	Универсальное
Верхняя часть	fltkernel.h (включая Fltkernel.h)
Библиотека	FltMgr.lib
DLL	Fltmgr.sys
IRQL	PASSIVE_LEVEL