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 應用程式]
標頭
IoAPI.h (包括 Windows.h) ;
Windows Server 2008 R2、Windows 7、Windows Server 2008 和 Windows Vista 上的 WinBase.h (包括 Windows.h)
程式庫
Kernel32.lib
DLL
Kernel32.dll

另請參閱

概觀主題

檔案管理功能

I/O 完成埠

使用 Windows 標頭

函式

ConnectNamedPipe

CreateIoCompletionPort

DeviceIoControl

GetQueuedCompletionStatusEx

LockFileEx

ReadFile

PostQueuedCompletionStatus

TransactNamedPipe

WaitCommEvent

WriteFile