getQueuedCompletionStatus 函式 (ioapiset.h)

發行項
05/20/2023

嘗試從指定的 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 作業時所指定的重迭結構位址。

即使您已傳遞函式與完成埠和有效 OVERLAPPED 結構相關聯的檔案控制碼，應用程式仍可能會防止完成埠通知。這是藉由指定重迭結構之 hEvent成員的有效事件控制碼，以及設定其低序位來完成。設定低序位的有效事件控制碼可防止重迭 I/O 將完成封包排入佇列至完成埠。

[in] dwMilliseconds

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

如果 dwMilliseconds 是 INFINITE，則函式永遠不會逾時。如果 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值不包含花費在低電量的時間國家。例如，當電腦進入睡眠狀態時，逾時不會繼續倒數。

傳回值

如果成功或零 (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) 時，這些相同的參數可以包含特定的值組合，如下所示：

如果 *lpOverlapped 為 Null，則函式不會從完成埠取消佇列完成封包。在此情況下，函式不會將資訊儲存在 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 應用程式]
目標平台	Windows
標頭	ioapiset.h (包含 Windows.h)
程式庫	Kernel32.lib
DLL	Kernel32.dll