GetQueuedCompletionStatusEx 函式（ioapiset.h）

發行項
11/08/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。

如果 dwMillisecondsINFINITE （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 和更新版本：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 作業。

當未清除 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 應用程式]
目標平臺	窗戶
標頭	ioapiset.h （包括 Windows.h）
連結庫	Kernel32.lib
DLL	Kernel32.dll