Función SetWaitableTimer (synchapi.h)

Artículo
03/08/2023

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. La función CreateWaitableTimer o OpenWaitableTimer devuelve este identificador.

El identificador debe tener el derecho de acceso TIMER_MODIFY_STATE . 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 se establecerá el estado del temporizador en señalizado, en intervalos de 100 nanosegundos. Use el formato descrito por la estructura FILETIME . Los valores positivos indican tiempo absoluto. Asegúrese de usar una hora absoluta basada en UTC, ya que el sistema usa internamente el tiempo basado en UTC. Los valores negativos indican la hora relativa. La precisión real del temporizador depende de la funcionalidad del hardware. Para obtener más información sobre la hora basada en UTC, consulte Hora del sistema.

[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 reactiva automáticamente cada vez que transcurre el período, hasta que se cancele el temporizador mediante la función CancelWaitableTimer o restablezca mediante SetWaitableTimer. Si lPeriod es menor que cero, se produce un error en la función.

[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 va a ejecutar cuando se señala el temporizador. Para obtener más información sobre la función de devolución de llamada del temporizador, vea 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 realiza correctamente, el valor devuelto es distinto de cero.

Si la función no se realiza correctamente, el valor devuelto es cero. Para obtener información de error extendida, llame a GetLastError.

Comentarios

Los temporizadores están inactivos inicialmente. Para activar un temporizador, llame a SetWaitableTimer. Si el temporizador ya está activo cuando se llama a SetWaitableTimer, se detiene el temporizador y 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 deja de estar 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ñalado, 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 un estado de espera alertable. Para obtener más información, vea QueueUserAPC. Tenga en cuenta que las API no funcionan así como 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 esperable, como un temporizador creado con CreateThreadpoolTimer. Para E/S, use un objeto de finalización de E/S creado con CreateThreadpoolIo o una estructura SUPERPUESTA basada en hEvent, donde el evento se puede pasar 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 terminació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, un temporizador de restablecimiento manual periódico se establece en el estado señalado cuando llega el tiempo de vencimiento inicial y permanece señalado hasta que se restablece. Cuando un temporizador de sincronización se establece 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 Uso de los encabezados de Windows.

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 ver un ejemplo que usa SetWaitableTimer, vea Using Waitable Timer Objects.

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