ReadFile2

由于 ReadFile 已经被创建，故建立本条。

　　4.15.46 ReadFile

　　函数功能：该函数从文件指针指示的位置开始从文件读数据，在读操作完成后，如果文件句柄不是用重叠属性来创建，则文件指针用实际读的字数来调整。

　　如果文件句柄为重叠的输入和输出（I/O）操作而创建，则应用程序必须在读操作之后调整文件指针的位置。

　　函数原型：BOOL ReadFile(HANDLE hFile, LPVOID lpBuffer, DWORD nNumberOfBytesToRead, LPDWORD lpNumberOfBytesRead, LPOVERLAPPED lpOverlapped);

　　参数：

　　hFile：指向要读的文件的句柄，文件句柄一定用 GENERIC_READ 对文件的访问来创建。

　　Windows NT：对于异步读操作，hFile 可为任何一个句柄，该句柄可以通过 CreatFile函数用 FILE_FLAG_OVERLAPPED 标志来打开或通过插孔或接收函数返回的插孔句柄来打开。

　　Windows 95：对于异步读操作，hFILE 可以是一个通信源、邮件插孔或命名的管道句柄，此管道句柄通过 CreatFile 用 FILE_FLAG_OVERLAPPED 标志来打开或通过插孔或接收函数返回的插孔句柄来打开，Windows 95 不支持磁盘文件的异步读操作。

　　lpBuffer：指向一个从文件存取数据的缓冲区的指针。

　　nNumberOfBytesToRead：从文件读的字节数目。

　　lpNumberOfBytesRead：指向一个读字节数的指针，在做任何工作或错误检测之前，ReadFile 把此值设置为零，当 ReadFile 在命名管道上返回 TRUE 时，如果此参数为零，则用 nNumberOfBytesToWrite 调用 WriteFile 函数的信息模块将管道的另一端设置为零。

　　Windows NT：如果 lpOverlapped 为 NULL，则 lpNumberOfBytesRead 不为 NULL；如果 lpOverlapped 不为 NULL，则 lpNumberOfBytesRead 可以为 NULL，如果这是一个重叠写操作，则可通过调用 GetQueuedCompletionStatus 来得到读字节的数目。

　　Windows 95 或 Windows 98：此参数不能为 NULL。

　　lpOverlapped：指向一个OVERLAPPED 结构的指针，如果用 FILE_FLAG_OVERLAPPED 来创建 hFile，则需要此结构，如果用 FILE_FLAG_OVERLAPPED 来打开 hFile，则 lpOverlapped 参数一定不是 NULL，它必须指向一个有效的 OVERLAPPED结构，如果 hFile 是由 FILE_FLAG_OVERLAPPED 创建且 lpOverlapped 为 NULL，则函数可不正确地记录关于读操作是完全的。

　　如果 hFile 用 FILE_FLAG_OVERLAPPED 打开，且 lpOverlapped 不为 NULL，则读操作在 OVERLAPPED 结构中指定的位移处开始，在完成操作之前，且 ReadFile 可以返回在这种情况下 ReadFile 返回 FALSE 且 GetLastError 函数返回 ERROR_IO_PENDING 这使在读操作完成时，调用应用系统继续。在 OVERLAPPED 结构中指定的事件被设置为读操作完成的发送信号状态。

　　如果 hFile 不用 FILE_FLAG_OVERLAPPED 打开，且 lpOverlapped 不为 NULL，则读操作在当前文件位置开始且至操作完成，ReadFile 函数返回。

　　如果 hFile 不用 FILE_FLAG_OVERLAPPED 打开，且 lpOverlapped 不为 NULL，则读操作 OVERLAPPED 结构指定的位移处开始，直到操作完成，ReadFile 函数返回。

　　返回值：当下列之一的为真时，ReadFile 函数返回。写操作的管道写终端完成，请求读的字节数目或出现错误。如果函数调用成功，则返回值为非零值。如果返回值为非零值，且读字节数目为零，则在读操作时文件指针超出文件终端。但是，如果文件用 FILE_FLAG_OVERLAPPED 打开且 lpOverlapped 不为 NULL，则返回值为 FALSE，且当文件指针超过文件当前终端时 GetLastError 函数返回 ERROR_HANDLE_EOF。如果函数调用失败，则返回值为零。若想获得更多错误信息，请调用 GetLastError 函数。

　　文件访问一定在文件内字节位移处开始，该文件为容量扇区大小的整数倍，为决定一个容量扇区的大小，调用 GetDiskFreeSpace 函数。

　　文件访问必须是对于字节数目的访问，该字节数目为容量扇区大小的整数倍，例如如果扇区大小为512字节，应用程序可以请求512、1024或2048字节的读和写访问，但不是335、981、7171字节。缓冲区对读、写操作的地址一定为对齐扇区（在内存地址上对齐，该内存为容量扇区大小的整数倍）。一种对齐扇区的缓冲区的方法是用 VirtualAlloc 函数来分配缓冲区，此函数分配内存，该内存在为系统页面大小的整数倍的地址上对齐，因为无论是页面还是扇区大小都是2的幂，用系统页面大小的倍数对齐的内存也可用容量扇区大小的倍数来对齐调整（‘对齐’改为‘调整’）。

　　在读操作正在有缓冲区时访问输入缓冲区，则可导致输入缓冲区数据的破坏，直到读操作完成为止，应用程序才能读、写重分配或释放一个正被一个读操作使用的输入缓冲区。

　　如果一个命名的管道正在信息模块中读且狭义个信息比 nNumberOfBytesToRead 参数长，则 ReadFile 返回 FALSE 且 GetLastError 返回 ERROR_MODE_DATA，剩下的信息也许通过下一次对 ReadFile 或 PeekNamePipe 函数的调用来读。

　　当从通信设备来读数据时，且当用 SetCommTimeouts 和 GetCommTimeouts 函数来设置和检取超时时，ReadFile的行为由当前通信超时来操纵，如果不能设置超时时，则会出现不可预料的结果，有关信息超时更详细的资料，参见 COMMTIMEOUTS。

　　如果 ReadFile 试图从缓冲区太小的邮件插孔读数据，则函数返回 FALSE 且 GetLastError 函数返回 ERROR_INSUFFICENT_BUFFER。

　　如果匿名写通道句柄已经被关闭且 ReadFile 试图用相应的匿名读通道句柄来读，则函数返回 FALSE 且 GetLastError 返回 ERROR_BROKEN_PIPE。

　　当不足够多的明显异步 I/O 请求时，ReadFile 函数可能失败且返回 ERROR_INVALID_USER_BUFFER 或 ERROR_NOT_ENOUGH_MEMORY。

　　ReadFile 代码为状态文件终端而检测与异步和同步读操作不同。

　　当一个同步读操作到达文件末尾时，ReadFile 返回 TRUE 且把 lpNumberOfBytesResd 设置为零，下列样本代码用来为同步读操作文件末尾的检测。

　　// Attempt a synchronous read operation

　　bResut = ReadFile(hFile, &inBuffer, nBytesToRead, &nBytesRead, NULL);

　　// Check for end of file

　　if(bResult&nBytesRead==0)

　　{// we're at the end of the file}

　　在其始的 ReadFile 调用期间，或下一步异步操作期间，一个异步读操作可以遇到文件的末尾。

　　如果对于异步读操作在 ReadFile 时间 EOF 被删除，则 ReadFile 返回 FALSE 且 GetLastError 返回 ERROR_HANDLE_EOF。

　　如果下一次异步操作期间 EOF 被删除，对 GetOverlappedResult 的调用，可以导致操作返回 FALSE 且 GetError 返回 ERROR_HANDLE_EOF。

　　用 Cancel 函数来取消所有未知异步 I/O 操作，此函数只取消由关于指定文件句柄的调用线程发布的操作，被取消的 I/O 操作用错误 ERROR_OPERATION_ABORTED 来完成。

　　如果试图从一个没有软盘的软驱中读数据，则系统显示一个信息框告诉用户重新执行此操作，为避免系统显示此信息框，用 SEM_NOOPENFILEERRORBOX 来调用 SetErrorMode 函数。

　　Windows CE：lpOverlapped 参数一定被设置为 NULL，Windows CE 不允许用重叠属性来创建文件，Windows CE 不支持对文件的异步读操作。

　　速查：Windows NT 3.1及以上版本、Windows 95及以上版本、Windows CE 1.0及以上版本，头文件：winbase.h；库文件：kernel32.lib。