readFileScatter 函数 (fileapi.h)

项目
01/10/2024

从文件读取数据并将其存储在缓冲区数组中。

函数开始从文件读取由 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 位应用程序使用此函数。

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 宏。

在 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