Función SetWaitableTimerEx (synchapi.h)

Activa el temporizador de espera especificado y proporciona información de contexto para el temporizador. 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 SetWaitableTimerEx(
  [in] HANDLE              hTimer,
  [in] const LARGE_INTEGER *lpDueTime,
  [in] LONG                lPeriod,
  [in] PTIMERAPCROUTINE    pfnCompletionRoutine,
  [in] LPVOID              lpArgToCompletionRoutine,
  [in] PREASON_CONTEXT     WakeContext,
  [in] ULONG               TolerableDelay
);

Parámetros

[in] hTimer

Identificador del objeto de temporizador. El CreateWaitableTimer o openWaitableTimer función devuelve este identificador.

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 de CancelWaitableTimer o se restablece mediante SetWaitableTimerEx. Si lPeriod es menor que cero, se produce un error en la función.

[in] 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] lpArgToCompletionRoutine

Puntero a una estructura que se pasa a la rutina de finalización.

[in] WakeContext

Puntero a una estructura REASON_CONTEXT que contiene información de contexto para el temporizador.

[in] TolerableDelay

Retraso tolerable para el tiempo de expiración, en milisegundos.

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

La función setWaitableTimerEx es similar a la función setWaitableTimer , excepto setWaitableTimerEx se puede usar para especificar una cadena de contexto y un retraso tolerable para la expiración del temporizador.

Para compilar una aplicación que use esta función, defina _WIN32_WINNT como 0x0601 o posterior. Para obtener más información, vea Using the Windows Headers.

Los temporizadores están inicialmente inactivos. Para activar un temporizador, llame a SetWaitableTimerEx. Si el temporizador ya está activo cuando se llama a SetWaitableTimerEx, 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 SetWaitableTimerEx 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.

Si sale el subproceso que llamó a SetWaitableTimerEx, se cancela el temporizador. Esto detiene el temporizador antes de que se pueda establecer en el estado señalado y cancela las API pendientes; no cambia el estado señalado del temporizador.

Para usar un temporizador para programar un evento para una ventana, use la función SetTimer.

Requisitos

Requisito	Valor
cliente mínimo admitido	Windows 7 [aplicaciones de escritorio | Aplicaciones para UWP]
servidor mínimo admitido	Windows Server 2008 R2 [aplicaciones de escritorio | Aplicaciones para UWP]
de la plataforma de destino de	Windows
encabezado de	synchapi.h (incluya Windows.h)
biblioteca de	Kernel32.lib
DLL de	Kernel32.dll

Consulte también

REASON_CONTEXT

SetWaitableTimer