GetQueuedCompletionStatusEx 函数（ioapiset.h）

项目
11/08/2024

同时检索多个完成端口条目。它等待与指定的完成端口关联的挂起 I/O 操作完成。

若要逐个取消 I/O 完成数据包的排队，请使用 GetQueuedCompletionStatus 函数。

语法

BOOL GetQueuedCompletionStatusEx(
  [in]  HANDLE             CompletionPort,
  [out] LPOVERLAPPED_ENTRY lpCompletionPortEntries,
  [in]  ULONG              ulCount,
  [out] PULONG             ulNumEntriesRemoved,
  [in]  DWORD              dwMilliseconds,
  [in]  BOOL               fAlertable
);

参数

[in] CompletionPort

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

[out] lpCompletionPortEntries

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

在输出中，接收包含条目的 OVERLAPPED_ENTRY 结构的数组。数组元素的数目由 ulNumEntriesRemoved 提供。

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

[in] ulCount

要删除的最大条目数。

[out] ulNumEntriesRemoved

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

[in] dwMilliseconds

调用方愿意等待完成数据包出现在完成端口上的毫秒数。如果完成数据包未出现在指定时间内，函数超时并返回 FALSE。

如果 dwMillisecondsINFINITE （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 及更新版本：dwMilliseconds 值不包括在低功率状态下花费的时间。例如，当计算机处于睡眠状态时，超时不会继续倒计时。

[in] fAlertable

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

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

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

返回值

如果成功或零（FALSE），则返回非零（TRUE）。

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

言论

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

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

如果未取消 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 应用]
目标平台	窗户
标头	ioapiset.h （包括 Windows.h）
库	Kernel32.lib
DLL	Kernel32.dll