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.
EX_CALLBACK_FUNCTION ExCallbackFunction;
NTSTATUS ExCallbackFunction(
[in] PVOID CallbackContext,
[in, optional] PVOID Argument1,
[in, optional] PVOID Argument2
)
{...}
[in] CallbackContext
Valeur que le pilote a passée en tant que paramètre Context à CmRegisterCallback ou CmRegisterCallbackEx lorsqu’il a inscrit cette routine RegistryCallback.
[in, optional] Argument1
Valeur REG_NOTIFY_CLASS-typée qui identifie le type d’opération de Registre en cours d’exécution et indique si la routine RegistryCallback est appelée avant ou après l’exécution de 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 REG_NOTIFY_CLASS-typée pour Argument1, comme indiqué dans le tableau suivant. Pour plus d’informations sur les valeurs REG_NOTIFY_CLASS typées disponibles pour les versions du système d’exploitation, consultez REG_NOTIFY_CLASS.
À compter de Windows 7, la structure de données réelle passée 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 |
Pour plus d’informations sur le moment où une routine RegistryCallback doit retourner chacune de ces valeurs d’état, consultez d’appels de Registre de filtrage.
Pour être averti 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 de 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 (par exemple, RegCreateKeyEx ou RegOpenKeyEx) ou par un pilote qui appelle une routine de registre en mode noyau (par exemple, ZwCreateKey ou ZwOpenKey). Une mémoire tampon d’entrée est une mémoire tampon fournie par l’initiateur à partir duquel 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, les sondes du noyau (pour vérifier l’alignement et l’accessibilité) tous les membres de l'Argument2 structures qui pointent vers des mémoires tampons de sortie 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 placer l’accès d’une mémoire tampon de sortie dans un essayer/sauf bloc. 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 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 de la structure Argument2 dans la mémoire système avant d’appeler la routine RegistryCallback. Dans les versions de Windows antérieures à Windows 8, le noyau sonde tous les membres de l'Argument2 structures qui pointent vers des mémoires tampons d’entrée 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 placer l’accès d’une mémoire tampon d’entrée dans un essayer/sauf bloc. 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 mode utilisateur, la routine de rappel doit d’abord capturer la mémoire tampon.
Le tableau suivant résume les conditions requises pour les accès aux mémoires tampons 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 pour accéder directement ? | Sécurité pour passer à des 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 des données capturées ou une mémoire tampon en mode utilisateur d’origine. | Non. Doit lire sous try/except. | Non. Doit allouer de la mémoire du noyau, copier des données à partir de la mémoire tampon d’origine sous try/except et transmettre les données copiées à la routine système. |
| Sortie en mode utilisateur | Tout | Pointe vers la mémoire tampon en mode utilisateur d’origine. | Non. Doit écrire sous try/except. | Non. Doit allouer de 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 | Tout | Pointe vers la mémoire tampon en mode noyau d’origine. | Oui | Oui |
Pour plus d’informations sur routines de RegistryCallback et les pilotes de filtre de Registre, consultez des appels de Registre de filtrage.
Un RegistryCallback s’exécute à IRQL = PASSIVE_LEVEL et dans le contexte du thread qui effectue l’opération de Registre.
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 fonctions de rappel permet d'Analyse du code pour les pilotes, static Driver Verifier (SDV) et d’autres outils de vérification recherchent des erreurs, et il est nécessaire d’écrire des 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 lorsque vous exécutez les 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 les exigences relatives aux 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 annoter le comportement de la fonction.
| Exigence | Valeur |
|---|---|
| client minimum pris en charge | Prise en charge à partir de Windows XP (voir la section Valeur de retour). |
| plateforme cible | Bureau |
| d’en-tête | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h) |
| IRQL | Appelé à PASSIVE_LEVEL (voir la section Remarques). |