共用方式為


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 結構的 OffsetOffsetHigh 成員來指定此位移。 對於不支援位元組位移的檔案或裝置, 會忽略 OffsetOffsetHigh

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

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

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

[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_BUFFERERROR_NOT_ENOUGH_MEMORY

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

  • CancelIo—此函式只會取消由指定之檔句柄之呼叫線程發出的作業。
  • CancelIoEx—此函式會取消線程針對指定之檔句柄發出的所有作業。
使用 CancelSynchronousIo 取消暫止的同步 I/O 作業。

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

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

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

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

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

使用 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

另請參閱

CancelIo

CancelIoEx

CancelSynchronousIo

CreateFile

檔案管理功能

FileIOCompletionRoutine

MsgWaitForMultipleObjectsEx

ReadFile

SetErrorMode

SleepEx

WaitForMultipleObjectsEx

WaitForSingleObjectEx

WriteFileEx