GetQueuedCompletionStatusEx 函数

2025-05-08

同时检索多个完成端口条目。它等待与指定完成端口关联的待处理 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
);

参数

完成端口[in]

完成端口的句柄。要创建完成端口，请使用 CreateIoCompletionPort 函数。

lpCompletionPort条目[out]

在输入时，指向预先分配的 OVERLAPPED_ENTRY 结构数组。

在输出时，接收保存条目的 OVERLAPPED_ENTRY 结构体的数组。数组元素的数量由 ulNumEntriesRemoved 提供。

每个 I/O 期间传输的字节数、指示每个 I/O 发生在哪个文件的完成键以及每个原始 I/O 中使用的重叠结构地址都在 lpCompletionPortEntries 数组中返回。

ulCount[in]

要删除的最大条目数。

ulNumEntriesRemoved[out]

指向变量的指针，该变量接收实际删除的条目数。

dw毫秒[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 值不包括在低功耗状态下花费的时间。例如，当计算机处于休眠状态时，超时不会一直倒计时。

f可警报[in]

如果此参数为 FALSE，则函数在超时期限已过或检索到条目之前不会返回。

如果参数为 TRUE 且没有可用条目，则函数将执行可警报的等待。当系统将 I/O 完成例程或 APC 排队到线程并且线程执行该函数时，线程将返回。

当指定完成例程的 ReadFileEx 或 WriteFileEx 函数完成时，完成例程将排队，调用线程是启动该作的线程。当您调用 QueueUserAPC 时，APC 将排队。

返回值

如果成功，则返回非零 TRUE ，否则返回零 FALSE 。

要获取扩展的错误信息，请调用 GetLastError。

注解

此函数将线程与指定的完成端口相关联。一个线程最多可以与一个完成端口相关联。

当至少完成一个挂起的 I/O 时，此函数将返回 TRUE ，但一个或多个 I/O作可能会失败。请注意，此函数的用户负责检查 lpCompletionPortEntries 参数中返回的条目列表，通过查看每个 OVERLAPPED_ENTRY 中 lpOverlapped 成员中包含的状态，确定其中哪些条目对应于任何可能的失败 I/O作。

此函数在没有 I/O作取消排队时返回 FALSE 。这通常意味着在处理此调用的参数时发生错误，或者 CompletionPort 句柄已关闭或无效。 GetLastError 函数提供扩展的错误信息。

如果对 GetQueuedCompletionStatusEx 的调用因与其关联的句柄已关闭而失败，则函数将返回 FALSEGetLastErrorERROR_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`） `WinBase.h` 在 Windows Server 2008 R2、Windows 7、Windows Server 2008 和 Windows Vista（包括 `Windows.h`）上
图书馆	`Kernel32.lib`
DLL	`Kernel32.dll`