EX_CALLBACK_FUNCTION fonction de rappel (wdm.h)
La routine RegistryCallback d’un pilote de filtre peut surveiller, bloquer ou modifier une opération de Registre.
Syntaxe
EX_CALLBACK_FUNCTION ExCallbackFunction;
NTSTATUS ExCallbackFunction(
[in] PVOID CallbackContext,
[in, optional] PVOID Argument1,
[in, optional] PVOID Argument2
)
{...}
Paramètres
[in] CallbackContext
Valeur que le pilote a passée en tant que paramètre Context à CmRegisterCallback ou CmRegisterCallbackEx lors de l’inscription de cette routine RegistryCallback .
[in, optional] Argument1
Valeur de type REG_NOTIFY_CLASS qui identifie le type d’opération de Registre en cours d’exécution et si la routine RegistryCallback est appelée avant ou après l’opération de Registre.
[in, optional] Argument2
Pointeur vers une structure qui contient des informations spécifiques au type d’opération de Registre. Le type de structure dépend de la valeur de type REG_NOTIFY_CLASS pour Argument1, comme indiqué dans le tableau suivant. Pour plus d’informations sur les valeurs de type REG_NOTIFY_CLASS disponibles pour les versions de système d’exploitation, consultez REG_NOTIFY_CLASS.
À compter de Windows 7, la structure de données réelle transmise lorsque la classe de notification est RegNtPreCreateKeyEx ou RegNtPreOpenKeyEx est la version V1 de cette structure, REG_CREATE_KEY_INFORMATION_V1 ou REG_OPEN_KEY_INFORMATION_V1, respectivement. Vérifiez le membre Réservé pour déterminer la version de la structure.
| Numéro de version | Nom de la structure |
|---|---|
| 0 | REG_CREATE_KEY_INFORMATION et REG_OPEN_KEY_INFORMATION |
| 1 | REG_CREATE_KEY_INFORMATION_V1 et REG_OPEN_KEY_INFORMATION_V1 |
Valeur retournée
Pour plus d’informations sur le moment où une routine RegistryCallback doit retourner chacune de ces valeurs status, consultez Filtrage des appels du Registre.
Remarques
Pour être informé des opérations de Registre, un composant en mode noyau (tel que le composant pilote d’un package logiciel antivirus) peut appeler CmRegisterCallback ou CmRegisterCallbackEx pour inscrire une routine RegistryCallback .
La routine RegistryCallback peut inspecter le contenu des mémoires tampons d’entrée et de sortie fournies pour les opérations du Registre. Une opération de Registre peut être lancée par une application en mode utilisateur qui appelle une routine de registre en mode utilisateur (telle que RegCreateKeyEx ou RegOpenKeyEx) ou par un pilote qui appelle une routine de registre en mode noyau (telle que ZwCreateKey ou ZwOpenKey). Une mémoire tampon d’entrée est une mémoire tampon fournie par l’initiateur à partir de laquelle le Registre lit les données d’entrée pour l’opération. Une mémoire tampon de sortie est une mémoire tampon fournie par l’initiateur dans laquelle le Registre écrit les données de sortie demandées par l’initiateur.
Avant d’appeler la routine RegistryCallback , le noyau sonde (pour vérifier l’alignement et l’accessibilité) tous les membres des structures Argument2 qui pointent vers des mémoires tampons de sortie dans la mémoire en mode utilisateur, mais ne capturent pas les mémoires tampons de sortie en mode utilisateur dans la mémoire système. La routine de rappel doit contenir tout accès d’une mémoire tampon de sortie dans un bloc try/except . Si la routine de rappel doit passer un pointeur de mémoire tampon de sortie à une routine système (par exemple, ZwOpenKey) et que la mémoire tampon est en mémoire en mode utilisateur, la routine de rappel doit d’abord capturer la mémoire tampon.
La gestion des mémoires tampons d’entrée dépend de la version de Windows. À compter de Windows 8, le noyau capture toutes les mémoires tampons d’entrée pointées par les membres des structures Argument2 dans la mémoire système avant d’appeler la routine RegistryCallback. Dans les versions de Windows avant Windows 8, le noyau sonde tous les membres des structures Argument2 qui pointent vers des mémoires tampons d’entrée dans la mémoire en mode utilisateur, mais capture uniquement certaines de ces mémoires tampons dans la mémoire système. Dans ces versions antérieures de Windows, la routine de rappel doit contenir tout accès d’une mémoire tampon d’entrée dans un bloc try/except . En outre, si la routine de rappel doit passer un pointeur de mémoire tampon d’entrée à une routine système (par exemple, ZwOpenKey) et que la mémoire tampon est en mémoire en mode utilisateur, la routine de rappel doit d’abord capturer la mémoire tampon.
Le tableau suivant récapitule la configuration requise pour les accès à la mémoire tampon par la routine RegistryCallback .
| Type de mémoire tampon | Version de Windows | Pointeur de mémoire tampon passé à la routine de rappel | Sécurité pour la routine de rappel à accéder directement ? | Coffre-fort à transmettre aux routines système (telles que ZwOpenKey) ? |
|---|---|---|---|---|
| Entrée en mode utilisateur | Windows 8 et versions ultérieures | Pointe vers les données capturées. | Oui | Oui |
| Entrée en mode utilisateur | Windows 7 et versions antérieures | Pointe vers les données capturées ou la mémoire tampon en mode utilisateur d’origine. | Non. Doit être lu sous try/except. | Non. Vous devez allouer la mémoire du noyau, copier les données de la mémoire tampon d’origine sous try/except et passer les données copiées à la routine système. |
| Sortie en mode utilisateur | Tous | Pointe vers la mémoire tampon en mode utilisateur d’origine. | Non. Doit écrire sous try/except. | Non. Doit allouer la mémoire du noyau, passer la mémoire du noyau à la routine système et copier les résultats dans la mémoire tampon d’origine sous try/except. |
| Entrée et sortie en mode noyau | Tous | Pointe vers la mémoire tampon en mode noyau d’origine. | Oui | Oui |
Pour plus d’informations sur les routines RegistryCallback et les pilotes de filtre du Registre, consultez Filtrage des appels du Registre.
Un RegistryCallback s’exécute à IRQL = PASSIVE_LEVEL et dans le contexte du thread qui effectue l’opération de Registre.
Exemples
Pour définir une routine de rappel RegistryCallback , vous devez d’abord fournir une déclaration de fonction qui identifie le type de routine de rappel que vous définissez. Windows fournit un ensemble de types de fonctions de rappel pour les pilotes. La déclaration d’une fonction à l’aide des types de fonction de rappel aide l’analyse du code pour les pilotes, le vérificateur de pilotes statique (SDV) et d’autres outils de vérification à la recherche d’erreurs. Il s’agit d’une exigence pour l’écriture de pilotes pour le système d’exploitation Windows.
Par exemple, pour définir une routine de rappel RegistryCallback nommée MyRegistryCallback, utilisez le type EX_CALLBACK_FUNCTION comme indiqué dans cet exemple de code :
EX_CALLBACK_FUNCTION MyRegistryCallback;
Ensuite, implémentez votre routine de rappel comme suit :
_Use_decl_annotations_
NTSTATUS
MyRegistryCallback(
PVOID CallbackContext,
PVOID Argument1,
PVOID Argument2
)
{
// Function body
}
Le type de fonction EX_CALLBACK_FUNCTION est défini dans le fichier d’en-tête Wdm.h. Pour identifier plus précisément les erreurs lors de l’exécution des outils d’analyse du code, veillez à ajouter l’annotation Use_decl_annotations à votre définition de fonction. L’annotation Use_decl_annotations garantit que les annotations appliquées au type de fonction EX_CALLBACK_FUNCTION dans le fichier d’en-tête sont utilisées. Pour plus d’informations sur la configuration requise pour les déclarations de fonction, consultez Déclaration de fonctions à l’aide de types de rôles de fonction pour les pilotes WDM. Pour plus d’informations sur Use_decl_annotations, consultez Annotating Function Behavior.
Configuration requise
| Condition requise | Valeur |
|---|---|
| Client minimal pris en charge | Prise en charge à partir de Windows XP (voir la section Valeur de retour). |
| Plateforme cible | Desktop (Expérience utilisateur) |
| En-tête | wdm.h (inclure Wdm.h, Ntddk.h, Ntifs.h) |
| IRQL | Appelé à PASSIVE_LEVEL (voir la section Remarques). |