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

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

Синтаксис

NTSTATUS FLTAPI FltWriteFileEx(
  [in]            PFLT_INSTANCE                    InitiatingInstance,
  [in]            PFILE_OBJECT                     FileObject,
  [in, optional]  PLARGE_INTEGER                   ByteOffset,
  [in]            ULONG                            Length,
  [in]            PVOID                            Buffer,
  [in]            FLT_IO_OPERATION_FLAGS           Flags,
  [out, optional] PULONG                           BytesWritten,
  [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 файла, в который записываются данные. Этот объект файла должен быть открыт в настоящее время. Вызов FltWriteFileEx , когда объект файла еще не открыт или больше не открыт (например, в подпрограмме обратного вызова предварительного создания или после очистки) приводит к тому, что система будет УТВЕРЖДАТЬ в проверенной сборке. Этот параметр является обязательным и не может иметь значение 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-LowPart> для FILE_WRITE_TO_END_OF_FILE и ByteOffset-HighPart>, чтобы -1 начать запись в конце файла (т. е. выполнить добавление записи).

Если ByteOffset не указан:

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

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

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

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

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

FltWriteFileEx не поддерживает флаг FILE_WRITE_TO_END_OF_FILE.

[in] Length

Размер буфера в байтах, на который указывает параметр Buffer . Если MDL предоставляется в MDL, длина — это размер данных, описываемых MDL.

[in] Buffer

Указатель на буфер, содержащий данные для записи в файл. Если файл открыт для некшированных операций ввода-вывода, этот буфер должен быть выровнен в соответствии с требованием выравнивания базового устройства хранения. Драйверы минифильтра могут выделить такой выровненный буфер, вызвав FltAllocatePoolAlignedWithTag.

Если MDL предоставляется в MDL, буфер должен иметь значение NULL.

[in] Flags

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

[out, optional] BytesWritten

Указатель на выделенную вызывающим переменную, которая получает количество байтов, записанных в файл. Если 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.

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

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

Замечания

Драйвер минифильтра вызывает FltWriteFileEx для записи данных в открытый файл.

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

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

• Вызывающий объект задает флаг FLTFL_IO_OPERATION_NON_CACHED в параметре Flags .

• Объект файла был открыт для некшированных операций ввода-вывода. Обычно это делается путем указания флага FILE_NO_INTERMEDIATE_BUFFERINGCreateOptions в предыдущем вызове FltCreateFile, FltCreateFileEx или ZwCreateFileEx.

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

• Буфер, который указывает на то, что параметр Буфера должен быть выровнен в соответствии с требованием выравнивания базового устройства хранения. Чтобы выделить такой выровненный буфер, вызовите FltAllocatePoolAlignedWithTag.

• Смещение байтов, указывающее на параметр ByteOffset , должно быть ненужным, кратным размером сектора тома.

• Длина, указанная в параметре Length , должна быть ненагрегативной для размера сектора тома.

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

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

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

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

Требования

См. также

FILE_OBJECT

FltAllocatePoolAlignedWithTag

FltCreateFile

FltCreateFileEx

FltReadFileEx

ObReferenceObjectByHandle

PFLT_COMPLETED_ASYNC_IO_CALLBACK

ZwCreateFile

ZwReadFile

ZwWriteFile