Funzione SetCoalescableTimer (winuser.h)

Articolo
08/28/2023

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	Significato
TIMERV_DEFAULT_COALESCING 0x00000000	Usa l'unione del timer predefinito del sistema.
TIMERV_NO_COALESCING 0xffffffff	Non viene utilizzata alcuna unione timer. Quando si usa questo valore, il timer creato non viene unito, indipendentemente dal fatto che l'unione del timer predefinito del sistema sia o i flag di compatibilità dell'applicazione. Nota Non utilizzare questo valore, a meno che non si sia certi che il timer non richieda alcuna unione.
0x1 - 0x7FFFFFF5	Specifica il ritardo di tolleranza di unione, espresso in millisecondi. Le applicazioni devono impostare questo valore sul valore predefinito del sistema (TIMERV_DEFAULT_COALESCING) o sul valore più grande possibile. Se la somma di uElapse e uToleranceDelay supera USER_TIMER_MAXIMUM (0x7FFFFFFF), si verifica un'eccezione ERROR_INVALID_PARAMETER. Per altri dettagli e procedure consigliate, vedi Unione timer di Windows .
Qualsiasi altro valore	Valore non valido. Se uToleranceDelay è impostato su un valore non valido, la funzione ha esito negativo e restituisce zero.

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


Client minimo supportato	Windows 8 [solo app desktop]
Server minimo supportato	Windows Server 2012 [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)