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

重疊數據結構的指標。

ReadFileScatter 函式需要有效的重疊結構。 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位，指派 緩衝區 成員的指標將會簽署擴充值;這可能會中斷在設定為 4 GB 微調的系統上執行的大型位址感知應用程式，或在 64 位 Windows 上的 WOW64 下執行。因此，將指標指派給 Buffer 時，請使用 PtrToPtr64 宏。

在 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