Función WaitForSingleObjectEx (synchapi.h)

  • Artículo

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

Para esperar varios objetos, use el 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

Intervalo de tiempo de espera, en milisegundos. Si se especifica un valor distinto de cero, la función espera hasta que se señaliza el objeto, 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 dwMilliseconds es INFINITE, la función devolverá solo cuando el objeto se señale 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 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 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 solo se llama a la rutina de finalización si bAlertable es TRUEy 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.

Código y valor devueltos Descripción
WAIT_ABANDONED
0x00000080L
 El objeto especificado es un objeto de exclusión mutua no liberado por 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 no asignada.

Si la exclusión mutua protegía la información de estado persistente, debe comprobar si hay coherencia.
WAIT_IO_COMPLETION
0x000000C0L
 La espera finalizó con uno o varios modos de usuario llamadas de procedimiento asincrónico (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.

Observaciones

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

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 ha provocado que la función devuelva. Por ejemplo, el recuento de un objeto de semáforo se reduce en uno.

La función WaitForSingleObjectEx puede esperar a los siguientes objetos:

  • 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
Tenga cuidado al llamar a las funciones de espera y el código que crea ventanas directamente 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 provocar que el sistema se interbloquee. Dos ejemplos de código que crean ventanas indirectamente 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 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

Consulte también

Funciones de sincronización de

funciones de espera