Función CreateTimerQueueTimer (threadpoollegacyapiset.h)

Crea un temporizador de cola de temporizador. Este temporizador expira en el momento de vencimiento especificado y, a continuación, después de cada período especificado. Cuando expira el temporizador, se llama a la función de devolución de llamada.

Sintaxis

BOOL CreateTimerQueueTimer(
  [out]          PHANDLE             phNewTimer,
  [in, optional] HANDLE              TimerQueue,
  [in]           WAITORTIMERCALLBACK Callback,
  [in, optional] PVOID               Parameter,
  [in]           DWORD               DueTime,
  [in]           DWORD               Period,
  [in]           ULONG               Flags
);

Parámetros

[out] phNewTimer

Puntero a un búfer que recibe un identificador para el temporizador de la cola del temporizador cuando se devuelve. Cuando este identificador ha expirado y ya no es necesario, líquelo llamando a DeleteTimerQueueTimer.

[in, optional] TimerQueue

Identificador de la cola del temporizador. La función CreateTimerQueue devuelve este identificador.

Si este parámetro es NULL, el temporizador se asocia a la cola del temporizador predeterminada.

[in] Callback

Puntero a la función definida por la aplicación del tipo WAITORTIMERCALLBACK que se va a ejecutar cuando expira el temporizador. Para obtener más información, vea WaitOrTimerCallback.

[in, optional] Parameter

Valor de parámetro único que se pasará a la función de devolución de llamada.

[in] DueTime

Cantidad de tiempo en milisegundos en relación con la hora actual que debe transcurrir antes de que el temporizador se indique por primera vez.

[in] Period

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 se reactiva automáticamente cada vez que transcurre el período, hasta que se cancela el temporizador.

[in] Flags

Este parámetro puede ser uno o varios de los valores siguientes de WinNT.h.

Valor Significado
WT_EXECUTEDEFAULT
0x00000000
De forma predeterminada, la función de devolución de llamada se pone en cola en un subproceso de trabajo que no es de E/S.
WT_EXECUTEINTIMERTHREAD
0x00000020
El propio subproceso del temporizador invoca la función de devolución de llamada. Esta marca solo se debe usar para tareas cortas o podría afectar a otras operaciones del temporizador.

La función de devolución de llamada se pone en cola como un APC. No debe realizar operaciones de espera que se puedan generar alertas.

WT_EXECUTEINIOTHREAD
0x00000001
Esta marca no se usa.

Windows Server 2003 y Windows XP: La función de devolución de llamada se pone en cola en un subproceso de trabajo de E/S. Esta marca se debe usar si la función debe ejecutarse en un subproceso que espera en un estado de alerta.

Los subprocesos de trabajo de E/S se quitaron a partir de Windows Vista y Windows Server 2008.

WT_EXECUTEINPERSISTENTTHREAD
0x00000080
La función de devolución de llamada se pone en cola en un subproceso que nunca finaliza. No garantiza que se use el mismo subproceso cada vez. Esta marca solo se debe usar para tareas cortas o podría afectar a otras operaciones del temporizador.

Esta marca debe establecerse si el subproceso llama a funciones que usan API. Para obtener más información, vea Llamadas asincrónicas a procedimientos.

Tenga en cuenta que actualmente no hay ningún subproceso de trabajo realmente persistente, aunque ningún subproceso de trabajo finalizará si hay solicitudes de E/S pendientes.

WT_EXECUTELONGFUNCTION
0x00000010
La función de devolución de llamada puede realizar una larga espera. Esta marca ayuda al sistema a decidir si debe crear un subproceso nuevo.
WT_EXECUTEONLYONCE
0x00000008
El temporizador se establecerá en el estado señalado una sola vez. Si se establece esta marca, el parámetro Period debe ser cero.
WT_TRANSFER_IMPERSONATION
0x00000100
Las funciones de devolución de llamada usarán el token de acceso actual, ya sea un token de proceso o suplantación. Si no se especifica esta marca, las funciones de devolución de llamada solo se ejecutan con el token de proceso.

Windows XP: Esta marca no se admite hasta Windows XP con SP2 y Windows Server 2003.

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

Si los parámetros DueTime y Period son distintos de cero, el temporizador se indicará primero en el momento de vencimiento y, a continuación, periódicamente. Se llama a la devolución de llamada cada vez que transcurre el período, independientemente de si la devolución de llamada anterior ha terminado de ejecutarse. Las funciones de devolución de llamada se ponen en cola en el grupo de subprocesos. Estos subprocesos están sujetos a retrasos de programación, por lo que el tiempo puede variar en función de lo que ocurra en la aplicación o en el sistema.

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 pasa en el estado de reactivación coincide con el tiempo de vencimiento o el período del temporizador.

Windows Server 2003 y Windows XP: 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 cancelar un temporizador, llame a la función DeleteTimerQueueTimer . Para cancelar todos los temporizadores de una cola del temporizador, llame a la función DeleteTimerQueueEx .

De forma predeterminada, el grupo de subprocesos tiene un máximo de 500 subprocesos. Para aumentar este límite, use la macro WT_SET_MAX_THREADPOOL_THREAD definida en WinNT.h.

#define WT_SET_MAX_THREADPOOL_THREADS(Flags,Limit) \
    ((Flags)|=(Limit)<<16)

Use esta macro al especificar el parámetro Flags . Los parámetros de macro son las marcas deseadas y el nuevo límite (hasta (2<<16)-1 subprocesos). Sin embargo, tenga en cuenta que la aplicación puede mejorar su rendimiento manteniendo el número de subprocesos de trabajo bajos.

Para compilar una aplicación que usa esta función, defina _WIN32_WINNT como 0x0500 o posterior. Para obtener más información, vea Usar los encabezados de Windows.

Ejemplos

Para obtener un ejemplo que usa CreateTimerQueueTimer, vea Using Timer Queues.

Requisitos

Requisito Value
Cliente mínimo compatible Windows XP [solo aplicaciones de escritorio]
Servidor mínimo compatible Windows Server 2003 [solo aplicaciones de escritorio]
Plataforma de destino Windows
Encabezado threadpoollegacyapiset.h
Library Kernel32.lib
Archivo DLL Kernel32.dll

Vea también

CreateTimerQueue

DeleteTimerQueueEx

DeleteTimerQueueTimer

Funciones de sincronización

Agrupación de subprocesos

Colas del temporizador