fltReadFile 函数 (fltkernel.h)

项目
11/16/2023

FltReadFile 从打开的文件、流或设备读取数据。

语法

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

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

[in] FileObject

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

[in, optional] ByteOffset

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

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

如果在文件对象的“标志”字段中) 为同步 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 ：

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

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

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

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

[in] Length

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

[out] Buffer

指向调用方分配的缓冲区的指针，该缓冲区接收从文件读取的数据。

[in] Flags

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

标志	含义
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	微筛选器驱动程序可以设置此标志以指定同步分页 I/O 读取。设置此标志的微筛选器驱动程序还必须设置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，则忽略此参数。

返回值

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

注解

微筛选器驱动程序调用 FltReadFile 以从打开的文件读取数据。

FltReadFile 创建读取请求，并将其发送到附加到启动实例下方的微筛选器驱动程序实例，以及文件系统。指定的实例和上面附加的实例不会接收读取请求。

如果以下任一情况为 true，FltReadFile 将执行非缓存 I/O：

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

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

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

如果尝试读取文件末尾以外的内容， FltReadFile 将返回错误。

如果 CallbackRoutine 参数的值不是 NULL，则异步执行读取操作。

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

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