ファイルからデータを読み取ります。ファイルポインタの現在位置が、読み取りの開始位置になります。同期読み取り操作では、読み取り操作が終了すると、ファイルハンドルがオーバーラップ属性指定で作成されていない限り、ファイルポインタの位置は実際に読み取られたデータのバイト数だけ進められます。非同期読み取り操作では、アプリケーション側でファイルポインタを調整する必要があります。
BOOL ReadFile(
HANDLE hFile, // ファイルハンドル
LPCVOID pBuffer, // バッファアドレス
DWORD nNumberOfBytesToRead, // サイズ
LPDWORD pNumberOfBytesRead, // 実際のサイズを格納する変数
LPOVERLAPPED pOverlapped // OVERLAPPED構造体
);
KERNEL32.DLL
読み取り先のファイルのハンドルを指定します。ファイルハンドルは CreateFile 関数で取得できます。このハンドルは、 GENERIC_READ アクセスを持っていなければなりません。
Windows NT/2000/XP： CreateFile 関数で FILE_FLAG_OVERLAPPED フラグを指定してオープンされたあらゆる種類のハンドル、または、 socket 関数もしくは accept 関数から返されたソケットハンドルを、非同期読み取り操作で hFile パラメータに指定することができます。
Windows 95/98/Me： CreateFile 関数で FILE_FLAG_OVERLAPPED フラグを指定してオープンされたコミュニケーションリソースのハンドル、または、 socket 関数もしくは accept 関数から返されたソケットハンドルを、非同期読み取り操作で hFile パラメータに指定することができます。メールスロットや名前付きパイプ、ディスクファイルからの非同期読み取り操作を行なうことはできません。
ファイルから読み取ったデータを格納するためのバッファのアドレスを指定します。
読み取るバイト数を指定します。
実際に読み取られたバイト数を格納するための変数のアドレスを指定します。
Windows NT/2000/XP： pOverlapped パラメータに有効なアドレスを指定した場合は 0 (NULL) を指定することができます。非同期読み取り操作の場合は、 GetOverlappedResult 関数を呼び出すことで読み取られたバイト数を取得することができます。 hFile パラメータが I/O 完了ポートと関連付けられている場合は、 GetQueuedCompletionStatus 関数を呼び出すことで読み取られたバイト数を取得することができます。
Windows 95/98/Me： このパラメータに 0 (NULL) を指定することはできません。
有効な OVERLAPPED 構造体のアドレスまたは 0 (NULL) を指定します。
hFile パラメータのハンドルが FILE_FLAG_OVERLAPPED フラグを持たないとき、かつ、このパラメータに 0 (NULL) を指定したときは、ファイルポインタの現在位置からファイルが同期的に読み取られます。読み取りが完了すると、制御が返ります。
hFile パラメータのハンドルが FILE_FLAG_OVERLAPPED フラグを持つとき、かつ、このパラメータで有効な OVERLAPPED 構造体のアドレスを指定したときは、 OVERLAPPED 構造体で指定されたオフセットからファイルが非同期的に読み取られます。制御はすぐに返りますが、読み取りが完了しているとは限りません。読み取りが終了していない場合は、 ReadFile 関数は失敗し、 GetLastError 関数は 997 (ERROR_IO_PENDING) を返します。その後、読み取りが完了すると、 OVERLAPPED 構造体で指定されたイベントがシグナル状態になります。
Windows NT/2000/XP： hFile パラメータのハンドルが FILE_FLAG_OVERLAPPED フラグを持たないとき、かつ、このパラメータで有効な OVERLAPPED 構造体のアドレスを指定したときは、 OVERLAPPED 構造体で指定したオフセットからファイルが同期的に読み取られます。読み取りが完了すると、制御が返ります。
Windows 95/98/Me： ファイル、ディスク、パイプ、メールスロットへの操作を行なう場合、このパラメータは 0 (NULL) でなければなりません。 0 (NULL) 以外の値を指定すると呼び出しは失敗します。ただし、シリアルポートおよびパラレルポートの非同期入出力はサポートされます。
成功すると 0 以外の値が返ります。
失敗すると 0 が返ります。拡張エラー情報を取得するには、 GetLastError 関数を使います。
戻り値が 0 以外で、かつ、実際に読み取られたバイト数が 0 の場合、読み取り操作の時点でファイルポインタがファイルの終端を超えていたことを示します。ただし、ファイルが FILE_FLAG_OVERLAPPED フラグ付きでオープンされていて pOverlapped パラメータに 0 (NULL) 以外の値を指定していた場合には、ファイルポインタがファイルの終端を超えていると、戻り値は 0 になり、 GetLastError 関数は 38 (ERROR_HANDLE_EOF) を返します。
ほかのプロセスによってロックされている領域を読み取ろうとすると、この関数は失敗します。
読み取り操作が終了しない限り、 pBuffer パラメータで指定されたバッファの内容を変更してはいけません。
未処理の非同期 I/O が大量に残っているとき、 ReadFile 関数が失敗して GetLastError 関数が 1784 (ERROR_INVALID_USER_BUFFER) または 8 (ERROR_NOT_ENOUGH_MEMORY) を返すことがあります。
Windows 95 以降 / Windows NT 3.1 以降