writeFileGather 函式 (fileapi.h)

發行項
01/10/2024

從緩衝區陣列擷取數據，並將數據寫入檔案。

函式會開始將數據寫入至檔案，該位置是由 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