NdisSetCoalescableTimerObject, fonction (ndis.h)

Article
08/07/2023

La fonction NdisSetCoalescableTimerObject définit un objet de minuteur que le système d’exploitation coordonne avec d’autres minuteurs, généralement pour réduire la consommation d’énergie, lorsque l’expiration exacte du minuteur n’est pas importante pour le fonctionnement du pilote.

Syntaxe

BOOLEAN NdisSetCoalescableTimerObject(
  [in]           NDIS_HANDLE   TimerObject,
  [in]           LARGE_INTEGER DueTime,
  [in, optional] LONG          MillisecondsPeriod,
  [in, optional] PVOID         FunctionContext,
  [in, optional] ULONG         Tolerance
);

Paramètres

[in] TimerObject

Handle d’un objet de minuteur fourni par NDIS lorsqu’un pilote appelle le Fonction NdisAllocateTimerObject .

[in] DueTime

Heure absolue ou relative à laquelle le minuteur expire. Si la valeur du paramètre DueTime est négative, le délai d’expiration est relatif à l’heure système actuelle. Sinon, le délai d’expiration est absolu. Le temps d’expiration est exprimé en unités de temps système (intervalles de 100 nanosecondes). Les temps d’expiration absolus suivent les modifications apportées à l’heure système ; les temps d’expiration relatifs ne sont pas affectés par les changements d’heure système.

[in, optional] MillisecondsPeriod

Intervalle de temps périodique facultatif, en millisecondes, qui s’écoule entre chaque instance lorsque le minuteur se déclenche et l’appel suivant à la fonction NetTimerCallback, sauf si le minuteur est annulé. La valeur de ce paramètre doit être inférieure ou égale à MAXLONG. Ce paramètre peut être défini sur zéro pour indiquer que le minuteur n’est pas périodique.

[in, optional] FunctionContext

Pointeur vers une zone de contexte fournie par l’appelant que NDIS transmet à la fonction NetTimerCallback associée lorsqu’un minuteur se déclenche. Si ce paramètre a la valeur NULL, NDIS utilise la valeur par défaut spécifiée dans le NDIS_TIMER_CHARACTERISTICS structure.

[in, optional] Tolerance

Tolérance, en millisecondes, entre la période du minuteur spécifiée par MillisecondsPeriod et l’intervalle de temps initial spécifié par DueTime . Un minuteur périodique expire d’abord dans l’intervalle de temps entre ( Tolérance DueTime - ) et (Tolérance DueTime + ). L’intervalle de temps entre deux expirations ultérieures d’un minuteur périodique est compris entre ( MillisecondsPeriod - Tolerance ) et ( MillisecondsPeriod + Tolerance ).

Valeur retournée

NdisSetCoalescableTimerObject retourne TRUE si l’objet du minuteur se trouvait déjà dans la file d’attente du minuteur système ; sinon, elle retourne FALSE.

Remarques

Un objet de minuteur défini par cette fonction fonctionne comme un minuteur défini par NdisSetTimerObject, avec une valeur de tolérance supplémentaire ajoutée au paramètre d’expiration DueTime . Le système d’exploitation utilise cette valeur de tolérance supplémentaire pour ajuster le délai d’expiration du minuteur afin qu’il coïncide avec l’expiration d’autres minuteurs logiciels. Ce faisant, le système d’exploitation peut réduire la consommation d’énergie et améliorer l’efficacité énergétique.

NdisSetTimerObject fonctionne de la même façon que NdisSetCoalescableTimerObject lorsque Tolerance est défini sur zéro.

Après qu’un pilote a appelé NdisSetCoalescableTimerObject, l’objet minuteur est mis en file d’attente jusqu’à l’expiration d’un intervalle qui se trouve dans la plage de ( Tolérance DueTime - ) et (Tolérance DueTime + ). Une fois l’intervalle expiré, le système d’exploitation supprime l’objet minuteur de la file d’attente, et la fonction NetTimerCallback fournie par l’appelant est exécutée une seule fois dans IRQL = DISPATCH_LEVEL dès qu’un processeur devient disponible.

Si une valeur différente de zéro est spécifiée dans le paramètre MillisecondsPeriod , l’objet minuteur est à nouveau mis en file d’attente jusqu’à ce qu’un intervalle dans la plage de ( MillisecondsPeriod - Tolerance ) et ( MillisecondsPeriod + Tolerance ) expire. Une fois cet intervalle expiré, l’objet du minuteur est à nouveau soumis à la file d’attente et la fonction NetTimerCallback fournie par l’appelant est exécutée une seule fois dans IRQL = DISPATCH_LEVEL dès qu’un processeur est disponible.

Pour utiliser efficacement la fusion du minuteur, un appelant doit spécifier une valeur de tolérance d’au moins 32 millisecondes. Cette valeur est égale à environ deux intervalles d’horloge système par défaut de 15,6 millisecondes. Utilisez une valeur de tolérance supérieure si vous pouvez le faire, par exemple 100 millisecondes.

Nous vous recommandons de définir MillisecondsPeriod et Tolerance sur des multiples de 50 millisecondes. Les valeurs typiques millisecondesPeriod sont 50, 100, 250, 500 et 1 000 millisecondes. Les valeurs de tolérance standard sont 50, 100, 150 et 250 millisecondes.

En règle générale, un minuteur avec une valeur millisecondesPeriod élevée peut utiliser une valeur de tolérance proportionnellement grande. Par exemple, un minuteur avec MillisecondsPeriod = 500 millisecondes peut utiliser Tolerance = 50 millisecondes. Toutefois, un minuteur avec MillisecondsPeriod = 10 secondes peut utiliser Tolerance = 1 seconde.

Pour plus d’informations sur le comportement du minuteur, consultez KeSetTimerEx.

Pour annuler un minuteur, appelez la fonction NdisCancelTimerObject .

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Pris en charge dans NDIS 6.20 et versions ultérieures.
Plateforme cible	Universal
En-tête	ndis.h (inclure Ndis.h)
Bibliothèque	Ndis.lib
IRQL	<= DISPATCH_LEVEL