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 de TIMER_MODIFY_STATE correto. Para obter mais informações, consulte 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 FILETIME . Valores positivos indicam tempo absoluto. Certifique-se de usar um tempo absoluto baseado em UTC, pois o sistema usa o tempo baseado em UTC internamente. Valores negativos indicam tempo relativo. A precisão real do temporizador depende da capacidade do hardware. Para obter mais informações sobre a hora baseada em UTC, consulte Tempo do sistema.

[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 CancelWaitableTimer ou redefinido usando SetWaitableTimerEx. Se lPeriod for menor que zero, a função falhará.

[in] pfnCompletionRoutine

Um ponteiro para uma rotina de conclusão opcional. A rotina de conclusão é a 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 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

A função SetWaitableTimerEx é semelhante à função SetWaitableTimer , exceto que SetWaitableTimerEx pode ser usado para especificar uma cadeia de caracteres de contexto e um atraso tolerável para expiração do temporizador.

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 todas as rotinas de conclusão pendentes.

Quando o tempo de conclusão especificado chega, o temporizador fica inativo e o APC opcional é enfileirado para o thread que define o temporizador se não houver nenhum APC pendente já enfileirado. 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 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 ou outro mecanismo de sinalização baseado em APC, use um objeto de espera, como um temporizador criado com CreateThreadpoolTimer. Para E/S, use um objeto de conclusão de E/S criado com CreateThreadpoolIo ou uma estrutura OVERLAPPED baseada em hEvent em que o evento pode ser passado para a função SetThreadpoolWait.

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 rotina de conclusão, encerrar o thread não terá efeito no temporizador.

Quando um temporizador de redefinição manual é definido como o estado sinalizado, ele permanece nesse estado até SetWaitableTimerEx ser chamado para redefinir o temporizador. Como resultado, um temporizador periódico de redefinição manual é 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 qualquer temporizador absoluto pendente 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

Confira também

REASON_CONTEXT

SetWaitableTimer