Fonction WdfTimerStart (wdftimer.h)

Article
02/27/2024

[S’applique à KMDF et UMDF]

La méthode WdfTimerStart démarre l’horloge d’un minuteur.

Syntaxe

BOOLEAN WdfTimerStart(
  [in] WDFTIMER Timer,
  [in] LONGLONG DueTime
);

Paramètres

[in] Timer

Handle d’un objet de minuteur d’infrastructure obtenu en appelant WdfTimerCreate.

[in] DueTime

Période, en unités de temps système (intervalles de 100 nanosecondes). L’infrastructure appelle la fonction de rappel EvtTimerFunc du pilote lorsque la période spécifiée s’écoule. La valeur de la période peut être négative ou positive comme suit :

Si la valeur est négative, la période est relative à l’heure système actuelle.
Si la valeur est positive, la période spécifie une heure absolue (qui est en fait relative au 1er janvier 1601).

Avertissement

Si vous définissez le membre UseHighResolutionTimer de WDF_TIMER_CONFIG 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.

Les temps relatifs ne sont pas affectés par les modifications apportées à l’heure système qui peuvent se produire au cours de la période spécifiée. Les heures absolues reflètent les changements d’heure système.

L’infrastructure fournit des fonctions de conversion de temps qui convertissent des valeurs de temps en unités de temps système.

Valeur retournée

WdfTimerStart retourne TRUE si l’objet minuteur se trouvait dans la file d’attente du minuteur du système. Sinon, cette méthode retourne FALSE. Pour plus d'informations, consultez la section Notes qui suit.

Un bogue case activée se produit si le pilote fournit un handle d’objet non valide.

Remarques

Les pilotes doivent toujours appeler WdfTimerStart pour démarrer un minuteur après l’avoir créé, que le minuteur soit un minuteur périodique ou non.

Après qu’un pilote a appelé WdfTimerStart, l’infrastructure appelle la fonction de rappel EvtTimerFunc du pilote lorsque l’heure spécifiée pour le paramètre DueTime est écoulée. Après ce premier appel, l’infrastructure appelle la fonction de rappel chaque fois que la période spécifiée par le membre Period de la structure WDF_TIMER_CONFIG du pilote s’écoule.

L’expiration du minuteur dépend en fin de compte de la granularité de l’horloge système. La valeur spécifiée pour DueTime garantit que l’infrastructure appelle la fonction de rappel EvtTimerFunc du pilote sur ou après le DueTime donné. Toutefois, WdfTimerStart ne peut pas remplacer la granularité de l’horloge système, quelle que soit la valeur spécifiée pour DueTime.

Lorsqu’un pilote appelle WdfTimerStart, son objet minuteur est ajouté à la file d’attente d’objets du minuteur du système. Si le minuteur n’est pas un minuteur périodique, le système supprime l’objet minuteur de la file d’attente une fois que le « délai d’échéance » du minuteur est écoulé. Si le minuteur est un minuteur périodique, l’objet minuteur reste dans la file d’attente jusqu’à ce que le pilote appelle WdfTimerStop.

Un pilote peut appeler WdfTimerStart à partir de sa fonction de rappel EvtTimerFunc afin de redémarrer un minuteur non périodique après son expiration.

WdfTimerStart retourne TRUE si le pilote a précédemment appelé WdfTimerStart et que l’objet du minuteur se trouve toujours dans la file d’attente du système, car la période n’est pas écoulée (ou parce qu’il s’agit d’un minuteur périodique). Avant que WdfTimerStart retourne TRUE, le système d’exploitation réinitialise la période à la valeur spécifiée par le pilote dans le nouvel appel à WdfTimerStart. L’infrastructure appelle la fonction de rappel EvtTimerFunc uniquement après l’expiration de la nouvelle période.

Pour arrêter l’horloge du minuteur, le pilote peut appeler WdfTimerStop.

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

Exemples

L’exemple de code suivant démarre un minuteur. L’infrastructure appelle la fonction de rappel EvtTimerFunc du minuteur après 10 millisecondes.

BOOLEAN inTimerQueue;

inTimerQueue = WdfTimerStart(
                             timerHandle,
                             WDF_REL_TIMEOUT_IN_MS(10)
                             );

Configuration requise

Condition requise	Valeur
Plateforme cible	Universal
Version KMDF minimale	1.0
Version UMDF minimale	2.0
En-tête	wdftimer.h (inclure Wdf.h)
Bibliothèque	Wdf01000.sys (KMDF) ; WUDFx02000.dll (UMDF)
IRQL	<=DISPATCH_LEVEL
Règles de conformité DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

Voir aussi