SetCoalescableTimer-Funktion (winuser.h)

Artikel
08/28/2023

Erstellt einen Timer mit dem angegebenen Timeoutwert und dem angegebenen Toleranzverzögerung.

Syntax

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

Parameter

[in, optional] hWnd

Typ: HWND

Ein Handle für das Fenster, das dem Timer zugeordnet werden soll. Dieses Fenster muss dem aufrufenden Thread gehören. Wenn ein NULL-Wert für hWnd zusammen mit einem nIDEvent eines vorhandenen Timers übergeben wird, wird dieser Timer auf die gleiche Weise wie ein vorhandener hWnd-Timer ohne NULL ersetzt.

[in] nIDEvent

Typ: UINT_PTR

Ein Timerbezeichner. Wenn der hWnd-ParameterNULL ist und das nIDEvent nicht mit einem vorhandenen Timer übereinstimmt, wird das nIDEvent ignoriert, und eine neue Timer-ID wird generiert. Wenn der hWnd-Parameter nicht NULL ist und das von hWnd angegebene Fenster bereits über einen Timer mit dem Wert nIDEvent verfügt, wird der vorhandene Timer durch den neuen Timer ersetzt. Wenn SetCoalescableTimer einen Timer ersetzt, wird der Timer zurückgesetzt. Daher wird eine Nachricht gesendet, nachdem der aktuelle Timeoutwert abgelaufen ist, aber der zuvor festgelegte Timeoutwert ignoriert wird. Wenn der Aufruf nicht zum Ersetzen eines vorhandenen Timers vorgesehen ist, sollte nIDEvent 0 sein, wenn der hWndNULL ist.

[in] uElapse

Typ: UINT

Der Timeoutwert in Millisekunden.

Wenn uElapse kleiner als USER_TIMER_MINIMUM (0x0000000A) ist, wird das Timeout auf USER_TIMER_MINIMUM festgelegt. Wenn uElapse größer als USER_TIMER_MAXIMUM (0x7FFFFFFF) ist, wird das Timeout auf USER_TIMER_MAXIMUM festgelegt.

Wenn die Summe von uElapse und uToleranceDelayUSER_TIMER_MAXIMUM überschreitet, tritt eine ERROR_INVALID_PARAMETER Ausnahme auf.

[in, optional] lpTimerFunc

Typ: TIMERPROC

Ein Zeiger auf die Funktion, die benachrichtigt werden soll, wenn der Timeoutwert verstrichen ist. Weitere Informationen zur Funktion finden Sie unter TimerProc. Wenn lpTimerFuncNULL ist, sendet das System eine WM_TIMER Nachricht an die Anwendungswarteschlange. Das hwnd-Element der MSG-Struktur der Nachricht enthält den Wert des hWnd-Parameters .

[in] uToleranceDelay

Typ: ULONG

Es kann sich um einen der folgenden Werte handeln:

Wert	Bedeutung
TIMERV_DEFAULT_COALESCING 0x00000000	Verwendet die Systemstandardtimer-Koalescing.
TIMERV_NO_COALESCING 0xFFFFFFFF	Verwendet keine Timer-Koalescierung. Wenn dieser Wert verwendet wird, wird der erstellte Timer nicht koalesciert, unabhängig davon, wie die Systemstandardzeitgeber-Koalescing ist oder wie die Anwendungskompatibilitätsflags aussehen. Hinweis Verwenden Sie diesen Wert nicht, es sei denn, Sie sind sicher, dass der Timer keine Zusammenführung erfordert.
0x1 – 0x7FFFFFF5	Gibt die Verzögerung der Koalescierungstoleranz in Millisekunden an. Anwendungen sollten diesen Wert auf den Systemstandard (TIMERV_DEFAULT_COALESCING) oder den größtmöglichen Wert festlegen. Wenn die Summe von uElapse und uToleranceDelayUSER_TIMER_MAXIMUM (0x7FFFFFFF) überschreitet, tritt eine ERROR_INVALID_PARAMETER Ausnahme auf. Weitere Informationen und bewährte Methoden finden Sie unter Windows Timer Coalescing .
Beliebige andere Werte	Ein ungültiger Wert. Wenn uToleranceDelay auf einen ungültigen Wert festgelegt ist, schlägt die Funktion fehl und gibt null zurück.

Rückgabewert

Typ: UINT_PTR

Wenn die Funktion erfolgreich ist und der hWnd-ParameterNULL ist, ist der Rückgabewert eine ganze Zahl, die den neuen Timer identifiziert. Eine Anwendung kann diesen Wert an die KillTimer-Funktion übergeben, um den Timer zu zerstören.

Wenn die Funktion erfolgreich ist und der hWnd-Parameter nicht NULL ist, ist der Rückgabewert eine ganze Zahl ohne Zero. Eine Anwendung kann den Wert des nIDEvent-Parameters an die KillTimer-Funktion übergeben, um den Timer zu zerstören.

Wenn die Funktion keinen Timer erstellt, ist der Rückgabewert 0. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Hinweise

Eine Anwendung kann WM_TIMER Nachrichten verarbeiten, indem sie eine WM_TIMER Case-Anweisung in die Fensterprozedur einschließt oder eine TimerProc-Rückruffunktion beim Erstellen des Timers angibt. Wenn Sie eine TimerProc-Rückruffunktion angeben, ruft die Standardfensterprozedur die Rückruffunktion auf, wenn sie WM_TIMER verarbeitet. Daher müssen Sie Nachrichten im aufrufenden Thread senden, auch wenn Sie TimerProc verwenden, anstatt WM_TIMER zu verarbeiten.

Der wParam-Parameter der WM_TIMER Nachricht enthält den Wert des nIDEvent-Parameters .

Der Timerbezeichner nIDEvent ist spezifisch für das zugeordnete Fenster. Ein anderes Fenster kann über einen eigenen Timer verfügen, der denselben Bezeichner wie ein Timer besitzt, der einem anderen Fenster gehört. Die Timer sind unterschiedlich.

SetTimer kann Timer-IDs wiederverwenden, wenn hWndNULL ist.

Wenn uToleranceDelay auf 0 festgelegt ist, wird die Systemstandardtimer-Koalescing verwendet, und SetCoalescableTimer verhält sich wie SetTimer.

Vor der Verwendung von SetCoalescableTimer oder anderen timerbezogenen Funktionen empfiehlt es sich, das UOI_TIMERPROC_EXCEPTION_SUPPRESSION-Flag über die SetUserObjectInformationW-Funktion auf false festzulegen. Andernfalls könnte sich die Anwendung unvorhersehbar verhalten und anfällig für Sicherheits exploits sein. Weitere Informationen finden Sie unter SetUserObjectInformationW.

Anforderungen


Unterstützte Mindestversion (Client)	Windows 8 [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2012 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	winuser.h (einschließlich Windows.h)
Bibliothek	User32.lib
DLL	User32.dll
APIs	ext-ms-win-ntuser-window-l1-1-2 (eingeführt in Windows 10, Version 10.0.10240)