WDF_TIMER_CONFIG-Struktur (wdftimer.h)

Artikel
08/08/2023

[Gilt für KMDF und UMDF]

Die WDF_TIMER_CONFIG-Struktur enthält Konfigurationsinformationen für ein Framework-Timerobjekt.

Syntax

typedef struct _WDF_TIMER_CONFIG {
  ULONG         Size;
  PFN_WDF_TIMER EvtTimerFunc;
  ULONG         Period;
  BOOLEAN       AutomaticSerialization;
  ULONG         TolerableDelay;
  BOOLEAN       UseHighResolutionTimer;
} WDF_TIMER_CONFIG, *PWDF_TIMER_CONFIG;

Member

Size

Die Größe (in Bytes) dieser Struktur.

EvtTimerFunc

Ein Zeiger auf eine vom Treiber bereitgestellte EvtTimerFunc-Rückruffunktion oder NULL.

Period

Ein Zeitraum in Millisekunden. Das Framework ruft die EvtTimerFunc-Rückruffunktion des Treibers wiederholt auf, wenn die angegebene Anzahl von Millisekunden abläuft. Wenn dieser Wert 0 ist, ruft das Framework die EvtTimerFunc-Rückruffunktion des Treibers nicht wiederholt auf. Stattdessen wird die Rückruffunktion einmal aufgerufen, nachdem die DueTime-Methode der WdfTimerStart-Methode abgelaufen ist. (Der Zeitraum muss null sein, wenn WdfTimerCreate die Ausführungsebene auf WdfExecutionLevelPassive festlegt.) Der Zeitraum darf kein negativer Wert sein.

AutomaticSerialization

Ein boolescher Wert, der bei TRUE angibt, dass das Framework die Ausführung der EvtTimerFunc-Rückruffunktion des Zeitgeberobjekts mit Rückruffunktionen von anderen Objekten synchronisiert, die sich unterhalb des übergeordneten Geräteobjekts des Timers befinden. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise". Bei FALSE synchronisiert das Framework die Ausführung der EvtTimerFunc-Rückruffunktion nicht.

TolerableDelay

Gibt eine Toleranz in Millisekunden für den Zeitgeberzeitraum an, den Period angibt, und für das anfängliche Zeitintervall, das die DueTime-Methode der WdfTimerStart-Methode angibt. Bei einem periodischen Timer liegt das Zeitintervall zwischen zwei aufeinander folgenden Timerablaufzeiten im Bereich von (Period - TolerableDelay) bis (Period + TolerableDelay). Die anfängliche Ablaufzeit liegt im Bereich von DueTime bis (DueTime + TolerableDelay). Der TolerableDelay-Wert darf nicht negativ sein.

Das TolerableDelay-Element ist in Version 1.9 und höheren Versionen von KMDF verfügbar.

Ab Windows 8.1 können Sie in einem Treiber, der mindestens KMDF 1.13 oder UMDF 2.0 verwendet, diesen Member auf TolerableDelayUnlimited festlegen, um anzugeben, dass das System aufgrund des Ablaufs dieses Timers nicht aktiviert werden soll.

Wenn UseHighResolutionTimerauf WdfTrue festgelegt ist, müssen Sie TolerableDelay auf null festlegen. Andernfalls gibt WdfTimerCreate einen Fehlercode zurück.

Weitere Informationen zu diesem Member finden Sie im folgenden Abschnitt hinweise.

UseHighResolutionTimer

nur KMDF

Dieser Member ist ab version 1.13 Windows 8.1 und KMDF verfügbar.

Ein WDF_TRI_STATE typisierter Wert. Wenn dieser Wert WdfTrue ist, verwendet das Framework einen Timer mit hoher Auflösung mit einer Genauigkeit von einer Millisekunde. Wenn der Wert WdfFalse oder WdfDefault ist, verwendet das Framework einen Standardtimer, der eine Genauigkeit aufweist, die dem Tickintervall der Systemuhr entspricht, das standardmäßig 15,6 Millisekunden beträgt.

Warnung Wenn Sie UseHighResolutionTimer 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.

Wenn UseHighResolutionTimerauf WdfTrue festgelegt ist, müssen Sie TolerableDelay auf null festlegen. Andernfalls gibt WdfTimerCreate einen Fehlercode zurück.

Weitere Informationen zu diesem Member finden Sie im folgenden Abschnitt hinweise.

Hinweise

Die WDF_TIMER_CONFIG-Struktur wird als Eingabe für die WdfTimerCreate-Methode verwendet. Um eine WDF_TIMER_CONFIG-Struktur zu initialisieren, muss Ihr Treiber entweder WDF_TIMER_CONFIG_INIT oder WDF_TIMER_CONFIG_INIT_PERIODIC aufrufen.

Das Festlegen des AutomaticSerialization-Elements von WDF_TIMER_CONFIG auf TRUE hat keine Auswirkung, wenn der Synchronisierungsbereich des übergeordneten Objekts auf WdfSynchronizationScopeNone festgelegt ist.

Wenn die Ausführungsebene des übergeordneten Geräteobjekts WdfExecutionLevelPassive ist, können Sie den AutomaticSerialization-Member nur dann auf TRUE festlegen, wenn das Timerobjekt einen Timer auf passiver Ebene darstellt.

Wenn ein Treiber das TolerableDelay-Element verwendet, kann das Betriebssystem Ablaufzeiten gruppieren, die eng beieinander liegen, und sie alle gleichzeitig verarbeiten. Wenn das Betriebssystem die Ablaufzeiten mehrerer Timer gleichzeitig verarbeiten kann, kann es den Computer möglicherweise für längere Zeiträume in einem Energiesparzustand halten, um die Akkulaufzeit zu erhöhen.

Wenn der TolerableDelay-MemberTolerableDelayUnlimited ist, kehrt das System nicht in den Zustand vollständig on (S0) zurück, um den Timer zu bedienen, wenn er sich in einem Low-Power-Zustand (Sx) befindet, wenn der Timer abläuft. Ein Treiber kann TolerableDelayUnlimited angeben, um die Akkulaufzeit zu erhöhen, wenn der Timer im Zusammenhang mit einem nicht kritischen periodischen Betrieb steht.

Das Festlegen von UseHighResolutionTimer auf WdfTrue kann zu einer verringerten Akkulaufzeit führen.

Weitere Informationen zur AutomaticSerialisierung und zur Synchronisierung von Treiberrückruffunktionen finden Sie unter Synchronisierungstechniken für Framework-Based-Treiber.

Weitere Informationen zu Framework-Timerobjekten finden Sie unter Verwenden von Timern.