fltReadFile 函数 (fltkernel.h)

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。 在这方面, FltReadFileZwReadFile 不同。

要求

要求
目标平台 通用
标头 fltkernel.h (包括 Fltkernel.h)
Library FltMgr.lib
DLL Fltmgr.sys
IRQL PASSIVE_LEVEL

另请参阅

FILE_OBJECT

FltAllocatePoolAlignedWithTag

FltCreateFile

FltCreateFileEx

FltWriteFile

ObReferenceObjectByHandle

PFLT_COMPLETED_ASYNC_IO_CALLBACK

ZwCreateFile

ZwReadFile

ZwWriteFile