Partager via


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.

REG_NOTIFY_CLASS valeur Type de structure
RegNtDeleteKey REG_DELETE_KEY_INFORMATION
RegNtPreDeleteKey REG_DELETE_KEY_INFORMATION
RegNtPostDeleteKey REG_POST_OPERATION_INFORMATION
RegNtSetValueKey REG_SET_VALUE_KEY_INFORMATION
RegNtPreSetValueKey REG_SET_VALUE_KEY_INFORMATION
RegNtPostSetValueKey REG_POST_OPERATION_INFORMATION
RegNtDeleteValueKey REG_DELETE_VALUE_KEY_INFORMATION
RegNtPreDeleteValueKey REG_DELETE_VALUE_KEY_INFORMATION
RegNtPostDeleteValueKey REG_POST_OPERATION_INFORMATION
RegNtSetInformationKey REG_SET_INFORMATION_KEY_INFORMATION
RegNtPreSetInformationKey REG_SET_INFORMATION_KEY_INFORMATION
RegNtPostSetInformationKey REG_POST_OPERATION_INFORMATION
RegNtRenameKey REG_RENAME_KEY_INFORMATION
RegNtPreRenameKey REG_RENAME_KEY_INFORMATION
RegNtPostRenameKey REG_POST_OPERATION_INFORMATION
RegNtEnumerateKey REG_ENUMERATE_KEY_INFORMATION
RegNtPreEnumerateKey REG_ENUMERATE_KEY_INFORMATION
RegNtPostEnumerateKey REG_POST_OPERATION_INFORMATION
RegNtEnumerateValueKey REG_ENUMERATE_VALUE_KEY_INFORMATION
RegNtPreEnumerateValueKey REG_ENUMERATE_VALUE_KEY_INFORMATION
RegNtPostEnumerateValueKey REG_POST_OPERATION_INFORMATION
RegNtQueryKey REG_QUERY_KEY_INFORMATION
RegNtPreQueryKey REG_QUERY_KEY_INFORMATION
RegNtPostQueryKey REG_POST_OPERATION_INFORMATION
RegNtQueryValueKey REG_QUERY_VALUE_KEY_INFORMATION
RegNtPreQueryValueKey REG_QUERY_VALUE_KEY_INFORMATION
RegNtPostQueryValueKey REG_POST_OPERATION_INFORMATION
RegNtQueryMultipleValueKey REG_QUERY_MULTIPLE_VALUE_KEY_INFORMATION
RegNtPreQueryMultipleValueKey REG_QUERY_MULTIPLE_VALUE_KEY_INFORMATION
RegNtPostQueryMultipleValueKey REG_POST_OPERATION_INFORMATION
RegNtPreCreateKey REG_PRE_CREATE_KEY_INFORMATION
RegNtPreCreateKeyEx REG_CREATE_KEY_INFORMATION**
RegNtPostCreateKey REG_POST_CREATE_KEY_INFORMATION
RegNtPostCreateKeyEx REG_POST_OPERATION_INFORMATION
RegNtPreOpenKey REG_PRE_OPEN_KEY_INFORMATION**
RegNtPreOpenKeyEx REG_OPEN_KEY_INFORMATION
RegNtPostOpenKey REG_POST_OPEN_KEY_INFORMATION
RegNtPostOpenKeyEx REG_POST_OPERATION_INFORMATION
RegNtKeyHandleClose REG_KEY_HANDLE_CLOSE_INFORMATION
RegNtPreKeyHandleClose REG_KEY_HANDLE_CLOSE_INFORMATION
RegNtPostKeyHandleClose REG_POST_OPERATION_INFORMATION
RegNtPreFlushKey REG_FLUSH_KEY_INFORMATION
RegNtPostFlushKey REG_POST_OPERATION_INFORMATION
RegNtPreLoadKey REG_LOAD_KEY_INFORMATION
RegNtPostLoadKey REG_POST_OPERATION_INFORMATION
RegNtPreUnLoadKey REG_UNLOAD_KEY_INFORMATION
RegNtPostUnLoadKey REG_POST_OPERATION_INFORMATION
RegNtPreQueryKeySecurity REG_QUERY_KEY_SECURITY_INFORMATION
RegNtPostQueryKeySecurity REG_POST_OPERATION_INFORMATION
RegNtPreSetKeySecurity REG_SET_KEY_SECURITY_INFORMATION
RegNtPostSetKeySecurity REG_POST_OPERATION_INFORMATION
RegNtCallbackObjectContextCleanup REG_CALLBACK_CONTEXT_CLEANUP_INFORMATION
RegNtPreRestoreKey REG_RESTORE_KEY_INFORMATION
RegNtPostRestoreKey REG_POST_OPERATION_INFORMATION
RegNtPreSaveKey REG_SAVE_KEY_INFORMATION
RegNtPostSaveKey REG_POST_OPERATION_INFORMATION
RegNtPreReplaceKey REG_REPLACE_KEY_INFORMATION
RegNtPostReplaceKey REG_POST_OPERATION_INFORMATION
RegNtPreQueryKeyName REG_QUERY_KEY_NAME
RegNtPostQueryKeyName REG_POST_OPERATION_INFORMATION
RegNtPreSaveMergedKey REG_SAVE_MERGED_KEY_INFORMATION
RegNtPostSaveMergedKey REG_POST_OPERATION_INFORMATION

À 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).

Voir aussi

CmRegisterCallback

CmUnRegisterCallback

ProbeForRead

REG_NOTIFY_CLASS

ZwOpenKey