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
指向 OVERLAPPED 数据结构的指针。
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。
注解
WOW64 在基于 Itanium 的系统上，32 位应用程序不支持此函数。
typedef union _FILE_SEGMENT_ELEMENT {
PVOID64 Buffer;
ULONGLONG Alignment;
}FILE_SEGMENT_ELEMENT, *PFILE_SEGMENT_ELEMENT;
如果代码编译为 32 位，则为 Buffer 成员分配指针将对值进行签名扩展;这可能会中断在配置了 4 GB 优化 的系统上运行或在 64 位 Windows 上的 WOW64 下运行的大型地址感知应用程序。 因此，在将指针分配给 Buffer 时，请使用 PtrToPtr64 宏。
如果 hFile 指定的文件的一部分被另一个进程锁定，并且写入操作与锁定部分重叠， 则 WriteFileGather 函数将失败。
在 Windows 8 和 Windows Server 2012 中，此函数由以下技术支持。
| 技术 | 支持 |
|---|---|
| 服务器消息块 (SMB) 3.0 协议 | 是 |
| SMB 3.0 透明故障转移 (TFO) | 是 |
| 具有横向扩展文件共享的 SMB 3.0 (SO) | 是 |
| 群集共享卷文件系统 (CSV) | 是 |
| 弹性文件系统 (ReFS) | 是 |
事务处理操作
如果有绑定到文件句柄的事务，则会处理该操作。要求
| 最低受支持的客户端 | Windows XP [仅限桌面应用] |
| 最低受支持的服务器 | Windows Server 2003 [仅限桌面应用] |
| 目标平台 | Windows |
| 标头 | fileapi.h (包括 Windows.h) |
| Library | Kernel32.lib |
| DLL | Kernel32.dll |