ReadFileEx 函式 (fileapi.h)
從指定的檔案或輸入/輸出 (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—此函式會取消線程針對指定之檔句柄發出的所有作業。
取消的 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 |