ExRegisterCallback, fonction (wdm.h)
La routine ExRegisterCallback inscrit 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 CallbackContext de 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 de retour
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 est NULL si ExRegisterCallback se termine par 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 retourne NULL.
Les appelants de 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 dans 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)
Valeur constante PO_CB_XXX qui est castée en type PVOID.
PO_CB_AC_STATUS : indique que le système est passé de L’A/C à l’alimentation de la batterie, ou inversement.
PO_CB_LID_SWITCH_STATE : indique que le commutateur de 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 de l’alimentation du système est imminent. Les pilotes du chemin de pagination peuvent s’inscrire à ce rappel pour recevoir un avertissement précoce de cette modification, ce qui leur permet de verrouiller leur code en mémoire avant que l’état d’alimentation change.
Argument2 (PowerState)
Valeur TRUE ou FALSE qui est castée en type PVOID.
Si argument1 est PO_CB_AC_STATUS, argument2 est TRUE si l’ordinateur utilise actuellement une alimentation A/C et est FAUX si l’ordinateur est en cours d’exécution sur batterie.
Si Argument1 est PO_CB_LID_SWITCH_STATE, Argument2 est TRUE si le couvercle est actuellement ouvert et est 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 est FALSE si l’ordinateur est sur le point de quitter l’état de l’alimentation du système S0 et est TRUE si l’ordinateur vient de entrer 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’état d’erreur 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 d’état de la structure KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT à laquelle argument1 pointe est KeProcessorAddStartNotify.
Variable NSTATUS qui argument2 points pour contenir la valeur STATUS_SUCCESS. Autrement dit, la routine de rappel ne doit pas remplacer une valeur d’état d’erreur 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 KeRegisterProcessorChangeCall back fournit des informations similaires, mais prend également en charge un indicateur KE_PROCESSOR_CHANGE_ADD_EXISTING qu’un pilote peut utiliser pour énumérer les processeurs dans la configuration initiale du système multiprocesseur. 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 même IRQL auquel le pilote qui a créé le rappel appelé ExNotifyCallback routine.
Exigences
| Exigence | Valeur |
|---|---|
| plateforme cible | Universel |
| d’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) |