Fonction CmCallbackGetKeyObjectIDEx (wdm.h)
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 |