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 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 puede especificar, vea 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
El intervalo de tiempo de espera en milisegundos. Si se especifica un valor distinto de cero, la función espera hasta que se señalizan los objetos especificados, se pone en cola una rutina de finalización de E/S o APC o el intervalo transcurre. Si dwMilliseconds es cero, la función no especifica un estado de espera si no se cumplen los criterios; siempre devuelve inmediatamente. Si dwMilliseconds es INFINITE, la función solo devolverá cuando se señalen los objetos especificados o se pone en cola una rutina de finalización de E/S o APC.
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á suspendido.
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 estados de bajo consumo. Por ejemplo, el tiempo de espera no sigue contando mientras el equipo está suspendido.
[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 flagsGetQueueStatus.
[in] dwFlags
Tipo de espera. Este parámetro puede ser uno o más 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 hizo 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 señalizan todos los objetos de la matriz pHandles y se recibe un evento de entrada, al mismo tiempo. |
Valor devuelto
Si la función se realiza 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 0x00000080L).
| Código o valor devuelto | 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 índice de matriz pHandles del objeto que provocó que la función devolva. |
|
La nueva entrada del tipo especificado en el parámetro dwWakeMask está disponible en la cola de entrada del subproceso. Funciones como PeekMessage, GetMessage, GetQueueStatus 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 MsgWaitForMultipleObjectsEx 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, 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 índice de matriz pHandles de un objeto de exclusión mutua abandonado que provocó que la función devolva. 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 comprobar si hay coherencia. |
|
La espera finalizó mediante una o varias llamadas de procedimiento asincrónico en modo de usuario (APC) en cola al subproceso. |
|
El intervalo de tiempo de espera transcurrido, pero no se cumplen las condiciones especificadas por los parámetros dwFlags y dwWakeMask . |
|
Error en la función. Para obtener información de error extendida, llame a GetLastError. |
Comentarios
La función MsgWaitForMultipleObjectsEx determina si se han cumplido las condiciones especificadas por dwWakeMask y dwFlags . Si no se cumplen las condiciones, el subproceso que realiza la llamada entra en el estado de espera hasta que se cumplen las condiciones de los criterios de espera o transcurre el intervalo de tiempo de espera.
Cuando dwFlags es cero, esta función comprueba los identificadores de la matriz en orden a partir del índice 0, hasta que se señala 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 se ha leído la entrada 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 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 MsgWaitForMultipleObjectsEx no volverá hasta que llegue la 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 comprobó 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 u objetos cuyo estado señalado ha provocado que la función devuelva. 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 MsgWaitForMultipleObjectsEx puede especificar identificadores de cualquiera de los siguientes tipos de objeto en la matriz pHandles :
- Notificación de cambios
- Entrada de la consola
- Evento
- Notificación de recursos de memoria
- Mutex
- Proceso
- Semaphore
- Thread
- Temporizador de espera
Requisitos
| Requisito | Value |
|---|---|
| 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 (incluir 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