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

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

Комментарии

Функция 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
• Таймер для ожидания

Требования

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

MsgWaitForMultipleObjectsEx

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

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