WaitForMultipleObjectsEx 函数 （synchapi.h）
等待一个或多个指定对象处于信号状态、I/O 完成例程或异步过程调用（APC）排队到线程，或超时间隔已过。
语法
DWORD WaitForMultipleObjectsEx(
[in] DWORD nCount,
[in] const HANDLE *lpHandles,
[in] BOOL bWaitAll,
[in] DWORD dwMilliseconds,
[in] BOOL bAlertable
);
参数
[in] nCount
lpHandles指向的数组中等待的对象句柄数。 对象句柄的最大数目为 MAXIMUM_WAIT_OBJECTS。 此参数不能为零。
[in] lpHandles
对象句柄数组。 有关可以指定句柄的对象类型的列表，请参阅以下“备注”部分。 数组可以包含不同类型的对象的句柄。 它可能不包含同一句柄的多个副本。
如果在等待仍在挂起时关闭其中一个句柄，则函数的行为未定义。
句柄必须具有 SYNCHRONIZE 访问权限。 有关详细信息，请参阅 标准访问权限。
[in] bWaitAll
如果此参数 TRUE，则当 lpHandles 数组中的所有对象的状态设置为信号时，该函数将返回。 如果 FALSE，则当任一对象的状态设置为信号时，函数将返回。 在后一种情况下，返回值指示其状态导致函数返回的对象。
[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 及更新版本：dwMilliseconds 值不包括在低功率状态下花费的时间。 例如，当计算机处于睡眠状态时，超时不会不断倒计时。
[in] bAlertable
如果此参数 TRUE 且线程处于等待状态，则当系统排队 I/O 完成例程或 APC 时，该函数将返回，线程运行例程或函数。 否则，该函数不会返回，并且未执行完成例程或 APC 函数。
ReadFileEx 或 WriteFileEx 函数（在其中指定了该例程已完成）时，完成例程将排队。 仅当 bAlertableTRUE 并且调用线程是启动读取或写入操作的线程时，才调用等待函数返回并调用完成例程。 调用 QueueUserAPC时，APC 将排队。
返回值
如果函数成功，则返回值指示导致函数返回的事件。 它可以是以下值之一。 （请注意，WAIT_OBJECT_0 定义为 0，WAIT_ABANDONED_0 定义为 0x00000080L。
| 返回代码/值 | 描述 |
|---|---|
|
如果 bWaitAllTRUE，则此范围内的返回值指示所有指定对象的状态已发出信号。
如果 bWaitAllFALSE，则返回值减 WAIT_OBJECT_0 指示满足等待的对象 lpHandles 数组索引。 如果在调用期间发出了多个对象的信号，则这是信号对象的数组索引，其索引值为所有信号对象的最小索引值。 |
|
如果 bWaitAllTRUE，则此范围内的返回值指示所有指定对象的状态，并且至少有一个对象是放弃的互斥对象。
如果 bWaitAllFALSE，则返回值减去 WAIT_ABANDONED_0 指示满足等待的已放弃互斥体对象的 lpHandles 数组索引。 mutex 对象的所有权授予调用线程，互斥体设置为非对齐。 如果互斥体保护持久状态信息，则应检查它是否一致性。 |
|
等待由一个或多个用户模式结束，异步过程调用（APC）排队到线程。 |
|
超时间隔已过，bWaitAll 参数指定的条件未满足，并且没有排队完成例程。 |
|
函数失败。 若要获取扩展的错误信息，请调用 GetLastError。 |
言论
WaitForMultipleObjectsEx 函数确定是否满足等待条件。 如果条件尚未满足，则调用线程将进入等待状态，直到满足等待条件的条件或超时间隔已过。
当 bWaitAllTRUE时，函数的等待操作仅当所有对象的状态都设置为信号时才完成。 该函数不会修改指定对象的状态，直到所有对象的状态都设置为信号。 例如，可以发出互斥体信号，但在其他对象的状态也设置为信号之前，线程不会获得所有权。 同时，其他一些线程可能会获取互斥体的所有权，从而将其状态设置为非对齐状态。
当 bWaitAllFALSE时，此函数会检查数组中的句柄，从索引 0 开始，直到发出其中一个对象的信号。 如果多个对象被发出信号，该函数将返回数组中第一个句柄的索引，该句柄已发出信号。
该函数修改某些类型的同步对象的状态。 仅针对其信号状态导致函数返回的对象或对象进行修改。 例如，信号灯对象的计数减少一个。 有关详细信息，请参阅各个同步对象的文档。
若要等待多个 MAXIMUM_WAIT_OBJECTS 句柄，请使用以下方法之一：
- 创建一个线程来等待 MAXIMUM_WAIT_OBJECTS 句柄，然后等待该线程和其他句柄。 使用此技术可将句柄分解为 MAXIMUM_WAIT_OBJECTS组。
- 调用 RegisterWaitForSingleObject 或 SetThreadpoolWait 等待每个句柄。 线程池在句柄上高效等待，并在发出对象信号或超时间隔过期后分配工作线程。
- 更改通知
- 控制台输入
- 事件
- 内存资源通知
- Mutex
- 过程
- 信号
- 线
- 可等待计时器
要求
| 要求 | 价值 |
|---|---|
| 最低支持的客户端 | Windows XP [桌面应用 |UWP 应用] |
| 支持的最低服务器 | Windows Server 2003 [桌面应用 |UWP 应用] |
| 目标平台 | 窗户 |
| 标头 | synchapi.h （包括 Windows Server 2003、Windows Vista、Windows 7、Windows Server 2008 Windows Server 2008 R2 上的 Windows.h） |
| 库 | Kernel32.lib |
| DLL | Kernel32.dll |