Função SetTimer (winuser.h)

Artigo
03/13/2024

Cria um temporizador com o valor de tempo limite especificado.

Sintaxe

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

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 diferente de zero. Se o parâmetro hWnd for NULL e o nIDEvent não corresponder a um temporizador existente, ele 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 SetTimer 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.

[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 .

Retornar valor

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 DispatchMessage chama a função de retorno de chamada em vez de chamar o procedimento de janela quando processa WM_TIMER com um lParam não NULL. 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.

Antes de usar SetTimer 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.

Exemplos

Para obter um exemplo, consulte Criando um temporizador.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows 2000 Server [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)