GetQueuedCompletionStatus 函数 (ioapiset.h)

项目
05/20/2023

尝试从指定的 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
);

parameters

[in] CompletionPort

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

lpNumberOfBytesTransferred

指向变量的指针，该变量接收在完成的 I/O 操作中传输的字节数。

[out] lpCompletionKey

指向变量的指针，该变量接收与 I/O 操作已完成的文件句柄关联的完成键值。完成键是在对 CreateIoCompletionPort 的调用中指定的每个文件密钥。

[out] lpOverlapped

指向变量的指针，该变量接收在启动完成 I/O 操作时指定的 OVERLAPPED 结构的地址。

即使已将函数传递给与完成端口关联的文件句柄和有效的 OVERLAPPED 结构，应用程序也可以阻止完成端口通知。为此，为 OVERLAPPED 结构的 hEvent 成员指定有效的事件句柄，并设置其低序位。设置了低顺序位的有效事件句柄可防止重叠 I/O 完成将完成数据包排队到完成端口。

[in] dwMilliseconds

调用方愿意等待完成数据包出现在完成端口上的毫秒数。如果完成数据包未在指定时间内显示，则该函数超时，返回 FALSE，并将 *lpOverlapped 设置为 NULL。

如果 dwMilliseconds 为 INFINITE，则函数永远不会超时。如果 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 值不包括低功耗花费的时间国家。例如，当计算机处于睡眠状态时，超时不会继续倒计时。

返回值

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

要获得更多的错误信息，请调用 GetLastError。

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

备注

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

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

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

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

如果 *lpOverlapped 为 NULL，则函数不会从完成端口取消完成数据包排队。在这种情况下，函数不会将信息存储在 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 应用]
目标平台	Windows
标头	ioapiset.h (包括 Windows.h)
Library	Kernel32.lib
DLL	Kernel32.dll