ExRegisterCallback, fonction (wdm.h)

Article
03/08/2023

La routine ExRegisterCallback enregistre une routine de rappel donnée avec un objet de rappel donné.

Syntaxe

PVOID ExRegisterCallback(
  [in, out]      PCALLBACK_OBJECT   CallbackObject,
  [in]           PCALLBACK_FUNCTION CallbackFunction,
  [in, optional] PVOID              CallbackContext
);

Paramètres

[in, out] CallbackObject

Pointeur vers un objet de rappel obtenu à partir de la routine ExCreateCallback .

[in] CallbackFunction

Pointeur vers une routine de rappel implémentée par le pilote, qui doit être non modifiable. La routine de rappel doit être conforme au prototype suivant :

VOID
(*PCALLBACK_FUNCTION ) (
    IN PVOID CallbackContext,
    IN PVOID Argument1,
    IN PVOID Argument2
    );

Les paramètres de routine de rappel sont les suivants :

CallbackContext

Pointeur vers une zone de contexte fournie par le pilote, comme spécifié dans le paramètre CallbackContextd’ExRegisterCallback.

Argument1

Pointeur vers un paramètre défini par l’objet de rappel.

Argument2

Pointeur vers un paramètre défini par l’objet de rappel.

[in, optional] CallbackContext

Pointeur vers une structure définie par l’appelant d’éléments de données à passer en tant que paramètre de contexte de la routine de rappel chaque fois qu’elle est appelée. En règle générale, le contexte fait partie de l’extension d’objet d’appareil de l’appelant.

Valeur retournée

ExRegisterCallback retourne un pointeur vers un handle d’inscription de rappel qui doit être traité comme opaque et réservé pour une utilisation système. Ce pointeur a la valeur NULL si ExRegisterCallback se termine avec une erreur.

Remarques

Un pilote appelle ExRegisterCallback pour inscrire une routine de rappel avec un objet de rappel spécifié.

Si l’objet autorise une seule routine de rappel inscrite et qu’une telle routine est déjà inscrite, ExRegisterCallback renvoie la valeur NULL.

Les appelants d’ExRegisterCallback doivent enregistrer le pointeur retourné pour une utilisation ultérieure dans un appel à ExUnregisterCallback. Le pointeur est requis lors de la suppression de la routine de rappel de la liste des routines de rappel inscrites pour l’objet de rappel.

Les significations de Argument1 et Argument2 de la routine de rappel inscrite dépendent de l’objet de rappel et sont définies par le composant qui l’a créé. Voici les paramètres des objets de rappel définis par le système :

\Callback\SetSystemTime

Argument1 (SetSystemTime)

Non utilisé.

Argument2 (SetSystemTime)

Non utilisé.

\Callback\PowerState**

Argument1 (PowerState)

Une PO_CB_XXX valeur constante qui est convertie en type PVOID.
PO_CB_AC_STATUS : indique que le système est passé de l’alimentation par batterie, ou vice versa.
PO_CB_LID_SWITCH_STATE : indique que le commutateur du couvercle a changé d’état.
PO_CB_PROCESSOR_POWER_POLICY : indique que la stratégie d’alimentation du processeur système a changé.
PO_CB_SYSTEM_POWER_POLICY : indique que la stratégie d’alimentation du système a changé.
PO_CB_SYSTEM_STATE_LOCK : indique qu’un changement d’état d’alimentation du système est imminent. Les pilotes dans le chemin de pagination peuvent s’inscrire pour que ce rappel reçoive un avertissement précoce d’une telle modification, ce qui leur permet de verrouiller leur code en mémoire avant que l’état d’alimentation ne change.

Argument2 (PowerState)

Valeur TRUE ou FALSE qui est convertie en type PVOID.

Si Argument1 est PO_CB_AC_STATUS, Argument2 a la valeur TRUE si l’ordinateur utilise actuellement une alimentation A/C et a la valeur FALSE si l’ordinateur fonctionne sur batterie.
Si Argument1 est PO_CB_LID_SWITCH_STATE, Argument2 a la valeur TRUE si le couvercle est actuellement ouvert et a la valeur FALSE si le couvercle est fermé.
Si Argument1 est PO_CB_PROCESSOR_POWER_POLICY, Argument2 n’est pas utilisé.
Si Argument1 est PO_CB_SYSTEM_POWER_POLICY, Argument2 n’est pas utilisé.
Si Argument1 est PO_CB_SYSTEM_STATE_LOCK, Argument2 a la valeur FALSE si l’ordinateur est sur le point de quitter l’état d’alimentation du système S0, et a la valeur TRUE si l’ordinateur vient d’entrer de nouveau S0.

\Callback\ProcessorAdd

Argument1 (ProcessorAdd)

Pointeur vers une structure KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT qui décrit l’événement de notification de modification du processeur. Ce pointeur est converti en type PVOID. La routine de rappel ne doit pas modifier le contenu de cette structure.

Argument2 (ProcessorAdd)

Pointeur vers une variable qui contient une valeur NTSTATUS. Ce pointeur est converti en type PVOID. Dans certaines conditions, une routine de rappel peut écrire une valeur d’erreur status dans cette variable pour indiquer pourquoi le nouveau processeur ne doit pas être ajouté. Un pilote de périphérique ne doit pas modifier la valeur de cette variable, sauf si les trois conditions suivantes sont remplies :

Une erreur se produit pendant le traitement de la routine de rappel qui doit empêcher l’ajout du nouveau processeur.
La valeur du membre State de la structure KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT vers laquelle Argument1 pointe est KeProcessorAddStartNotify.
La variable NSTATUS vers laquelle Argument2 pointe contient la valeur STATUS_SUCCESS. Autrement dit, la routine de rappel ne doit pas remplacer une erreur status valeur précédemment écrite par un autre client de notification de rappel.

À compter de Windows Vista, l’objet de rappel \Callback\ProcessorAdd est disponible pour suivre dynamiquement les modifications dans la population du processeur. La routine KeRegisterProcessorChangeCallback fournit des informations similaires, mais prend également en charge un indicateur de KE_PROCESSOR_CHANGE_ADD_EXISTING qu’un pilote peut utiliser pour énumérer les processeurs dans la configuration système multiprocesseur initiale. Pour les pilotes qui s’exécutent dans Windows Server 2008 et versions ultérieures de Windows, utilisez KeRegisterProcessorChangeCallback au lieu de l’objet de rappel \Callback\ProcessorAdd , si possible.

Pour plus d’informations sur les objets de rappel, consultez Objets de rappel.

Le système d’exploitation appelle les routines de rappel inscrites au niveau du même IRQL que celui où le pilote qui a créé le rappel a appelé la routine ExNotifyCallback .

Configuration requise

Condition requise	Valeur
Plateforme cible	Universal
En-tête	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Bibliothèque	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	IRQL <= APC_LEVEL
Règles de conformité DDI	HwStorPortProhibitedDDIs(storport), IrqlExApcLte2(wdm)