GetQueuedCompletionStatus 函数 (ioapiset.h)
尝试从指定的 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。
在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 |
另请参阅
函数
概述主题