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. 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 Synchronization Object Security and Access Rights.

[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 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 el tiempo relativo. La precisión del temporizador real depende de la capacidad 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 se reactiva automáticamente cada vez que transcurre el período, hasta que se cancela el temporizador mediante la función 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 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] lpArgToCompletionRoutine

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

[in] WakeContext

Puntero a una estructura de 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 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

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 usa esta función, defina _WIN32_WINNT como 0x0601 o posterior. Para obtener más información, vea Usar los encabezados de Windows.

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ñalado, por lo que los subprocesos bloqueados en una operación de espera del 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ñ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 que se puede alertar. 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 SetWaitableTimerEx 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.

Si se cierra 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

Vea también

REASON_CONTEXT

SetWaitableTimer