GetQueuedCompletionStatus 函式（ioapiset.h）

發行項
11/08/2024

嘗試從指定的 I/O 完成埠清除 I/O 完成封包。如果沒有排入佇列的完成封包，函式會等候與完成埠相關聯的擱置 I/O 作業完成。

若要一次清除多個 I/O 完成封包，請使用 getQueuedCompletionStatusEx 函式。

語法

BOOL GetQueuedCompletionStatus(
  [in]  HANDLE       CompletionPort,
        LPDWORD      lpNumberOfBytesTransferred,
  [out] PULONG_PTR   lpCompletionKey,
  [out] LPOVERLAPPED *lpOverlapped,
  [in]  DWORD        dwMilliseconds
);

參數

[in] CompletionPort

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

lpNumberOfBytesTransferred

變數的指標，可接收在已完成 I/O 作業中傳輸的位元元組數目。

[out] lpCompletionKey

變數的指標，這個變數會接收與 I/O 作業已完成之檔句柄相關聯的完成索引鍵值。完成金鑰是呼叫 createIoCompletionPort 中指定的每個檔案索引鍵。

[out] lpOverlapped

變數的指標，這個變數會接收啟動完成 I/O 作業時所指定之重疊結構的位址。

即使您已將與完成埠相關聯的檔案句柄和有效的重疊結構傳遞給函式，應用程式仍可能會防止完成埠通知。這可藉由指定 hEvent 成員重疊結構的有效事件句柄，並設定其低序位來完成。設定低序位的有效事件句柄可防止重疊 I/O 將完成封包加入完成埠。

[in] dwMilliseconds

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

如果 dwMillisecondsINFINITE，則函式永遠不會逾時。如果 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 值不包含花費在低功率狀態的時間。例如，當計算機處於睡眠狀態時，逾時不會繼續倒數。

傳回值

如果成功或零（FALSE），則傳回非零（TRUE）。

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

如需詳細資訊，請參閱一節。

言論

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

如果呼叫 GetQueuedCompletionStatus 失敗，因為與它相關聯的完成埠句柄在呼叫未完成時已關閉，則函式會傳回 FALSE，*lpOverlapped 將會 NULL，而且 GetLastError 會傳回 ERROR_ABANDONED_WAIT_0。

Windows Server 2003 和 Windows XP：呼叫未完成時關閉完成埠句柄，不會產生先前所述的行為。如果指定為INFINITE 以外的值，函式會繼續等候從埠移除專案，或直到發生逾時為止。

如果 GetQueuedCompletionStatus 函式成功，它會從完成埠取消佇列，以取得成功的 I/O 作業完成封包，並將資訊儲存在下列參數所指向的變數中：lpNumberOfBytes、lpCompletionKey，以及 lpOverlapped。失敗時（傳回值 FALSE），這些相同的參數可以包含特定的值組合，如下所示：

如果 *lpOverlappedNULL，則函式不會從完成埠清除完成封包。在此情況下，函式不會將資訊儲存在 lpNumberOfBytes 和 lpCompletionKey 參數所指向的變數中，而且其值不確定。
如果 *lpOverlapped 未 NULL，且函式會從完成埠清除失敗 I/O 作業的完成封包，函式會將失敗作業的相關信息儲存在 lpNumberOfBytes、lpCompletionKey和 lpOverlapped所指向的變數中。若要取得擴充的錯誤資訊，請呼叫 GetLastError。

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

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

科技	支援
伺服器消息塊（SMB） 3.0 通訊協定	是的
SMB 3.0 透明故障轉移（TFO）	是的
具有向外延展檔案共用的SMB 3.0（SO）	是的
叢集共用磁碟區檔案系統（CsvFS）	是的
復原檔案系統（ReFS）	是的

要求

要求	價值
最低支援的用戶端	Windows XP [傳統型應用程式 \|UWP 應用程式]
支援的最低伺服器	Windows Server 2003 [傳統型應用程式 \|UWP 應用程式]
目標平臺	窗戶
標頭	ioapiset.h （包括 Windows.h）
連結庫	Kernel32.lib
DLL	Kernel32.dll