Функция MsgWaitForMultipleObjectsEx (winuser.h)

Статья
03/18/2023

Ожидает, пока один или все указанные объекты не будут помещены в состояние сигнала, подпрограмма завершения ввода-вывода или асинхронный вызов процедуры (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

Интервал времени ожидания в миллисекундах. Если указано ненулевое значение, функция ожидает передачи сигналов о указанных объектах, завершения операций ввода-вывода или APC в очередь или истечения интервала. Если значение dwMilliseconds равно нулю, функция не переходит в состояние ожидания, если условия не выполняются; он всегда возвращается немедленно. Если параметр dwMilliseconds имеет значение INFINITE, функция будет возвращать только в том случае, если указанные объекты будут поставлены в очередь, подпрограмма завершения ввода-вывода или 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 — как 0x000000080L.)

Возвращаемый код или значение	Описание
WAIT_OBJECT_0 на (WAIT_OBJECT_0 + nCount — 1)	Если используется флаг MWMO_WAITALL , возвращаемое значение в указанном диапазоне указывает, что сообщается о состоянии всех указанных объектов. В противном случае возвращаемое значение минус WAIT_OBJECT_0 указывает индекс массива pHandles объекта, вызвавшего возврат функции.
+ WAIT_OBJECT_0Ncount	Новые входные данные типа, указанного в параметре 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 заброшенного объекта мьютекса, который вызвал возврат функции. Владение объектом мьютекса предоставляется вызывающему потоку, а мьютексу присваивается значение без знака. Если мьютекс защищал сведения о постоянном состоянии, необходимо проверка их для обеспечения согласованности.
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
Процесс
Semaphore
Thread
Таймер для ожидания

Требования

Требование	Значение
Минимальная версия клиента	Windows XP [только классические приложения]
Минимальная версия сервера	Windows Server 2003 [только классические приложения]
Целевая платформа	Windows
Header	winuser.h (включая Windows.h)
Библиотека	User32.lib
DLL	User32.dll

См. также раздел

Функции синхронизации

Функции ожидания