共用方式為


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_OVERLAPPEDFILE_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 結構的 OffsetOffsetHigh 成員所指定的位置。

ReadFileScatter 函式可能會在讀取作業完成之前傳回。 在該案例中, ReadFileScatter 函式會傳回值 0 (零) , 而 GetLastError 函式會傳回值 ERROR_IO_PENDINGReadFileScatter 的這個異步操作可讓呼叫進程在讀取作業完成時繼續。 您可以呼叫 GetOverlappedResultHasOverlappedIoCompletedGetQueuedCompletionStatus 函式,以取得讀取作業完成的相關信息。 如需詳細資訊,請參閱 同步和異步 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

另請參閱

CreateFile

FILE_SEGMENT_ELEMENT

檔案管理功能

GetOverlappedResult

GetQueuedCompletionStatus

HasOverlappedIoCompleted

重疊

ReadFile

ReadFileEx

WriteFileGather