Função CreateTimerQueueTimer (threadpoollegacyapiset.h)
Cria um temporizador de fila de temporizador. Esse temporizador expira no tempo de conclusão especificado e, em seguida, após cada período especificado. Quando o temporizador expira, a função de retorno de chamada é chamada.
Sintaxe
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
Um ponteiro para um buffer que recebe um identificador para o temporizador de fila de temporizador no retorno. Quando esse identificador tiver expirado e não for mais necessário, libere-o chamando DeleteTimerQueueTimer.
[in, optional] TimerQueue
Um identificador para a fila do temporizador. Esse identificador é retornado pela função CreateTimerQueue .
Se esse parâmetro for NULL, o temporizador será associado à fila do temporizador padrão.
[in] Callback
Um ponteiro para a função definida pelo aplicativo do tipo WAITORTIMERCALLBACK a ser executado quando o temporizador expirar. Para obter mais informações, consulte WaitOrTimerCallback.
[in, optional] Parameter
Um único valor de parâmetro que será passado para a função de retorno de chamada.
[in] DueTime
A quantidade de tempo em milissegundos em relação ao tempo atual que deve decorrido antes que o temporizador seja sinalizado pela primeira vez.
[in] Period
O período do temporizador, em milissegundos. Se esse parâmetro for zero, o temporizador será sinalizado uma vez. Se esse parâmetro for maior que zero, o temporizador será periódico. Um temporizador periódico reativa automaticamente cada vez que o período passa, até que o temporizador seja cancelado.
[in] Flags
Esse parâmetro pode ser um ou mais dos seguintes valores de WinNT.h.
| Valor | Significado |
|---|---|
|
Por padrão, a função de retorno de chamada é enfileirada em um thread de trabalho que não seja de E/S. |
|
A função de retorno de chamada é invocada pelo thread do temporizador em si. Esse sinalizador deve ser usado apenas para tarefas curtas ou pode afetar outras operações de temporizador.
A função de retorno de chamada é enfileirada como um APC. Ele não deve executar operações de espera alertáveis. |
|
Esse sinalizador não é usado.
Windows Server 2003 e Windows XP: A função de retorno de chamada é enfileirada em um thread de trabalho de E/S. Esse sinalizador deve ser usado se a função deve ser executada em um thread que aguarda em um estado alertável. Os threads de trabalho de E/S foram removidos a partir do Windows Vista e do Windows Server 2008. |
|
A função de retorno de chamada é enfileirada em um thread que nunca termina. Ele não garante que o mesmo thread seja usado sempre. Esse sinalizador deve ser usado apenas para tarefas curtas ou pode afetar outras operações de temporizador.
Esse sinalizador deve ser definido se o thread chamar funções que usam APCs. Para obter mais informações, consulte Chamadas de procedimento assíncrono. Observe que atualmente nenhum thread de trabalho é realmente persistente, embora nenhum thread de trabalho seja encerrado se houver solicitações de E/S pendentes. |
|
A função de retorno de chamada pode executar uma longa espera. Esse sinalizador ajuda o sistema a decidir se ele deve criar um novo thread. |
|
O temporizador será definido como o estado sinalizado apenas uma vez. Se esse sinalizador for definido, o parâmetro Period deverá ser zero. |
|
As funções de retorno de chamada usarão o token de acesso atual, seja ele um token de processo ou representação. Se esse sinalizador não for especificado, as funções de retorno de chamada serão executadas somente com o token de processo.
Windows XP: Esse sinalizador não tem suporte até o Windows XP com SP2 e Windows Server 2003. |
Valor retornado
Se a função for bem-sucedida, o valor retornado será diferente de zero.
Se a função falhar, o valor retornado será zero. Para obter informações de erro estendidas, chame GetLastError.
Comentários
Se os parâmetros DueTime e Period não forem zero, o temporizador será sinalizado primeiro no momento devido e, em seguida, periodicamente. O retorno de chamada é chamado sempre que o período passa, independentemente de o retorno de chamada anterior ter terminado ou não de ser executado. As funções de retorno de chamada são enfileiradas no pool de threads. Esses threads estão sujeitos a atrasos de agendamento, portanto, o tempo pode variar dependendo do que mais está acontecendo no aplicativo ou no sistema.
O tempo que o sistema passa em suspensão ou hibernação não conta para a expiração do temporizador. O temporizador é sinalizado quando a quantidade cumulativa de tempo decorrido que o sistema passa no estado de ativação corresponde ao tempo ou período de vencimento do temporizador.
Windows Server 2003 e Windows XP: O tempo que o sistema passa em suspensão ou hibernação conta para a expiração do temporizador. Se o temporizador expirar enquanto o sistema estiver em suspensão, o temporizador será sinalizado imediatamente quando o sistema é ativado.
Para cancelar um temporizador, chame a função DeleteTimerQueueTimer . Para cancelar todos os temporizadores em uma fila de temporizador, chame a função DeleteTimerQueueEx .
Por padrão, o pool de threads tem no máximo 500 threads. Para aumentar esse limite, use a macro WT_SET_MAX_THREADPOOL_THREAD definida em WinNT.h.
#define WT_SET_MAX_THREADPOOL_THREADS(Flags,Limit) \
((Flags)|=(Limit)<<16)
Use essa macro ao especificar o parâmetro Flags . Os parâmetros de macro são os sinalizadores desejados e o novo limite (até (2<<16)-1 threads). No entanto, observe que seu aplicativo pode melhorar seu desempenho mantendo o número de threads de trabalho baixo.
Para compilar um aplicativo que usa essa função, defina _WIN32_WINNT como 0x0500 ou posterior. Para obter mais informações, consulte Usando os cabeçalhos do Windows.
Exemplos
Para obter um exemplo que usa CreateTimerQueueTimer, confira Usando filas de temporizador.
Requisitos
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte | Windows XP [somente aplicativos da área de trabalho] |
| Servidor mínimo com suporte | Windows Server 2003 [somente aplicativos da área de trabalho] |
| Plataforma de Destino | Windows |
| Cabeçalho | threadpoollegacyapiset.h |
| Biblioteca | Kernel32.lib |
| DLL | Kernel32.dll |