SetTimer-Funktion (winuser.h)

Artikel
03/13/2024

Erstellt einen Timer mit dem angegebenen Timeoutwert.

Syntax

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

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 nichtzero-Timerbezeichner. Wenn der hWnd-ParameterNULL ist und das nIDEvent nicht mit einem vorhandenen Timer übereinstimmt, wird er ignoriert und eine neue Timer-ID 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 SetTimer 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.

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

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 dispatchMessage die Rückruffunktion auf, anstatt die Fensterprozedur aufzurufen, wenn sie WM_TIMER mit einem lParam ohne NULL 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.

Vor der Verwendung von SetTimer oder anderen Timer-bezogenen Funktionen wird empfohlen, 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.

Beispiele

Ein Beispiel finden Sie unter Erstellen eines Timers.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server [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)