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 例程在文件系统驱动程序对象的FAST_IO_DISPATCH结构中将 FastIoRead 入口点设置为 FsRtlCopyRead 。 此外，文件系统必须执行以下操作：

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

    在大多数文件系统中，这是通过将FSRTL_COMMON_FCB_HEADER结构包含在文件控制块中， (FCB) 或类似结构来实现的，该结构用于维护打开的文件的状态。

    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 。

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

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

文件系统的 FastIoCheckIfPossible 例程负责确保 FileOffset 和 Length 定义的字节范围不包括调用方未传递相应 LockKey 值的任何独占锁定的字节范围。 如果文件系统使用 FsRtlXxxLockYyy 支持例程来管理字节范围锁，则可以在调用 FsRtlCopyRead 之前通过从 FastIoCheckIfPossible 例程调用 FsRtlFastCheckLockForRead 来完成此操作。

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

要求

要求 值
目标平台 通用
标头 ntifs.h (包括 Ntifs.h)
Library NtosKrnl.lib
DLL NtosKrnl.exe
IRQL PASSIVE_LEVEL
DDI 符合性规则 PowerIrpDDis (wdm)

另请参阅

CcInitializeCacheMap

FsRtlCopyWrite

FsRtlFastCheckLockForRead