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結構緩衝區陣列的指標。 如需此等位的描述，請參閱。
每個元素都代表一頁的數據。
注意
若要判斷系統頁面的大小，請使用 GetSystemInfo 函式。
陣列必須包含足夠的元素，才能代表 nNumberOfBytesToWrite 位元組的數據。 例如，如果要寫入 40 KB，且頁面大小為 4 KB，則陣列必須有 10 個元素。
每個緩衝區都必須至少是系統記憶體頁面的大小，而且必須對齊系統記憶體頁面大小界限。 系統會從每個緩衝區寫入一個系統記憶體頁面的數據。
函式會依循序順序從緩衝區收集數據。 例如，它會從第一個緩衝區將數據寫入檔案，然後寫入第二個緩衝區，依此類說，直到 寫入 nNumberOfBytesToWrite 位元組為止。
由於此函式的異步操作，因此必須採取預防措施，以確保此參數一律會參考異步寫入存留期的有效記憶體。 例如，常見的程式設計錯誤是使用本機堆疊記憶體，然後允許執行超出範圍。
[in] nNumberOfBytesToWrite
要寫入的位元組總數。 aSegmentArray 的每個元素都包含此總計的一頁區塊。 因為檔案必須以 FILE_FLAG_NO_BUFFERING開啟，所以位元組數目必須是檔案所在文件系統的扇區大小的倍數。
如果 nNumberOfBytesToWrite 為零 (0) ，則函式會執行 Null 寫入作業。 Null 寫入作業的行為取決於基礎文件系統。 如果 nNumberOfBytesToWrite 不是零 (0) ，而且寫入位置數據的位移和長度超出檔案的目前結尾， 則 WriteFileGather 函式會擴充檔案。
lpReserved
此參數保留供日後使用，且必須為 NULL。
[in, out] lpOverlapped
重疊數據結構的指標。
WriteFileGather 函式需要有效的 OVERLAPPED 結構。 lpOverlapped 參數不可為 NULL。
WriteFileGather 函式會開始將數據寫入檔案，該位置是由 OVERLAPPED 結構的 Offset 和 OffsetHigh 成員所指定。
WriteFileGather 函式可能會在寫入作業完成之前傳回。 在該案例中， WriteFileGather 函式會傳回值零 (0) ，而 GetLastError 函式會傳回值 ERROR_IO_PENDING。 WriteFileGather 函式的這個異步操作可讓呼叫進程在寫入作業完成時繼續。
您可以呼叫 GetOverlappedResult、 HasOverlappedIoCompleted 或 GetQueuedCompletionStatus 函式，以取得寫入作業完成的相關信息。 如需詳細資訊，請參閱 同步和異步 I/O。
傳回值
如果函式成功，則傳回非零的值。
如果函式失敗，傳回值為零， (0) 。 若要取得擴充的錯誤資訊，請呼叫 GetLastError 函 式。
如果函式在寫入作業完成之前傳回，則函式會傳回零 (0) ，而 GetLastError 函 式會 傳回ERROR_IO_PENDING。
備註
Itanium 型系統上的 WOW64 不支援此函式。
FILE_SEGMENT_ELEMENT結構的定義如下：
typedef union _FILE_SEGMENT_ELEMENT {
PVOID64 Buffer;
ULONGLONG Alignment;
}FILE_SEGMENT_ELEMENT, *PFILE_SEGMENT_ELEMENT;
如果程式代碼編譯為32位，指派 緩衝區 成員的指標將會簽署擴充值;這可能會中斷在設定 為 4 GB 微調 的系統上執行的大型位址感知應用程式，或在 64 位 Windows 上的 WOW64 下執行。 因此，將指標指派給 Buffer 時，請使用 PtrToPtr64 宏。
如果 hFile 指定的檔案部分被另一個進程鎖定，而且寫入作業與鎖定的部分重疊， WriteFileGather 函式會失敗。
在 Windows 8 和 Windows Server 2012 中，下列技術支援此函式。
| 技術 | 支援 |
|---|---|
| 伺服器消息塊 (SMB) 3.0 通訊協定 | Yes |
| SMB 3.0 透明故障轉移 (TFO) | Yes |
| 具有向外延展檔案共用的SMB 3.0 (SO) | Yes |
| 叢集共用磁碟區文件系統 (CsvFS) | Yes |
| 彈性檔案系統 (ReFS) | Yes |
交易作業
如果有系結至檔句柄的交易，則會交易作業。規格需求
| 最低支援的用戶端 | Windows XP [僅限傳統型應用程式] |
| 最低支援的伺服器 | Windows Server 2003 [僅限桌面應用程式] |
| 目標平台 | Windows |
| 標頭 | fileapi.h (包含 Windows.h) |
| 程式庫 | Kernel32.lib |
| DLL | Kernel32.dll |