Función SetWaitableTimer (synchapi.h)
Activa el temporizador de espera especificado. Cuando llega el tiempo de vencimiento, se señala el temporizador y el subproceso que establece el temporizador llama a la rutina de finalización opcional.
Sintaxis
BOOL SetWaitableTimer(
[in] HANDLE hTimer,
[in] const LARGE_INTEGER *lpDueTime,
[in] LONG lPeriod,
[in, optional] PTIMERAPCROUTINE pfnCompletionRoutine,
[in, optional] LPVOID lpArgToCompletionRoutine,
[in] BOOL fResume
);
Parámetros
[in] hTimer
Identificador del objeto de temporizador. El CreateWaitableTimer
El identificador debe tener el TIMER_MODIFY_STATE derecho de acceso. Para obtener más información, vea Seguridad de objetos de sincronización y derechos de acceso.
[in] lpDueTime
Hora después de la cual el estado del temporizador se va a establecer en señalizado, en intervalos de 100 nanosegundos. Use el formato descrito por la estructura FILETIME. Los valores positivos indican la hora absoluta. Asegúrese de usar una hora absoluta basada en UTC, ya que el sistema usa el tiempo basado en UTC internamente. Los valores negativos indican tiempo relativo. La precisión real del temporizador depende de la capacidad del hardware. Para obtener más información sobre la hora basada en UTC, consulte hora del sistema.
Windows XP, Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 y Windows Server 2008 R2: Si se especifica el tiempo relativo, el temporizador incluye el tiempo invertido en estados de baja potencia. Por ejemplo, el temporizador continúa contando hacia abajo mientras el equipo está dormido.
Windows 8 y versiones más recientes, Windows Server 2012 y versiones posteriores: Si se especifica el tiempo relativo, el temporizador no incluye el tiempo invertido en estados de baja potencia. Por ejemplo, el temporizador no continúa contando mientras el equipo está dormido.
[in] lPeriod
Período del temporizador, en milisegundos. Si lPeriod es cero, el temporizador se señala una vez. Si lPeriod es mayor que cero, el temporizador es periódico. Un temporizador periódico se reactiva automáticamente cada vez que transcurre el período, hasta que se cancele el temporizador mediante la función CancelWaitableTimer
[in, optional] pfnCompletionRoutine
Puntero a una rutina de finalización opcional. La rutina de finalización es una función definida por la aplicación de tipo PTIMERAPCROUTINE que se ejecutará cuando se señale el temporizador. Para obtener más información sobre la función de devolución de llamada del temporizador, consulte TimerAPCProc. Para obtener más información sobre las API y los subprocesos del grupo de subprocesos, vea Comentarios.
[in, optional] lpArgToCompletionRoutine
Puntero a una estructura que se pasa a la rutina de finalización.
[in] fResume
Si este parámetro es TRUE, restaura un sistema en modo de conservación de energía suspendida cuando el estado del temporizador se establece en señalizado. De lo contrario, el sistema no se restaura. Si el sistema no admite una restauración, la llamada se realiza correctamente, pero GetLastError devuelve ERROR_NOT_SUPPORTED.
Valor devuelto
Si la función se ejecuta correctamente, el valor devuelto es distinto de cero.
Si se produce un error en la función, el valor devuelto es cero. Para obtener información de error extendida, llame a GetLastError.
Observaciones
Los temporizadores están inicialmente inactivos. Para activar un temporizador, llame a SetWaitableTimer. Si el temporizador ya está activo cuando se llama a SetWaitableTimer, se detiene el temporizador y, a continuación, se reactiva. Detener el temporizador de esta manera no establece el estado del temporizador en señalizado, por lo que los subprocesos bloqueados en una operación de espera en el temporizador permanecen bloqueados. Sin embargo, cancela las rutinas de finalización pendientes.
Cuando llega el tiempo de vencimiento especificado, el temporizador se vuelve inactivo y el APC opcional se pone en cola en el subproceso que establece el temporizador si no hay ningún APC pendiente ya en cola. El estado del temporizador se establece en señalizado, el temporizador se reactiva mediante el período especificado y el subproceso que establece el temporizador llama a la rutina de finalización cuando entra en estado de espera alertable. Para obtener más información, vea QueueUserAPC. Tenga en cuenta que las API no funcionan ni otros mecanismos de señalización para los subprocesos del grupo de subprocesos porque el sistema controla la duración de los subprocesos del grupo de subprocesos, por lo que es posible que un subproceso finalice antes de que se entregue la notificación. En lugar de usar el parámetro pfnCompletionRoutine u otro mecanismo de señalización basado en APC, use un objeto que se pueda esperar, como un temporizador creado con CreateThreadpoolTimer. Para E/S, use un objeto de finalización de E/S creado con CreateThreadpoolIo o una hEventbasada en estructura de SUPERPUESTA donde se puede pasar el evento a la función SetThreadpoolWait.
Si el subproceso que establece el temporizador finaliza y hay una rutina de finalización asociada, se cancela el temporizador. Sin embargo, el estado del temporizador permanece sin cambios. Si no hay ninguna rutina de finalización, la finalización del subproceso no tiene ningún efecto en el temporizador.
Cuando se establece un temporizador de restablecimiento manual en el estado señalado, permanece en este estado hasta que se llama a SetWaitableTimer para restablecer el temporizador. Como resultado, se establece un temporizador de restablecimiento manual periódico en el estado señalado cuando llega el tiempo de vencimiento inicial y permanece señalado hasta que se restablece. Cuando se establece un temporizador de sincronización en el estado señalado, permanece en este estado hasta que un subproceso completa una operación de espera en el objeto de temporizador.
Si se ajusta la hora del sistema, se ajusta el tiempo de vencimiento de los temporizadores absolutos pendientes.
Para compilar una aplicación que use esta función, defina _WIN32_WINNT como 0x0400 o posterior. Para obtener más información, vea Using the Windows Headers.
Para usar un temporizador para programar un evento para una ventana, use la función SetTimer.
Las API que tratan con temporizadores usan diferentes relojes de hardware. Estos relojes pueden tener resoluciones significativamente diferentes de lo que espera: algunos pueden medirse en milisegundos (para aquellos que usan un chip de temporizador basado en RTC), a los medidos en nanosegundos (para aquellos que usan contadores ACPI o TSC). Puede cambiar la resolución de la API con una llamada a las funciones timeBeginPeriod y timeEndPeriod. La precisión con la que puede cambiar la resolución depende del reloj de hardware que usa la API concreta. Para más información, consulte la documentación de hardware.
Ejemplos
Para obtener un ejemplo que usa SetWaitableTimer, vea Using Waitable Timer 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
timerAPCProc de