Fonction CmCallbackGetKeyObjectIDEx (wdm.h)

Article
05/02/2024

La routine CmCallbackGetKeyObjectIDEx récupère l’identificateur unique et le nom de l’objet qui sont associés à un objet de clé de Registre spécifié.

Cette routine est disponible à partir de Windows 8. Dans les versions antérieures de Windows, utilisez plutôt la routine CmCallbackGetKeyObjectID . Pour plus d’informations, consultez la section Remarques ci-dessous.

Syntaxe

NTSTATUS CmCallbackGetKeyObjectIDEx(
  [in]            PLARGE_INTEGER   Cookie,
  [in]            PVOID            Object,
  [out, optional] PULONG_PTR       ObjectID,
  [out, optional] PCUNICODE_STRING *ObjectName,
  [in]            ULONG            Flags
);

Paramètres

[in] Cookie

Valeur de cookie qui représente l’inscription de l’appelant pour recevoir les rappels de filtre du Registre. Le pilote a précédemment obtenu cette valeur de cookie à partir de la routine CmRegisterCallback ou CmRegisterCallbackEx .

[in] Object

Pointeur vers l’objet de clé de Registre. Ce paramètre est la valeur de pointeur que la routine de rappel RegistryCallback du pilote a reçue dans le membre Object de l’une des structures REG_XXX_KEY_INFORMATION .

Avertissement

Dans certaines circonstances, les structures de notification de rappel de registre peuvent contenir des pointeurs d’objets non NULL non valides. Les pilotes de filtrage du Registre ne doivent pas passer de tels pointeurs à cette routine. Pour plus d’informations, consultez Pointeurs d’objets clés non valides dans les notifications du Registre.

[out, optional] ObjectID

Pointeur vers un emplacement qui reçoit un pointeur vers l’identificateur de clé pour la clé de Registre que l’objet représente. Cet identificateur est unique sur toutes les clés du Registre. Ce paramètre est facultatif et peut être NULL. Pour plus d’informations, consultez la section Remarques ci-dessous.

[out, optional] ObjectName

Pointeur vers un emplacement qui reçoit un pointeur vers une structure UNICODE_STRING . Cette structure contient le nom de l’objet de clé de Registre spécifié par Object . Le nom de l’objet est en fait le nom complet du chemin d’accès de la clé de Registre que l’objet représente. L’appelant est chargé de libérer cette structure en appelant la routine CmCallbackReleaseKeyObjectIDEx . Ce paramètre est facultatif et peut être NULL. Pour plus d'informations, consultez la section Notes.

[in] Flags

Réservé. Définit la valeur zéro.

Valeur retournée

CmCallbackGetKeyObjectIDEx retourne STATUS_SUCCESS si l’opération réussit. Les valeurs de retour d’erreur possibles incluent le code status suivant :

Code de retour	Description
STATUS_INVALID_PARAMETER	Le paramètre Cookie, Object ou Flags n’est pas valide.

Remarques

Les pilotes peuvent utiliser CmCallbackGetKeyObjectIDEx pour obtenir l’identificateur de clé de Registre, le nom de l’objet ou les deux, en fournissant des valeurs non NULL pour les paramètres ObjectID ou ObjectName .

L’appelant peut obtenir l’identificateur de clé via le paramètre ObjectID . Si deux objets de clé de Registre représentent la même clé de Registre, les identificateurs de clé obtenus à partir de CmCallbackGetKeyObjectIDEx pour les deux objets sont identiques. Si le nom de la clé de Registre change, l’identificateur de clé obtenu à partir de CmCallbackGetKeyObjectIDEx ne change pas. L’appelant peut utiliser l’identificateur de clé pour suivre de manière fiable les accès effectués à une clé de Registre particulière par le biais de plusieurs objets de clé, et même des modifications apportées au nom de la clé du Registre.

L’appelant peut obtenir le nom de l’objet via le paramètre ObjectName . Le stockage de la structure UNICODE_STRING qui contient le nom de l’objet reste valide jusqu’à ce que l’appelant appelle CmCallbackReleaseKeyObjectIDEx pour libérer la structure.

CmCallbackGetKeyObjectIDEx est une version améliorée de la routine CmCallbackGetKeyObjectID , disponible à partir de Windows Vista. Les pilotes qui s’exécutent dans des versions de Windows antérieures à Windows 8 doivent appeler CmCallbackGetKeyObjectID au lieu de CmCallbackGetKeyObjectIDEx. Les pilotes qui s’exécutent uniquement dans Windows 8 et versions ultérieures de Windows doivent appeler CmCallbackGetKeyObjectIDEx au lieu de CmCallbackGetKeyObjectID.

CmCallbackGetKeyObjectIDEx a deux fonctionnalités importantes qui ne sont pas disponibles à partir de CmCallbackGetKeyObjectID.

Tout d’abord, CmCallbackGetKeyObjectIDEx permet à un pilote de filtre du Registre de contrôler explicitement la durée de vie de la structure ObjectName . Le pilote peut appeler CmCallbackReleaseKeyObjectIDEx à tout moment pour libérer cette structure. En revanche, le pilote ne peut pas libérer explicitement la structure ObjectName reçue de CmCallbackGetKeyObjectID. Cette structure est automatiquement libérée lorsque tous les handles de la clé sont fermés.

Deuxièmement, si un pilote de filtre de Registre appelle CmCallbackGetKeyObjectID pour obtenir un pointeur de structure ObjectName et, après cet appel, le nom de la clé de Registre a changé, les appels suivants à CmCallbackGetKeyObjectID obtiennent un pointeur vers une copie obsolète de la structure ObjectName , qui contient l’ancien nom de clé. La copie obsolète de cette structure persiste jusqu’à ce que tous les handles de la clé soient fermés. En revanche, la structure ObjectName obtenue à partir de CmCallbackGetKeyObjectIDEx contient toujours le nom de clé le plus à jour.

Pour plus d’informations sur les pilotes de filtre du Registre, consultez Filtrage des appels du Registre.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Disponible à partir de Windows 8.
Plateforme cible	Universal
En-tête	wdm.h (inclure Wdm.h, Ntddk.h, Ntifs.h)
Bibliothèque	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	IRQL <= APC_LEVEL