WriteFileGather 関数 (fileapi.h)

バッファーの配列からデータを取得し、データをファイルに書き込みます。

関数は、 OVERLAPPED 構造体で指定された位置でファイルへのデータの書き込みを開始します。 WriteFileGather 関数は非同期的に動作します。

構文

BOOL WriteFileGather(
  [in]      HANDLE                  hFile,
  [in]      FILE_SEGMENT_ELEMENT [] aSegmentArray,
  [in]      DWORD                   nNumberOfBytesToWrite,
            LPDWORD                 lpReserved,
  [in, out] LPOVERLAPPED            lpOverlapped
);

パラメーター

[in] hFile

ファイルへのハンドル。 ファイル ハンドルは、GENERIC_WRITEアクセス権と、 FILE_FLAG_OVERLAPPED フラグと FILE_FLAG_NO_BUFFERING フラグを使用して作成 する 必要があります。 詳細については、「 ファイル のセキュリティとアクセス権」を参照してください。

[in] aSegmentArray

データを含む FILE_SEGMENT_ELEMENT構造体 バッファーの配列へのポインター。 この共用体の説明については、「解説」を参照してください。

各要素は、データの 1 ページを表します。

配列には、 データの nNumberOfBytesToWrite バイトを表す十分な要素が含まれている必要があります。 たとえば、40 KB の書き込みがあり、ページ サイズが 4 KB の場合、配列には 10 個の要素が必要です。

各バッファーは、少なくともシステム メモリ ページのサイズである必要があり、システム メモリ ページ サイズの境界に配置する必要があります。 システムは、各バッファーからデータの 1 つのシステム メモリ ページを書き込みます。

関数は、バッファーからデータを順番に収集します。 たとえば、 nNumberOfBytesToWrite バイトが書き込まれるまで、最初のバッファー、次に 2 番目のバッファーからファイルにデータを書き込みます。

この関数の非同期操作により、このパラメーターが非同期書き込みの有効期間にわたって常に有効なメモリを参照するように注意する必要があります。 たとえば、一般的なプログラミング エラーは、ローカル スタック ストレージを使用し、スコープを使い果たせるようにすることです。

[in] nNumberOfBytesToWrite

書き込まれるバイトの合計数。 aSegmentArray の各要素には、この合計の 1 ページのチャンクが含まれています。 ファイルは FILE_FLAG_NO_BUFFERINGで開く必要があるため、バイト数は、ファイルが配置されているファイル システムのセクター サイズの倍数である必要があります。

nNumberOfBytesToWrite がゼロ (0) の場合、関数は null 書き込み操作を実行します。 null 書き込み操作の動作は、基になるファイル システムによって異なります。 nNumberOfBytesToWrite がゼロ (0) ではなく、書き込み場所データのオフセットと長さがファイルの現在の末尾を超える場合、WriteFileGather 関数はファイルを拡張します。

lpReserved

このパラメーターは将来使用するために予約されており、 NULL である必要があります。

[in, out] lpOverlapped

OVERLAPPED データ構造へのポインター。

WriteFileGather 関数には、有効な OVERLAPPED 構造体が必要です。 lpOverlapped パラメーターを NULL にすることはできません。

WriteFileGather 関数は、OVERLAPPED 構造体の Offset メンバーと OffsetHigh メンバーによって指定された位置で、ファイルへのデータの書き込みを開始します。

WriteFileGather 関数は、書き込み操作が完了する前に を返す場合があります。 そのシナリオでは、 WriteFileGather 関数は値 0 を返し、 GetLastError 関数は 値ERROR_IO_PENDINGを返します。 WriteFileGather 関数のこの非同期操作により、書き込み操作の完了時に呼び出しプロセスを続行できます。

GetOverlappedResult、HasOverlappedIoCompleted、または GetQueuedCompletionStatus 関数を呼び出して、書き込み操作の完了に関する情報を取得できます。 詳細については、「 同期および非同期 I/O」を参照してください。

戻り値

関数が成功すると、戻り値は 0 以外になります。

関数が失敗した場合は、0 を返します。 エラーの詳細情報を得るには、GetLastError 関数を呼び出します。

書き込み操作が完了する前に 関数が を返した場合、関数はゼロ (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 マクロを使用 します。

hFile で指定されたファイルの一部が別のプロセスによってロックされ、書き込み操作がロックされた部分と重複している場合、WriteFileGather 関数は失敗します。

Windows 8 と Windows Server 2012 では、この関数は、次のテクノロジによってサポートされています。

Transacted Operations

要件

関連項目

CreateFile

FILE_SEGMENT_ELEMENT

File Management 関数

GetOverlappedResult

GetQueuedCompletionStatus

HasOverlappedIoCompleted

OVERLAPPED

ReadFile

ReadFileEx

ReadFileScatter

同期および非同期 I/O