structure WDF_TIMER_CONFIG (wdftimer.h)

Article
08/08/2023

[S’applique à KMDF et UMDF]

La structure WDF_TIMER_CONFIG contient des informations de configuration pour un objet de minuteur d’infrastructure.

Syntaxe

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;

Membres

Size

Taille, en octets, de cette structure.

EvtTimerFunc

Pointeur vers une fonction de rappel EvtTimerFunc fournie par le pilote ou NULL.

Period

Période, en millisecondes. L’infrastructure appelle la fonction de rappel EvtTimerFunc du pilote à plusieurs reprises, chaque fois que le nombre spécifié de millisecondes s’écoule. Si cette valeur est égale à zéro, l’infrastructure n’appelle pas la fonction de rappel EvtTimerFunc du pilote à plusieurs reprises. Au lieu de cela, il appelle la fonction de rappel une fois, une fois que la méthode WdfTimerStart est écoulée. (La période doit être égale à zéro si WdfTimerCreate définit le niveau d’exécution sur WdfExecutionLevelPassive.) La période ne peut pas être une valeur négative.

AutomaticSerialization

Valeur booléenne qui, si TRUE, indique que l’infrastructure synchronisera l’exécution de la fonction de rappel EvtTimerFunc de l’objet de minuteur avec les fonctions de rappel d’autres objets qui se trouvent sous l’objet d’appareil parent du minuteur. Pour plus d'informations, consultez la section Notes qui suit. Si la valeur est FALSE, l’infrastructure ne synchronise pas l’exécution de la fonction de rappel EvtTimerFunc .

TolerableDelay

Spécifie une tolérance, en millisecondes, pour la période du minuteur spécifiée par Period et pour l’intervalle de temps initial spécifié par la méthode WdfTimerStart. Pour un minuteur périodique, l’intervalle de temps entre deux expirations successives du minuteur est compris entre (Period - IntolérableDelay) et (Period + IntolérableDelay). L’heure d’expiration initiale est comprise entre DueTime et (DueTime + IntolérableDelay). La valeur TolerableDelay ne peut pas être négative.

Le membre TolerableDelay est disponible dans les versions 1.9 et ultérieures de KMDF.

À partir de Windows 8.1, dans un pilote utilisant au minimum KMDF 1.13 ou UMDF 2.0, vous pouvez définir ce membre sur IntolérableDelayUnlimited pour spécifier que le système ne doit pas être réveillé en raison de l’expiration de ce minuteur.

Si UseHighResolutionTimer est WdfTrue, vous devez définir IntolérableDelay sur zéro. Sinon, WdfTimerCreate retourne un code d’échec.

Pour plus d’informations sur ce membre, consultez la section Remarques suivante.

UseHighResolutionTimer

KMDF uniquement

Ce membre est disponible à partir de Windows 8.1 et KMDF version 1.13.

Valeur de type WDF_TRI_STATE. Si cette valeur est WdfTrue, l’infrastructure utilise un minuteur haute résolution qui a une précision d’une milliseconde. Si la valeur est WdfFalse ou WdfDefault, l’infrastructure utilise un minuteur standard qui a une précision correspondant à l’intervalle de graduation de l’horloge système, qui est par défaut de 15,6 millisecondes.

Avertissement Si vous définissez UseHighResolutionTimer sur WdfTrue, vous devez appeler WdfTimerStart avec le paramètre DueTime défini sur une valeur négative. Sinon, l’appel provoque le blocage du système.

Si UseHighResolutionTimer est WdfTrue, vous devez définir IntolérableDelay sur zéro. Sinon, WdfTimerCreate retourne un code d’échec.

Pour plus d’informations sur ce membre, consultez la section Remarques suivante.

Remarques

La structure WDF_TIMER_CONFIG est utilisée comme entrée dans la méthode WdfTimerCreate . Pour initialiser une structure de WDF_TIMER_CONFIG , votre pilote doit appeler WDF_TIMER_CONFIG_INIT ou WDF_TIMER_CONFIG_INIT_PERIODIC.

La définition du membre AutomaticSerialization de WDF_TIMER_CONFIG sur TRUE n’a aucun effet si l’étendue de synchronisation de l’objet parent est définie sur WdfSynchronizationScopeNone.

Si le niveau d’exécution de l’objet d’appareil parent est WdfExecutionLevelPassive, vous pouvez définir le membre AutomaticSerialization sur TRUE uniquement si l’objet minuteur représente un minuteur de niveau passif.

Si un pilote utilise le membre IntolérableDelay , le système d’exploitation peut regrouper les heures d’expiration qui sont proches les unes des autres et les traiter en même temps. Si le système d’exploitation peut gérer les expirations de plusieurs minuteurs à la fois, il peut potentiellement maintenir l’ordinateur dans un état de faible consommation pendant des périodes plus longues afin d’augmenter l’autonomie de la batterie.

Si le membre TolerableDelay est IntolérableDelayUnlimited, le système ne revient pas à son état complet sur (S0) pour traiter le minuteur s’il est dans un état de faible consommation (Sx) à l’expiration du minuteur. Un pilote peut spécifier IntolérableDelayUnlimited pour augmenter l’autonomie de la batterie lorsque le minuteur est lié à une opération périodique non critique.

La définition de UseHighResolutionTimer sur WdfTrue peut entraîner une diminution de l’autonomie de la batterie.

Pour plus d’informations sur l’automaticSérialisation et la synchronisation des fonctions de rappel de pilote, consultez Techniques de synchronisation pour les pilotes Framework-Based.

Pour plus d’informations sur les objets du minuteur d’infrastructure, consultez Utilisation des minuteurs.