ファイルからデータを読み取ります。ファイルポインタの現在位置が読み取りの開始位置になります。ファイルハンドルがオーバーラップ属性（非同期I/O）指定で作成されていない場合には、読み取り操作が終了すると、実際に読み取られたデータのバイト数だけファイルポインタの位置が進められます。ファイルハンドルが非同期I/O用に作成されている場合には、アプリケーション側がファイルポインタの位置を変更する必要があります。
BOOL ReadFile( HANDLE hFile, // file handle LPCVOID pBuffer, // buffer DWORD nNumberOfBytesToRead, // buffer size LPDWORD pNumberOfBytesRead, // read size LPOVERLAPPED pOverlapped // OVERLAPPED );
KERNEL32.DLL
読み取り先のファイルのハンドルを指定します。このハンドルは、GENERIC_READアクセス権を持っていなければなりません。
非同期読み取り操作では、CreateFile関数でFILE_FLAG_OVERLAPPEDフラグを指定してオープンされたあらゆる種類のハンドル、またはsocket関数やaccept関数から返されたソケットハンドルを、hFileパラメータに指定することができます。
Windows 95/98/Me： 非同期読み取り操作では、CreateFile関数でFILE_FLAG_OVERLAPPEDフラグを指定してオープンされた通信リソース、またはsocket関数やaccept関数から返されたソケットハンドルを、hFileパラメータに指定することができます。メールスロットや名前付きパイプ、ディスクファイルからの非同期読み取り操作を行うことはできません。
ファイルから読み取ったデータを格納するバッファのアドレスを指定します。
ファイルから読み取るバイト数を指定します。
実際に読み取られたバイト数を格納するための変数のアドレスを指定します。ReadFile関数は操作やエラーチェックを行う前に、この値を0に設定します。
名前付きパイプに対するReadFile関数呼び出しが成功し、かつ、この値が0である場合、メッセージモードパイプの他方のクライアントエンドがWriteFile関数のnNumberOfBytesToWriteパラメータに0を指定したことを表しています。
pOverlappedパラメータに0 (NULL) を指定した場合は、このパラメータに0 (NULL) を指定することはできません。pOverlappedパラメータに有効なアドレスを指定した場合は、このパラメータに0 (NULL) を指定することができます。非同期読み取り操作の場合は、GetOverlappedResult関数を呼び出すことで読み取られたバイト数を取得することができます。hFileパラメータがI/O完了ポートに関連付けられている場合は、GetQueuedCompletionStatus関数を呼び出すことで読み取られたバイト数を取得することができます。
I/O完了ポートを使用していて、pOverlappedパラメータが指すOVERLAPPED構造体に割り当てられたメモリを解放するためにコールバック関数を使用している場合は、このパラメータに0 (NULL) を指定することによって、解放時に起こるメモリ破壊の問題を避けるようにするべきです。このメモリ破壊の問題は、このパラメータに無効なバイト数が返されることによって引き起こされます。
Windows 95/98/Me： このパラメータに0 (NULL) を指定することはできません。
有効なOVERLAPPED構造体のアドレスまたは0 (NULL) を指定します。hFileパラメータのハンドルがFILE_FLAG_OVERLAPPEDフラグを指定してオープンされている場合にはこの構造体が要求されます。
hFileパラメータのハンドルがFILE_FLAG_OVERLAPPEDフラグを指定してオープンされている場合には、このパラメータに0 (NULL) を指定してはいけません。もし0 (NULL) を指定すると、関数が読み取り操作の完了を不正に報告する可能性があります。
hFileパラメータのハンドルがFILE_FLAG_OVERLAPPEDフラグを指定してオープンされていて、このパラメータにOVERLAPPED構造体のアドレスを指定したときは、OVERLAPPED構造体で指定されたオフセットからファイルが非同期的に読み取られます。制御はすぐに返りますが、読み取りが完了しているとは限りません。この場合、ReadFile関数は0 (FALSE) を返し、GetLastError関数は997 (ERROR_IO_PENDING) を返します。これにより、呼び出しプロセスは読み取り操作が完了するまで処理を続けることができます。読み取りが完了するとOVERLAPPED構造体で指定されたイベントがシグナル状態になります。
hFileパラメータのハンドルがFILE_FLAG_OVERLAPPEDフラグを指定されずにオープンされていて、このパラメータに0 (NULL) を指定したときは、ファイルポインタの現在位置からファイルが同期的に読み取られます。読み取りが完了すると、制御が返ります。
hFileパラメータのハンドルがFILE_FLAG_OVERLAPPEDフラグを指定されずにオープンされていて、このパラメータで有効なOVERLAPPED構造体のアドレスを指定したときは、OVERLAPPED構造体で指定したオフセットからファイルが同期的に読み取られます。読み取りが完了すると、制御が返ります。
Windows 95/98/Me： ファイル、ディスク、パイプ、メールスロットへの操作を行う場合、このパラメータは0 (NULL) でなければなりません。0 (NULL) 以外の値を指定すると呼び出しは失敗します。ただし、シリアルポートおよびパラレルポートの非同期入出力を行うことはできます。
成功すると0以外の値が返ります。
失敗すると0が返ります。拡張エラー情報を取得するには、GetLastError関数を使います。
戻り値が0以外で、かつ、実際に読み取られたバイト数が0の場合、読み取り操作の時点でファイルポインタがファイルの終端を超えていたことを示します。ただし、hFileパラメータのハンドルがFILE_FLAG_OVERLAPPEDフラグを指定してオープンされていて、pOverlappedパラメータにOVERLAPPED構造体のアドレスを指定している場合には、ファイルポインタがファイルの終端を超えていると、戻り値は0になり、GetLastError関数は38 (ERROR_HANDLE_EOF) を返します。
ほかのプロセスによってロックされている領域を読み取ろうとすると、この関数は失敗します。
読み取り操作中の入力バッファにアクセスすると、そのバッファに読み取られらデータの破壊を引き起こす可能性があります。読み取り操作が終了しない限り、読み取り操作で使用されている入力バッファの書き込み、読み取り、再割り当て、解放を行ってはいけません。
コンソール入力のハンドルを渡すことによって、コンソール入力バッファから文字を読み取ることができます。ReadFile関数の正確な動作はコンソールモードによって決定されます。
名前付きパイプをメッセージモードで読み取る際に、次のメッセージの長さがnNumberOfBytesToReadパラメータで指定されたものよりも長い場合、ReadFile関数は失敗してGetLastError関数が234 (ERROR_MORE_DATA) を返します。続けてReadFile関数またはPeekNamedPipe関数を呼び出すことで、残りのメッセージを読み取ることができます。
通信デバイスから読み取る場合、現在の通信タイムアウト値によってReadFile関数の動作が決定されます。タイムアウト値の設定および取得はSetCommTimeouts関数およびSetCommTimeouts関数で行うことができます。タイムアウト値の設定をしないと、予測できない結果を引き起こす可能性があります。
バッファが小さすぎるメールスロットから読み取ろうとすると、関数は失敗してGetLastError関数が122 (ERROR_INSUFFICIENT_BUFFER) を返します。
匿名書き込みパイプハンドルをクローズした後で、対応する匿名読み取りパイプハンドルを使用して読み取ろうとすると、関数は失敗してGetLastError関数が109 (ERROR_BROKEN_PIPE) を返します。
大量の未処理の非同期I/Oが存在する場合には、関数が失敗してGetLastError関数が1784 (ERROR_INVALID_USER_BUFFER) または8 (ERROR_NOT_ENOUGH_MEMORY) を返すことがあります。
ファイル終端の状態を確認するためのReadFile関数のプログラムコードは、同期読み取り操作と非同期読み取り操作とで異なります。同期読み取り操作でファイル終端に達すると、関数は成功し、pNumberOfBytesReadパラメータが指す変数には0が格納されます。非同期読み取り操作では、ReadFile関数への最初の読み出しの間にファイル終端に達するかもしれませんし、後で行われる非同期操作の間にファイル終端に到達するかもしれません。非同期読み取り操作のためのReadFile関数呼び出し中にファイル終端を検出すると、関数は失敗してGetLastError関数が38 (ERROR_HANDLE_EOF) を返します。後で行われる非同期操作中にファイル終端を検出すると、捜査の結果を取得するためのGetOverlappedResult関数呼び出しが0 (FALSE) を返し、GetLastError関数が38 (ERROR_HANDLE_EOF) を返します。
未処理の非同期I/Oをすべて中止するには、CancelIO関数を使います。この関数は、指定されたファイルハンドルに対して呼び出しスレッドが発行した操作のみを中止します。中止されるI/O操作はエラー値995 (ERROR_OPERATION_ABORTED) とともに終了します。
フロッピーディスクが入っていないフロッピードライブから読み取りを試みた場合、ユーザーにもう一度操作を試みるように指示するメッセージボックスが表示されます。メッセージボックスが表示されないようにするには、SetErrorMode関数にSEM_NOOPENFILEERRORBOXを指定します。
Windows 95 以降 / Windows NT 3.1 以降