GetQueuedCompletionStatus 函数（ioapiset.h）

项目
11/08/2024

尝试从指定的 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 结构，应用程序也可以阻止完成端口通知。为此，可以指定 hEventOVERLAPPED 结构的成员的有效事件句柄，并设置其低序位。设置低序位的有效事件句柄可防止重叠 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 及更新版本：dwMilliseconds 值不包括在低功率状态下花费的时间。例如，当计算机处于睡眠状态时，超时不会继续倒计时。

返回值

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

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

有关详细信息，请参阅“备注”部分。

言论

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

如果对 GetQueuedCompletionStatus 的调用失败，因为与调用关联的完成端口句柄在未完成时关闭，则该函数将返回 FALSE，*lpOverlapped 将 NULL，GetLastError 将返回 ERROR_ABANDONED_WAIT_0。

Windows Server 2003 和 Windows XP：在调用未完成时关闭完成端口句柄不会导致先前声明的行为。如果指定为除 INFINITE以外的值，函数将继续等待从端口中删除条目或超时。

如果 GetQueuedCompletionStatus 函数成功，则会从完成端口取消对成功的 I/O 操作的完成数据包，并将信息存储在以下参数指向的变量中：lpNumberOfBytes、lpCompletionKey，以及 lpOverlapped。失败后（返回值 FALSE），这些相同的参数可以包含特定的值组合，如下所示：

如果 *lpOverlappedNULL，则该函数不会从完成端口取消完成数据包的排队。在这种情况下，该函数不会将信息存储在 lpNumberOfBytes 和 lpCompletionKey 参数所指向的变量中，并且其值不确定。
如果 *lpOverlapped 未 NULL，并且该函数将从完成端口取消对失败的 I/O 操作的完成数据包进行排队，该函数将有关失败操作的信息存储在由 lpNumberOfBytes、lpCompletionKey和 lpOverlapped指向的变量中。若要获取扩展的错误信息，请调用 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 应用]
目标平台	窗户
标头	ioapiset.h （包括 Windows.h）
库	Kernel32.lib
DLL	Kernel32.dll