CmCallbackGetKeyObjectID, fonction (wdm.h)

Article
02/27/2024

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

À compter de Windows 8, les pilotes de filtre de Registre doivent appeler la routine CmCallbackGetKeyObjectIDEx au lieu de CmCallbackGetKeyObjectID. Pour plus d’informations, consultez la section Remarques ci-dessous.

Syntaxe

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

Paramètres

[in] Cookie

Valeur de cookie que le pilote a précédemment obtenue en appelant la routine CmRegisterCallback ou CmRegisterCallbackEx .

[in] Object

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 ces 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 unique qui représente la clé de Registre spécifiée par Object . Ce paramètre est facultatif et peut être NULL.

[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 ne doit pas écrire dans cette structure UNICODE_STRING ou la libérer. Ce paramètre est facultatif et peut être NULL.

Valeur retournée

CmCallbackGetKeyObjectID 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 ou Object n’est pas valide.

Remarques

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

Les pilotes peuvent utiliser CmCallbackGetKeyObjectID 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 .

Une fois que le pilote a obtenu l’identificateur ou le nom, l’identificateur ou le nom est valide jusqu’à ce que la routine RegistryCallback du pilote reçoive une notification préalable de fermeture de handle.

Le pilote ne doit pas modifier le nom de l’objet.

Si deux objets de clé de Registre représentent la même clé de Registre, les identificateurs de clé pour les deux objets sont identiques.

Pour plus d’informations sur cmCallbackGetKeyObjectID et les opérations de filtrage du Registre, consultez Filtrage des appels de registre.