Función MsgWaitForMultipleObjects (winuser.h)
Espera hasta que transcurre uno o todos los objetos especificados en el estado señalado o el intervalo de tiempo de espera. Los objetos pueden incluir objetos de evento de entrada, que se especifican mediante el parámetro dwWakeMask .
Para especificar un estado de espera alertable, use la función MsgWaitForMultipleObjectsEx .
Sintaxis
DWORD MsgWaitForMultipleObjects(
[in] DWORD nCount,
[in] const HANDLE *pHandles,
[in] BOOL fWaitAll,
[in] DWORD dwMilliseconds,
[in] DWORD dwWakeMask
);
Parámetros
[in] nCount
Número de identificadores de objeto en la matriz a la 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 se pueden especificar, vea la siguiente sección Comentarios. La matriz puede contener identificadores de objetos de diferentes tipos. 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] fWaitAll
Si este parámetro es TRUE, la función devuelve cuando se han recibido los estados de todos los objetos de la matriz pHandles en señalizado y se ha recibido un evento de entrada. Si este parámetro es FALSE, la función devuelve cuando se ha recibido el estado de cualquiera de los objetos en señalizado o se ha recibido un evento de entrada. En este caso, el valor devuelto indica el objeto cuyo estado hizo que la función devolva.
[in] dwMilliseconds
El intervalo de tiempo de espera en milisegundos. Si se especifica un valor distinto de cero, la función espera hasta que transcurren los objetos especificados o el intervalo. Si dwMilliseconds es cero, la función no entra en un estado de espera si los objetos especificados no están señalados; siempre devuelve inmediatamente. Si dwMilliseconds es INFINITE, la función solo devolverá cuando se señalen los objetos especificados.
Windows XP, Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 y Windows Server 2008 R2: El valor dwMilliseconds incluye el tiempo invertido en estados de bajo consumo. Por ejemplo, el tiempo de espera sigue contando mientras el equipo está dormido.
Windows 8, Windows Server 2012, Windows 8.1, Windows Server 2012 R2, Windows 10 y Windows Server 2016: el valor dwMilliseconds no incluye el tiempo invertido en baja potencia Estados. 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 el parámetro flags GetQueueStatus.
Valor devuelto
Si la función se ejecuta correctamente, el valor devuelto indica el evento que provocó que la función se devolva. 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 0x000000080L).
| Código o valor devuelto | Descripción |
|---|---|
|
Si bWaitAll es TRUE, un valor devuelto dentro del intervalo especificado indica que se señala el estado de todos los objetos especificados. Si bWaitAll es FALSE, el valor devuelto menos WAIT_OBJECT_0 indica el índice de matriz pHandles del objeto que cumplió la espera. |
|
La nueva entrada del tipo especificado en el parámetro dwWakeMask está disponible en la cola de entrada del subproceso. Funciones como PeekMessage, GetMessage y WaitMessage marcan mensajes en la cola como mensajes antiguos. Por lo tanto, después de llamar a una de estas funciones, una llamada posterior a MsgWaitForMultipleObjects no volverá hasta que llegue la nueva entrada del tipo especificado.
Este valor también se devuelve cuando se produce un evento del sistema que requiere la acción del subproceso, como la activación en primer plano. Por lo tanto, MsgWaitForMultipleObjects 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 volver a intentar la llamada a MsgWaitForMultipleObjects . |
|
Si bWaitAll es TRUE, 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. Si bWaitAll es FALSE, el valor devuelto menos WAIT_ABANDONED_0 indica el índice de matriz pHandles de un objeto de exclusión mutua abandonado que cumplió la espera. La propiedad del objeto de exclusión mutua se concede al subproceso que realiza la llamada y la exclusión mutua se establece en sin signo.
Si la exclusión mutua protegía la información de estado persistente, debe comprobarla para comprobar la coherencia. |
|
No se cumplió el intervalo de tiempo de espera y las condiciones especificadas por los parámetros bWaitAll y dwWakeMask . |
|
Error en la función. Para obtener información de error extendida, llame a GetLastError. |
Comentarios
La función MsgWaitForMultipleObjects determina si se han cumplido los criterios de espera. Si no se han cumplido los criterios, el subproceso que realiza la llamada entra en estado de espera hasta que se cumplan las condiciones de los criterios de espera o el intervalo de tiempo de espera transcurrido.
Cuando bWaitAll es TRUE, la función no modifica los estados de los objetos especificados hasta que los estados de todos los objetos se han establecido en señalizado. Por ejemplo, se puede señalar una exclusión mutua, pero el subproceso no obtiene la propiedad hasta que los estados de los demás objetos también se han establecido en señalizado. Mientras tanto, algún otro subproceso puede obtener la propiedad de la exclusión mutua, estableciendo así su estado en sin signo.
Cuando bWaitAll es TRUE, la espera de la función solo se completa cuando se han establecido los estados de todos los objetos en señalizado y se ha recibido un evento de entrada. Por lo tanto, si se establece bWaitAll en TRUE , se impide que la entrada se procese hasta que el estado de todos los objetos de la matriz pHandles se haya establecido en señalizado. Por este motivo, si establece bWaitAll en TRUE, debe usar un breve valor de tiempo de espera en dwMilliseconds. Si tiene un subproceso que crea ventanas que esperan todos los objetos de la matriz pHandles , incluidos los eventos de entrada especificados por dwWakeMask, sin intervalo de tiempo de espera, el sistema interbloqueo. Esto se debe a que los subprocesos que crean ventanas deben procesar mensajes. DDE envía un mensaje a todas las ventanas del sistema. Por lo tanto, si un subproceso crea ventanas, no establezca el parámetro bWaitAll en TRUE en llamadas a MsgWaitForMultipleObjects realizadas desde ese subproceso.
Cuando bWaitAll es FALSE, esta función comprueba los identificadores de la matriz en orden a partir del índice 0, hasta que se señala a 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ó.
MsgWaitForMultipleObjects no devuelve si hay entradas no 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. Esto se debe a que las funciones como PeekMessage, GetMessage, GetQueueStatus y WaitMessage comprueban la cola y, a continuación, cambian la información de estado de la cola para que la entrada ya no se considere nueva. Una llamada posterior a MsgWaitForMultipleObjects no se devolverá hasta que llegue la nueva entrada del tipo especificado. 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 recuento de un objeto semáforo se reduce en uno. Para obtener más información, consulte la documentación de los objetos de sincronización individuales.
La función MsgWaitForMultipleObjects puede especificar identificadores de cualquiera de los siguientes tipos de objeto en la matriz pHandles :
- Notificación de cambio
- Entrada de consola
- Evento
- Notificación de recursos de memoria
- Mutex
- Proceso
- Semaphore
- Thread
- Temporizador que se puede esperar
Requisitos
| Cliente mínimo compatible | Windows XP [solo aplicaciones de escritorio] |
| Servidor mínimo compatible | Windows Server 2003 [solo aplicaciones de escritorio] |
| Plataforma de destino | Windows |
| Encabezado | winuser.h (incluya Windows.h) |
| Library | User32.lib |
| Archivo DLL | User32.dll |
Consulte también
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de