Функция 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, а входное событие получено. Если этот параметр FALSE, функция возвращается, когда состояние любого из объектов задано для сигнала или получено входное событие. В этом случае возвращаемое значение указывает объект, состояние которого вызвало возвращаемую функцию.
[in] dwMilliseconds
Интервал времени ожидания в миллисекундах. Если указано ненулевое значение, функция ожидает, пока указанные объекты не будут сигнализировать или интервал истекает. Если dwMilliseconds равно нулю, функция не вводит состояние ожидания, если указанные объекты не сигнализируют; он всегда возвращается немедленно. Если dwMillisecondsINFINITE, функция возвращается только при сигнале указанных объектов.
Windows XP, Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 и Windows Server 2008 R2: значение dwMilliseconds включает время, потраченное в состояниях низкой мощности. Например, время ожидания сохраняет подсчет во время сна компьютера.
[in] dwWakeMask
Входные типы, для которых будет добавлен дескриптор объекта входного события в массив дескрипторов объектов. Этот параметр может быть любым сочетанием значений, перечисленных в параметре
Возвращаемое значение
Если функция выполнена успешно, возвращаемое значение указывает событие, вызвавшее возвращаемую функцию. Это может быть одно из следующих значений. (Обратите внимание, что WAIT_OBJECT_0 определяется как 0 и WAIT_ABANDONED_0 определяется как 0x000000080L.)
| Возврат кода или значения | Описание |
|---|---|
|
Если bWaitAllTRUE, возвращаемое значение в указанном диапазоне указывает, что состояние всех указанных объектов сигнализирует. Если bWaitAllFALSE, возвращаемое значение минус WAIT_OBJECT_0 указывает индекс массива pHandles объекта, удовлетворяющего ожиданию. |
|
Новые входные данные типа, указанного в параметре dwWakeMask, доступны в очереди входных данных потока. Такие функции, как PeekMessage, GetMessageи WaitMessage пометить сообщения в очереди как старые сообщения. Таким образом, после вызова одной из этих функций последующий вызов msgWaitForMultipleObjects не возвращается до тех пор, пока не появится новый вход указанного типа.
Это значение также возвращается при возникновении системного события, требующего действия потока, например активации переднего плана. Таким образом, msgWaitForMultipleObjects может возвращать, даже если для dwWakeMask задано значение 0. Если это происходит, вызовите GetMessage или PeekMessage, чтобы обработать системное событие перед попыткой вызова MsgWaitForMultipleObjects. |
|
Если bWaitAllTRUE, возвращаемое значение в указанном диапазоне указывает, что состояние всех указанных объектов сигнализирует, а по крайней мере один из объектов является заброшенным объектом мьютекса. Если bWaitAllFALSE, возвращаемое значение минус WAIT_ABANDONED_0 указывает индекс массива pHandles массива заброшенного объекта мьютекса, удовлетворяющего ожиданию. Владение объектом мьютекса предоставляется вызывающему потоку, а мьютекс имеет значение nonsignalaled.
Если мьютекс защищает сведения о постоянном состоянии, необходимо проверить его согласованность. |
|
Интервал времени ожидания истек и условия, указанные bWaitAll и dwWakeMask параметры не удовлетворены. |
|
Сбой функции. Чтобы получить расширенные сведения об ошибке, вызовите GetLastError. |
Замечания
Функция msgWaitForMultipleObjects
Если bWaitAllTRUE, функция не изменяет состояния указанных объектов до тех пор, пока состояния всех объектов не будут заданы для сигнала. Например, мьютекс может быть сигнален, но поток не получает владение до тех пор, пока состояния других объектов также не были заданы для сигнала. В то же время некоторый другой поток может получить владение мьютексом, тем самым задав его состояние незначаемым.
Если bWaitAllTRUE, ожидание функции завершается только в том случае, если состояние всех объектов было задано для сигнала и получено входное событие. Поэтому параметр bWaitAll значение TRUE запрещает обработку входных данных до тех пор, пока не задано состояние всех объектов в массиве pHandles. По этой причине если для параметра bWaitAll значение TRUE, следует использовать короткое значение времени ожидания в dwMilliseconds. Если у вас есть поток, который создает окна, ожидающие всех объектов в массиве pHandles, включая входные события, указанные dwWakeMask, без интервала времени ожидания система будет взаимоблокировкой. Это связано с тем, что потоки, создающие окна, должны обрабатывать сообщения. DDE отправляет сообщение всем окнам в системе. Таким образом, если поток создает окна, не устанавливайте параметр bWaitAll значение TRUE в вызовах msgWaitForMultipleObjects, сделанных из этого потока.
Если bWaitAllFALSE, эта функция проверяет дескрипторы в массиве, начиная с индекса 0, пока один из объектов не будет сигнализован. Если несколько объектов становятся сигнализованными, функция возвращает индекс первого дескриптора в массиве, объект которого был сигнализован.
msgWaitForMultipleObjects не возвращается, если в очереди сообщений нет непрочитанных входных данных указанного типа после вызова функции для проверки очереди. Это связано с тем, что такие функции, как PeekMessage, GetMessage, GetQueueStatusи WaitMessage проверить очередь, а затем изменить сведения о состоянии очереди, чтобы входные данные больше не считались новыми. Последующий вызов MsgWaitForMultipleObjects не возвращается до поступления новых входных данных указанного типа. Существующие непрочитанные входные данные (полученные до последнего проверки потока очереди) игнорируются.
Функция изменяет состояние некоторых типов объектов синхронизации. Изменение происходит только для объекта или объектов, состояние которого привело к возврату функции. Например, количество объектов семафора уменьшается на один. Дополнительные сведения см. в документации по отдельным объектам синхронизации.
Функция MsgWaitForMultipleObjects может указывать дескриптор любого из следующих типов объектов в массиве pHandles:
- Уведомление об изменении
- Входные данные консоли
- Событие
- Уведомление о ресурсе памяти
- Мьютекс
- Процесс
- Семафор
- Нить
- Таймер ожидания
Требования
| Требование | Ценность |
|---|---|
| минимальные поддерживаемые клиентские | Windows XP [только классические приложения] |
| минимальный поддерживаемый сервер | Windows Server 2003 [только классические приложения] |
| целевая платформа | Виндоус |
| заголовка | winuser.h (включая Windows.h) |
| библиотеки |
User32.lib |
| DLL | User32.dll |