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

指向 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 位应用程序不支持此函数。

FILE_SEGMENT_ELEMENT结构定义如下：

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