MsgWaitForMultipleObjectsEx 函数 (winuser.h)

项目
03/04/2024

等待一个或所有指定对象处于信号状态、I/O 完成例程或异步过程调用 (APC) 排队到线程，或者超时间隔已过。对象的数组可以包含使用 dwWakeMask 参数指定的输入事件对象。

语法

DWORD MsgWaitForMultipleObjectsEx(
  [in] DWORD        nCount,
  [in] const HANDLE *pHandles,
  [in] DWORD        dwMilliseconds,
  [in] DWORD        dwWakeMask,
  [in] DWORD        dwFlags
);

参数

[in] nCount

pHandles 指向的数组中对象句柄的数目。最大对象句柄数 为MAXIMUM_WAIT_OBJECTS 减 1。如果此参数的值为零，则函数仅等待输入事件。

[in] pHandles

对象句柄的数组。有关可以指定其句柄的对象类型的列表，请参阅本主题后面的“备注”部分。数组可以包含多种类型的对象的句柄。它不能包含同一句柄的多个副本。

如果在等待仍处于挂起状态时关闭其中一个句柄，则函数的行为是未定义的。

句柄必须具有 SYNCHRONIZE 访问权限。有关详细信息，请参阅标准访问权限。

[in] dwMilliseconds

超时间隔（以毫秒为单位）。如果指定了非零值，则函数将等到指定对象收到信号、I/O 完成例程或 APC 排队，或者间隔已过。如果 dwMilliseconds 为零，则如果不满足条件，函数不会进入等待状态;它始终立即返回。如果 dwMilliseconds 为 INFINITE，则仅当指定对象发出信号或 I/O 完成例程或 APC 排队时，函数才会返回。

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] dwWakeMask

输入事件对象句柄将添加到对象句柄数组的输入类型。此参数可以是 GetQueueStatus标志参数中列出的值的任意组合。

[in] dwFlags

等待类型。此参数可使用以下一个或多个值。

值	含义
0	当向任何一个对象发出信号时，函数将返回。返回值指示其状态导致函数返回的对象。
MWMO_ALERTABLE 0x0002	如果在线程处于等待状态时，APC 已使用 QueueUserAPC 将线程排入队列，函数也会返回。
MWMO_INPUTAVAILABLE 0x0004	如果队列存在输入，则函数返回，即使输入已 (但未使用调用其他函数（如 PeekMessage）删除) 也是如此。
MWMO_WAITALL 0x0001	当向 pHandles 数组中的所有对象发出信号并同时收到输入事件时，函数将返回。

返回值

如果函数成功，则返回值指示导致函数返回的事件。可以是下列值之一。 (请注意，WAIT_OBJECT_0定义为 0，WAIT_ABANDONED_0定义为 0x00000080L.)

返回代码/值	说明
WAIT_OBJECT_0 到 (WAIT_OBJECT_0 + nCount - 1)	如果使用 MWMO_WAITALL 标志，则指定范围内的返回值指示所有指定对象的状态都已发出信号。否则，返回值减去 WAIT_OBJECT_0 指示导致函数返回的对象的 pHandles 数组索引。
+ WAIT_OBJECT_0nCount	在线程的输入队列中提供了 dwWakeMask 参数中指定的类型的新输入。 PeekMessage、GetMessage、GetQueueStatus 和 WaitMessage 等函数将队列中的消息标记为旧消息。因此，调用其中一个函数后，在指定类型的新输入到达之前，不会返回对 MsgWaitForMultipleObjectsEx 的后续调用。发生需要线程操作的系统事件（例如前台激活）时，也会返回此值。因此，即使没有可用的适当输入，即使 dwWakeMask 设置为 0，MsgWaitForMultipleObjectsEx 也可以返回。如果发生这种情况，请在再次尝试调用 MsgWaitForMultipleObjectsEx 之前调用 GetMessage 或 PeekMessage 来处理系统事件。
WAIT_ABANDONED_0 (WAIT_ABANDONED_0 + nCount - 1)	如果使用 MWMO_WAITALL 标志，则指定范围内的返回值指示所有指定对象的状态都已发出信号，并且至少有一个对象是放弃的互斥对象。否则，返回值减去 WAIT_ABANDONED_0 指示导致函数返回的已放弃互斥对象的 pHandles 数组索引。互斥对象的所有权授予调用线程，互斥体设置为非签名。如果互斥体正在保护永久性状态信息，则应检查它以确保一致性。
WAIT_IO_COMPLETION 0x000000C0L	等待由一个或多个用户模式异步过程调用结束， (APC) 排队到线程。
WAIT_TIMEOUT 258L	超时间隔已过，但不符合 dwFlags 和 dwWakeMask 参数指定的条件。
WAIT_FAILED (DWORD) 0xFFFFFFFF	函数失败。要获得更多的错误信息，请调用 GetLastError。

注解

MsgWaitForMultipleObjectsEx 函数确定是否满足 dwWakeMask 和 dwFlags 指定的条件。如果条件尚未满足，调用线程将进入等待状态，直到满足等待条件或超时间隔已过。

当 dwFlags 为零时，此函数将按从索引 0 开始的顺序检查数组中的句柄，直到向其中一个对象发出信号。如果多个对象被发出信号，函数将返回数组中第一个句柄的索引，该句柄已发出对象信号。

除非使用 MWMO_INPUTAVAILABLE 标志，否则在线程调用函数以检查队列后，如果消息队列中存在指定类型的未读输入，则 MsgWaitForMultipleObjectsEx 不会返回。这是因为 PeekMessage、GetMessage、GetQueueStatus 和 WaitMessage 等函数检查队列，然后更改队列的状态信息，使输入不再被视为新输入。除非使用 MWMO_INPUTAVAILABLE 标志，否则在指定类型的新输入到达之前，对 MsgWaitForMultipleObjectsEx 的后续调用不会返回。如果未使用此标志，则会忽略线程上次检查队列) 之前收到的现有未读输入 (。

函数修改某些类型的同步对象的状态。仅针对其信号状态导致函数返回的对象或对象进行修改。例如，系统将信号量对象的计数减少一个。有关详细信息，请参阅各个同步对象的文档。

MsgWaitForMultipleObjectsEx 函数可以指定 pHandles 数组中以下任何对象类型的句柄：

更改通知
控制台输入
事件
内存资源通知
Mutex
进程
Semaphore
线程
可等待计时器

要求

要求	值
最低受支持的客户端	Windows XP [仅限桌面应用]
最低受支持的服务器	Windows Server 2003 [仅限桌面应用]
目标平台	Windows
标头	winuser.h (包括 Windows.h)
Library	User32.lib
DLL	User32.dll

另请参阅

同步函数

Wait 函数

MsgWaitForMultipleObjectsEx 函数 (winuser.h)

语法

参数

返回值

注解

要求

另请参阅

反馈

反馈

其他资源