ReadFileScatter 関数 (fileapi.h)
ファイルからデータを読み取り、バッファーの配列に格納します。
関数は、 OVERLAPPED 構造体で指定された位置でファイルからデータの読み取りを開始します。 ReadFileScatter 関数は非同期的に動作します。
構文
BOOL ReadFileScatter(
[in] HANDLE hFile,
[in] FILE_SEGMENT_ELEMENT [] aSegmentArray,
[in] DWORD nNumberOfBytesToRead,
LPDWORD lpReserved,
[in, out] LPOVERLAPPED lpOverlapped
);
パラメーター
[in] hFile
読み取るファイルへのハンドル。
ファイル ハンドルは、GENERIC_READ権限と、 FILE_FLAG_OVERLAPPED フラグと FILE_FLAG_NO_BUFFERING フラグを使用して作成 する 必要があります。 詳細については、「 ファイル のセキュリティとアクセス権」を参照してください。
[in] aSegmentArray
データを受け取る FILE_SEGMENT_ELEMENT構造体 バッファーの配列へのポインター。 この共用体の説明については、「 解説」を参照してください。
各要素は、データの 1 ページを表します。
注意
システム ページのサイズを確認するには、 GetSystemInfo を使用します。
配列には、 データの nNumberOfBytesToRead バイトを表す十分な要素が含まれている必要があります。 たとえば、読み取る 40 KB があり、ページ サイズが 4 KB の場合、配列には 10 個の要素が必要です。
各バッファーは、少なくともシステム メモリ ページのサイズである必要があり、システム メモリ ページ サイズの境界に配置する必要があります。 システムは、データの 1 つのシステム メモリ ページを各バッファーに読み取ります。
関数は、バッファー内のデータを順番に格納します。 たとえば、各バッファーが格納されてすべてのデータが格納されるまで、または nNumberOfBytesToRead バイトが読み取られるまで、データを最初のバッファーに格納し、次に 2 番目のバッファーに格納します。
[in] nNumberOfBytesToRead
ファイルから読み取る合計バイト数。 aSegmentArray の各要素には、この合計の 1 ページのチャンクが含まれています。 ファイルは FILE_FLAG_NO_BUFFERINGで開く必要があるため、バイト数は、ファイルが配置されているファイル システムのセクター サイズの倍数である必要があります。
lpReserved
このパラメーターは将来使用するために予約されており、 NULL である必要があります。
[in, out] lpOverlapped
OVERLAPPED データ構造へのポインター。
ReadFileScatter 関数には、有効な OVERLAPPED 構造体が必要です。 lpOverlapped パラメーターを NULL にすることはできません。
ReadFileScatter 関数は、OVERLAPPED 構造体の Offset メンバーと OffsetHigh メンバーによって指定された位置で、ファイルからデータの読み取りを開始します。
ReadFileScatter 関数は、読み取り操作が完了する前に を返す場合があります。 このシナリオでは、 ReadFileScatter 関数は値 0 (ゼロ) を返し、 GetLastError 関数は ERROR_IO_PENDING値を返します。 ReadFileScatter のこの非同期操作を使用すると、読み取り操作の完了時に呼び出しプロセスを続行できます。 GetOverlappedResult、HasOverlappedIoCompleted、または GetQueuedCompletionStatus 関数を呼び出して、読み取り操作の完了に関する情報を取得できます。 詳細については、「 同期および非同期 I/O」を参照してください。
戻り値
関数が成功すると、戻り値は 0 以外になります。
関数が失敗した場合は、0 を返します。 エラーの詳細情報を得るには、GetLastError 関数を呼び出します。
ReadFileScatter がファイルの末尾 (EOF) を超えて読み取ろうとした場合、その操作の GetOverlappedResult の呼び出しは FALSE を返し、GetLastError はERROR_HANDLE_EOFを返します。
読み取り操作が完了する前に 関数が を返す場合、関数はゼロ (0) を返し、GetLastError はERROR_IO_PENDINGを返します。
注釈
この関数は、Itanium ベースのシステム上の WOW64 によって 32 ビット アプリケーションではサポートされていません。
FILE_SEGMENT_ELEMENT構造体は次のように定義されます。
typedef union _FILE_SEGMENT_ELEMENT {
PVOID64 Buffer;
ULONGLONG Alignment;
}FILE_SEGMENT_ELEMENT, *PFILE_SEGMENT_ELEMENT;
Buffer メンバーへのポインターを割り当てると、コードが 32 ビットとしてコンパイルされる場合、値の符号が拡張されます。これにより、4 ギガバイト チューニングで構成されたシステムで実行されている、または 64 ビット Windows の WOW64 で実行されている大アドレス対応アプリケーションが破損する可能性があります。 したがって、Buffer へのポインターを割り当てるときは 、PtrToPtr64 マクロを使用 します。
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
ファイル ハンドルにバインドされたトランザクションがある場合、関数はファイルのトランザクション処理対象ビューからデータを返します。 トランザクション処理対象の読み取りハンドルは、ハンドルの存続期間中、ファイルの同じビューを表示することが保証されます。要件
| サポートされている最小のクライアント | Windows XP (デスクトップ アプリのみ) |
| サポートされている最小のサーバー | Windows Server 2003 (デスクトップ アプリのみ) |
| 対象プラットフォーム | Windows |
| ヘッダー | fileapi.h (Windows.h を含む) |
| Library | Kernel32.lib |
| [DLL] | Kernel32.dll |