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 |
|---|---|
|
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. |
|
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. |
|
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. |
|
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. |
|
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. |
|
El temporizador se establecerá en el estado señalado una sola vez. Si se establece esta marca, el parámetro Period debe ser cero. |
|
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 |