Função SetCoalescableTimer (winuser.h)

Cria um temporizador com o valor de tempo limite especificado e o atraso de tolerância de união.

Sintaxe

UINT_PTR SetCoalescableTimer(
  [in, optional] HWND      hWnd,
  [in]           UINT_PTR  nIDEvent,
  [in]           UINT      uElapse,
  [in, optional] TIMERPROC lpTimerFunc,
  [in]           ULONG     uToleranceDelay
);

Parâmetros

[in, optional] hWnd

Digite: HWND

Um identificador para a janela a ser associada ao temporizador. Essa janela deve pertencer ao thread de chamada. Se um valor NULL para hWnd for passado junto com um nIDEvent de um temporizador existente, esse temporizador será substituído da mesma forma que um temporizador hWnd não NULL existente.

[in] nIDEvent

Tipo: UINT_PTR

Um identificador de temporizador. Se o parâmetro hWnd for NULL e o nIDEvent não corresponder a um temporizador existente, o nIDEvent será ignorado e uma nova ID de temporizador será gerada. Se o parâmetro hWnd não for NULL e a janela especificada por hWnd já tiver um temporizador com o valor nIDEvent, o temporizador existente será substituído pelo novo temporizador. Quando SetCoalescableTimer substitui um temporizador, o temporizador é redefinido. Portanto, uma mensagem será enviada após o decorrido do valor de tempo limite atual, mas o valor de tempo limite definido anteriormente é ignorado. Se a chamada não for destinada a substituir um temporizador existente, nIDEvent deverá ser 0 se o hWnd for NULL.

[in] uElapse

Tipo: UINT

O valor de tempo limite, em milissegundos.

Se uElapse for menor que USER_TIMER_MINIMUM (0x0000000A), o tempo limite será definido como USER_TIMER_MINIMUM. Se uElapse for maior que USER_TIMER_MAXIMUM (0x7FFFFFFF), o tempo limite será definido como USER_TIMER_MAXIMUM.

Se a soma de uElapse e uToleranceDelay exceder USER_TIMER_MAXIMUM, ocorrerá uma exceção ERROR_INVALID_PARAMETER.

[in, optional] lpTimerFunc

Tipo: TIMERPROC

Um ponteiro para a função a ser notificada quando o valor de tempo limite decorrer. Para obter mais informações sobre a função, consulte TimerProc. Se lpTimerFunc for NULL, o sistema postará uma mensagem WM_TIMER na fila do aplicativo. O membro hwnd da estrutura MSG da mensagem contém o valor do parâmetro hWnd .

[in] uToleranceDelay

Tipo: ULONG

Pode ser um dos seguintes valores:

Valor retornado

Tipo: UINT_PTR

Se a função for bem-sucedida e o parâmetro hWnd for NULL, o valor retornado será um inteiro que identifica o novo temporizador. Um aplicativo pode passar esse valor para a função KillTimer para destruir o temporizador.

Se a função for bem-sucedida e o parâmetro hWnd não for NULL, o valor retornado será um inteiro diferente de zero. Um aplicativo pode passar o valor do parâmetro nIDEvent para a função KillTimer para destruir o temporizador.

Se a função não criar um temporizador, o valor retornado será zero. Para obter informações de erro estendidas, chame GetLastError.

Comentários

Um aplicativo pode processar mensagens WM_TIMER incluindo uma instrução case WM_TIMER no procedimento de janela ou especificando uma função de retorno de chamada TimerProc ao criar o temporizador. Quando você especifica uma função de retorno de chamada TimerProc , o procedimento de janela padrão chama a função de retorno de chamada quando processa WM_TIMER. Portanto, você precisa expedir mensagens no thread de chamada, mesmo quando usa TimerProc em vez de processar WM_TIMER.

O parâmetro wParam da mensagem WM_TIMER contém o valor do parâmetro nIDEvent .

O identificador de temporizador, nIDEvent, é específico para a janela associada. Outra janela pode ter seu próprio temporizador que tem o mesmo identificador que um temporizador pertencente a outra janela. Os temporizadores são distintos.

SetTimer pode reutilizar IDs de temporizador no caso em que hWnd é NULL.

Quando uToleranceDelay é definido como 0, a união do temporizador padrão do sistema é usada e SetCoalescableTimer se comporta da mesma forma que SetTimer.

Antes de usar SetCoalescableTimer ou outras funções relacionadas ao temporizador, é recomendável definir o sinalizador UOI_TIMERPROC_EXCEPTION_SUPPRESSION como false por meio da função SetUserObjectInformationW , caso contrário, o aplicativo pode se comportar de forma imprevisível e pode estar vulnerável a explorações de segurança. Para obter mais informações, consulte SetUserObjectInformationW.

Requisitos

Confira também

Amostra de temporizadores de união

Conceitual

KeSetCoalescableTimer

KeSetTimer

Killtimer

MSG

Referência

Amostra

Settimer

Timerproc

Temporizadores

Usando temporizadores

WM_TIMER