Función MsgWaitForMultipleObjectsEx (winuser.h)
Espera hasta que uno o todos los objetos especificados estén en estado señalado, se pone en cola una rutina de finalización de E/S o una llamada de procedimiento asincrónico (APC) al subproceso o el intervalo de tiempo de espera transcurrido. La matriz de objetos puede incluir objetos de evento de entrada, que se especifican mediante el parámetro dwWakeMask.
Sintaxis
DWORD MsgWaitForMultipleObjectsEx(
[in] DWORD nCount,
[in] const HANDLE *pHandles,
[in] DWORD dwMilliseconds,
[in] DWORD dwWakeMask,
[in] DWORD dwFlags
);
Parámetros
[in] nCount
Número de identificadores de objeto de la matriz a las que apunta pHandles. El número máximo de identificadores de objeto es MAXIMUM_WAIT_OBJECTS menos uno. Si este parámetro tiene el valor cero, la función espera solo para un evento de entrada.
[in] pHandles
Matriz de identificadores de objeto. Para obtener una lista de los tipos de objeto cuyos identificadores puede especificar, consulte la sección Comentarios más adelante en este tema. La matriz puede contener identificadores para varios tipos de objetos. Puede que no contenga varias copias del mismo identificador.
Si se cierra uno de estos identificadores mientras la espera sigue pendiente, el comportamiento de la función no está definido.
Los identificadores deben tener el derecho de acceso SYNCHRONIZE. Para obtener más información, consulte Derechos de acceso estándar.
[in] dwMilliseconds
Intervalo de tiempo de espera, en milisegundos. Si se especifica un valor distinto de cero, la función espera hasta que se señalen los objetos especificados, se pone en cola una rutina de finalización de E/S o APC o el intervalo transcurrido. Si dwMilliseconds es cero, la función no especifica un estado de espera si no se cumplen los criterios; siempre devuelve inmediatamente. Si
Windows XP, Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 y Windows Server 2008 R2: El dwMilliseconds valor incluye el tiempo invertido en estados de baja potencia. Por ejemplo, el tiempo de espera sigue contando mientras el equipo está dormido.
Windows 8 y versiones más recientes, Windows Server 2012 y versiones posteriores: El dwMilliseconds valor no incluye el tiempo invertido en estados de baja potencia. Por ejemplo, el tiempo de espera no sigue contando mientras el equipo está dormido.
[in] dwWakeMask
Los tipos de entrada para los que se agregará un identificador de objeto de evento de entrada a la matriz de identificadores de objeto. Este parámetro puede ser cualquier combinación de los valores enumerados en GetQueueStatusmarcas parámetro.
[in] dwFlags
Tipo de espera. Este parámetro puede ser uno o varios de los siguientes valores.
| Valor | Significado |
|---|---|
|
La función devuelve cuando se señala a cualquiera de los objetos . El valor devuelto indica el objeto cuyo estado provocó que la función devolva. |
|
La función también devuelve si un APC se ha puesto en cola en el subproceso con QueueUserAPC mientras el subproceso está en estado de espera. |
|
La función devuelve si la entrada existe para la cola, incluso si la entrada se ha visto (pero no se ha quitado) mediante una llamada a otra función, como PeekMessage. |
|
La función devuelve cuando se indican todos los objetos de la matriz de pHandles y se recibe un evento de entrada, al mismo tiempo. |
Valor devuelto
Si la función se ejecuta correctamente, el valor devuelto indica el evento que provocó que se devuelva la función. Puede ser uno de los siguientes valores. (Tenga en cuenta que WAIT_OBJECT_0 se define como 0 y WAIT_ABANDONED_0 se define como 0x00000080L).
| Código y valor devueltos | Descripción |
|---|---|
|
Si se usa la marca MWMO_WAITALL, un valor devuelto dentro del intervalo especificado indica que se señala el estado de todos los objetos especificados. De lo contrario, el valor devuelto menos WAIT_OBJECT_0 indica el pHandles índice de matriz del objeto que provocó que la función devolvera. |
|
La nueva entrada del tipo especificado en el parámetro dwWakeMask está disponible en la cola de entrada del subproceso. Funciones como PeekMessage, GetMessage, GetQueueStatusy WaitMessage marcar mensajes en la cola como mensajes antiguos. Por lo tanto, después de llamar a una de estas funciones, una llamada posterior a MsgWaitForMultipleObjectsEx no devolverá hasta que llegue una nueva entrada del tipo especificado.
Este valor también se devuelve tras la aparición de un evento del sistema que requiere la acción del subproceso, como la activación en primer plano. Por lo tanto, msgWaitForMultipleObjectsEx puede devolver aunque no haya ninguna entrada adecuada disponible e incluso si dwWakeMask está establecido en 0. Si esto ocurre, llame a GetMessage o PeekMessage para procesar el evento del sistema antes de intentar la llamada a MsgWaitForMultipleObjectsEx de nuevo. |
|
Si se usa la marca MWMO_WAITALL, un valor devuelto dentro del intervalo especificado indica que el estado de todos los objetos especificados se señala y al menos uno de los objetos es un objeto de exclusión mutua abandonado. De lo contrario, el valor devuelto menos WAIT_ABANDONED_0 indica el pHandles índice de matriz de un objeto de exclusión mutua abandonado que provocó que la función devolvera. La propiedad del objeto de exclusión mutua se concede al subproceso que realiza la llamada y la exclusión mutua se establece en no asignada.
Si la exclusión mutua protegía la información de estado persistente, debe comprobar si hay coherencia. |
|
La espera finalizó con uno o varios modos de usuario llamadas de procedimiento asincrónico (APC) en cola al subproceso. |
|
El intervalo de tiempo de espera transcurrido, pero no se cumplen las condiciones especificadas por el dwFlags y dwWakeMask parámetros. |
|
Error en la función. Para obtener información de error extendida, llame a GetLastError. |
Observaciones
La función msgWaitForMultipleObjectsEx
Cuando dwFlags es cero, esta función comprueba los identificadores de la matriz en orden a partir del índice 0, hasta que se señale uno de los objetos. Si se señalizan varios objetos, la función devuelve el índice del primer identificador de la matriz cuyo objeto se señalizó.
msgWaitForMultipleObjectsEx no devuelve si no hay entradas leídas del tipo especificado en la cola de mensajes después de que el subproceso haya llamado a una función para comprobar la cola, a menos que use la marca MWMO_INPUTAVAILABLE. Esto se debe a que funciones como PeekMessage, GetMessage, GetQueueStatusy WaitMessage comprobar la cola y, a continuación, cambiar la información de estado de la cola para que la entrada ya no se considere nueva. Una llamada posterior a MsgWaitForMultipleObjectsEx no devolverá hasta que llegue una nueva entrada del tipo especificado, a menos que use la marca MWMO_INPUTAVAILABLE. Si no se usa esta marca, se omite la entrada no leída existente (recibida antes de la última vez que el subproceso ha comprobado la cola).
La función modifica el estado de algunos tipos de objetos de sincronización. La modificación solo se produce para el objeto o los objetos cuyo estado señalado hizo que la función devolva. Por ejemplo, el sistema reduce el recuento de un objeto de semáforo en uno. Para obtener más información, consulte la documentación de los objetos de sincronización individuales.
La función
- Notificación de cambios
- Entrada de la consola
- Evento
- Notificación de recursos de memoria
- Exclusión mutua
- Proceso
- Semáforo
- Hilo
- Temporizador que se puede esperar
Requisitos
| Requisito | Valor |
|---|---|
| cliente mínimo admitido | Windows XP [solo aplicaciones de escritorio] |
| servidor mínimo admitido | Windows Server 2003 [solo aplicaciones de escritorio] |
| de la plataforma de destino de |
Windows |
| encabezado de |
winuser.h (incluya Windows.h) |
| biblioteca de |
User32.lib |
| DLL de |
User32.dll |