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

Статья
03/18/2023

Ожидает, пока один или все указанные объекты не будут в состоянии сигнала или не истекает интервал времени ожидания. Объекты могут включать входные объекты событий, которые указываются с помощью параметра dwWakeMask .

Чтобы войти в состояние ожидания с оповещениями, используйте функцию MsgWaitForMultipleObjectsEx .

Синтаксис

DWORD MsgWaitForMultipleObjects(
  [in] DWORD        nCount,
  [in] const HANDLE *pHandles,
  [in] BOOL         fWaitAll,
  [in] DWORD        dwMilliseconds,
  [in] DWORD        dwWakeMask
);

Параметры

[in] nCount

Количество дескрипторов объектов в массиве, на который указывает pHandles. Максимальное количество дескрипторов объекта MAXIMUM_WAIT_OBJECTS минус один. Если этот параметр имеет нулевое значение, функция ожидает только входного события.

[in] pHandles

Массив дескрипторов объектов. Список типов объектов, дескрипторов которых можно указать, см. в следующем разделе Примечания. Массив может содержать дескрипторы объектов разных типов. Он не может содержать несколько копий одного дескриптора.

Если один из этих дескрипторов закрывается, пока ожидание еще не завершено, поведение функции не определено.

Дескрипторы должны иметь право доступа SYNCHRONIZE . Дополнительные сведения см. в разделе Стандартные права доступа.

[in] fWaitAll

Если этот параметр имеет значение TRUE, функция возвращает, когда для состояний всех объектов в массиве pHandles задано значение signaled и получено входное событие. Если этот параметр имеет значение FALSE, функция возвращает значение , если для любого из объектов задано значение Signaled или получено входное событие. В этом случае возвращаемое значение указывает объект, состояние которого привело к возврату функции.

[in] dwMilliseconds

Интервал времени ожидания в миллисекундах. Если указано ненулевое значение, функция ожидает передачи сигналов о указанных объектах или истечения интервала. Если dwMilliseconds равно нулю, функция не переходит в состояние ожидания, если указанные объекты не получают сигнал; он всегда возвращается немедленно. Если параметр dwMilliseconds имеет значение INFINITE, функция возвращает только при сигнале указанных объектов.

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.

Возвращаемое значение

Если функция выполнена успешно, возвращаемое значение указывает на событие, вызвавшее возврат функции. Может быть одним из указанных далее. (Обратите внимание, что WAIT_OBJECT_0 определяется как 0, а WAIT_ABANDONED_0 — как 0x000000080L.)

Возвращаемый код или значение	Описание
WAIT_OBJECT_0 в (WAIT_OBJECT_0 + nCount – 1)	Если параметр bWaitAll имеет значение TRUE, возвращаемое значение в указанном диапазоне указывает на то, что подается сигнал о состоянии всех указанных объектов. Если значение bWaitAll равно FALSE, то возвращаемое значение минус WAIT_OBJECT_0 указывает индекс массива pHandles объекта, удовлетворяющего ожиданию.
+ WAIT_OBJECT_0 Ncount	Новые входные данные типа, указанного в параметре dwWakeMask , доступны во входной очереди потока. Такие функции, как PeekMessage, GetMessage и WaitMessage , помечают сообщения в очереди как старые. Таким образом, после вызова одной из этих функций последующий вызов MsgWaitForMultipleObjects не вернется, пока не поступит новый вход указанного типа. Это значение также возвращается при возникновении системного события, требующего действия потока, например активации переднего плана. Таким образом, MsgWaitForMultipleObjects может возвращать, даже если нет соответствующих входных данных и даже если dwWakeMask имеет значение 0. В этом случае вызовите Метод GetMessage или PeekMessage , чтобы обработать системное событие, прежде чем повторить вызов MsgWaitForMultipleObjects .
WAIT_ABANDONED_0 на (WAIT_ABANDONED_0 + nCount– 1)	Если bWaitAll имеет значение TRUE, возвращаемое значение в указанном диапазоне указывает, что состояние всех указанных объектов сигнализируется, и по крайней мере один из объектов является заброшенным объектом мьютекса. Если значение bWaitAll равно FALSE, возвращаемое значение минус WAIT_ABANDONED_0 указывает индекс массива pHandles для заброшенного объекта мьютекса, удовлетворяющего ожиданию. Владение объектом мьютекса предоставляется вызывающему потоку, а мьютексу присваивается значение без знака. Если мьютекс защищал сведения о постоянном состоянии, следует проверить их на согласованность.
WAIT_TIMEOUT 258L	Истек интервал времени ожидания и условия, заданные параметрами bWaitAll и dwWakeMask , не выполнены.
WAIT_FAILED (DWORD)0xFFFFFFFF	Сбой функции. Дополнительные сведения об ошибке можно получить, вызвав GetLastError.

Функция MsgWaitForMultipleObjects определяет, выполнены ли критерии ожидания. Если условия не были выполнены, вызывающий поток переходит в состояние ожидания до тех пор, пока не будут выполнены условия условий ожидания или не истекает интервал времени ожидания.

Если bWaitAll имеет значение TRUE, функция не изменяет состояния указанных объектов до тех пор, пока состояния всех объектов не будут заданы как сигнальные. Например, можно сигнализировать о мьютексе, но поток не получает права владения до тех пор, пока состояния других объектов также не будут заданы как сигнальные. В то же время, некоторые другие потоки могут получить права владения мьютексом, тем самым устанавливая его состояние в незначаемое.

Если параметр bWaitAll имеет значение TRUE, ожидание функции завершается только в том случае, если для состояний всех объектов задано значение Signaled и получено входное событие. Таким образом, если присвоить параметру bWaitAll значение TRUE , входные данные не будут обрабатываться до тех пор, пока состояние всех объектов в массиве pHandles не будет задано как сигнальное. По этой причине, если для параметра bWaitAll задано значение TRUE, следует использовать короткое значение времени ожидания в dwMilliseconds. Если у вас есть поток, который создает окна, ожидающие всех объектов в массиве pHandles , включая входные события, заданные dwWakeMask, без интервала ожидания, система будет взаимоблокирована. Это связано с тем, что потоки, создающие окна, должны обрабатывать сообщения. DDE отправляет сообщение во все окна в системе. Поэтому, если поток создает окна, не устанавливайте для параметра bWaitAllзначение TRUE в вызовах MsgWaitForMultipleObjects, сделанных из этого потока.

Если bWaitAll имеет значение FALSE, эта функция проверяет дескрипторы в массиве в порядке, начиная с индекса 0, пока не будет положен сигнал одному из объектов. Если несколько объектов становятся сигнальными, функция возвращает индекс первого дескриптора в массиве, объект которого был сигнализован.

MsgWaitForMultipleObjects не возвращается при наличии непрочитанных входных данных указанного типа в очереди сообщений после того, как поток вызвал функцию для проверки очереди. Это связано с тем, что такие функции, как PeekMessage, GetMessage, GetQueueStatus и WaitMessage , проверяют очередь, а затем изменяют сведения о состоянии очереди, чтобы входные данные больше не считались новыми. Последующий вызов MsgWaitForMultipleObjects не будет возвращать, пока не будут поступать новые входные данные указанного типа. Существующие непрочитанные входные данные (полученные до последней проверки очереди потоком) игнорируются.

Функция изменяет состояние некоторых типов объектов синхронизации. Изменение происходит только для объекта или объектов, состояние которых привело к возврату функции. Например, количество объектов семафора уменьшается на единицы. Дополнительные сведения см. в документации по отдельным объектам синхронизации.

Функция MsgWaitForMultipleObjects может указывать дескриптор любого из следующих типов объектов в массиве pHandles :

Уведомление об изменениях
Входные данные консоли
Событие
Уведомление о ресурсе памяти
Mutex
Процесс
Semaphore
Thread
Таймер для ожидания

Требования


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

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

MsgWaitForMultipleObjectsEx

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

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