Fonction ExAllocateTimer (wdm.h)

Article
08/08/2023

La routine ExAllocateTimer alloue et initialise un objet de minuteur.

Syntaxe

PEX_TIMER ExAllocateTimer(
  [in, optional] PEXT_CALLBACK Callback,
  [in, optional] PVOID         CallbackContext,
  [in]           ULONG         Attributes
);

Paramètres

[in, optional] Callback

Pointeur vers une routine de rappel ExTimerCallback implémentée par le pilote. Le système d’exploitation appelle cette routine lorsque le minuteur expire. Ce paramètre est facultatif et peut être NULL si aucune routine de rappel n’est nécessaire.

[in, optional] CallbackContext

Valeur de contexte pour la routine de rappel pointée vers le paramètre Callback . Le système d’exploitation transmet cette valeur en tant que paramètre à la routine de rappel ExTimerCallback , le cas échéant. Ce paramètre est généralement un pointeur vers une structure définie par l’appelant qui contient des informations de contexte utilisées par la routine de rappel. Ce paramètre est facultatif et peut être défini sur NULL si aucune information de contexte n’est nécessaire.

[in] Attributes

Attributs du minuteur. Définissez ce paramètre sur zéro ou sur le bit-OR d’un ou plusieurs des bits d’indicateur de minuteur suivants.

Bit de l’indicateur du minuteur	Description
EX_TIMER_HIGH_RESOLUTION	Minuteur haute résolution. Rendez le minuteur plus précis en utilisant une horloge de résolution plus élevée pour piloter le minuteur.
EX_TIMER_NO_WAKE	Aucun minuteur de veille. Faites en sorte que le minuteur retarde l’expiration du processeur jusqu’à ce que le délai d’expiration du minuteur, plus sa tolérance de retard, soit dépassé.
EX_TIMER_NOTIFICATION	Minuteur de notification. Faites du minuteur un minuteur de notification au lieu d’un minuteur de synchronisation. Si cet indicateur n’est pas défini, le minuteur est un minuteur de synchronisation.

Le bit d’indicateur EX_TIMER_NOTIFICATION peut être défini indépendamment des autres bits d’indicateur définis.

Les bits d’indicateur EX_TIMER_HIGH_RESOLUTION et EX_TIMER_NO_WAKE s’excluent mutuellement. Si l’appelant définit ces deux bits d’indicateur, le bogue de routine est vérifié.

Pour plus d’informations sur les attributs du minuteur, consultez Remarques.

Valeur retournée

Cette routine retourne un pointeur vers une structure EX_TIMER , si l’appel réussit. Cette structure est l’objet de minuteur que la routine a alloué et initialisé. Si l’appel échoue, la routine retourne NULL.

Remarques

Cette routine retourne un pointeur vers le nouvel objet de minuteur. Pour utiliser le minuteur, le pilote appelant fournit ce pointeur dans les appels suivants aux routines ExSetTimer, ExCancelTimer et ExDeleteTimer . Si le pilote fournit un pointeur vers une routine de rappel ExTimerCallback en tant que paramètre d’entrée pour la routine ExAllocateTimer , le système d’exploitation transmet cet objet de minuteur en tant que paramètre d’entrée à la routine ExTimerCallback .

Un minuteur peut être un minuteur de notification ou un minuteur de synchronisation. Lorsqu’un minuteur de notification est signalé, tous les threads en attente ont leur attente satisfaite. L’état de ce minuteur reste signalé jusqu’à ce qu’il soit explicitement réinitialisé. Lorsqu’un minuteur de synchronisation expire, son état est défini sur signalé jusqu’à ce qu’un seul thread en attente soit libéré. Ensuite, le minuteur est réinitialisé à l’état non signalé.

Si le bit d’indicateur EX_TIMER_HIGH_RESOLUTION est défini dans Attributs, le système d’exploitation augmente la résolution de l’horloge système, si nécessaire, de sorte que les heures d’expiration du minuteur correspondent plus précisément aux durées d’expiration nominales spécifiées dans les paramètres DueTime et Period pour la routine ExSetTimer . Pour plus d’informations, consultez Minuteurs haute résolution.

Si le bit d’indicateur EX_TIMER_NO_WAKE est défini dans Attributs, le minuteur évite de réveiller inutilement le processeur d’un état de faible consommation. Pour plus d’informations, consultez Minuteurs sans éveil.

ExAllocateTimer alloue le stockage pour l’objet minuteur. Lorsque cet objet n’est plus nécessaire, l’appelant est chargé de libérer cet objet en appelant la routine ExDeleteTimer .

Le paramètre Callback est facultatif. Un pilote qui ne fournit pas de routine ExTimerCallback peut à la place lancer une opération d’attente sur l’objet minuteur. Un thread de pilote peut appeler une routine telle que KeWaitForSingleObject ou KeWaitForMultipleObjects pour attendre l’expiration du minuteur. Lorsque le minuteur expire, l’objet minuteur est signalé.

Pour plus d’informations, consultez Routines et EX_TIMER Objets ExXxxTimer.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Disponible à partir de Windows 8.1.
Plateforme cible	Universal
En-tête	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Bibliothèque	Ntoskrnl.lib
IRQL	<= DISPATCH_LEVEL

Voir aussi