GetQueuedCompletionStatusEx 函式
同時擷取多個完成埠專案。 它會等候與指定完成埠相關聯的擱置 I/O 作業完成。
若要一次取消佇列 I/O 完成封包，請使用 GetQueuedCompletionStatus 函式。
語法
BOOL WINAPI GetQueuedCompletionStatusEx(
_In_ HANDLE CompletionPort,
_Out_ LPOVERLAPPED_ENTRY lpCompletionPortEntries,
_In_ ULONG ulCount,
_Out_ PULONG ulNumEntriesRemoved,
_In_ DWORD dwMilliseconds,
_In_ BOOL fAlertable
);
參數
-
CompletionPort [in]
-
完成埠的控制碼。 若要建立完成埠，請使用 CreateIoCompletionPort 函式。
-
lpCompletionPortEntries [out]
-
在輸入上，指向 預先配置的OVERLAPPED_ENTRY 結構陣列。
在輸出中，接收保存專案的 OVERLAPPED_ENTRY 結構陣列。 ulNumEntriesRemoved提供陣列元素的數目。
在每個 I/O 期間傳輸的位元組數目、指出每個 I/O 發生檔案的完成索引鍵，以及每個原始 I/O 中使用的重迭結構位址都會在 lpCompletionPortEntries 陣列中傳回。
-
ulCount [in]
-
要移除的專案數目上限。
-
ulNumEntriesRemoved [out]
-
接收實際移除專案數之變數的指標。
-
dwMilliseconds [in]
-
呼叫端願意等候完成封包出現在完成埠的毫秒數。 如果完成封包未出現在指定的時間內，函式會逾時並傳回 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值不包含花費在低電量的時間國家。 例如，當電腦處於睡眠狀態時，逾時不會保持倒數。
-
fAlertable [in]
-
如果此參數為 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 通訊協定 |
是 |
| SMB 3.0 透明容錯移轉 (TFO) |
是 |
| 具有向外延展檔案共用的 SMB 3.0 (SO) |
是 |
| 叢集共用磁片區檔案系統 (CsvFS) |
是 |
| 彈性檔案系統 (ReFS) |
是 |
規格需求
| 需求 | 值 |
|---|---|
| 最低支援的用戶端 |
Windows Vista [傳統型應用程式 |UWP 應用程式] |
| 最低支援的伺服器 |
Windows Server 2008 [傳統型應用程式 |UWP 應用程式] |
| 標頭 |
|
| 程式庫 |
|
| DLL |
|