通过

MsgWaitForMultipleObjectsEx 函数 （winuser.h）

  • 项目

等待一个或多个指定对象处于信号状态、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 减一。 如果此参数的值为零，则函数仅等待输入事件。

[in] pHandles

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

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

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

[in] dwMilliseconds

超时间隔（以毫秒为单位）。 如果指定了非零值，则函数将等待指定对象发出信号、I/O 完成例程或 APC 排队或间隔运行。 如果 dwMilliseconds 为零，则如果未满足条件，则函数不会进入等待状态;它始终会立即返回。 如果 dwMillisecondsINFINITE，则仅当指定对象发出信号或 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_0 + nCount
 dwWakeMask 参数中指定的类型的新输入在线程的输入队列中可用。 PeekMessage、GetMessage、GetQueueStatus等函数，WaitMessage 将队列中的消息标记为旧消息。 因此，调用其中一个函数后，对 MsgWaitForMultipleObjectsEx 的后续调用将不会返回，直到指定类型的新输入到达。

当出现需要线程操作的系统事件（例如前台激活）时，也会返回此值。 因此，即使没有适当的输入，MsgWaitForMultipleObjectsEx 也可以返回，即使 dwWakeMask 设置为 0。 如果发生这种情况，请调用 GetMessage 或 PeekMessage 来处理系统事件，然后再再次尝试调用 MsgWaitForMultipleObjectsEx。
WAIT_ABANDONED_0 到 （WAIT_ABANDONED_0 + nCount - 1）
 如果使用 MWMO_WAITALL 标志，则指定范围内的返回值指示所有指定对象的状态，并且至少有一个对象是放弃的互斥对象。 否则，返回值减去 WAIT_ABANDONED_0 指示导致函数返回的已放弃互斥体对象的 pHandles 数组索引。 mutex 对象的所有权授予调用线程，互斥体设置为非对齐。

如果互斥体保护持久状态信息，则应检查它是否一致性。
WAIT_IO_COMPLETION
0x000000C0L
 等待由一个或多个用户模式结束，异步过程调用（APC）排队到线程。
WAIT_TIMEOUT
258L
 超时间隔已过，但未满足由 dwFlags 和 dwWakeMask 参数指定的条件。
WAIT_FAILED
（DWORD）0xFFFFFFFF
 函数失败。 若要获取扩展的错误信息，请调用 GetLastError。

言论

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

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

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

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

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

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

要求

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

另请参阅

同步函数

等待函数