windows ReadFile Function

ReadFile Function

从特定的文件或者input/ouput(I/O)设备中读取数据。如果设备是受支持的，读操作将发生在文件指针指向的特定位置。

这个函数同时支持同步操作和异步操作。如果想了解异步操作的一个简单的函数，可以看ReadFileEx。

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

参数

hFile [in]

设备的一个句柄。例如，file，file stream, physical disk, volume, console buffer, tape drive, socket, communications resource, mailslot, or pipe).

hFile参数必须在创建时让它具有读权限。更多信息，可以看Generic Access Right 和 File Security and Access Rights 。

对于异步的读操作，hFile参数可以是CreateFile函数打开的带有FILE_FLAG_OVERLAPPED标签的任何句柄，也可以是socket函数或者accept函数返回的socket句柄。

lpBuffer [out]

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

   buffer必须在整个读操作期间都是有效的。调用方不能使用buffer知道读操作完成。

nNumberOfBytesToRead  [in]

   读取字节的最大长度

lpNumberOfBytesRead [out, optional]

   当使用同步的hFile参数时，接收字节数的变量的引用。ReadFile会在初始化之前将这个值设置为0。如果是异步操作上设置这个值为null。

lpOverlapped [in, out, optional]

   如果hFile参数被打开时带有FILE_FLAG_OVERLAPPED，我们需要这个参数作为指向OVERLAPPED结构体的指针。

  如果hFile支持btye offset，如果你使用这个参数必须明确读操作开始的btye offset的位置。这个offset可以通过OVERFLAPPED结构体的Offset和OffsetHigh成员明确下来。

返回值

如果函数成功，返回nozero（TRUE）。

如果函数失败，或者操作正在异步进行，返回zero（FALSE）。

示例

下面的示例将通过CreateFile函数打开一个已经存在的文件，并通过ReadFileEx函数从文件中读取数据。

Opening a File for Reading or Writing

要求

Minimum supported client	Windows XP [desktop apps | UWP apps]
Minimum supported server	Windows Server 2003 [desktop apps | UWP apps]
Minimum supported phone	Windows Phone 8
Header	FileAPI.h (include Windows.h); WinBase.h on Windows Server 2008 R2, Windows 7, Windows Server 2008, Windows Vista, Windows Server 2003 and Windows XP (include Windows.h)
Library	Kernel32.lib
DLL	Kernel32.dll

翻译自：windows ReadFile Function