win32 ReadFile 函数

参考网页：

https://msdn.microsoft.com/en-us/library/windows/desktop/aa365467(v=vs.85).aspx

ReadFile function

从指定的文件或者I/O设备中，读取数据。
如果该设备支持文件指针，读取的位置就是文件指针的位置。
这个函数被设置为同步和异步两种操作都支持。
一个相似的函数，仅仅支持异步操作，名字是ReadFileEx.

函数原型：

BOOL WINAPI ReadFile(
  _In_        HANDLE       hFile,
  _Out_       LPVOID       lpBuffer,
  _In_        DWORD        nNumberOfBytesToRead,
  _Out_opt_   LPDWORD      lpNumberOfBytesRead,
  _Inout_opt_ LPOVERLAPPED lpOverlapped
);

参数：

hFile

函数指针

lpBuffer

指针指向从文件读出的数据存放的缓冲区

nNumberOfBytesToRead

要读取的最多的字节数

lpNumberOfBytesRead

当使用同步读的方式的时候，一个指向变量的指针，表示实际读取的字节数。
ReadFile函数在实际工作或者检查错误之前，设置这个值为0.
如果是异步操作，可以将这个值设置为NULL，以避免错误的结果。
只有lpOverlapped 参数不为NULL的时候，这个参数才可以设置为NULL。

lpOverlapped

指向 OVERLAPPED 结构体的指针。
如果文件在打开的时候，使用了参数，FILE_FLAG_OVERLAPPED,
这个参数是必须的。如果没有使用FILE_FLAG_OVERLAPPED，这个参数为NULL。

如果文件是FILE_FLAG_OVERLAPPED 打开的，lpOverlapped 参数必须指向一个特定的
OVERLAPPED 结构，否则函数不能正确的汇报 读操作是否完成。

对于支持 字节偏移的 句柄，你使用这个参数的时候，你需要指定一个字节偏移，从这个字节偏移的位置开始读文件。偏移指定为 the OVERLAPPED 结构体中的Offset和OffsetHigh变量。
对于不支持偏移的文件句柄，Offset和OffsetHigh变量的值，被忽略。

返回值

如果成功，返回非0 的TRUE
如果失败，或者正在进行异步操作，返回 FALSE。
为了得到扩展的错误信息，调用GetLastError function.

注意

Note The GetLastError code ERROR_IO_PENDING is not a failure; it
designates the read operation is pending completion asynchronously.
For more information, see Remarks.

在读操作使用缓冲区的时候，访问 输入缓冲区将会导致放入数据的时候冲突。
应用在读操作完成之前，千万不要读取，写到，分配，或者释放输入缓冲区。
在使用异步操作的时候，这个地方需要尤其注意。

使用ReadFile ，用一个指向console input的句柄，可以冲console的input buffer中读取字符。
console的模式决定了ReadFile的准确的行为。
默认的，console的模式是ENABLE_LINE_INPUT，这个表示ReadFile需要一直读，直到一个CR回车。
如果输入Ctrl+C ，这个调用完成。但是最终返回t GetLastError returns ERROR_OPERATION_ABORTED

当从串口设备读取数据的时候，ReadFile的行为是由当前的串口设置的time-out参数决定。
time-out参数由函数SetCommTimeouts and GetCommTimeouts functions设置。

如果文件是由FILE_FLAG_OVERLAPPED打开的，
lpNumberOfBytesRead 需要设置为NULL
Use the GetOverlappedResult function to get the actual number of bytes read
如果句柄是和an I/O completion port 连接，you can also get the number of bytes read by calling the GetQueuedCompletionStatus function.