Função SetWaitableTimer (synchapi.h)
Ativa o temporizador de espera especificado. 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 SetWaitableTimer(
[in] HANDLE hTimer,
[in] const LARGE_INTEGER *lpDueTime,
[in] LONG lPeriod,
[in, optional] PTIMERAPCROUTINE pfnCompletionRoutine,
[in, optional] LPVOID lpArgToCompletionRoutine,
[in] BOOL fResume
);
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, optional] 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, optional] lpArgToCompletionRoutine
Um ponteiro para uma estrutura que é passada para a rotina de conclusão.
[in] fResume
Se esse parâmetro for VERDADEIRO, restaurará um sistema no modo de conservação de energia suspenso quando o estado do temporizador estiver definido como sinalizado. Caso contrário, o sistema não será restaurado. Se o sistema não der suporte a uma restauração, a chamada será bem-sucedida, mas GetLastError retornará ERROR_NOT_SUPPORTED.
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
Os temporizadores são inicialmente inativos. Para ativar um temporizador, chame SetWaitableTimer. Se o temporizador já estiver ativo quando você chamar SetWaitableTimer, 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 SetWaitableTimer 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.
Para compilar um aplicativo que usa essa função, defina _WIN32_WINNT como 0x0400 ou posterior. Para obter mais informações, consulte Usando os cabeçalhos do Windows.
Para usar um temporizador para agendar um evento para uma janela, use a função SetTimer.
AS APIs que lidam com temporizadores usam vários relógios de hardware diferentes. Esses relógios podem ter resoluções significativamente diferentes do esperado: alguns podem ser medidos em milissegundos (para aqueles que usam um chip de temporizador baseado em RTC), para aqueles medidos em nanossegundos (para aqueles que usam contadores ACPI ou TSC). Você pode alterar a resolução da API com uma chamada para as funções timeBeginPeriod e timeEndPeriod. Quão preciso você pode alterar a resolução depende de qual relógio de hardware a API específica usa. Para obter mais informações, verifique a documentação do hardware.
Exemplos
Para obter um exemplo que usa SetWaitableTimer, consulte Usando objetos timer de espera.
Requisitos
| Requisito | Valor |
|---|---|
| de cliente com suporte mínimo | Windows XP [aplicativos da área de trabalho | Aplicativos UWP] |
| servidor com suporte mínimo | Windows Server 2003 [aplicativos da área de trabalho | Aplicativos UWP] |
| da Plataforma de Destino |
Windows |
| cabeçalho | synchapi.h (inclua Windows.h no Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2) |
| biblioteca | Kernel32.lib |
| de DLL |
Kernel32.dll |
Consulte também