ReadFileEx

指定したファイルまたは入出力(I/O)デバイスからデータを読み取る。完了状態は非同期に報告され、読み取りが完了またはキャンセルされ、呼び出し側スレッドがアラート可能な待機状態にあるときに指定した完了ルーチンを呼び出す。

ReadFileEx hFile, lpBuffer, nNumberOfBytesToRead, lpOverlapped, lpCompletionRoutine

hFile : [intptr] ファイルまたは I/O デバイス(例: ファイル、ファイルストリーム、物理ディスク、ボリューム、コンソールバッファ、テープドライブ、ソケット、通信リソース、メールスロット、パイプ)へのハンドル。このパラメータには、CreateFile 関数で FILE_FLAG_OVERLAPPED フラグ付きで開いた任意のハンドル、または socket もしくは accept 関数が返すソケットハンドルを指定できる。このハンドルはまた GENERIC_READ アクセス権を持つ必要がある。アクセス権の詳細は File Security and Access Rights を参照。
lpBuffer : [var] ファイルまたはデバイスから読み取られたデータを受け取るバッファへのポインタ。このバッファは読み取り操作の間有効でなければならない。アプリケーションは読み取り操作が完了するまでこのバッファを使用してはならない。
nNumberOfBytesToRead : [int] 読み取るバイト数。
lpOverlapped : [var] 非同期(オーバーラップ)ファイル読み取り操作中に使用するデータを提供する OVERLAPPED データ構造体へのポインタ。バイトオフセットをサポートするファイルでは、ファイルから読み取りを開始するバイトオフセットを指定する必要がある。このオフセットは OVERLAPPED 構造体の Offset および OffsetHigh メンバを設定することで指定する。バイトオフセットをサポートしないファイルまたはデバイスでは、Offset および OffsetHigh は無視される。ReadFileEx 関数は OVERLAPPED 構造体の hEvent メンバを無視する。アプリケーションは ReadFileEx 呼び出しの文脈でそのメンバを独自の目的のために自由に使用できる。ReadFileEx は lpCompletionRoutine が指す完了ルーチンを呼び出すか、呼び出しをキューイングすることで読み取り操作の完了を通知するため、イベントハンドルを必要としない。ReadFileEx 関数は OVERLAPPED 構造体の Internal および InternalHigh メンバを使用する。アプリケーションはこれらのメンバを設定してはならない。OVERLAPPED データ構造体は読み取り操作の間有効でなければならない。読み取り操作の完了を待っている間にスコープ外となる変数にしてはならない。
lpCompletionRoutine : [int] 読み取り操作が完了し、呼び出し側スレッドがアラート可能な待機状態にあるときに呼び出される完了ルーチンへのポインタ。完了ルーチンの詳細は FileIOCompletionRoutine を参照。

(プラグイン / モジュール : kernel32.dll)

解説

指定したファイルまたは入出力(I/O)デバイスからデータを読み取る。完了状態は非同期に報告され、読み取りが完了またはキャンセルされ、呼び出し側スレッドがアラート可能な待機状態にあるときに指定した完了ルーチンを呼び出す。

[戻り値]
関数が成功した場合、戻り値は 0 以外である。関数が失敗した場合、戻り値は 0 である。拡張エラー情報を取得するには
GetLastError を呼び出す。関数が成功した場合、呼び出し側スレッドには非同期 I/O
操作(ファイルからのオーバーラップ読み取り操作)が保留状態となる。この I/O
操作が完了し、呼び出し側スレッドがアラート可能な待機状態でブロックされているとき、システムは lpCompletionRoutine
が指す関数を呼び出し、待機状態は WAIT_IO_COMPLETION
の戻りコードで完了する。関数が成功し、ファイル読み取り操作が完了しても、呼び出し側スレッドがアラート可能な待機状態でない場合、システムは完了ルーチンの呼び出しをキューイングし、呼び出し側スレッドがアラート可能な待機状態に入るまで保留する。アラート可能な待機とオーバーラップ入出力操作の詳細は
About Synchronization を参照。ReadFileEx
がファイル終端(EOF)を越えて読み取ろうとした場合、その操作に対する GetOverlappedResult の呼び出しは FALSE
を返し、GetLastError は ERROR_HANDLE_EOF を返す。

[備考]
ReadFileEx を使用する際は、関数が "成功" を返した場合でも、"成功" であるが知りたい結果を伴う状態がないかを判断するために
GetLastError を確認するべきである。たとえば ReadFileEx 呼び出し時のバッファオーバーフローは TRUE
を返すが、GetLastError はそのオーバーフローを ERROR_MORE_DATA
で報告する。関数呼び出しが成功し警告状態がない場合、GetLastError は ERROR_SUCCESS を返す。未処理の非同期
I/O 要求が多すぎる場合、ReadFileEx 関数は失敗する可能性がある。そのような失敗時、GetLastError は
ERROR_INVALID_USER_BUFFER または ERROR_NOT_ENOUGH_MEMORY
を返すことがある。全ての保留中の非同期 I/O 操作をキャンセルするには、次のいずれかを使用する。
（以下省略）

情報