WdfTimerStart-Funktion (wdftimer.h)
[Gilt für KMDF und UMDF]
Die WdfTimerStart-Methode startet die Uhr eines Zeitgebers.
Syntax
BOOLEAN WdfTimerStart(
[in] WDFTIMER Timer,
[in] LONGLONG DueTime
);
Parameter
[in] Timer
Ein Handle für ein Framework-Timerobjekt, das durch Aufrufen von WdfTimerCreate abgerufen wurde.
[in] DueTime
Ein Zeitraum in Systemzeiteinheiten (Intervalle von 100 Nanosekunden). Das Framework ruft die EvtTimerFunc-Rückruffunktion des Treibers auf, wenn der angegebene Zeitraum abgelaufen ist. Der Zeitraumwert kann wie folgt negativ oder positiv sein:
- Wenn der Wert negativ ist, ist der Zeitraum relativ zur aktuellen Systemzeit.
- Wenn der Wert positiv ist, gibt der Zeitraum eine absolute Zeit an (die tatsächlich relativ zum 1. Januar 1601 ist).
Warnung
Wenn Sie das UseHighResolutionTimer-Element von WDF_TIMER_CONFIG auf WdfTrue festlegen, müssen Sie WdfTimerStart aufrufen, wobei der DueTime-Parameter auf einen negativen Wert festgelegt ist. Andernfalls führt der Aufruf zum Absturz des Systems.
Relative Zeiten werden nicht durch Änderungen an der Systemzeit beeinflusst, die innerhalb des angegebenen Zeitraums auftreten können. Absolute Zeiten spiegeln Systemzeitänderungen wider.
Das Framework stellt Zeitkonvertierungsfunktionen bereit, die Zeitwerte in Systemzeiteinheiten konvertieren.
Rückgabewert
WdfTimerStart gibt TRUE zurück, wenn sich das Timerobjekt in der Zeitgeberwarteschlange des Systems befand. Andernfalls gibt diese Methode FALSE zurück. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".
Eine Fehlerüberprüfung tritt auf, wenn der Treiber ein ungültiges Objekthandle bereitstellt.
Hinweise
Treiber müssen immer WdfTimerStart aufrufen, um einen Timer nach dessen Erstellung zu starten, unabhängig davon, ob der Timer ein regelmäßiger Timer ist oder nicht.
Nachdem ein Treiber WdfTimerStart aufgerufen hat, ruft das Framework die EvtTimerFunc-Rückruffunktion des Treibers auf, wenn die für den DueTime-Parameter angegebene Zeit verstrichen ist. Nach diesem ersten Aufruf ruft das Framework die Rückruffunktion jedes Mal auf, wenn der vom Period-Member der WDF_TIMER_CONFIG-Struktur des Treibers angegebene Zeitraum abgelaufen ist.
Der Ablauf des Timers hängt letztendlich von der Granularität der Systemuhr ab. Der für DueTime angegebene Wert garantiert, dass das Framework die EvtTimerFunc-Rückruffunktion des Treibers auf oder nach dem angegebenen DueTime aufruft. WdfTimerStart kann jedoch nicht die Granularität der Systemuhr außer Kraft setzen, unabhängig vom für DueTime angegebenen Wert.
Wenn ein Treiber WdfTimerStart aufruft, wird sein Timerobjekt der Warteschlange des Systems mit Timerobjekten hinzugefügt. Wenn der Timer kein periodischer Timer ist, entfernt das System das Timerobjekt aus der Warteschlange, nachdem die "Fälligkeitszeit" des Timers abgelaufen ist. Wenn der Timer ein regelmäßiger Timer ist, verbleibt das Timerobjekt in der Warteschlange, bis der Treiber WdfTimerStop aufruft.
Ein Treiber kann WdfTimerStart über seine EvtTimerFunc-Rückruffunktion aufrufen, um einen nicht periodischen Timer neu zu starten, nachdem er abläuft.
WdfTimerStart gibt TRUE zurück, wenn der Treiber zuvor WdfTimerStart aufgerufen hat und sich das Timerobjekt noch in der Warteschlange des Systems befindet, weil der Zeitraum nicht abgelaufen ist (oder weil es sich um einen regelmäßigen Timer handelt). Bevor WdfTimerStartTRUE zurückgibt, setzt das Betriebssystem den Zeitraum auf den Wert zurück, den der Treiber im neuen Aufruf von WdfTimerStart angegeben hat. Das Framework ruft die EvtTimerFunc-Rückruffunktion erst auf, wenn der neue Zeitraum abgelaufen ist.
Um die Zeitgeberuhr zu beenden, kann der Treiber WdfTimerStop aufrufen.
Weitere Informationen zu Framework-Timerobjekten finden Sie unter Verwenden von Timern.
Beispiele
Im folgenden Codebeispiel wird ein Timer gestartet. Das Framework ruft die EvtTimerFunc-Rückruffunktion des Zeitgebers nach 10 Millisekunden auf.
BOOLEAN inTimerQueue;
inTimerQueue = WdfTimerStart(
timerHandle,
WDF_REL_TIMEOUT_IN_MS(10)
);
Anforderungen
| Anforderung | Wert |
|---|---|
| Zielplattform | Universell |
| KMDF-Mindestversion | 1.0 |
| UMDF-Mindestversion | 2.0 |
| Kopfzeile | wdftimer.h (include Wdf.h) |
| Bibliothek | Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF) |
| IRQL | <=DISPATCH_LEVEL |
| DDI-Complianceregeln | DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf) |