GetOverlappedResultEx 函式 (ioapiset.h)

發行項
03/05/2024

擷取指定之檔案、命名管道或通訊裝置上重迭作業的結果，該作業在指定的超時時間間隔內。呼叫線程可以執行可警示的等候。

語法

BOOL GetOverlappedResultEx(
  [in]  HANDLE       hFile,
  [in]  LPOVERLAPPED lpOverlapped,
  [out] LPDWORD      lpNumberOfBytesTransferred,
  [in]  DWORD        dwMilliseconds,
  [in]  BOOL         bAlertable
);

參數

[in] hFile

檔案、命名管道或通訊裝置的句柄。這是在呼叫 ReadFile、 WriteFile、 ConnectNamedPipe、 TransactNamedPipe、 DeviceIoControl 或 WaitCommEvent 函式時所指定的相同句柄。

[in] lpOverlapped

重疊作業啟動時所指定之重疊結構的指標。

[out] lpNumberOfBytesTransferred

變數的指標，接收讀取或寫入作業實際傳輸的位元元組數目。對於 TransactNamedPipe 作業，這是從管道讀取的位元組數目。針對 DeviceIoControl 作業，這是設備驅動器所傳回的輸出數據位元組數目。針對 ConnectNamedPipe 或 WaitCommEvent 作業，此值未定義。

[in] dwMilliseconds

逾時間隔，以毫秒為單位。

如果 dwMilliseconds 為零且作業仍在進行中，則函式會立即傳回，而 GetLastError 函式會傳回 ERROR_IO_INCOMPLETE。

如果 dwMilliseconds 為非零，且作業仍在進行中，則函式會等到發出訊號的物件、已排入佇列的 I/O 完成例程或 APC，或傳回之前經過的間隔。使用 GetLastError 取得擴充的錯誤資訊。

如果 dwMilliseconds 是 INFINITE，則函式只會在收到訊號或 I/O 完成例程或 APC 排入佇列時傳回。

Windows XP、Windows Server 2003、Windows Vista、Windows 7、Windows Server 2008 和 Windows Server 2008 R2： dwMilliseconds 值包括花費在低電源狀態的時間。例如，當計算機處於睡眠狀態時，逾時會繼續倒數。

Windows 8、Windows Server 2012、Windows 8.1、Windows Server 2012 R2、Windows 10 和 Windows Server 2016：dwMilliseconds 值不包含花費在低電量的時間國家。例如，當計算機處於睡眠狀態時，逾時不會繼續倒數。

[in] bAlertable

如果此參數為 TRUE ，且呼叫線程處於等候狀態，則當系統排入 I/O 完成例程或 APC 時，函式會傳回。呼叫端線程接著會執行例程或函式。否則，函式不會傳回，而且不會執行完成例程或APC函式。

當已指定完成的 ReadFileEx 或 WriteFileEx 函式完成時，完成例程就會排入佇列。只有在 bAlertable 為 TRUE 時，函式才會傳回並呼叫完成例程，而呼叫線程則是起始讀取或寫入作業的線程。當您呼叫 QueueUserAPC 時，APC 會排入佇列。

傳回值

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

如果此函式失敗，則傳回值為零。若要取得擴充的錯誤資訊，請呼叫 GetLastError。常見的錯誤碼包括下列各項：

如果 dwMilliseconds 為零，且作業仍在進行中， GetLastError 會傳回 ERROR_IO_INCOMPLETE。
如果 dwMilliseconds 非零，且 I/O 完成例程或 APC 已排入佇列， GetLastError 會傳回 WAIT_IO_COMPLETION。
如果 dwMilliseconds 非零，且指定的逾時間隔經過， GetLastError 會傳回 WAIT_TIMEOUT。

備註

GetOverlappedResultEx 函式與 GetOverlappedResult 不同：dwMilliseconds 參數可以指定作業的逾時間隔，而 bAlertable 參數可以指定呼叫線程應該執行可警示的等候。

GetOverlappedResultEx 函式所報告的結果是所指定句柄的最後一個重疊作業，其中提供指定的 OVERLAPPED 結構，以及作業的結果擱置中。啟動作業的函式傳回 FALSE 時，會指出暫止作業，而 GetLastError 函式會傳回 ERROR_IO_PENDING。當 I/O 作業擱置時，啟動作業的函式會將重疊結構的 hEvent 成員重設為非簽署狀態。然後，當擱置作業完成時，系統會將事件物件設定為已發出訊號的狀態。

在 RESETED 結構中指定手動重設事件物件。如果使用自動重設事件物件，則啟動重疊作業和 GetOverlappedResultEx 呼叫之間的間隔，不得在任何其他等候作業中指定事件句柄。例如，事件物件有時會在其中一個等候函式中指定，以等候作業完成。當等候函式傳回時，系統會將自動重設事件的狀態設定為非ignaled，而後續呼叫 GetOverlappedResultEx 並將 dwMilliseconds 參數設定為 INFINITE ，就會無限期地封鎖函式。

如果 OVERLAPPED 結構的 hEvent 成員為 NULL，系統會使用 hFile 句柄的狀態，在作業完成時發出訊號。不建議針對此目的使用檔案、命名管道或通訊裝置句柄。使用事件對象比較安全，因為在同一個檔案、命名管道或通訊裝置上執行多個同時重疊作業時可能發生的混淆。在此情況下，無法得知哪個作業導致物件的狀態發出訊號。

規格需求

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