NdisSetCoalescableTimerObject, fonction (ndis.h)
La fonction NdisSetCoalescableTimerObject définit un objet minuteur que le système d’exploitation coordonne avec d’autres minuteurs, généralement pour réduire la consommation d’alimentation, lorsque l’expiration exacte du minuteur n’est pas importante pour l’opération 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 vers un objet 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, l’heure d’expiration est relative à l’heure système actuelle. Sinon, le temps d’expiration est absolu. Le temps d’expiration est exprimé en unités de temps système (intervalles de 100 nanosecondes). Les heures d’expiration absolues suivent les modifications apportées à l’heure système ; les heures d’expiration relatives ne sont pas affectées par les modifications de temps 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 NetTimerCall back associée lorsqu’un minuteur se déclenche. Si ce paramètre est null, NDIS utilise la valeur par défaut spécifiée dans le structure NDIS_TIMER_CHARACTERISTICS.
[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 ( DueTime - Tolerance ) et ( DueTime + Tolerance ). L’intervalle de temps entre deux expirations ultérieures d’un minuteur périodique est compris entre ( MillisecondsPeriod - Tolerance ) et ( MillisecondsPeriod + Tolerance ).
Valeur de retour
NdisSetCoalescableTimerObject retourne TRUE si l’objet minuteur était déjà dans la file d’attente du minuteur système ; sinon, elle retourne FALSE.
Remarques
Un objet minuteur défini par cette fonction fonctionne de la même façon qu’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 temps d’expiration du minuteur pour coïncider avec l’expiration d’autres minuteurs logiciels. En procédant ainsi, 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 tolérance est définie sur zéro.
Une fois qu’un pilote appelle NdisSetCoalescableTimerObject, l’objet minuteur est mis en file d’attente jusqu’à l’expiration d’un intervalle qui se trouve dans la plage de ( DueTime - Tolerance) et ( DueTime + Tolerance). Une fois l’intervalle expiré, le système d’exploitation supprime l’objet du minuteur de la file d’attente et la fonction NetTimerCall back fournie par l’appelant est exécutée une fois à IRQL = DISPATCH_LEVEL dès qu’un processeur est 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 remis à la file d’attente, et la fonction NetTimerCall back fournie par l’appelant est exécutée une fois à IRQL = DISPATCH_LEVEL dès qu’un processeur est disponible.
Pour utiliser efficacement la fusion du minuteur, un appelant doit spécifier une valeur Tolerance 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 tolérance supérieure si vous pouvez le faire, par exemple 100 millisecondes.
Nous vous recommandons de définir MillisecondsPeriod et Tolérance sur plusieurs de 50 millisecondes. Les valeurs millisecondes standard sont 50, 100, 250, 500 et 1 000 millisecondes. Les valeurs de tolérance standard sont de 50, 100, 150 et 250 millisecondes.
En règle générale, un minuteur avec une valeur de millisecondes volumineuse peut utiliser une valeur de tolérance proportionnellement importante. Par exemple, un minuteur avec MillisecondsPeriod = 500 millisecondes peut utiliser Tolérance = 50 millisecondes. Mais un minuteur avec MillisecondsPeriod = 10 secondes peut utiliser Tolérance = 1 seconde.
Pour plus d’informations sur le comportement du minuteur, consultez KeSetTimerEx.
Pour annuler un minuteur, appelez la fonction NdisCancelTimerObject.
Exigences
| Exigence | Valeur |
|---|---|
| client minimum pris en charge | Pris en charge dans NDIS 6.20 et versions ultérieures. |
| plateforme cible | Universel |
| d’en-tête | ndis.h (include Ndis.h) |
| bibliothèque | Ndis.lib |
| IRQL | <= DISPATCH_LEVEL |