SetWaitableTimerEx-Funktion (synchapi.h)

  • Artikel

Aktiviert den angegebenen wartebaren Timer und stellt Kontextinformationen für den Timer bereit. 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 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 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 Sicherheit und Zugriffsrechte für Synchronisierungsobjekte.

[in] lpDueTime

Die Zeit, nach der der Zustand des Timers in Intervallen von 100 Nanosekunden auf signalisiert festgelegt werden soll. Verwenden Sie das format, das von der FILETIME-Struktur beschrieben wird. 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 null ist, wird der Timer einmal signalisiert. Wenn lPeriod größer als 0 (null) 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 SetWaitableTimerEx zurückgesetzt wird. Wenn lPeriod kleiner als 0 (null) ist, schlägt die Funktion fehl.

[in] 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] lpArgToCompletionRoutine

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

[in] WakeContext

Zeiger 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 fehlerhaft ist, ist der Rückgabewert null. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Hinweise

Die SetWaitableTimerEx-Funktion ähnelt der SetWaitableTimer-Funktion , mit der Ausnahme, dass 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 zunächst inaktiv. Um einen Timer zu aktivieren, rufen Sie SetWaitableTimerEx auf. Wenn der Timer bereits aktiv ist, wenn Sie SetWaitableTimerEx aufrufen, wird der Timer beendet, dann wird er reaktiviert. Wenn Sie den Timer auf diese Weise beenden, wird der Zeitgeberzustand nicht auf signalisiert festgelegt, sodass Threads, die in einem Wartevorgang auf dem Timer blockiert sind, blockiert bleiben. Es werden jedoch alle ausstehenden Vervollständigungsroutinen abgebrochen.

Wenn die angegebene Fälligkeitszeit eintrifft, wird der Timer inaktiv, und der optionale APC wird in die Warteschlange des Threads eingereiht, der den Timer festlegt, wenn noch kein ausstehender APC in die Warteschlange eingereiht ist. Der Status des Timers wird 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 Signalisierungsmechanismen 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 zugeordnete 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, verbleibt er in diesem Zustand, bis SetWaitableTimerEx aufgerufen wird, um den Timer zurückzusetzen. Daher wird ein periodischer Timer für manuelles Zurücksetzen auf den signalierten Zustand festgelegt, wenn die anfängliche Fälligkeit eintrifft, und bleibt signalisiert, bis er zurückgesetzt wird. Wenn ein Synchronisierungszeitgeber auf den signalierten Zustand festgelegt ist, verbleibt 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.

Wenn der Thread, der SetWaitableTimerEx aufgerufen hat, beendet wird, wird der Timer abgebrochen. Dadurch wird der Timer beendet, bevor er auf den signalierten Zustand festgelegt werden kann, und ausstehende APCs werden abgebrochen. Der Signalzustand des Timers wird nicht geändert.

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

Anforderungen

   
Unterstützte Mindestversion (Client) Windows 7 [Desktop-Apps | UWP-Apps]
Unterstützte Mindestversion (Server) Windows Server 2008 R2 [Desktop-Apps | UWP-Apps]
Zielplattform Windows
Kopfzeile synchapi.h (windows.h einschließen)
Bibliothek Kernel32.lib
DLL Kernel32.dll

Siehe auch

REASON_CONTEXT

SetWaitableTimer