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

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

[in, optional] Event

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

[in, optional] ApcRoutine

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

[in, optional] ApcContext

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

[out] IoStatusBlock

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

[out] Buffer

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

[in] Length

缓冲区所指向的大小(以字节为单位)。

[in, optional] ByteOffset

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

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

  • 指定指向 highPart 成员设置为 -1 且 LowPart 成员设置为系统定义值FILE_USE_FILE_POINTER_POSITION的LARGE_INTEGER值的指针。
  • 传递 ByteOffsetNULL 指针。
如果 NtReadFile 使用 I/O 管理器维护的当前文件位置,则通过添加读取操作时读取的字节数来更新当前文件位置。

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

[in, optional] Key

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

返回值

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

备注

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

如果上述对 ZwCreateFile 的调用将 CreateOptions 参数中的FILE_NO_INTERMEDIATE_BUFFERING标志设置为 NtCreateFile,则 LengthByteOffset 参数必须是扇区大小的倍数

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 将通过 APC 回调例程通知驱动程序 I/O 完成情况,该驱动程序会传递到 NtReadFile
文件和事件句柄仅在创建句柄的进程上下文中有效。 因此,为了避免安全漏洞,驱动程序应创建它传递到系统进程的上下文中的 NtReadFile 的任何文件或事件句柄,而不是驱动程序所处的进程的上下文。

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

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

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

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

要求

   
最低受支持的客户端 从 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

ZwQueryInformationFile

ZwSetInformationFile

ZwWriteFile