readFileScatter 函数 (fileapi.h)
从文件读取数据并将其存储在缓冲区数组中。
函数开始从文件读取由 OVERLAPPED 结构指定的位置的数据。 ReadFileScatter 函数异步操作。
语法
BOOL ReadFileScatter(
[in] HANDLE hFile,
[in] FILE_SEGMENT_ELEMENT [] aSegmentArray,
[in] DWORD nNumberOfBytesToRead,
LPDWORD lpReserved,
[in, out] LPOVERLAPPED lpOverlapped
);
参数
[in] hFile
要读取的文件的句柄。
必须使用 GENERIC_READ 权限以及 FILE_FLAG_OVERLAPPED 和 FILE_FLAG_NO_BUFFERING 标志创建文件句柄。 有关详细信息，请参阅 文件安全和访问权限。
[in] aSegmentArray
指向接收数据的 FILE_SEGMENT_ELEMENT结构 缓冲区数组的指针。 有关此联合的说明，请参阅 备注。
每个元素表示一页数据。
注意
若要确定系统页的大小，请使用 GetSystemInfo。
数组必须包含足够的元素来表示 nNumberOfBytesToRead 数据字节。 例如，如果要读取 40 KB 且页面大小为 4 KB，则数组必须具有 10 个元素。
每个缓冲区必须至少为系统内存页的大小，并且必须在系统内存页大小边界上对齐。 系统将一个系统内存页的数据读入每个缓冲区。
函数按顺序将数据存储在缓冲区中。 例如，它将数据存储到第一个缓冲区，然后存储到第二个缓冲区，依依如此，直到填充每个缓冲区并存储所有数据，或读取 nNumberOfBytesToRead 字节。
[in] nNumberOfBytesToRead
要从文件读取的总字节数。 aSegmentArray 的每个元素都包含此总计的一页区块。 由于必须使用 FILE_FLAG_NO_BUFFERING 打开文件，因此字节数必须是文件所在文件系统扇区大小的倍数。
lpReserved
此参数保留供将来使用，必须为 NULL。
[in, out] lpOverlapped
指向 OVERLAPPED 数据结构的指针。
ReadFileScatter 函数需要有效的 OVERLAPPED 结构。 lpOverlapped 参数不能为 NULL。
ReadFileScatter 函数开始从文件读取数据的位置，该位置由 OVERLAPPED 结构的 Offset 和 OffsetHigh 成员指定。
ReadFileScatter 函数可能会在读取操作完成之前返回。 在这种情况下， ReadFileScatter 函数返回值 0 (零 ) ，GetLastError 函数 返回值ERROR_IO_PENDING。 ReadFileScatter 的此异步操作允许调用进程在读取操作完成时继续。 可以调用 GetOverlappedResult、 HasOverlappedIoCompleted 或 GetQueuedCompletionStatus 函数来获取有关读取操作完成的信息。 有关详细信息，请参阅 同步和异步 I/O。
返回值
如果该函数成功，则返回值为非零值。
如果函数失败，则返回值为零 (0)。 若要获得更多的错误信息，请调用 GetLastError 函数。
如果 ReadFileScatter 尝试读取超过文件末尾 (EOF) ，则调用该操作的 GetOverlappedResult 将返回 FALSE，GetLastError 返回ERROR_HANDLE_EOF。
如果函数在读取操作完成之前返回，则函数返回零 (0 ) ，GetLastError 返回 ERROR_IO_PENDING。
注解
基于 Itanium 的系统上的 WOW64 不支持 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 宏。
在 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 |