SetWaitableTimerEx-Funktion (synchapi.h)
Aktiviert den angegebenen Wartezeitgeber und stellt Kontextinformationen für den Timer bereit. Wenn die Fälligkeitszeit eingeht, wird der Timer signalisiert, und der Thread, der den Timer festgelegt hat, ruft die optionale Abschlussroutine auf.
Syntax
BOOL SetWaitableTimerEx(
[in] HANDLE hTimer,
[in] const LARGE_INTEGER *lpDueTime,
[in] LONG lPeriod,
[in] PTIMERAPCROUTINE pfnCompletionRoutine,
[in] LPVOID lpArgToCompletionRoutine,
[in] PREASON_CONTEXT WakeContext,
[in] ULONG TolerableDelay
);
Parameter
[in] hTimer
Ein Handle für das Timerobjekt. Die CreateWaitableTimer- oder OpenWaitableTimer--Funktion gibt dieses Handle zurück.
Das Handle muss über das TIMER_MODIFY_STATE Zugriffsrecht verfügen. Weitere Informationen finden Sie unter Sync Object Security and Access Rights.
[in] lpDueTime
Die Zeit, nach der der Zustand des Timers in 100 Nanosekundenintervallen signalisiert werden soll. Verwenden Sie das von der FILETIME--Struktur beschriebene Format. Positive Werte geben absolute Zeit an. Achten Sie darauf, eine UTC-basierte absolute Zeit zu verwenden, da das System UTC-basierte Zeit intern verwendet. Negative Werte deuten auf relative Zeit hin. Die tatsächliche Zeitgebergenauigkeit hängt von der Funktion Ihrer Hardware ab. Weitere Informationen zur UTC-basierten Zeit finden Sie unter Systemzeit.
Windows XP, Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 und Windows Server 2008 R2: Wenn relative Zeit angegeben ist, enthält der Timer Zeitaufwand für Energiesparzustände. Beispielsweise wird der Timer weiter gezählt, während der Computer eingeschlafen ist.
Windows 8 und höher, Windows Server 2012 und höher: Wenn relative Zeit angegeben ist, enthält der Timer keine Zeit, die in Energiesparzuständen aufgewendet wurde. Beispielsweise wird der Timer nicht weiter gezählt, während der Computer eingeschlafen ist.
[in] lPeriod
Der Zeitraum des Zeitgebers in Millisekunden. Wenn lPeriod null 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 wird oder mithilfe SetWaitableTimerEx-zurückgesetzt wird. Wenn lPeriod- kleiner als 0 ist, schlägt die Funktion fehl.
[in] pfnCompletionRoutine
Ein Zeiger auf eine optionale Abschlussroutine. Die Abschlussroutine ist anwendungsdefinierte Funktion vom Typ PTIMERAPCROUTINE ausgeführt werden, wenn der Timer signalisiert wird. Weitere Informationen zur Timerrückruffunktion finden Sie unter TimerAPCProc. Weitere Informationen zu APCs und Threadpoolthreads finden Sie in den Hinweisen.
[in] lpArgToCompletionRoutine
Ein Zeiger auf eine Struktur, die an die Abschlussroutine übergeben wird.
[in] WakeContext
Zeigen Sie auf eine REASON_CONTEXT Struktur, die Kontextinformationen für den Timer enthält.
[in] TolerableDelay
Die tolerierbare Verzögerung für die Ablaufzeit in Millisekunden.
Rückgabewert
Wenn die Funktion erfolgreich ist, ist der Rückgabewert ungleich Null.
Wenn die Funktion fehlschlägt, ist der Rückgabewert null. Rufen Sie GetLastErrorauf, um erweiterte Fehlerinformationen zu erhalten.
Bemerkungen
Die SetWaitableTimerEx--Funktion ähnelt der SetWaitableTimer--Funktion, außer SetWaitableTimerEx- verwendet werden kann, um eine Kontextzeichenfolge und eine tolerierbare Verzögerung für den Ablauf des Timers anzugeben.
Um eine Anwendung zu kompilieren, die diese Funktion verwendet, definieren Sie _WIN32_WINNT als 0x0601 oder höher. Weitere Informationen finden Sie unter Verwenden der Windows-Header.
Timer sind anfänglich inaktiv. Rufen Sie zum Aktivieren eines Timers SetWaitableTimerEx-auf. Wenn der Timer bereits aktiv ist, wenn Sie SetWaitableTimerEx-aufrufen, wird der Timer beendet, dann wird er erneut aktiviert. Wenn der Timer auf diese Weise beendet wird, wird der Zeitgeberzustand nicht auf signalisiert festgelegt, sodass Threads, die in einem Wartevorgang für den Timer blockiert sind, blockiert bleiben. Allerdings werden alle ausstehenden Abschlussroutinen abgebrochen.
Wenn die angegebene Fälligkeitszeit eingeht, wird der Timer inaktiv, und der optionale APC wird an den Thread in die Warteschlange gestellt, der den Timer festlegt, wenn kein ausstehender APC bereits in die Warteschlange eingereiht ist. Der Zustand des Timers wird auf signalisiert, 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 genauso funktionieren wie andere Signalmechanismen für Threadpoolthreads, da das System die Lebensdauer von Threadpoolthreads steuert, sodass es möglich ist, dass ein Thread beendet werden kann, bevor die Benachrichtigung übermittelt wird. Anstatt den pfnCompletionRoutine Parameter oder einen anderen APC-basierten Signalisierungsmechanismus zu verwenden, verwenden Sie ein mit CreateThreadpoolTimererstelltes Zeitgeberobjekt. Verwenden Sie für E/A ein E/A-Vervollständigungsobjekt, das mit CreateThreadpoolIo oder einer hEvent--basierten OVERLAPPED- Struktur erstellt wird, in der das Ereignis an die SetThreadpoolWait--Funktion übergeben werden kann.
Wenn der Thread, der den Timer festgelegt hat, beendet wird und eine zugeordnete Abschlussroutine vorhanden ist, wird der Timer abgebrochen. Der Zustand des Timers bleibt jedoch unverändert. Wenn keine Abschlussroutine vorhanden ist, hat das Beenden des Threads keine Auswirkungen auf den Timer.
Wenn ein manuell zurückgesetzter Timer auf den signalgesteuerten Zustand festgelegt ist, verbleibt er in diesem Zustand, bis SetWaitableTimerEx- aufgerufen wird, um den Timer zurückzusetzen. Daher wird ein periodischer Zeitgeber für manuelles Zurücksetzen auf den signalgesteuerten Zustand festgelegt, wenn die anfängliche Fälligkeitszeit eingeht und bis zum Zurücksetzen signalisiert bleibt. Wenn ein Synchronisierungszeitgeber auf den signalisierten Zustand festgelegt ist, verbleibt er in diesem Zustand, bis ein Thread einen Wartezeitvorgang für das Timerobjekt abgeschlossen hat.
Wenn die Systemzeit angepasst wird, wird die Fälligkeitszeit aller ausstehenden absoluten Timer angepasst.
Wenn der Thread, der SetWaitableTimerEx aufgerufen wird, beendet wird, wird der Timer abgebrochen. Dadurch wird der Timer beendet, bevor er auf den signalierten Zustand festgelegt und ausstehende APCs abgebrochen werden kann. sie ändert nicht den signalierten Zustand des Timers.
Wenn Sie einen Timer verwenden möchten, um ein Ereignis für ein Fenster zu planen, verwenden Sie die SetTimer--Funktion.
Anforderungen
| Anforderung | Wert |
|---|---|
| mindestens unterstützte Client- | Windows 7 [Desktop-Apps | UWP-Apps] |
| mindestens unterstützte Server- | Windows Server 2008 R2 [Desktop-Apps | UWP-Apps] |
| Zielplattform- | Fenster |
| Header- | synchapi.h (enthalten Windows.h) |
| Library | Kernel32.lib |
| DLL- | Kernel32.dll |