Función WaitForSingleObjectEx (synchapi.h)

  • Artículo

Espera hasta que el objeto especificado se encuentra en el estado señalado, se pone en cola una rutina de finalización de E/S o una llamada de procedimiento asincrónica (APC) al subproceso o el intervalo de tiempo de espera.

Para esperar varios objetos, use WaitForMultipleObjectsEx.

Sintaxis

DWORD WaitForSingleObjectEx(
  [in] HANDLE hHandle,
  [in] DWORD  dwMilliseconds,
  [in] BOOL   bAlertable
);

Parámetros

[in] hHandle

Identificador del objeto . Para obtener una lista de los tipos de objeto cuyos identificadores se pueden especificar, vea la siguiente sección Comentarios.

Si se cierra este identificador mientras la espera sigue pendiente, el comportamiento de la función no está definido.

El identificador debe 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ñala el objeto, 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ñale el objeto 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] 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 o 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 se llama a la rutina de finalización solo si bAlertable es TRUE y el subproceso que realiza la llamada es el subproceso que inició la operación de lectura o escritura. Una instancia de APC se pone en cola cuando se llama a QueueUserAPC.

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.

Código o valor devuelto Descripción
WAIT_ABANDONED
0x00000080L
 El objeto especificado es un objeto de exclusión mutua que el subproceso que pertenece al objeto de exclusión mutua antes de que finalice el subproceso propietario. 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.
WAIT_IO_COMPLETION
0x000000C0L
 La espera finalizó con una o varias llamadas de procedimiento asincrónico en modo de usuario (APC) en cola al subproceso.
WAIT_OBJECT_0
0x00000000L
 Se señala el estado del objeto especificado.
WAIT_TIMEOUT
0x00000102L
 El intervalo de tiempo de espera transcurrido y el estado del objeto no está asignado.
WAIT_FAILED
(DWORD)0xFFFFFFFF
 Error en la función. Para obtener información de error extendida, llame a GetLastError.

Comentarios

La función WaitForSingleObjectEx 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.

La función modifica el estado de algunos tipos de objetos de sincronización. La modificación solo se produce para el objeto cuyo estado señalado hizo que la función se devolva. Por ejemplo, el recuento de un objeto semáforo se reduce en uno.

La función WaitForSingleObjectEx puede esperar los siguientes objetos:

  • Notificación de cambio
  • Entrada de consola
  • Evento
  • Notificación de recursos de memoria
  • Mutex
  • Proceso
  • Semaphore
  • Thread
  • Temporizador que se puede esperar
Tenga cuidado al llamar a las funciones de espera y el código que crea ventanas directa o indirectamente. Si un subproceso crea ventanas, debe procesar mensajes. Las difusión de mensajes se envían a todas las ventanas del sistema. Un subproceso que usa una función de espera sin intervalo de tiempo de espera puede hacer que el sistema se interbloquee. Dos ejemplos de código que crea indirectamente ventanas son DDE y la función CoInitialize . Por lo tanto, si tiene un subproceso que crea ventanas, use MsgWaitForMultipleObjects o MsgWaitForMultipleObjectsEx, en lugar de WaitForSingleObjectEx.

Ejemplos

Para obtener un ejemplo, vea Servidor de canalización con nombre mediante rutinas de finalización.

Requisitos

Requisito Value
Cliente mínimo compatible Windows XP [aplicaciones de escritorio | aplicaciones para UWP]
Servidor mínimo compatible Windows Server 2003 [aplicaciones de escritorio | aplicaciones para UWP]
Plataforma de destino Windows
Encabezado synchapi.h (incluye Windows.h en Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2)
Library Kernel32.lib
Archivo DLL Kernel32.dll

Vea también

Funciones de sincronización

Funciones wait