SetWaitableTimer-Funktion (synchapi.h)
Aktiviert den angegebenen Wartezeitgeber. Wenn die Fälligkeitszeit eingeht, wird der Timer signalisiert, und der Thread, der den Timer festgelegt hat, ruft die optionale Abschlussroutine 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 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 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 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, optional] lpArgToCompletionRoutine
Ein Zeiger auf eine Struktur, die an die Abschlussroutine übergeben wird.
[in] fResume
Wenn dieser Parameter TRUEist, wird ein System im Energiesparmodus für angehaltene Energie wiederhergestellt, wenn der Zeitgeberzustand auf signalisiert wird. Andernfalls wird das System nicht wiederhergestellt. Wenn das System keine Wiederherstellung unterstützt, wird der Aufruf erfolgreich ausgeführt, aber GetLastError gibt ERROR_NOT_SUPPORTEDzurück.
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
Timer sind anfänglich inaktiv. Rufen Sie zum Aktivieren eines Timers SetWaitableTimer-auf. Wenn der Timer bereits aktiv ist, wenn Sie SetWaitableTimer-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 SetWaitableTimer- 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.
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 mit Zeitgebern umgehen, verwenden verschiedene Hardwareuhren. Diese Uhren unterscheiden sich möglicherweise erheblich von ihren Erwartungen: Einige können in Millisekunden gemessen werden (für diejenigen, die einen RTC-basierten Timerchip verwenden), zu denen in Nanosekunden gemessen wird (für diejenigen, die ACPI- oder TSC-Zähler verwenden). Sie können die Auflösung Ihrer API mit einem Aufruf der timeBeginPeriod- und timeEndPeriod--Funktionen ä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 Using Waitable Timer Objects.
Anforderungen
| Anforderung | Wert |
|---|---|
| mindestens unterstützte Client- | Windows XP [Desktop-Apps | UWP-Apps] |
| mindestens unterstützte Server- | Windows Server 2003 [Desktop-Apps | UWP-Apps] |
| Zielplattform- | Fenster |
| Header- | synchapi.h (enthalten Windows.h unter Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2) |
| Library | Kernel32.lib |
| DLL- | Kernel32.dll |