Compartir a través de

Función WaitForSingleObject (synchapi.h)

  • Artículo

Espera hasta que el objeto especificado esté en estado señalado o el intervalo de tiempo de espera transcurrido.

Para especificar un estado de espera alertable, use la función WaitForSingleObjectEx . Para esperar varios objetos, use WaitForMultipleObjects.

Sintaxis

DWORD WaitForSingleObject(
  [in] HANDLE hHandle,
  [in] DWORD  dwMilliseconds
);

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 transcurre el objeto o el intervalo. Si dwMilliseconds es cero, la función no entra en un estado de espera si el objeto no está señalado; siempre devuelve inmediatamente. Si dwMilliseconds es INFINITE, la función solo devolverá cuando se señale el objeto.

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.

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 el estado de 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_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 WaitForSingleObject comprueba el estado actual del objeto especificado. Si el estado del objeto no tiene signo, el subproceso que realiza la llamada entra en el estado de espera hasta que se señala el objeto o transcurre el intervalo de tiempo de espera.

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 WaitForSingleObject 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 WaitForSingleObject.

Ejemplos

Para obtener un ejemplo, vea Uso de objetos de exclusión mutua.

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