fltWriteFile 函数 (fltkernel.h)

项目
11/16/2023

FltWriteFile 用于将数据写入打开的文件、流或设备。

语法

NTSTATUS FLTAPI FltWriteFile(
  [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] InitiatingInstance

操作要发送到的微筛选器驱动程序实例的不透明实例指针。实例必须附加到文件所在的卷。此参数是必需的，不能为 NULL。

[in] FileObject

指向要写入数据的文件的 FILE_OBJECT 的指针。此文件对象当前必须处于打开状态。例如，在文件对象尚未打开或不再打开时调用 FltWriteFile (例如，在创建前或清理后的回调例程) 会导致系统在已检查的生成上 ASSERT。此参数是必需的，不能为 NULL。

[in, optional] ByteOffset

指向调用方分配的变量的指针，该变量指定要开始读取操作的文件内的起始字节偏移量。

如果指定了 ByteOffset ，则无论文件对象的 CurrentByteOffset 字段的当前值如何，I/O 都会在该偏移量处执行。

如果在文件对象的 Flags 字段中) 为同步 I/O 打开文件 (FO_SYNCHRONOUS_IO，则调用方可以将 ByteOffset-LowPart> 设置为 FILE_USE_FILE_POINTER_POSITION，将 ByteOffset-HighPart> 设置为 -1，以便在文件对象的 CurrentByteOffset 字段中执行 I/O。如果未为同步 I/O 打开文件，则使用 FILE_USE_FILE_POINTER_POSITION 是一个错误。
调用方可以将 ByteOffset-LowPart> 设置为 FILE_WRITE_TO_END_OF_FILE，将 ByteOffset-HighPart> 设置为 -1，以在文件末尾开始写入 (即执行追加写入) 。

如果未指定 ByteOffset ：

如果未为同步 I/O 打开文件，则为错误。
否则，在文件对象的 CurrentByteOffset 上执行 I/O。

如果为同步 I/O 打开了文件对象，则 CurrentByteOffset 字段将更新，除非调用方传递FLTFL_IO_OPERATION_DO_NOT_UPDATE_BYTE_OFFSET标志。

注意：在这种情况下，文件系统仍会更新 CurrentByteOffset 。筛选器管理器在将 I/O 向下发送堆栈之前保存 CurrentByteOffset 值，并在 I/O 返回时还原它。从 FltWriteFile 的调用方的角度来看， (和筛选器位于较高高度) CurrrentByteOffset 不会更新。但调用方下方的筛选器在其读/写后回调中可以看到更新的 CurrentByteOffset 值。

如果未为同步 I/O 打开文件对象，则无论 ByteOffset 参数的状态如何，CurrentByteOffset 字段都不会更新。

如果为异步 I/O 打开 了 FileObject 指向的文件对象，则此参数是必需的，并且不能为 NULL。

在Windows 8之前，此参数不支持FILE_WRITE_TO_END_OF_FILE和FILE_USE_FILE_POINTER_POSITION的特殊常量。

[in] Length

Buffer 参数指向的缓冲区的大小（以字节为单位）。

[in] Buffer

指向包含要写入文件的数据的缓冲区的指针。如果针对非缓存 I/O 打开文件，则必须根据基础存储设备的对齐要求对齐此缓冲区。微筛选器驱动程序可以通过调用 FltAllocatePoolAlignedWithTag 来分配此类对齐的缓冲区。

[in] Flags

指定要执行的写入操作类型的标志的位掩码。

标志	含义
FLTFL_IO_OPERATION_DO_NOT_UPDATE_BYTE_OFFSET	微筛选器驱动程序可以设置此标志以指定 FltWriteFile 不会更新文件对象的 CurrentByteOffset 字段。
FLTFL_IO_OPERATION_NON_CACHED	微筛选器驱动程序可以设置此标志以指定非缓存写入，即使文件对象未使用FILE_NO_INTERMEDIATE_BUFFERING打开也是如此。
FLTFL_IO_OPERATION_PAGING	微筛选器驱动程序可以设置此标志以指定分页写入。
FLTFL_IO_OPERATION_SYNCHRONOUS_PAGING	微筛选器驱动程序可以设置此标志以指定同步分页 I/O 写入。设置此标志的微筛选器驱动程序还必须设置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，则忽略此参数。

返回值

FltWriteFile 返回文件系统返回的 NTSTATUS 值。

注解

微筛选器驱动程序调用 FltWriteFile 将数据写入打开的文件。

FltWriteFile 会导致写入请求发送到附加到启动实例下方的微筛选器驱动程序实例和文件系统。指定的实例及其上方附加的实例不会接收写入请求。

如果符合以下任一情况，FltWriteFile 将执行非缓存 I/O：

调用方在 Flags 参数中设置FLTFL_IO_OPERATION_NON_CACHED标志。
已为非缓存 I/O 打开文件对象。通常，这是通过在前面调用 FltCreateFile、FltCreateFileEx 或 ZwCreateFile 时指定 FILE_NO_INTERMEDIATE_BUFFERING CreateOptions 标志来完成的。

非缓存 I/O 对传递给 FltWriteFile 的参数值施加以下限制：

Buffer 参数指向的 缓冲区 必须根据基础存储设备的对齐要求进行对齐。若要分配此类对齐的缓冲区，请调用 FltAllocatePoolAlignedWithTag。
ByteOffset 参数指向的字节偏移量必须是卷扇区大小的非否定倍数。
Length 参数中指定的长度必须是卷扇区大小的非否定倍数。

如果 CallbackRoutine 参数的值不为 NULL，则异步执行写入操作。

如果 CallbackRoutine 参数的值为 NULL，则写入操作将同步执行。也就是说， FltWriteFile 将等待写入操作完成，然后再返回。即使为异步 I/O 打开了 FileObject 指向的文件对象，也是如此。

如果多个线程为同一文件对象调用 FltWriteFile ，并且为同步 I/O 打开了文件对象，则筛选器管理器不会尝试对文件序列化 I/O。在这方面， FltWriteFile 不同于 ZwWriteFile。