Compartir a través de

Función WaitForSingleObject (synchapi.h)

  • Artículo

Espera hasta que el objeto especificado se encuentra en el 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

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 o el intervalo transcurre. 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 devolverá solo cuando se señale el objeto.

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.

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 el estado de exclusión mutua se establece en no asignado.

Si la exclusión mutua protegía la información de estado persistente, debe comprobar si hay 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.

Observaciones

La función WaitForSingleObject comprueba el estado actual del objeto especificado. Si el estado del objeto no está asignado, el subproceso que realiza la llamada entra en el estado de espera hasta que se señaliza el objeto 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 waitForSingleObject 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 con una infinito intervalo de tiempo de espera puede hacer 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 WaitForSingleObject.

Ejemplos

Para obtener un ejemplo, vea Using Mutex Objects.

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