Función WaitForSingleObject (synchapi.h)
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 |
---|---|
|
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. |
|
Se señala el estado del objeto especificado. |
|
El intervalo de tiempo de espera transcurrido y el estado del objeto no está asignado. |
|
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
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 |