GetQueuedCompletionStatusEx 函式 (ioapiset.h)

發行項
02/26/2024

同時擷取多個完成埠專案。它會等候與指定完成埠相關聯的擱置 I/O 作業完成。

若要一次取消佇列 I/O 完成封包，請使用 GetQueuedCompletionStatus 函式。

語法

BOOL GetQueuedCompletionStatusEx(
  [in]  HANDLE             CompletionPort,
  [out] LPOVERLAPPED_ENTRY lpCompletionPortEntries,
  [in]  ULONG              ulCount,
  [out] PULONG             ulNumEntriesRemoved,
  [in]  DWORD              dwMilliseconds,
  [in]  BOOL               fAlertable
);

參數

[in] CompletionPort

完成埠的句柄。若要建立完成埠，請使用 CreateIoCompletionPort 函式。

[out] lpCompletionPortEntries

在輸入上，指向預先配置的OVERLAPPED_ENTRY 結構陣列。

在輸出中，接收保存專案的 OVERLAPPED_ENTRY 結構陣列。 ulNumEntriesRemoved 提供陣列元素的數目。

在每個 I/O 期間傳輸的位元組數目、指出每個 I/O 發生檔案的完成索引鍵，以及每個原始 I/O 中使用的重疊結構地址都會在 lpCompletionPortEntries 陣列中傳回。

[in] ulCount

要移除的項目數目上限。

[out] ulNumEntriesRemoved

接收實際移除項目數之變數的指標。

[in] dwMilliseconds

呼叫端願意等候完成封包出現在完成埠的毫秒數。如果完成封包未出現在指定的時間內，函式會逾時並傳回 FALSE。

如果 dwMilliseconds 是 INFINITE (0xFFFFFFFF) ，則函式永遠不會逾時。如果 dwMilliseconds 為零，而且沒有要清除佇列的 I/O 作業，函式將會立即逾時。

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] fAlertable

如果此參數為 FALSE，則函式不會在逾時期間經過或擷取專案之前傳回。

如果參數為 TRUE 且沒有可用的專案，則函式會執行可警示的等候。當系統將 I/O 完成例程或 APC 排入線程，且線程執行函式時，線程會傳回。

完成例程會在指定完成的 ReadFileEx 或 WriteFileEx 函式完成時排入佇列，而呼叫線程是起始作業的線程。當您呼叫 QueueUserAPC 時，APC 會排入佇列。

傳回值

如果成功或零 (FALSE) 則傳回非零 (TRUE) 。

若要取得擴充的錯誤資訊，請呼叫 GetLastError。

備註

此函式會將線程與指定的完成埠產生關聯。線程最多可以與一個完成埠相關聯。

當至少有一個擱置的 I/O 完成時，此函式會傳回 TRUE ，但一或多個 I/O 作業可能會失敗。請注意，此函式的用戶可檢查 lpCompletionPortEntries 參數中傳回的專案清單，藉由查看每個OVERLAPPED_ENTRY中 lpOverlapped 成員中包含的狀態，判斷哪些項目對應至任何可能的失敗 I/O 作業。

未清除佇列時，此函式會傳回 FALSE 。這通常表示處理此呼叫的參數時發生錯誤，或是 CompletionPort 句柄已關閉或無效。 GetLastError 函式提供擴充的錯誤資訊。

如果呼叫 GetQueuedCompletionStatusEx 失敗，因為與其相關聯的句柄已關閉，則函式會傳回 FALSE ，而 GetLastError 會 傳回ERROR_ABANDONED_WAIT_0。

伺服器應用程式可能有數個線程呼叫相同完成埠的 GetQueuedCompletionStatusEx 函 式。當 I/O 作業完成時，它們會依先出順序排入此埠。如果線程正在主動等候此呼叫，一或多個佇列要求只會完成該線程的呼叫。

如需 I/O 完成埠理論、使用方式和相關函式的詳細資訊，請參閱 I/O 完成埠。

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

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

規格需求

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