共用方式為


getQueuedCompletionStatus 函式 (ioapiset.h)

嘗試從指定的 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

如果 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、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 作業的完成封包,並將資訊儲存在下列參數所指向的變數中: lpNumberOfByteslpCompletionKeylpOverlapped。 失敗 (傳回值為 FALSE) 時,這些相同的參數可以包含特定的值組合,如下所示:

  • 如果 *lpOverlappedNull,則函式不會從完成埠取消佇列完成封包。 在此情況下,函式不會將資訊儲存在 lpNumberOfByteslpCompletionKey 參數所指向的變數中,而且其值不確定。
  • 如果 *lpOverlapped 不是 Null ,而且函式會從完成埠清除失敗 I/O 作業的完成封包,則函式會將失敗作業的相關資訊儲存在 lpNumberOfByteslpCompletionKeylpOverlapped所指向的變數中。 若要取得擴充的錯誤資訊,請呼叫 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

另請參閱

ConnectNamedPipe

CreateIoCompletionPort

DeviceIoControl

檔案管理功能

函式

GetQueuedCompletionStatusEx

I/O 完成埠

LockFileEx

概觀主題

PostQueuedCompletionStatus

ReadFile

TransactNamedPipe

使用 Windows 標頭

WaitCommEvent

WriteFile