Função SetCoalescableTimer (winuser.h)

Artigo
08/28/2023

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	Significado
TIMERV_DEFAULT_COALESCING 0x00000000	Usa a união de temporizador padrão do sistema.
TIMERV_NO_COALESCING 0xFFFFFFFF	Não usa nenhuma união de temporizador. Quando esse valor é usado, o temporizador criado não é unido, não importa qual seja a união do temporizador padrão do sistema ou os sinalizadores de compatibilidade do aplicativo. Nota Não use esse valor, a menos que você tenha certeza de que o temporizador não requer nenhuma união.
0x1 - 0x7FFFFFF5	Especifica o atraso de tolerância de união, em milissegundos. Os aplicativos devem definir esse valor como o padrão do sistema (TIMERV_DEFAULT_COALESCING) ou o maior valor possível. Se a soma de uElapse e uToleranceDelay exceder USER_TIMER_MAXIMUM (0x7FFFFFFF), ocorrerá uma exceção ERROR_INVALID_PARAMETER. Confira União de Temporizador do Windows para obter mais detalhes e melhores práticas.
Qualquer outro valor	Um valor inválido. Se uToleranceDelay for definido como um valor inválido, a função falhará e retornará zero.

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


Cliente mínimo com suporte	Windows 8 [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2012 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	winuser.h (inclua Windows.h)
Biblioteca	User32.lib
DLL	User32.dll
Conjunto de APIs	ext-ms-win-ntuser-window-l1-1-2 (introduzido no Windows 10, versão 10.0.10240)