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 将拒绝阻止，如果无法获取文件的主资源或缓存文件所需的页面尚未驻留在内存中，则返回 FALSE。

文件系统的 FastIoCheckIf 可能 例程负责确保 FileOffset 和 Length 定义的字节范围不包含调用方不传递相应 LockKey 值的任何独占锁定字节范围。 如果文件系统使用 FsRtl.。LockXxx 支持用于管理字节范围的锁的例程，这可以通过在调用 FsRtlCopyRead 之前从 FastIoCheckIfPossible 例程调用 FsRtlFastCheckLockForRead 来实现。

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

要求

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

请参阅

CcInitializeCacheMap

FsRtlCopyWrite

FsRtlFastCheckLockForRead