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 ページを表します。
注意
システム ページのサイズを確認するには、 GetSystemInfo 関数を使用します。
配列には、 データの 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 では、この関数は、次のテクノロジによってサポートされています。
| テクノロジ | サポートされています |
|---|---|
| サーバー メッセージ ブロック (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 |
関連項目
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示