Función WaitForMultipleObjectsEx (synchapi.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.
Sintaxis
DWORD WaitForMultipleObjectsEx(
[in] DWORD nCount,
[in] const HANDLE *lpHandles,
[in] BOOL bWaitAll,
[in] DWORD dwMilliseconds,
[in] BOOL bAlertable
);
Parámetros
[in] nCount
Número de identificadores de objeto a esperar en la matriz a la que apunta lpHandles. El número máximo de identificadores de objeto es MAXIMUM_WAIT_OBJECTS. Este parámetro no puede ser cero.
[in] lpHandles
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] bWaitAll
Si este parámetro es TRUE, la función devuelve cuando el estado de todos los objetos de la matriz lpHandles se establece en señalizado. Si FALSE, la función devuelve cuando el estado de cualquiera de los objetos se establece en señalizado. En este último caso, el valor devuelto indica el objeto cuyo estado hizo que la función devolva.
[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] bAlertable
Si este parámetro es TRUE y el subproceso está en estado de espera, la función devuelve cuando el sistema pone en cola una rutina de finalización de E/S o APC, y el subproceso ejecuta la rutina o función. De lo contrario, la función no devuelve y no se ejecuta la rutina de finalización ni la función APC.
Una rutina de finalización se pone en cola cuando se ha completado la función ReadFileEx o WriteFileEx en la que se especificó. La función wait devuelve y solo se llama a la rutina de finalización si bAlertable es TRUE y el subproceso que realiza la llamada es el subproceso que inició la operación de lectura o escritura. Se pone en cola un APC cuando se llama a QueueUserAPC.
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 bWaitAll es TRUE, un valor devuelto en este intervalo 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 de lpHandles del objeto que cumplió la espera. Si se señala más de un objeto durante la llamada, este es el índice de matriz del objeto señalado con el valor de índice más pequeño de todos los objetos señalados. |
|
Si bWaitAll es TRUE, un valor devuelto en este intervalo indica que el estado de todos los objetos especificados está señalado 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 lpHandles índice de matriz 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 no asignada. Si una 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, las condiciones especificadas por el parámetro bWaitAll no se cumplen y no se ponen en cola ninguna rutina de finalización. |
|
Error en la función. Para obtener información de error extendida, llame a GetLastError. |
Observaciones
La función WaitForMultipleObjectsEx determina si se han cumplido los criterios de espera. Si no se han cumplido los criterios, el subproceso de llamada entra en el estado de espera hasta que se cumplen las condiciones de los criterios de espera o el intervalo de tiempo de espera transcurrido.
Cuando bWaitAll es TRUE, la operación de espera de la función solo se completa cuando los estados de todos los objetos se han establecido en señalizado. 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 otros objetos también se establecen en señalizado. Mientras tanto, algún otro subproceso puede obtener la propiedad de la exclusión mutua, estableciendo así su estado en no asignado.
Cuando bWaitAll es FALSE, 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ó.
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 de semáforo se reduce en uno. Para obtener más información, consulte la documentación de los objetos de sincronización individuales.
Para esperar más de MAXIMUM_WAIT_OBJECTS identificadores, use uno de los métodos siguientes:
- Cree un subproceso para esperar a MAXIMUM_WAIT_OBJECTS identificadores y, a continuación, espere en ese subproceso más los demás identificadores. Use esta técnica para dividir los identificadores en grupos de MAXIMUM_WAIT_OBJECTS.
- Llame a RegisterWaitForSingleObject o SetThreadpoolWait para esperar en cada identificador. El grupo de subprocesos espera eficazmente en los identificadores y asigna un subproceso de trabajo después de que el objeto se señale o expire el intervalo de tiempo de espera.
- 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 [aplicaciones de escritorio | Aplicaciones para UWP] |
| servidor mínimo admitido | Windows Server 2003 [aplicaciones de escritorio | Aplicaciones para UWP] |
| de la plataforma de destino de |
Windows |
| encabezado de |
synchapi.h (incluya Windows.h en Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2) |
| biblioteca de |
Kernel32.lib |
| DLL de |
Kernel32.dll |