通过

FsRtlCopyRead 函数 （ntifs.h）

  • 项目

FsRtlCopyRead 例程将数据从缓存文件复制到用户缓冲区。

语法

BOOLEAN FsRtlCopyRead(
  [in]  PFILE_OBJECT     FileObject,
  [in]  PLARGE_INTEGER   FileOffset,
  [in]  ULONG            Length,
  [in]  BOOLEAN          Wait,
  [in]  ULONG            LockKey,
  [out] PVOID            Buffer,
  [out] PIO_STATUS_BLOCK IoStatus,
  [in]  PDEVICE_OBJECT   DeviceObject
);

参数

[in] FileObject

指向要从中读取数据的缓存文件的文件对象的指针。

[in] FileOffset

从缓存文件中的字节偏移量开始。

[in] Length

要读取的数据的长度（以字节为单位）。

[in] Wait

如果调用方可以置于等待状态，直到复制所有数据，则设置为 TRUE，否则为 FALSE。

[in] LockKey

与要锁定的字节范围关联的值。 如果锁定的范围与已锁定的另一个范围重叠，且已具有非显式锁的锁定范围，或者要读取的范围是另一个范围（非显式锁定范围）的子范围，则此参数中的值必须是该非公开锁的键。该锁必须由调用线程的父进程保留。 否则，此参数不起作用。

[out] Buffer

指向要将数据复制到其中的缓冲区的指针。

[out] IoStatus

指向调用方分配的结构的指针，该结构接收最终完成状态和有关操作的信息。 如果成功复制数据，IoStatus.Status 包含STATUS_SUCCESS。 如果未成功复制所有数据，IoStatus.Information 包含复制的实际字节数。

[in] DeviceObject

保存文件数据的设备的设备对象。

返回值

FsRtlCopyRead 如果复制请求完成，则返回 TRUE，否则返回 FALSE。 请注意，TRUE 的返回值不一定意味着复制操作成功。

如果 FsRtlCopyRead 返回 FALSE，或者如果 IoStatus 的内容 指示复制操作失败，则调用方必须分配读取 IRP 而不是调用 FsRtlCopyRead。

言论

支持文件缓存的文件系统的开发人员应考虑使用 FsRtlCopyRead 作为文件系统处理快速 I/O 读取请求的入口点，而不是实现特定于文件系统的快速 I/O 读取例程。 这要求文件系统的 DriverEntry 例程将 FastIoRead 入口点设置为文件系统驱动程序对象的FAST_IO_DISPATCH结构中的 FsRtlCopyRead。 此外，文件系统必须执行以下操作：

  1. 对于执行快速 I/O 的每个文件，文件系统必须分配和初始化FSRTL_COMMON_FCB_HEADER结构。

    在大多数文件系统中，这是通过在文件控制块（FCB）或用于维护打开文件状态的可比结构中包含FSRTL_COMMON_FCB_HEADER结构来实现的。

    FSRTL_COMMON_FCB_HEADER结构的存储通常从分页池进行分配。

  2. 对于执行快速 I/O 的每个文件，文件系统必须将文件的任何文件对象链接到FSRTL_COMMON_FCB_HEADER结构。 为此，请将每个文件对象的 FsContext 成员设置为指向此结构（或 FCB 或其他包含FSRTL_COMMON_FCB_HEADER结构的结构）。

  3. 缓存文件时，文件系统必须将文件的FSRTL_COMMON_FCB_HEADER结构的 IsFastIoPossible 成员设置为适当的值。 只要文件保持缓存状态，就应根据需要更新此值。

    具体而言，文件系统应将FSRTL_COMMON_FCB_HEADER结构的 IsFastIoPossible 成员设置为 FastIoIsQuestionable，只要缓存文件上存在任何排他字节范围锁。

如果 等待 为 TRUE，则保证 FsRtlCopyRead 完成复制请求并返回 TRUE。 如果缓存文件所需的页已驻留在内存中，则会立即复制数据，并且不会发生阻塞。 如果任何所需页面不驻留，则调用方将进入等待状态，直到所有必需的页面都成为常驻页面，并且可以复制数据。

如果 Wait 为 FALSE，FsRtlCopyRead 将拒绝阻止，如果它无法获取文件的主资源或缓存文件所需的页面尚未驻留在内存中，则返回 FALSE。

文件系统的 FastIoCheckIfPossible 例程负责确保由 fileOffset 定义的字节范围，Length 不包括调用方不传递相应 LockKey 值的任何独占锁定字节范围。 如果文件系统使用 FsRtlXxxLockYy 支持例程来管理字节范围锁，则可以通过从 FastIoCheckIfPossible 例程调用 FsRtlFastCheckLockForRead，然后调用 FsRtlCopyRead来实现此目的。

若要缓存文件，请使用 CcInitializeCacheMap 例程。

要求

要求 价值
目标平台 普遍
标头 ntifs.h （include Ntifs.h）
库 NtosKrnl.lib
DLL NtosKrnl.exe
IRQL PASSIVE_LEVEL
DDI 符合性规则 PowerIrpDDis（wdm）

另请参阅

CcInitializeCacheMap

FsRtlCopyWrite

FsRtlFastCheckLockForRead