Função SetWaitableTimerEx (synchapi.h)
Ativa o temporizador de espera especificado e fornece informações de contexto para o temporizador. Quando o tempo de conclusão chega, o temporizador é sinalizado e o thread que define o temporizador chama a rotina de conclusão opcional.
Sintaxe
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
Um identificador para o objeto de temporizador. A função CreateWaitableTimer ou OpenWaitableTimer retorna esse identificador.
O identificador deve ter o acesso TIMER_MODIFY_STATE correto. Para obter mais informações, consulte de Segurança do Objeto de Sincronização e Direitos de Acesso.
[in] lpDueTime
O tempo após o qual o estado do temporizador deve ser definido como sinalizado, em intervalos de 100 nanossegundos. Use o formato descrito pela estrutura de
Windows XP, Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 e Windows Server 2008 R2: Se o tempo relativo for especificado, o temporizador incluirá o tempo gasto em estados de baixa potência. Por exemplo, o temporizador continua em contagem regressiva enquanto o computador está dormindo.
Windows 8 e mais recente, Windows Server 2012 e mais recente: Se o tempo relativo for especificado, o temporizador não inclui o tempo gasto em estados de baixa potência. Por exemplo, o temporizador não continua a contagem regressiva enquanto o computador está dormindo.
[in] lPeriod
O período do temporizador, em milissegundos. Se lPeriod for zero, o temporizador será sinalizado uma vez. Se lPeriod 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 usando a função
[in] pfnCompletionRoutine
Um ponteiro para uma rotina de conclusão opcional. A rotina de conclusão é uma função definida pelo aplicativo do tipo PTIMERAPCROUTINE a ser executada quando o temporizador é sinalizado. Para obter mais informações sobre a função de retorno de chamada do temporizador, consulte TimerAPCProc. Para obter mais informações sobre APCs e threads do pool de threads, consulte Comentários.
[in] lpArgToCompletionRoutine
Um ponteiro para uma estrutura que é passada para a rotina de conclusão.
[in] WakeContext
Ponteiro para uma estrutura REASON_CONTEXT que contém informações de contexto para o temporizador.
[in] TolerableDelay
O atraso tolerável para o tempo de expiração, em milissegundos.
Valor de retorno
Se a função for bem-sucedida, o valor retornado não será zero.
Se a função falhar, o valor retornado será zero. Para obter informações de erro estendidas, chame GetLastError.
Observações
A função
Para compilar um aplicativo que usa essa função, defina _WIN32_WINNT como 0x0601 ou posterior. Para obter mais informações, consulte Usando os cabeçalhos do Windows.
Os temporizadores são inicialmente inativos. Para ativar um temporizador, chame SetWaitableTimerEx. Se o temporizador já estiver ativo quando você chamar SetWaitableTimerEx, o temporizador será interrompido e ele será reativado. Parar o temporizador dessa maneira não define o estado do temporizador como sinalizado, portanto, os threads bloqueados em uma operação de espera no temporizador permanecem bloqueados. No entanto, ele cancela qualquer rotina de conclusão pendente.
Quando o tempo de conclusão especificado chega, o temporizador fica inativo e o APC opcional é enfileirado no thread que define o temporizador se não houver nenhum APC pendente já na fila.
O estado do temporizador é definido como sinalizado, o temporizador é reativado usando o período especificado e o thread que define o temporizador chama a rotina de conclusão quando ele entra em um estado de espera alertável.
Para obter mais informações, consulte QueueUserAPC. Observe que as APCs não funcionam tão bem quanto outros mecanismos de sinalização para threads de pool de threads porque o sistema controla o tempo de vida dos threads do pool de threads, portanto, é possível que um thread seja encerrado antes que a notificação seja entregue. Em vez de usar o parâmetro pfnCompletionRoutine
Se o thread que define o temporizador for encerrado e houver uma rotina de conclusão associada, o temporizador será cancelado. No entanto, o estado do temporizador permanece inalterado. Se não houver nenhuma rotina de conclusão, a terminação do thread não terá efeito no temporizador.
Quando um temporizador de redefinição manual é definido como o estado sinalizado, ele permanece nesse estado até que SetWaitableTimerEx seja chamado para redefinir o temporizador. Como resultado, um temporizador de redefinição manual periódico é definido como o estado sinalizado quando o tempo de conclusão inicial chega e permanece sinalizado até que seja redefinido. Quando um temporizador de sincronização é definido como o estado sinalizado, ele permanece nesse estado até que um thread conclua uma operação de espera no objeto de temporizador.
Se o tempo do sistema for ajustado, o tempo de conclusão de todos os temporizadores absolutos pendentes será ajustado.
Se o thread chamado SetWaitableTimerEx for encerrado, o temporizador será cancelado. Isso interrompe o temporizador antes que ele possa ser definido como o estado sinalizado e cancela APCs pendentes; ele não altera o estado sinalizado do temporizador.
Para usar um temporizador para agendar um evento para uma janela, use a função SetTimer.
Requisitos
| Requisito | Valor |
|---|---|
| de cliente com suporte mínimo | Windows 7 [aplicativos da área de trabalho | Aplicativos UWP] |
| servidor com suporte mínimo | Windows Server 2008 R2 [aplicativos da área de trabalho | Aplicativos UWP] |
| da Plataforma de Destino |
Windows |
| cabeçalho | synchapi.h (inclua Windows.h) |
| biblioteca | Kernel32.lib |
| de DLL |
Kernel32.dll |