WriteFileGather

バッファの配列からデータを取り出してファイルに書き込む。

WriteFileGather hFile, aSegmentArray, nNumberOfBytesToWrite, lpReserved, lpOverlapped

hFile : [intptr] ファイルのハンドル。**GENERIC_WRITE** アクセス権、**FILE_FLAG_OVERLAPPED**、**FILE_FLAG_NO_BUFFERING** フラグを付けて作成する必要がある。詳細は File Security and Access Rights を参照。
aSegmentArray : [var] データを含む FILE_SEGMENT_ELEMENT 構造体バッファの配列へのポインタ。各要素は 1 ページ分のデータのアドレスを含む。> [!NOTE] > システムページサイズは GetSystemInfo で調べる。配列には _nNumberOfBytesToWrite_ バイトを格納するのに十分な要素数と終端 NULL 用の 1 要素が必要。たとえば 40 KB を書き込みページサイズが 4 KB なら、配列は 11 要素 (データ 10 + NULL 1) を持つ必要がある。各バッファはシステムメモリページサイズ以上で、システムメモリページサイズ境界に整列する必要がある。システムは各バッファから 1 ページずつ書き込む。本関数は順次収集する。本関数は非同期動作するため、本パラメータが非同期書き込みの間有効なメモリを参照し続けるよう注意する必要がある。たとえばローカルスタックを使い実行スコープが外れるのは典型的な誤用である。
nNumberOfBytesToWrite : [int] 書き込む合計バイト数。aSegmentArray の各要素は合計のうち 1 ページ分のチャンクを含む。ファイルは **FILE_FLAG_NO_BUFFERING** で開かなければならないため、バイト数はファイルが存在するファイルシステムのセクタサイズの倍数である必要がある。0 を指定すると関数は null 書き込み操作を行う。null 書き込みの動作は基になるファイルシステムに依存する。0 でなく、書き込みのオフセットと長さがファイル末尾を超える場合、**WriteFileGather** はファイルを拡張する。
lpReserved : [var] 将来用に予約。NULL でなければならない。
lpOverlapped : [var] OVERLAPPED 構造体へのポインタ。**WriteFileGather** は有効な OVERLAPPED 構造体を必要とし、_lpOverlapped_ を NULL にできない。**WriteFileGather** は OVERLAPPED 構造体の **Offset** と **OffsetHigh** で指定された位置からファイルへデータの書き込みを始める。**WriteFileGather** は書き込み完了前に戻ることがある。その場合、戻り値は 0 で GetLastError は **ERROR_IO_PENDING** を返す。これにより呼び出し側プロセスは書き込み完了中も処理を続けられる。完了情報の取得には GetOverlappedResult、HasOverlappedIoCompleted、GetQueuedCompletionStatus を使える。

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

解説

バッファの配列からデータを取り出してファイルに書き込む。

[戻り値]
関数が成功した場合、戻り値は 0 以外である。関数が失敗した場合、戻り値は 0 となる。拡張エラー情報を取得するには
GetLastError を呼ぶ。書き込み完了前に戻った場合、戻り値は 0 で GetLastError は
**ERROR_IO_PENDING** を返す。

[備考]
本関数は Itanium ベースシステム上の WOW64 では 32
ビットアプリケーションに対してサポートされない。FILE_SEGMENT_ELEMENT 構造体は次のように定義される。
（以下省略）

情報