ntReadFile 函数 (ntifs.h)

  • 项目

NtReadFile 例程从打开的文件读取数据。

语法

__kernel_entry NTSYSCALLAPI NTSTATUS NtReadFile(
  [in]           HANDLE           FileHandle,
  [in, optional] HANDLE           Event,
  [in, optional] PIO_APC_ROUTINE  ApcRoutine,
  [in, optional] PVOID            ApcContext,
  [out]          PIO_STATUS_BLOCK IoStatusBlock,
  [out]          PVOID            Buffer,
  [in]           ULONG            Length,
  [in, optional] PLARGE_INTEGER   ByteOffset,
  [in, optional] PULONG           Key
);

参数

[in] FileHandle

文件对象的句柄。 此句柄是通过成功调用 NtCreateFile 或 NtOpenFile 创建的。

[in, optional] Event

（可选）在读取操作完成后设置为信号状态的事件对象的句柄。 设备和中间驱动程序应将此参数设置为 NULL。

[in, optional] ApcRoutine

此参数为保留参数。 设备和中间驱动程序应将此指针设置为 NULL。

[in, optional] ApcContext

此参数为保留参数。 设备和中间驱动程序应将此指针设置为 NULL。

[out] IoStatusBlock

指向 IO_STATUS_BLOCK 结构的指针，该结构接收最终完成状态和有关请求的读取操作的信息。 Information 成员接收实际从文件读取的字节数。

[out] Buffer

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

[in] Length

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

[in, optional] ByteOffset

指向变量的指针，该变量指定将开始读取操作的文件中起始字节偏移量。 如果尝试读取文件末尾以外的内容， NtReadFile 将返回错误。

如果对 NtCreateFile 的调用设置 CreateOptions 标志FILE_SYNCHRONOUS_IO_ALERT或FILE_SYNCHRONOUS_IO_NONALERT，则 I/O 管理器将保留当前文件位置。 如果是这样， NtReadFile 的调用方可以指定使用当前文件位置偏移量而不是显式 ByteOffset 值。 可以使用以下方法之一进行此规范：

  • 指定指向LARGE_INTEGER值的指针，其中 HighPart 成员设置为 - 1，LowPart 成员设置为系统定义的值FILE_USE_FILE_POINTER_POSITION。
  • 传递 ByteOffset 的 NULL 指针。

如果 NtReadFile 使用由 I/O 管理器维护的当前文件位置，则通过添加完成读取操作时读取的字节数来更新当前文件位置。

即使 I/O 管理器维护当前文件位置，调用方也可以通过将显式 ByteOffset 值传递给 NtReadFile 来重置此位置。 执行此操作会自动将当前文件位置更改为该 ByteOffset 值，执行读取操作，然后根据实际读取的字节数更新位置。 此方法为调用方提供原子查找和读取服务。

[in, optional] Key

设备和中间驱动程序应将此指针设置为 NULL。

返回值

NtReadFile 返回STATUS_SUCCESS或相应的 NTSTATUS 错误代码。

注解

NtReadFile 的调用方必须已使用 DesiredAccess 参数中设置FILE_READ_DATA或GENERIC_READ值调用 NtCreateFile。

如果前面对 NtCreateFile 的调用将 CreateOptions 参数中的FILE_NO_INTERMEDIATE_BUFFERING标志设置为 NtCreateFile，则 NtReadFile 的 Length 和 ByteOffset 参数必须是扇区大小的倍数。

NtReadFile 开始从给定的 ByteOffset 或当前文件位置读取到给定 的缓冲区。 它会在以下条件之一下终止读取操作：

  • 缓冲区已满，因为已读取 Length 参数指定的字节数。 因此，在未发生溢出的情况下，无法将更多数据放入缓冲区中。
  • 读取操作期间会到达文件末尾，因此文件中没有更多要传输到缓冲区中的数据。

如果调用方在 DesiredAccess 中设置了 SYNCHRONIZE 标志打开文件，则调用线程可以通过等待文件句柄 FileHandle 来同步到读取操作的完成。 每次在句柄上发出的 I/O 操作完成时，都会发出句柄的信号。 但是，调用方不得等待为同步文件访问打开的句柄 (FILE_SYNCHRONOUS_IO_NONALERT 或FILE_SYNCHRONOUS_IO_ALERT) 。 在这种情况下， NtReadFile 代表调用方等待，在读取操作完成之前不会返回。 仅当满足以下所有三个条件时，调用方才能安全地等待文件句柄：

  • 为异步访问打开了句柄， (，即) 未指定FILE_SYNCHRONOUS_IO_XXX 标志。
  • 句柄一次只用于一个 I/O 操作。
  • NtReadFile 返回STATUS_PENDING。

如果存在以下任何条件，驱动程序应在系统进程的上下文中调用 NtReadFile ：

  • 驱动程序创建了传递给 NtReadFile 的文件句柄。
  • NtReadFile 将通过驱动程序创建的事件通知驱动程序 I/O 完成。
  • NtReadFile 将通过驱动程序传递给 NtReadFile 的 APC 回调例程通知驱动程序 I/O 完成情况。

文件和事件句柄仅在创建句柄的进程上下文中有效。 因此，为了避免安全漏洞，驱动程序应在系统进程的上下文（而不是驱动程序所处的进程上下文）中创建传递给 NtReadFile 的任何文件或事件句柄。

同样，如果 NtReadFile 通过 APC 通知驱动程序 I/O 完成，则应在系统进程的上下文中调用，因为 APC 始终在发出 I/O 请求的线程上下文中触发。 如果驱动程序在非系统进程的上下文中调用 NtReadFile ，则 APC 可能会无限期延迟，或者根本无法触发。

有关使用文件的详细信息，请参阅 在驱动程序中使用文件。

NtReadFile 的调用方必须在 IRQL = PASSIVE_LEVEL且启用了特殊内核 APC 的情况下运行。

如果在用户模式下调用此函数，则应使用名称“NtReadFile”而不是“ZwReadFile”。

对于来自内核模式驱动程序的调用，Windows Native System Services 例程的 NtXxx 和 ZwXxx 版本在处理和解释输入参数的方式上的行为可能有所不同。 有关例程的 NtXxx 和 ZwXxx 版本之间的关系的详细信息，请参阅 使用本机系统服务例程的 Nt 和 Zw 版本。

要求

要求 值
最低受支持的客户端 Windows 2000
目标平台 通用
标头 ntifs.h（包括 Wdm.h、Ntddk.h、Ntifs.h）
Library NtosKrnl.lib
DLL NtosKrnl.exe
IRQL PASSIVE_LEVEL (请参阅“备注”部分)
DDI 符合性规则 BufAfterReqCompletedIntIoctlA、BufAfterReqCompletedIoctlA、BufAfterReqCompletedReadA、BufAfterReqCompletedWriteA、HwStorPortProhibitedDDIs、PowerIrpDDis

另请参阅

KeInitializeEvent

ZwCreateFile

NtQueryInformationFile

NtSetInformationFile

NtWriteFile