Funzione SetCoalescableTimer (winuser.h)

Crea un timer con il valore di timeout specificato e il ritardo di tolleranza di unione.

Sintassi

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

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 del timer. Se il parametro hWnd è NULL e nIDEvent non corrisponde a un timer esistente, nIDEvent 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 SetCoalescableTimer 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.

Se la somma di uElapse e uToleranceDelay supera USER_TIMER_MAXIMUM, si verifica un'eccezione ERROR_INVALID_PARAMETER.

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

[in] uToleranceDelay

Tipo: ULONG

Può essere uno dei valori seguenti:

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 , la routine della finestra predefinita chiama la funzione di callback quando elabora WM_TIMER. 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.

Quando uToleranceDelay è impostato su 0, viene usata la unione del timer predefinita del sistema e SetCoalescableTimer si comporta come SetTimer.

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

Requisiti

Vedi anche

Esempio di timer di unione

Informazioni concettuali

KeSetCoalescableTimer

KeSetTimer

KillTimer

MSG

Riferimento

Esempio

SetTimer

TimerProc

Timer

Uso dei timer

WM_TIMER