getQueuedCompletionStatusEx 函数 (ioapiset.h)

项目
02/29/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。

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

[in] fAlertable

如果此参数为 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 关联的句柄关闭而调用失败，则函数返回 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)	是
群集共享卷文件系统 (CSV)	是
弹性文件系统 (ReFS)	是

要求

要求	值
最低受支持的客户端	Windows Vista [桌面应用 \| UWP 应用]
最低受支持的服务器	Windows Server 2008 [桌面应用 \| UWP 应用]
目标平台	Windows
标头	ioapiset.h (包括 Windows.h)
Library	Kernel32.lib
DLL	Kernel32.dll