ReadFile功能

大家好，欢迎来到IT知识分享网。

此功能设计用于同步和异步操作。有关专门为异步操作设计的类似功能，请参见ReadFileEx。

BOOL ReadFile( HANDLE hFile, LPVOID lpBuffer, DWORD nNumberOfBytesToRead, LPDWORD lpNumberOfBytesRead, LPOVERLAPPED lpOverlapped ); 

参量

hFile 

设备的句柄（例如，文件，文件流，物理磁盘，卷，控制台缓冲区，磁带驱动器，套接字，通信资源，邮槽或管道）。

该HFILE参数必须已经具有读取权限创建。有关更多信息，请参见通用访问权限和 文件安全性和访问权限。

对于异步读取操作，hFile可以是CreateFile函数使用FILE_FLAG_OVERLAPPED标志 打开的任何句柄 ，或者是socket或 accept函数返回的套接字句柄 。

lpBuffer 

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

该缓冲区必须在读取操作期间保持有效。在读取操作完成之前，调用者不得使用此缓冲区。

nNumberOfBytesToRead 

读取的最大字节数。

lpNumberOfBytesRead 

指向变量的指针，该变量接收使用同步hFile参数时读取的字节 数。在执行任何工作或错误检查之前，ReadFile将此值设置为零。如果这是异步操作，请对该参数使用NULL以避免潜在的错误结果。

仅当lpOverlapped 参数不为NULL时，此参数才能为NULL。

有关更多信息，请参见“备注”部分。

lpOverlapped 

如果使用FILE_FLAG_OVERLAPPED打开hFile参数， 则需要指向OVERLAPPED结构的指针，否则可以为NULL。

如果使用FILE_FLAG_OVERLAPPED打开hFile，则 lpOverlapped参数必须指向有效且唯一的OVERLAPPED结构，否则该函数可能会错误地报告读取操作已完成。

对于支持字节偏移量的hFile，如果使用此参数，则必须指定一个字节偏移量，从该位置开始从文件或设备读取。通过设置OVERLAPPED结构的Offset和OffsetHigh成员 来指定此偏移量 。对于不支持字节偏移量的 hFile，将忽略Offset和 OffsetHigh。

有关lpOverlapped和 FILE_FLAG_OVERLAPPED的不同组合的更多信息，请参见“备注”部分和“ 同步和文件位置”部分。

如果函数失败或异步完成，则返回值为零（FALSE）。若要获取扩展的错误信息，请调用 GetLastError函数。

注意 该GetLastError函数代码 ERROR_IO_PENDING还不是一个失败者; 它指定读取操作正在异步完成中。有关更多信息，请参见备注。

要取消所有暂挂的异步I / O操作，请使用以下任一方法：

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

该ReadFile的功能可能会失败， ERROR_NOT_ENOUGH_QUOTA，这意味着调用进程的缓冲区不能页面锁定。有关更多信息，请参见 SetProcessWorkingSetSize。

如果文件的一部分被另一个进程锁定，并且读取操作与锁定的部分重叠，则此功能将失败。

在读取操作使用缓冲区的同时访问输入缓冲区可能会导致读入该缓冲区的数据损坏。在读取操作完成之前，应用程序不得读取，写入，重新分配或释放读取操作正在使用的输入缓冲区。使用异步文件句柄时，这可能尤其成问题。有关同步文件句柄和异步文件句柄的其他信息，可以在“ 同步和文件位置”部分以及“ CreateFile”参考主题中找到。

通过使用带有控制台输入句柄的ReadFile，可以从控制台输入缓冲区读取字符 。控制台模式确定ReadFile函数的确切行为。默认情况下，控制台模式为ENABLE_LINE_INPUT，它指示 ReadFile应该读取直到到达回车符为止。如果按Ctrl + C，则调用成功，但是GetLastError返回 ERROR_OPERATION_ABORTED。有关更多信息，请参见 CreateFile。

从通信设备读取时，ReadFile的行为 由设置和使用SetCommTimeouts和 GetCommTimeouts函数检索的当前通信超时确定。如果您无法设置超时值，则可能会发生不可预测的结果。有关通信超时的更多信息，请参见 COMMTIMEOUTS。

如果ReadFile尝试从缓冲区太小的邮槽读取，则该函数返回FALSE，而 GetLastError返回 ERROR_INSUFFICIENT_BUFFER。

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

如果使用FILE_FLAG_OVERLAPPED打开hFile，则以下条件有效：

如果ReadFile在管道上返回TRUE时lpNumberOfBytesRead参数为零 ，则管道的另一端称为WriteFile函数，且 nNumberOfBytesToWrite设置为零。

有关管道的更多信息，请参见管道。