Funzione SetTimer (winuser.h)

Articolo
04/06/2023

Crea un timer con il valore di timeout specificato.

Sintassi

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

Parametri

[in, optional] hWnd

Tipo: HWND

Handle della finestra da associare al timer. Questa finestra deve essere di proprietà del thread chiamante. Se viene passato un valore NULL per hWnd insieme a un nIDEvent di un timer esistente, tale timer verrà sostituito nello stesso modo in cui sarà presente un timer hWnd non NULL esistente.

[in] nIDEvent

Tipo: UINT_PTR

Identificatore timer diverso da zero. Se il parametro hWnd è NULL e nIDEvent non corrisponde a un timer esistente, viene ignorato e viene generato un nuovo ID timer. Se il parametro hWnd non è NULL e la finestra specificata da hWnd ha già un timer con il valore nIDEvent, il timer esistente viene sostituito dal nuovo timer. Quando SetTimer sostituisce un timer, il timer viene reimpostato. Pertanto, un messaggio verrà inviato dopo la scadenza del valore di timeout corrente, ma il valore di timeout impostato in precedenza viene ignorato. Se la chiamata non deve sostituire un timer esistente, nIDEvent deve essere 0 se hWnd è NULL.

[in] uElapse

Tipo: UINT

Il valore di timeout in millisecondi.

Se uElapse è minore di USER_TIMER_MINIMUM (0x0000000A), il timeout viene impostato su USER_TIMER_MINIMUM. Se uElapse è maggiore di USER_TIMER_MAXIMUM (0x7FFFFFFF), il timeout viene impostato su USER_TIMER_MAXIMUM.

[in, optional] lpTimerFunc

Tipo: TIMERPROC

Puntatore alla funzione da notificare quando scade il valore di timeout. Per altre informazioni sulla funzione, vedere TimerProc. Se lpTimerFunc è NULL, il sistema invia un messaggio WM_TIMER alla coda dell'applicazione. Il membro hwnd della struttura MSG del messaggio contiene il valore del parametro hWnd .

Valore restituito

Tipo: UINT_PTR

Se la funzione ha esito positivo e il parametro hWnd è NULL, il valore restituito è un numero intero che identifica il nuovo timer. Un'applicazione può passare questo valore alla funzione KillTimer per eliminare definitivamente il timer.

Se la funzione ha esito positivo e il parametro hWnd non è NULL, il valore restituito è un numero intero diverso da zero. Un'applicazione può passare il valore del parametro nIDEvent alla funzione KillTimer per eliminare definitivamente il timer.

Se la funzione non riesce a creare un timer, il valore restituito è zero. Per informazioni dettagliate sull'errore, chiamare GetLastError.

Commenti

Un'applicazione può elaborare WM_TIMER messaggi includendo un'istruzione case WM_TIMER nella routine finestra o specificando una funzione di callback TimerProc durante la creazione del timer. Quando si specifica una funzione di callback TimerProc , DispatchMessage chiama la funzione di callback anziché chiamare la routine window quando elabora WM_TIMER con un lParam diverso da NULL. Pertanto, è necessario inviare messaggi nel thread chiamante, anche quando si usa TimerProc invece di elaborare WM_TIMER.

Il parametro wParam del messaggio WM_TIMER contiene il valore del parametro nIDEvent .

L'identificatore timer , nIDEvent, è specifico della finestra associata. Un'altra finestra può avere un proprio timer con lo stesso identificatore di un timer di proprietà di un'altra finestra. I timer sono distinti.

SetTimer può riutilizzare gli ID timer nel caso in cui hWnd sia NULL.

Prima di usare SetTimer o altre funzioni correlate al timer, è consigliabile impostare il flag di UOI_TIMERPROC_EXCEPTION_SUPPRESSION su false tramite la funzione SetUserObjectInformationW , altrimenti l'applicazione potrebbe comportarsi in modo imprevedibile e potrebbe essere vulnerabile agli exploit di sicurezza. Per altre info, vedi SetUserObjectInformationW.

Esempio

Per un esempio, vedere Creazione di un timer.

Requisiti

Requisito	Valore
Client minimo supportato	Windows 2000 Professional [solo app desktop]
Server minimo supportato	Windows 2000 Server [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	winuser.h (include Windows.h)
Libreria	User32.lib
DLL	User32.dll
Set di API	ext-ms-win-ntuser-window-l1-1-2 (introdotto in Windows 10 versione 10.0.10240)