ReadFileEx 関数 (fileapi.h)
指定したファイルまたは入出力 (I/O) デバイスからデータを読み取ります。 読み取りが完了するか取り消され、呼び出し元のスレッドがアラート可能な状態にあるときに、指定した完了ルーチンが呼び出され、その完了状態が非同期的に報告されます。
ファイルまたはデバイスからデータを同期的に読み取る場合は、 ReadFile 関数を使用します。
構文
BOOL ReadFileEx(
[in] HANDLE hFile,
[out, optional] LPVOID lpBuffer,
[in] DWORD nNumberOfBytesToRead,
[in, out] LPOVERLAPPED lpOverlapped,
[in] LPOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine
);
パラメーター
[in] hFile
ファイルまたは I/O デバイスへのハンドル (ファイル、ファイル ストリーム、物理ディスク、ボリューム、コンソール バッファー、テープ ドライブ、ソケット、通信リソース、mailslot、パイプなど)。
このパラメーターには、CreateFile 関数によって FILE_FLAG_OVERLAPPED フラグで開かれた任意のハンドル、またはソケットまたは accept 関数によって返されるソケット ハンドルを指定できます。
このハンドルには、 GENERIC_READ アクセス権も必要です。 アクセス権の詳細については、「 ファイル セキュリティとアクセス権」を参照してください。
[out, optional] lpBuffer
ファイルまたはデバイスから読み取られたデータを受信するバッファーへのポインター。
このバッファーは、読み取り操作の間は有効なままである必要があります。 読み取り操作が完了するまで、アプリケーションはこのバッファーを使用しないでください。
[in] nNumberOfBytesToRead
読み取るバイト数。
[in, out] lpOverlapped
非同期 (重複) ファイルの読み取り操作中に使用されるデータを提供する OVERLAPPED データ構造へのポインター。
バイト オフセットをサポートするファイルの場合は、ファイルからの読み取りを開始するバイト オフセットを指定する必要があります。 このオフセットを指定するには、OVERLAPPED 構造体の Offset メンバーと OffsetHigh メンバーを設定します。 バイト オフセットをサポートしていないファイルまたはデバイスの場合、 Offset と OffsetHigh は無視されます。
ReadFileEx 関数は、OVERLAPPED 構造体の hEvent メンバーを無視します。 アプリケーションは、 ReadFileEx 呼び出しのコンテキストで、そのメンバーを独自の目的で自由に使用できます。 ReadFileEx は、 lpCompletionRoutine が指す完了ルーチンを呼び出すか、呼び出しをキューに入れるという方法で読み取り操作の完了を通知するため、イベント ハンドルは必要ありません。
ReadFileEx 関数は、OVERLAPPED 構造体の Internal メンバーと InternalHigh メンバーを使用します。 アプリケーションでは、これらのメンバーを設定しないでください。
OVERLAPPED データ構造は、読み取り操作の間有効なままである必要があります。 読み取り操作が完了待ちの間にスコープ外に出ることができる変数にすることはできません。
[in] lpCompletionRoutine
読み取り操作が完了し、呼び出し元のスレッドが警告可能な待機状態のときに呼び出される完了ルーチンへのポインター。 完了ルーチンの詳細については、「 FileIOCompletionRoutine」を参照してください。
戻り値
関数が成功すると、戻り値は 0 以外になります。
関数が失敗した場合は、0 を返します。 詳細なエラー情報を得るには、GetLastError を呼び出します。
関数が成功した場合、呼び出し元スレッドには非同期 I/O 操作が保留中です。ファイルからの読み取り操作が重複しています。 この I/O 操作が完了し、呼び出し元スレッドが警告可能な待機状態でブロックされると、システムは lpCompletionRoutine によって指される関数を呼び出し、待機状態は WAIT_IO_COMPLETION の戻りコードで完了します。
関数が成功し、ファイルの読み取り操作が完了したが、呼び出し元のスレッドが警告可能な待機状態でない場合、システムは完了ルーチン呼び出しをキューに入れ、呼び出し元のスレッドが警告可能な待機状態になるまで呼び出しを保持します。 アラート可能な待機と重複する入出力操作の詳細については、「 同期について」を参照してください。
ReadFileEx がファイルの末尾 (EOF) を超えて読み取ろうとすると、その操作の GetOverlappedResult の呼び出しは FALSE を返し、GetLastError はERROR_HANDLE_EOFを返します。
注釈
ReadFileEx を使用する場合は、関数が "success" を返しても GetLastError をチェックして、"成功" の条件をチェックしますが、何らかの結果を知りたい場合もあります。 たとえば、 ReadFileEx を呼び出すときのバッファー オーバーフローは TRUE を返しますが、 GetLastError は ERROR_MORE_DATAでオーバーフローを報告します。 関数呼び出しが成功し、警告条件がない場合、 GetLastError は ERROR_SUCCESSを返します。
未処理の非同期 I/O 要求が多すぎると 、ReadFileEx 関数が失敗する可能性があります。 このようなエラーが発生した場合、GetLastError はERROR_INVALID_USER_BUFFERまたはERROR_NOT_ENOUGH_MEMORYを返すことができます。
保留中のすべての非同期 I/O 操作を取り消すには、次のいずれかを使用します。
- CancelIo — この関数は、指定されたファイル ハンドルに対して呼び出し元スレッドによって発行された操作のみを取り消します。
- CancelIoEx — この関数は、指定されたファイル ハンドルに対してスレッドによって発行されたすべての操作を取り消します。
取り消された I/O 操作は、エラー ERROR_OPERATION_ABORTEDで完了します。
hFile で指定されたファイルの一部が別のプロセスによってロックされ、ReadFileEx の呼び出しで指定された読み取り操作がロックされた部分と重複している場合、ReadFileEx の呼び出しは失敗します。
バッファーが小さすぎるメールスロットからデータを読み取ろうとすると、 ReadFileEx は FALSE を返し、 GetLastError は ERROR_INSUFFICIENT_BUFFERを返します。
読み取り操作でバッファーを使用しているときに入力バッファーにアクセスすると、そのバッファーに読み取られたデータが破損する可能性があります。 アプリケーションは、読み取り操作が完了するまで、読み取り操作で使用されている入力バッファーの読み取り、書き込み、再割り当て、または解放を行う必要はありません。
アプリケーションでは 、MsgWaitForMultipleObjectsEx、 WaitForSingleObjectEx、 WaitForMultipleObjectsEx、 および SleepEx 関数を使用して、アラート可能な待機状態を入力します。 アラート可能な待機と重複する入出力の詳細については、「 同期について」を参照してください。
FILE_FLAG_NO_BUFFERINGを使用して CreateFile で開かれたファイルを正常に操作するための厳密な要件があります。 詳細については、「 ファイルバッファリング」を参照してください。
Windows 8 と Windows Server 2012 では、この関数は、次のテクノロジによってサポートされています。
| テクノロジ | サポートされています |
|---|---|
| サーバー メッセージ ブロック (SMB) 3.0 プロトコル | はい |
| SMB 3.0 Transparent Failover (TFO) | はい |
| スケールアウト ファイル共有 (SO) を使う SMB 3.0 | はい |
| クラスターの共有ボリューム ファイル システム (CsvFS) | はい |
| Resilient File System (ReFS) | はい |
Transacted Operations
ファイル ハンドルにバインドされたトランザクションがある場合、関数はファイルのトランザクション処理対象ビューからデータを返します。 トランザクション処理対象の読み取りハンドルは、ハンドルの存続期間中、ファイルの同じビューを表示することが保証されます。 詳細については、「 トランザクション NTFS について」を参照してください。例
例については、「 完了ルーチンを使用した名前付きパイプ サーバー」を参照してください。
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows XP [デスクトップ アプリ | UWP アプリ] |
| サポートされている最小のサーバー | Windows Server 2003 [デスクトップ アプリのみ | UWP アプリ] |
| 対象プラットフォーム | Windows |
| ヘッダー | fileapi.h (Windows.h を含む) |
| Library | Kernel32.lib |
| [DLL] | Kernel32.dll |