On-line справка по Win32 API

БЕСПЛАТНАЯ ежедневная online лотерея! Выигрывай каждый день БЕСПЛАТНО!

A-B-C-D-E-F-G-H-I-J-K-L-M-N-O-P-Q-R-S-T-U-V-W-X-Y-Z | Скачать

MsgWaitForMultipleObjectsEx

[New - Windows NT]

The MsgWaitForMultipleObjectsEx function returns when one of the following occurs:

· Either any one or all of the specified objects are in the signaled state. The array of objects can include input event objects, which you specify using the dwWakeMask parameter.
· An I/O completion routine or asynchronous procedure call (APC) is queued to the thread.
· The time-out interval elapses.

The MsgWaitForMultipleObjectsEx function does not return if there is unread input of the specified type in the queue. It returns only when new input arrives.

DWORD MsgWaitForMultipleObjectsEx(

DWORD nCount, // number of handles in handle array
LPHANDLE pHandles, // pointer to an object-handle array
DWORD dwMilliseconds, // time-out interval in milliseconds
DWORD dwWakeMask, // type of input events to wait for
DWORD dwFlags // wait flags
);

Parameters

nCount

Specifies the number of object handles in the array pointed to by pHandles. The maximum number of object handles is MAXIMUM_WAIT_OBJECTS minus one.

pHandles

Points to an array of object handles. For a list of the object types whose handles you can specify, see the Remarks section later in this topic. The array can contain handles to multiple types of objects.
Windows NT: The handles must have SYNCHRONIZE access.

dwMilliseconds

Specifies the time-out interval, in milliseconds. The function returns if the interval elapses, even if the conditions specified by the dwWakeMask and dwFlags parameters are not met. If dwMilliseconds is zero, the function tests the states of the specified objects and returns immediately. If dwMilliseconds is INFINITE, the function's time-out interval never elapses.

dwWakeMask

Specifies input types for which an input event object handle will be added to the array of object handles. This parameter can be any combination of the following values:

Value Meaning
QS_ALLINPUT Any message is in the queue.
QS_HOTKEY A WM_HOTKEY message is in the queue.
QS_INPUT An input message is in the queue.
QS_KEY A WM_KEYUP, WM_KEYDOWN, WM_SYSKEYUP, or WM_SYSKEYDOWN message is in the queue.
QS_MOUSE A WM_MOUSEMOVE message or mouse-button message (WM_LBUTTONUP, WM_RBUTTONDOWN, and so on) is in the queue.
QS_MOUSEBUTTON A mouse-button message (WM_LBUTTONUP, WM_RBUTTONDOWN, and so on) is in the queue.
QS_MOUSEMOVE A WM_MOUSEMOVE message is in the queue.
QS_PAINT A WM_PAINT message is in the queue.
QS_POSTMESSAGE A posted message (other than those just listed) is in the queue.
QS_SENDMESSAGE A message sent by another thread or application is in the queue.
QS_TIMER A WM_TIMER message is in the queue.

dwFlags

Specifies the wait type. This parameter can be any combination of the following values:

Value Meaning
0 The function returns when any one of the objects is signaled. The return value indicates the object whose state caused the function to return.
MWMO_WAITALL The function returns when all objects in the pHandles array are signaled at the same time.
MWMO_ALERTABLE The function also returns if an APC has been queued to the thread with QueueUserAPC.

Return Values

If the function succeeds, the return value indicates the event that caused the function to return. The successful return value is one of the following:

Value Meaning
WAIT_OBJECT_0 to
(WAIT_OBJECT_0 + nCount - 1) If the MWMO_WAITALL flag is used, the return value indicates that the state of all specified objects is signaled. Otherwise, the return value minus WAIT_OBJECT_0 indicates the pHandles array index of the object that caused the function to return.
WAIT_OBJECT_0 + nCount Input of the type specified in the dwWakeMask parameter is available in the thread's input queue.
WAIT_ABANDONED_0 to
(WAIT_ABANDONED_0 + nCount - 1) If the MWMO_WAITALL flag is used, the return value indicates that the state of all specified objects is signaled and at least one of the objects is an abandoned mutex object. Otherwise, the return value minus WAIT_ABANDONED_0 indicates the pHandles array index of an abandoned mutex object that caused the function to return.
WAIT_IO_COMPLETION The wait was ended by a user-mode asynchronous procedure call (APC) queued to the thread.
WAIT_TIMEOUT The time-out interval elapsed, but the conditions specified by the dwFlags and dwWakeMask parameters were not met.

If the function fails, the return value is 0xFFFFFFFF. To get extended error information, call GetLastError.

Remarks

The MsgWaitForMultipleObjectsEx function determines whether the conditions specified by dwWakeMask and dwFlags have been met. If the conditions have not been met, the calling thread enters an efficient wait state. The thread uses very little processor time while waiting for one of the conditions to be met or for the time-out interval to elapse.
Before returning, a wait function modifies the state of some types of synchronization objects. Modification occurs only for the object or objects whose signaled state caused the function to return. For example, the system decreases the count of a semaphore object by one.

The MsgWaitForMultipleObjectsEx function can specify handles of any of the following object types in the pHandles array:

Object Description
Change notification The FindFirstChangeNotification function returns the handle. The state of a change notification object is set to signaled when a specified change occurs within a specified directory or directory tree.
Console input The CreateFile function returns the handle when the CONIN$ value is specified, or the GetStdHandle function returns the handle. The state of the object is set to signaled when there is unread input in the console's input buffer and nonsignaled when the input buffer is empty.
Event The CreateEvent or OpenEvent function returns the handle. The state of an event object is set explicitly to signaled by the SetEvent or PulseEvent function. The state of a manual-reset event object must be reset explicitly to nonsignaled by the ResetEvent function. For an auto-reset event object, the wait function resets the object state to nonsignaled before returning. Event objects are also used in overlapped operations, in which the state is set by the system.
Mutex The CreateMutex or OpenMutex function returns the handle. The state of a mutex object is signaled when it is not owned by any thread. The wait function requests ownership of the mutex for the calling thread, changing the mutex state to nonsignaled when ownership is granted.
Process The CreateProcess or OpenProcess function returns the handle. The state of a process object is set to signaled when the process terminates.
Semaphore The CreateSemaphore or OpenSemaphore function returns the handle. A semaphore object maintains a count between zero and the maximum count specified during its creation. Its state is set to signaled when its count is greater than zero and nonsignaled when its count is zero. If the current state of the semaphore is signaled, the wait function decreases the count by one.
Thread The CreateProcess, CreateThread, or CreateRemoteThread function returns the handle. The state of a thread object is set to signaled when the thread terminates.
Timer The CreateWaitableTimer or OpenWaitableTimer function returns the handle. Activate the timer by calling the SetWaitableTimer function. The state of an active timer is set to signaled when it reaches its due time. You can deactivate the timer by calling the CancelWaitableTimer function.

In some circumstances, you can specify a handle of a file, named pipe, or communications device as a synchronization object in lpHandles. However, their use for this purpose is discouraged.

See Also

CancelWaitableTimer, CreateEvent, CreateFile, CreateMutex, CreateProcess, CreateRemoteThread, CreateSemaphore, CreateThread, CreateWaitableTimer, FindFirstChangeNotification, GetStdHandle, MsgWaitForMultipleObjects, OpenEvent, OpenMutex, OpenProcess, OpenSemaphore, OpenWaitableTimer, PulseEvent, QueueUserAPC, ResetEvent, SetEvent, SetWaitableTimer

Пригласи друзей и счет твоего мобильника всегда будет положительным!

Пригласи друзей и счет твоего мобильника всегда будет положительным!

MsgWaitForMultipleObjectsEx

[Новый - Windows NT]

Функция MsgWaitForMultipleObjectsEx возвращается когда одно из следующего происходит:

Или любое или все определившее, что объекты - в сигнальном состоянии. Массив объектов может включить входные объекты случая, какое Вы определяете используя параметр dwWakeMask.
Программа завершения В/В или асинхронный вызов процедуры (APC), поставлены в очередь в резьбу.
Интервал задержки истекает.

Функция MsgWaitForMultipleObjectsEx не возвращается если есть unread вклад определенного типа в очереди. Это возвращается только когда новый вклад прибывает.

DWORD MsgWaitForMultipleObjectsEx(

DWORD nCount, // КОЛИЧЕСТВО ручек в массиве ручки LPHANDLE pHandles, // указатель в объектную ручку массива DWORD dwMilliseconds, // интервал задержки в течение миллисекунд DWORD dwWakeMask, // типа входных событий, чтобы ждать DWORD dwFlags // ожидать флаги
);

Параметры

nCount

Определяет количество объектных ручек в массиве указанном, чтобы pHandles. Максимальное количество объектных ручек - MAXIMUM_WAIT_OBJECTS минус одно.

pHandles

Точки на массив объектных ручек. Для списка объектных типов чьи ручки Вы можете определить, смотри секцию Замечаний последующую в этой теме. Массив может содержать ручки во многочисленные типы объектов.
Окно NT: ручки должны СИНХРОНИЗИРОВАТЬ доступ.

dwMilliseconds

Определяет интервал задержки, в течение миллисекунд. Функция возвращается если интервал истекает, даже если бы условия определялись dwWakeMask и параметры dwFlags не выполнены. Если dwMilliseconds - нуль, функция тестирует состояния определенных объектов и возвращает немедленно. Если dwMilliseconds БЕСКОНЕЧНЫЙ, функциональный интервал задержки никогда не истекает.

dwWakeMask

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

Значение Величины
QS_ALLINPUT Любого сообщения - в очереди.
QS_HOTKEY сообщение WM_HOTKEY - в очереди.
QS_INPUT входное сообщение - в очереди.
QS_KEY WM_KEYUP, WM_KEYDOWN, WM_SYSKEYUP, или сообщение WM_SYSKEYDOWN - в очереди.
QS_MOUSE сообщение WM_MOUSEMOVE или мышь-кнопка сообщения (WM_LBUTTONUP, WM_RBUTTONDOWN, и так далее), - в очереди.
QS_MOUSEBUTTON мышь-кнопка сообщения (WM_LBUTTONUP, WM_RBUTTONDOWN, и так далее), - в очереди.
QS_MOUSEMOVE сообщение WM_MOUSEMOVE - в очереди.
QS_PAINT сообщение WM_PAINT - в очереди.
QS_POSTMESSAGE объявленное сообщение (кроме тех только что указанное), - в очереди.
QS_SENDMESSAGE сообщение посылалось другой резьбой или приложение - в очереди.
QS_TIMER сообщение WM_TIMER - в очереди.

dwFlags

Определяет тип ожидания. Этот параметр может быть любой комбинацией следующего величин:

Значение Величины
0 Функциональный возврат когда любой из объектов сигнализированы. Обратная величина указывает объект, чье состояние заставляло функцию, чтобы возвращаться.
MWMO_WAITALL функциональный возврат когда все объекты в массиве pHandles сигнализируются в то же самое время.
MWMO_ALERTABLE функция также возвращается если APC поставлен в очередь в резьбу с QueueUserAPC.

Обратные Величины

Если функция добивается успеха, обратная величина указывает случай, который заставлял функцию, чтобы возвращаться. Успешная обратная величина - одно из следующего:

Оцените Значение WAIT_OBJECT_0, чтобы
(WAIT_OBJECT_0 + nCount - 1) Если флаг MWMO_WAITALL использован, обратная величина указывает, что состояние всех определившее, что объекты сигнализированы. В противном случае, обратная величина минус WAIT_OBJECT_0 указывает индекс массива pHandles объекта, который заставлял функцию, чтобы возвращаться.
WAIT_OBJECT_0 Вклада + nCount типа определенного в параметре dwWakeMask доступен в входной очереди резьбы.
WAIT_ABANDONED_0, чтобы
(WAIT_ABANDONED_0 + nCount - 1) Если флаг MWMO_WAITALL использован, обратная величина указывает, что состояние всех определившее, что объекты сигнализированы и по крайней мере один из объектов - заброшенный mutex объект. В противном случае, обратная величина минус WAIT_ABANDONED_0 указывает индекс массива pHandles заброшенного mutex объекта, который заставлял функцию, чтобы возвращаться.
WAIT_IO_COMPLETION ожидание было закончено потребителем-способом асинхронной процедуры вызова (APC) поставленное в очередь в резьбу.
WAIT_TIMEOUT интервал задержки проходил, но условия определялись dwFlags и параметры dwWakeMask не были выполнены.

Если функция терпит неудачу, обратная величина - 0xFFFFFFFF. Для того, чтобы расширять информацию ошибки, вызовите GetLastError.

Замечания

Функция MsgWaitForMultipleObjectsEx определяет независимо условия определенные dwWakeMask и dwFlags выполнен. Если условия не выполнены, разговор резьбы вводит эффективное состояние ожидания. Резьба использует очень небольшое время процессора при ожидании одно из условий, которые нужно выполнять или для интервала задержки, чтобы истекать.
Перед возвратом, функция ожидания модифицирует состояние некоторых типов объектов синхронизации. Модификация происходит только для объекта или объекты чье сигнализировавшее, что состояние заставляло функцию, чтобы возвращаться. Например, система уменьшает счет объекта семафора одной.

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

Описание Объекта
Уведомление Изменения функциональный возврат FindFirstChangeNotification ручка. Состояние объекта уведомления изменения установлено на сигнализированное когда определенное изменение происходит в пределах определенного дерева директория или директория.
Консоль вводит функцию CreateFile возвращает ручку когда CONIN$ величина определена, или функциональный возврат GetStdHandle ручка. Состояние объекта установлено на сигнализированное когда есть unread ввод в консольном входном буфере и nonsignaled когда входной буфер пустой.
Событие CreateEvent или функциональный возврат OpenEvent ручка. Состояние объекта события устанавливается явно на сигнализированное SetEvent или функция PulseEvent. Состояние руководства-было восстановлено объект события должен восстанавливаться явно на nonsignaled функцией ResetEvent. Для авто-восстановившее объект события, функция ожидания сбрасывает объектное состояние на nonsignaled перед возвратом. Объекты События также использованы на перекрытых операциях, в которых состояние установлено системой.
Mutex CreateMutex Или функциональный возврат OpenMutex ручка. Состояние объекта mutex сигнализировано когда оно не принадлежащее любой резьбе. Функция ожидания запрашивает собственность на mutex для разговор резьба, изменяющую состояние mutex на nonsignaled когда собственности предоставляют.
Обработайте CreateProcess или функциональному возврату OpenProcess ручку. Состояние объекта процесса установлено на сигнализированное когда процесс завершается.
Сигнализируйте CreateSemaphore или функциональному возврату OpenSemaphore ручку. Объект семафора поддерживает счету между нулем и максимальный счет определенными в течение своего создания. Состояние установлено на сигнализированное когда счет больше, чем нуль и nonsignaled когда счет нулевой. Если текущее состояние семафора сигнализировано, функция ожидания уменьшает счет одной.
Заправьте CreateProcess, CreateThread, или функцию CreateRemoteThread возвращает ручку. Состояние объекта резьбы установлено на сигнализированное когда резьба завершается.
Таймер CreateWaitableTimer или функциональный возврат OpenWaitableTimer ручка. Активизируйте таймер вызывая функцию SetWaitableTimer. Состояние активного таймера установлено на сигнализированное когда оно достигает своего подлежащего времени. Вы можете деактивизировать таймер вызывая функцию CancelWaitableTimer.

В некоторых обстоятельствах, Вы можете определить ручку файла, назвавшего трубу, или устройство связи как объект синхронизации в lpHandles. Тем не менее, их использование с этой целью отговорено.

Смотри Также

CancelWaitableTimer, CreateEvent, CreateFile, CreateMutex, CreateProcess, CreateRemoteThread, CreateSemaphore, CreateThread, CreateWaitableTimer, FindFirstChangeNotification, GetStdHandle, MsgWaitForMultipleObjects, OpenEvent, OpenMutex, OpenProcess, OpenSemaphore, OpenWaitableTimer, PulseEvent, QueueUserAPC, ResetEvent, SetEvent, SetWaitableTimer

Используются технологии uCoz