ReadFileEx 函数 (fileapi.h)

项目
08/23/2023

从指定的文件或输入/输出 (I/O) 设备读取数据。它以异步方式报告其完成状态，并在读取已完成或取消并且调用线程处于可警报等待状态时调用指定的完成例程。

若要以同步方式从文件或设备读取数据，请使用 ReadFile 函数。

语法

BOOL ReadFileEx(
  [in]            HANDLE                          hFile,
  [out, optional] LPVOID                          lpBuffer,
  [in]            DWORD                           nNumberOfBytesToRead,
  [in, out]       LPOVERLAPPED                    lpOverlapped,
  [in]            LPOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine
);

参数

[in] hFile

文件或 I/O 设备的句柄 (例如文件、文件流、物理磁盘、卷、控制台缓冲区、磁带驱动器、套接字、通信资源、mailslot 或管道) 。

此参数可以是 CreateFile 函数使用 FILE_FLAG_OVERLAPPED 标志打开的任何句柄，也可以是套接字或 accept 函数返回的套接字句柄。

此句柄还必须具有 GENERIC_READ 访问权限。有关访问权限的详细信息，请参阅文件安全和访问权限。

[out, optional] lpBuffer

指向接收从文件或设备读取的数据的缓冲区的指针。

此缓冲区必须在读取操作期间保持有效。在完成读取操作之前，应用程序不应使用此缓冲区。

[in] nNumberOfBytesToRead

要读取的字节数。

[in, out] lpOverlapped

指向 OVERLAPPED 数据结构的指针，该结构提供在异步 (重叠) 文件读取操作期间使用的数据。

对于支持字节偏移量的文件，必须指定要从文件中开始读取的字节偏移量。可以通过设置 OVERLAPPED 结构的 Offset 和 OffsetHigh 成员来指定此偏移量。对于不支持字节偏移的文件或设备， 将忽略 Offset 和 OffsetHigh 。

ReadFileEx 函数忽略 OVERLAPPED 结构的 hEvent 成员。应用程序可在 ReadFileEx 调用的上下文中随意使用该成员，以实现其自己的目的。 ReadFileEx 通过调用或排队调用 lpCompletionRoutine 指向的完成例程来指示其读取操作完成，因此它不需要事件句柄。

ReadFileEx 函数确实使用 OVERLAPPED 结构的 Internal 和 InternalHigh 成员。应用程序不应设置这些成员。

OVERLAPPED 数据结构必须在读取操作期间保持有效。当读取操作等待完成时，它不应是可能超出范围的变量。

[in] lpCompletionRoutine

指向在读取操作完成且调用线程处于可警报等待状态时调用的完成例程的指针。有关完成例程的详细信息，请参阅 FileIOCompletionRoutine。

返回值

如果该函数成功，则返回值为非零值。

如果函数失败，则返回值为零。要获得更多的错误信息，请调用 GetLastError。

如果函数成功，则调用线程具有挂起的异步 I/O 操作：文件中的重叠读取操作。当此 I/O 操作完成并且调用线程在可警报等待状态下被阻止时，系统将调用 lpCompletionRoutine 指向的函数，并且等待状态以 返回代码WAIT_IO_COMPLETION完成。

如果函数成功，并且文件读取操作完成，但调用线程未处于可警报等待状态，则系统会将完成例程调用排入队列，保持调用，直到调用线程进入可警报等待状态。有关可发出警报的等待和重叠的输入/输出操作的信息，请参阅关于同步。

如果 ReadFileEx 尝试读取超过 EOF) 的文件结尾 (，则对该操作的 GetOverlappedResult 的调用将返回 FALSE，GetLastError 返回ERROR_HANDLE_EOF。

注解

使用 ReadFileEx 时，即使函数返回“success”来检查“成功”，但仍应检查 GetLastError。如果条件是“成功”，但有一些你可能想知道的结果。例如，调用 ReadFileEx 时出现缓冲区溢出将返回 TRUE，但 GetLastError 将报告 溢出并ERROR_MORE_DATA。如果函数调用成功且没有警告条件， 则 GetLastError 将返回 ERROR_SUCCESS。

如果存在太多未完成的异步 I/O 请求， ReadFileEx 函数可能会失败。如果发生此类故障， GetLastError 可以返回 ERROR_INVALID_USER_BUFFER 或 ERROR_NOT_ENOUGH_MEMORY。

若要取消所有挂起的异步 I/O 操作，请使用以下任一函数：

CancelIo - 此函数仅取消由指定文件句柄的调用线程发出的操作。
CancelIoEx - 此函数取消由指定文件句柄的线程发出的所有操作。

使用 CancelSynchronousIo 取消挂起的同步 I/O 操作。

取消的 I/O 操作已完成， ERROR_OPERATION_ABORTED错误。

如果 hFile 指定的文件的一部分被另一个进程锁定，并且对 ReadFileEx 的调用中指定的读取操作与锁定部分重叠，则对 ReadFileEx 的调用将失败。

尝试从缓冲区太小的 mailslot 读取数据时，ReadFileEx 返回 FALSE，GetLastError 返回ERROR_INSUFFICIENT_BUFFER。

在读取操作使用缓冲区时访问输入缓冲区可能会导致读取到该缓冲区的数据损坏。在读取操作完成之前，应用程序不得读取、写入、重新分配或释放读取操作正在使用的输入缓冲区。

应用程序使用 MsgWaitForMultipleObjectsEx、 WaitForSingleObjectEx、 WaitForMultipleObjectsEx 和 SleepEx 函数进入可警报的等待状态。有关可发出警报的等待和重叠输入/输出的详细信息，请参阅关于同步。

使用 FILE_FLAG_NO_BUFFERING 成功处理使用 CreateFile 打开的文件有严格的要求。有关详细信息，请参阅文件缓冲。

在 Windows 8 和 Windows Server 2012 中，此函数由以下技术支持。

技术	支持
服务器消息块 (SMB) 3.0 协议	是
SMB 3.0 透明故障转移 (TFO)	是
具有横向扩展文件共享的 SMB 3.0 (SO)	是
群集共享卷文件系统 (CSV)	是
弹性文件系统 (ReFS)	是

事务处理操作

如果存在绑定到文件句柄的事务，则该函数将从文件的事务处理视图中返回数据。事务处理读取句柄保证在句柄持续时间内显示文件的相同视图。有关详细信息，请参阅关于事务 NTFS。

示例

有关示例，请参阅命名管道服务器使用完成例程。

要求

要求	值
最低受支持的客户端	Windows XP [桌面应用 \| UWP 应用]
最低受支持的服务器	Windows Server 2003 [桌面应用 \| UWP 应用]
目标平台	Windows
标头	fileapi.h (包括 Windows.h)
Library	Kernel32.lib
DLL	Kernel32.dll