Función SetThreadpoolTimerEx (threadpoolapiset.h)

Artículo
03/08/2023

Establece el objeto de temporizador, reemplazando el temporizador anterior, si existe. Un subproceso de trabajo llama a la devolución de llamada del objeto de temporizador después de que expire el tiempo de espera especificado.

Sintaxis

BOOL SetThreadpoolTimerEx(
  [in, out]      PTP_TIMER pti,
  [in, optional] PFILETIME pftDueTime,
  [in]           DWORD     msPeriod,
  [in, optional] DWORD     msWindowLength
);

Parámetros

[in, out] pti

Puntero a una estructura de TP_TIMER que define el objeto de temporizador que se va a establecer. La función CreateThreadpoolTimer devuelve este puntero.

[in, optional] pftDueTime

Puntero a una estructura FILETIME que especifica el tiempo absoluto o relativo en el que debe expirar el temporizador. Si este parámetro apunta a un valor positivo, indica la hora absoluta desde el 1 de enero de 1601 (UTC), medida en 100 unidades nanosegundas. Si este parámetro apunta a un valor negativo, indica la cantidad de tiempo que se debe esperar con respecto a la hora actual. Si este parámetro apunta a cero, el temporizador expira inmediatamente. Para obtener más información sobre los valores de hora, vea Tiempos de archivo.

Si este parámetro es NULL, el objeto de temporizador dejará de poner en cola nuevas devoluciones de llamada (pero las devoluciones de llamada ya en cola se seguirán produciendo).

El temporizador se establece si el parámetro pftDueTime no es NULL.

[in] msPeriod

Período del temporizador, en milisegundos. Si este parámetro es cero, el temporizador se señala una vez. Si este parámetro 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.

[in, optional] msWindowLength

La cantidad máxima de tiempo que el sistema puede retrasar antes de llamar a la devolución de llamada del temporizador. Si se establece este parámetro, el sistema puede realizar llamadas por lotes para conservar la energía.

Valor devuelto

Devuelve TRUE si el temporizador se estableció anteriormente y se canceló. En caso contrario, devuelve FALSE.

Si el estado anterior del temporizador era "establecido" y la función devuelve FALSE, una devolución de llamada está en curso o está a punto de comenzar. Consulte los comentarios para obtener más información.

Comentarios

Al establecer el temporizador, se cancela el temporizador anterior, si existe.

En algunos casos, las funciones de devolución de llamada se pueden ejecutar después de que una aplicación cierre el temporizador del grupo de subprocesos. Para evitar este comportamiento, una aplicación debe seguir los pasos descritos en CloseThreadpoolTimer.

Si el tiempo de vencimiento especificado por pftDueTime es relativo, el tiempo que el sistema pasa en suspensión o hibernación no cuenta para la expiración del temporizador. El temporizador se señala cuando la cantidad acumulativa de tiempo transcurrido que el sistema invierte en el estado de reactivación es igual al tiempo de vencimiento o período relativo del temporizador. Si el tiempo de vencimiento especificado por pftDueTime es absoluto, el tiempo que el sistema pasa en suspensión o hibernación cuenta para la expiración del temporizador. Si el temporizador expira mientras el sistema está en suspensión, el temporizador se señala inmediatamente cuando se activa el sistema.

Para compilar una aplicación que use esta función, defina _WIN32_WINNT como 0x0600 o superior.

Ejemplos

Para obtener un ejemplo, consulte Uso de las funciones del grupo de subprocesos.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows 8 [aplicaciones de escritorio \| Aplicaciones para UWP]
Servidor mínimo compatible	Windows Server 2012 [aplicaciones de escritorio \| Aplicaciones para UWP]
Plataforma de destino	Windows
Encabezado	threadpoolapiset.h
Library	Kernel32.lib
Archivo DLL	Kernel32.dll