Функция 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 , когда объект файла еще не открыт или больше не открыт (например, в процедуре обратного вызова перед созданием или после очистки), приводит к тому, что система будет использовать 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-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, то Length — это размер данных, описываемых MDL.
[in] Buffer
Указатель на буфер, содержащий данные для записи в файл. Если файл открыт для некэшированных операций ввода-вывода, этот буфер должен быть выровнен в соответствии с требованиями выравнивания базового запоминающего устройства. Драйверы мини-фильтра могут выделить такой выровненный буфер, вызвав FltAllocatePoolAlignedWithTag.
Если MDL предоставляется в Mdl, параметр Buffer должен иметь значение NULL.
[in] Flags
Битовая маска флагов, задающая тип выполняемой операции записи.
Flag | Значение |
---|---|
FLTFL_IO_OPERATION_DO_NOT_UPDATE_BYTE_OFFSET | Драйверы мини-фильтра могут установить этот флаг, чтобы указать, что FltWriteFileEx не будет обновлять поле 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] 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, описывающий данные для записи. Если буфер указан в buffer, Mdl должен иметь значение NULL.
Возвращаемое значение
FltWriteFileEx возвращает значение NTSTATUS, возвращенное файловой системой.
Комментарии
Драйвер минифильтра вызывает FltWriteFileEx для записи данных в открытый файл.
FltWriteFileEx вызывает отправку запроса на запись в экземпляры драйвера минифильтра, подключенные под экземпляром-инициатором, и в файловую систему. Указанный экземпляр и экземпляры, присоединенные к нему, не получают запрос на запись.
FltWriteFileEx выполняет некэшированные операции ввода-вывода, если выполняется одно из следующих действий:
Вызывающий объект задает флаг FLTFL_IO_OPERATION_NON_CACHED в параметре Flags .
Объект файла был открыт для операций ввода-вывода без кэширования. Обычно это делается путем указания флага FILE_NO_INTERMEDIATE_BUFFERING****CreateOptions в предыдущем вызове FltCreateFile, FltCreateFileEx или ZwCreateFile.
Некэшированные операции ввода-вывода накладывают следующие ограничения на значения параметров, передаваемые в FltWriteFileEx:
Буфер, на который указывает параметр Buffer , должен быть выровнен в соответствии с требованиями выравнивания базового запоминающего устройства. Чтобы выделить такой выровненный буфер, вызовите FltAllocatePoolAlignedWithTag.
Смещение байтов, на которое указывает параметр ByteOffset , должно быть неотрицательным, кратным размеру сектора тома.
Длина, указанная в параметре Length , должна быть кратной размеру сектора тома.
Если значение параметра CallbackRoutine не равно NULL, операция записи выполняется асинхронно.
Если значение параметра CallbackRoutine равно NULL, операция записи выполняется синхронно. То есть FltWriteFileEx ожидает завершения операции записи перед возвратом. Это верно, даже если объект файла, на который указывает FileObject , был открыт для асинхронного ввода-вывода.
Если несколько потоков вызывают FltWriteFileEx для одного и того же объекта файла, а файловый объект был открыт для синхронного ввода-вывода, диспетчер фильтров не пытается сериализовать операции ввода-вывода в файле. В этом отношении FltWriteFileEx отличается от ZwWriteFile.
Параметр Mdl предоставляется для удобства, если мини-фильтр уже имеет MDL. MDL используется напрямую, и можно избежать дополнительного шага сопоставления адреса для буфера .
Требования
Требование | Значение |
---|---|
Минимальная версия клиента | Windows 8 |
Целевая платформа | Универсальное |
Верхняя часть | fltkernel.h (включая Fltkernel.h) |
Библиотека | FltMgr.lib |
DLL | Fltmgr.sys |
IRQL | PASSIVE_LEVEL |