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 のこの非同期操作を使用すると、読み取り操作の完了時に呼び出しプロセスを続行できます。 GetOverlappedResultHasOverlappedIoCompleted、または 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

関連項目

CreateFile

FILE_SEGMENT_ELEMENT

File Management 関数

GetOverlappedResult

GetQueuedCompletionStatus

HasOverlappedIoCompleted

OVERLAPPED

ReadFile

ReadFileEx

WriteFileGather