ReadFileEx 函式 (fileapi.h)

發行項
02/28/2024

從指定的檔案或輸入/輸出 (I/O) 裝置讀取數據。它會以異步方式報告其完成狀態，並在讀取完成或取消時呼叫指定的完成例程，而且呼叫線程處於可警示的等候狀態。

若要以同步方式從檔案或裝置讀取數據，請使用 ReadFile 函式。

語法

BOOL ReadFileEx(
  [in]            HANDLE                          hFile,
  [out, optional] LPVOID                          lpBuffer,
  [in]            DWORD                           nNumberOfBytesToRead,
  [in, out]       LPOVERLAPPED                    lpOverlapped,
  [in]            LPOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine
);

參數

[in] hFile

檔案或 I/O 裝置的句柄 (例如檔案、檔案數據流、實體磁碟、磁碟區、控制台緩衝區、磁帶機、套接字、通訊資源、mailslot 或管道) 。

這個參數可以是由 CreateFile 函式以 FILE_FLAG_OVERLAPPED 旗標開啟的任何句柄，或是套接字或 accept 函式所傳回的套接字句柄。

此句柄也必須具有 GENERIC_READ 訪問許可權。如需訪問許可權的詳細資訊，請參閱檔案安全性和訪問許可權。

[out, optional] lpBuffer

緩衝區的指標，接收從檔案或裝置讀取的數據。

此緩衝區在讀取作業的持續期間必須保持有效。在讀取作業完成之前，應用程式不應該使用此緩衝區。

[in] nNumberOfBytesToRead

要讀取的位元組數。

[in, out] lpOverlapped

重疊數據結構的指標，提供異步 (重疊) 檔案讀取作業期間要使用的數據。

對於支援位元組位移的檔案，您必須指定要從檔案開始讀取的位元組位移。您可以藉由設定 OVERLAPPED 結構的 Offset 和 OffsetHigh 成員來指定此位移。對於不支援位元組位移的檔案或裝置， 會忽略 Offset 和 OffsetHigh 。

ReadFileEx 函式會忽略 OVERLAPPED 結構的 hEvent 成員。應用程式在 ReadFileEx 呼叫的內容中，可以自由使用該成員做為自己的用途。 ReadFileEx 會藉由呼叫或佇列呼叫來發出完成其讀取作業的訊號，也就是 lpCompletionRoutine 所指向的完成例程，因此不需要事件句柄。

ReadFileEx 函式會使用 OVERLAPPED 結構的 Internal 和 InternalHigh 成員。應用程式不應該設定這些成員。

重疊的數據結構在讀取作業期間必須維持有效狀態。它不應該是可在讀取作業擱置完成時超出範圍的變數。

[in] lpCompletionRoutine

讀取作業完成且呼叫線程處於可警示等候狀態時，要呼叫之完成例程的指標。如需完成例程的詳細資訊，請參閱 FileIOCompletionRoutine。

傳回值

如果函式成功，則傳回非零的值。

如果此函式失敗，則傳回值為零。若要取得擴充的錯誤資訊，請呼叫 GetLastError。

如果函式成功，呼叫線程會有暫止的異步 I/O 作業：檔案中的重迭讀取作業。當這個 I/O 作業完成，且呼叫線程以可警示的等候狀態封鎖時，系統會呼叫 lpCompletionRoutine 所指向的函式，而等候狀態會以傳回碼 WAIT_IO_COMPLETION完成。

如果函式成功，且檔案讀取作業完成，但呼叫線程並未處於可警示的等候狀態，則系統會將完成例程呼叫排入佇列，直到呼叫線程進入可警示的等候狀態為止。如需可警示等候和重疊輸入/輸出作業的相關信息，請參閱關於同步處理。

如果 ReadFileEx 嘗試讀取超過檔尾 (EOF) ，該作業的 GetOverlappedResult 呼叫會傳回 FALSE ，而 GetLastError 會 傳回ERROR_HANDLE_EOF。

備註

使用 ReadFileEx 時，即使函式傳回「成功」，還是應該檢查 GetLastError ，以檢查是否為「成功」，但有一些您可能想要知道的結果。例如，呼叫 ReadFileEx 時的緩衝區溢位會傳回 TRUE，但 GetLastError 會報告具有 ERROR_MORE_DATA的溢位。如果函數調用成功，而且沒有任何警告條件， GetLastError 會 傳回ERROR_SUCCESS。

如果有太多未處理的異步 I/O 要求， ReadFileEx 函式可能會失敗。發生這類失敗時， GetLastError 可以傳回 ERROR_INVALID_USER_BUFFER 或 ERROR_NOT_ENOUGH_MEMORY。

若要取消所有暫止的異步 I/O 作業，請使用：

CancelIo—此函式只會取消由指定之檔句柄之呼叫線程發出的作業。
CancelIoEx—此函式會取消線程針對指定之檔句柄發出的所有作業。

使用 CancelSynchronousIo 取消暫止的同步 I/O 作業。

取消的 I/O 作業已完成，錯誤 ERROR_OPERATION_ABORTED。

如果 hFile 所指定的檔案部分被另一個進程鎖定，而且呼叫 ReadFileEx 中指定的讀取作業與鎖定的部分重疊， 則 ReadFileEx 的呼叫會失敗。

嘗試從緩衝區太小的郵件集讀取數據時， ReadFileEx 會傳回 FALSE，而 GetLastError 會 傳回ERROR_INSUFFICIENT_BUFFER。

讀取作業使用緩衝區時存取輸入緩衝區，可能會導致讀取到該緩衝區的數據損毀。應用程式不得讀取、寫入、重新配置或釋放讀取作業所使用的輸入緩衝區，直到讀取作業完成為止。

應用程式會使用 MsgWaitForMultipleObjectsEx、 WaitForSingleObjectEx、 WaitForMultipleObjectsEx 和 SleepEx 函式來進入可警示的等候狀態。如需可警示等候和重疊輸入/輸出的詳細資訊，請參閱關於同步處理。

使用 createFile FILE_FLAG_NO_BUFFERING 成功使用 CreateFile 開啟的檔案有嚴格的需求。 如需詳細資訊，請參閱檔案緩衝。

在 Windows 8 和 Windows Server 2012 中，下列技術支援此函式。

技術	支援
伺服器消息塊 (SMB) 3.0 通訊協定	Yes
SMB 3.0 透明故障轉移 (TFO)	Yes
具有向外延展檔案共用的SMB 3.0 (SO)	Yes
叢集共用磁碟區文件系統 (CsvFS)	Yes
彈性檔案系統 (ReFS)	Yes

交易作業

如果有系結至檔句柄的交易，則函式會從檔案的交易檢視傳回數據。交易讀取句柄保證會在句柄期間顯示檔案的相同檢視。如需詳細資訊，請參閱關於交易式NTFS。

範例

如需範例，請參閱使用完成例程的命名管道伺服器。

規格需求

需求	值
最低支援的用戶端	Windows XP [傳統型應用程式 \|UWP 應用程式]
最低支援的伺服器	Windows Server 2003 [傳統型應用程式 \|UWP 應用程式]
目標平台	Windows
標頭	fileapi.h (包含 Windows.h)
程式庫	Kernel32.lib
DLL	Kernel32.dll