SetWaitableTimer-Funktion (synchapi.h)

Artikel
03/04/2024

Aktiviert den angegebenen wartebaren Timer. Wenn die fällige Zeit eintrifft, wird der Timer signalisiert, und der Thread, der den Timer festgelegt hat, ruft die optionale Vervollständigungsroutine auf.

Syntax

BOOL SetWaitableTimer(
  [in]           HANDLE              hTimer,
  [in]           const LARGE_INTEGER *lpDueTime,
  [in]           LONG                lPeriod,
  [in, optional] PTIMERAPCROUTINE    pfnCompletionRoutine,
  [in, optional] LPVOID              lpArgToCompletionRoutine,
  [in]           BOOL                fResume
);

Parameter

[in] hTimer

Ein Handle für das Timerobjekt. Die Funktion CreateWaitableTimer oder OpenWaitableTimer gibt dieses Handle zurück.

Das Handle muss über das zugriffsrecht TIMER_MODIFY_STATE verfügen. Weitere Informationen finden Sie unter Synchronisierungsobjektsicherheit und Zugriffsrechte.

[in] lpDueTime

Die Zeit, nach der der Zustand des Timers in Intervallen von 100 Nanosekunden auf signalisiert festgelegt werden soll. Verwenden Sie das von der FILETIME-Struktur beschriebene Format. Positive Werte geben die absolute Zeit an. Achten Sie darauf, eine UTC-basierte absolute Zeit zu verwenden, da das System intern UTC-basierte Zeit verwendet. Negative Werte geben die relative Zeit an. Die tatsächliche Timergenauigkeit hängt von der Funktionalität Ihrer Hardware ab. Weitere Informationen zur UTC-basierten Zeit finden Sie unter Systemzeit.

[in] lPeriod

Der Zeitraum des Timers in Millisekunden. Wenn lPeriod 0 ist, wird der Timer einmal signalisiert. Wenn lPeriod größer als 0 ist, ist der Timer periodisch. Ein periodischer Timer reaktiviert automatisch jedes Mal, wenn der Zeitraum verstrichen ist, bis der Timer mithilfe der CancelWaitableTimer-Funktion abgebrochen oder mit SetWaitableTimer zurückgesetzt wird. Wenn lPeriod kleiner als 0 ist, schlägt die Funktion fehl.

[in, optional] pfnCompletionRoutine

Ein Zeiger auf eine optionale Vervollständigungsroutine. Die Vervollständigungsroutine ist eine anwendungsdefinierte Funktion vom Typ PTIMERAPCROUTINE , die ausgeführt werden soll, wenn der Timer signalisiert wird. Weitere Informationen zur Timer-Rückruffunktion finden Sie unter TimerAPCProc. Weitere Informationen zu APCs und Threadpoolthreads finden Sie unter Hinweise.

[in, optional] lpArgToCompletionRoutine

Ein Zeiger auf eine Struktur, die an die Vervollständigungsroutine übergeben wird.

[in] fResume

Wenn dieser Parameter TRUE ist, stellt ein System im angehaltenen Energiesparmodus wieder her, wenn der Zeitgeberzustand auf Signal festgelegt ist. Andernfalls wird das System nicht wiederhergestellt. Wenn das System keine Wiederherstellung unterstützt, ist der Aufruf erfolgreich, aber GetLastError gibt ERROR_NOT_SUPPORTED zurück.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ungleich Null.

Wenn die Funktion fehlerhaft ist, ist der Rückgabewert null. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Hinweise

Timer sind zunächst inaktiv. Um einen Timer zu aktivieren, rufen Sie SetWaitableTimer auf. Wenn der Timer bereits aktiv ist, wenn Sie SetWaitableTimer aufrufen, wird der Timer beendet, dann wird er erneut aktiviert. Wenn Sie den Timer auf diese Weise beenden, wird der Timerstatus nicht auf signalisiert festgelegt, sodass Threads, die in einem Wartevorgang auf dem Timer blockiert sind, blockiert bleiben. Alle ausstehenden Vervollständigungsroutinen werden jedoch abgebrochen.

Wenn die angegebene Fälligkeit eintrifft, wird der Timer inaktiv, und der optionale APC wird in die Warteschlange für den Thread eingereiht, der den Timer festlegt, wenn bereits kein ausstehender APC in die Warteschlange eingereiht ist. Der Status des Timers ist auf signalisiert festgelegt, der Timer wird mithilfe des angegebenen Zeitraums reaktiviert, und der Thread, der den Timer festlegt, ruft die Abschlussroutine auf, wenn er in einen warnbaren Wartezustand wechselt. Weitere Informationen finden Sie unter QueueUserAPC. Beachten Sie, dass APCs nicht so gut funktionieren wie andere Signalmechanismen für Threadpoolthreads, da das System die Lebensdauer von Threadpoolthreads steuert, sodass es möglich ist, dass ein Thread beendet wird, bevor die Benachrichtigung übermittelt wird. Verwenden Sie anstelle des pfnCompletionRoutine-Parameters oder eines anderen APC-basierten Signalisierungsmechanismus ein wartebares Objekt, z. B. einen mit CreateThreadpoolTimer erstellten Timer. Verwenden Sie für E/A ein mit CreateThreadpoolIo erstelltes E/A-Vervollständigungsobjekt oder eine hEvent-basierteOVERLAPPED-Struktur , in der das Ereignis an die SetThreadpoolWait-Funktion übergeben werden kann.

Wenn der Thread, der den Timer festgelegt hat, beendet wird und eine zugehörige Vervollständigungsroutine vorhanden ist, wird der Timer abgebrochen. Der Zustand des Timers bleibt jedoch unverändert. Wenn keine Vervollständigungsroutine vorhanden ist, hat das Beenden des Threads keine Auswirkungen auf den Timer.

Wenn ein Timer für manuelles Zurücksetzen auf den Signalzustand festgelegt ist, bleibt er in diesem Zustand, bis SetWaitableTimer aufgerufen wird, um den Timer zurückzusetzen. Daher wird ein periodischer Timer für manuelles Zurücksetzen auf den Signalzustand festgelegt, wenn die anfängliche Fälligkeitszeit eintrifft, und bleibt signalisiert, bis er zurückgesetzt wird. Wenn ein Synchronisierungszeitgeber auf den signalierten Zustand festgelegt ist, bleibt er in diesem Zustand, bis ein Thread einen Wartevorgang für das Timerobjekt abgeschlossen hat.

Wenn die Systemzeit angepasst wird, wird die Fälligkeitszeit aller ausstehenden absoluten Timer angepasst.

Um eine Anwendung zu kompilieren, die diese Funktion verwendet, definieren Sie _WIN32_WINNT als 0x0400 oder höher. Weitere Informationen finden Sie unter Verwenden der Windows-Header.

Wenn Sie einen Timer verwenden möchten, um ein Ereignis für ein Fenster zu planen, verwenden Sie die SetTimer-Funktion .

APIs, die sich mit Timern befassen, verwenden verschiedene Hardwareuhren. Diese Uhren unterscheiden sich möglicherweise erheblich von den erwarteten Auflösungen: Einige werden möglicherweise in Millisekunden gemessen (für diejenigen, die einen RTC-basierten Timerchip verwenden), und diejenigen, die in Nanosekunden gemessen werden (für diejenigen, die ACPI- oder TSC-Zähler verwenden). Sie können die Auflösung Ihrer API mit einem Aufruf der Funktionen timeBeginPeriod und timeEndPeriod ändern. Wie präzise Sie die Auflösung ändern können, hängt davon ab, welche Hardwareuhr die jeweilige API verwendet. Weitere Informationen finden Sie in der Hardwaredokumentation.

Beispiele

Ein Beispiel, das SetWaitableTimer verwendet, finden Sie unter Verwenden von Wartezeitgeberobjekten.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows XP [Desktop-Apps \| UWP-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [Desktop-Apps \| UWP-Apps]
Zielplattform	Windows
Kopfzeile	synchapi.h (einschließlich Windows.h unter Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2)
Bibliothek	Kernel32.lib
DLL	Kernel32.dll