Fonction ZwOpenKeyEx (wdm.h)

  • Article

La routine ZwOpenKeyEx ouvre une clé de Registre existante.

Syntaxe

NTSYSAPI NTSTATUS ZwOpenKeyEx(
  [out] PHANDLE            KeyHandle,
  [in]  ACCESS_MASK        DesiredAccess,
  [in]  POBJECT_ATTRIBUTES ObjectAttributes,
  [in]  ULONG              OpenOptions
);

Paramètres

[out] KeyHandle

Pointeur vers une variable HANDLE dans laquelle la routine écrit le handle sur la clé.

[in] DesiredAccess

Spécifie le type d’accès à la clé que l’appelant demande. Ce paramètre est une valeur ACCESS_MASK . Pour plus d’informations, consultez la description du paramètre DesiredAccess de la routine ZwCreateKey .

[in] ObjectAttributes

Pointeur vers les attributs d’objet de la clé en cours d’ouverture. Ce paramètre pointe vers une structure OBJECT_ATTRIBUTES qui doit avoir été initialisée par la routine InitializeObjectAttributes . L’appelant doit spécifier le nom de la clé de Registre en tant que paramètre ObjectName dans l’appel à InitializeObjectAttributes. Si l’appelant n’est pas en cours d’exécution dans un contexte de thread système, il doit définir l’attribut OBJ_KERNEL_HANDLE lorsqu’il appelle InitializeObjectAttributes.

[in] OpenOptions

Spécifie les options à appliquer lors de l’ouverture de la clé. Définissez ce paramètre sur zéro ou sur la valeur OR au niveau du bit d’un ou plusieurs des bits d’indicateur REG_OPTION_XXX suivants :

Indicateur OpenOptions Description
REG_OPTION_OPEN_LINK La clé est un lien symbolique. Cet indicateur n’est pas utilisé par les pilotes d’appareil et intermédiaires.
REG_OPTION_BACKUP_RESTORE La clé doit être ouverte avec des privilèges spéciaux qui autorisent les opérations de sauvegarde et de restauration. Cet indicateur n’est pas utilisé par les pilotes d’appareil et intermédiaires.

Valeur retournée

ZwOpenKeyEx retourne STATUS_SUCCESS si l’appel réussit à ouvrir la clé. Les valeurs de retour d’erreur possibles sont les suivantes :

Code de retour Description
STATUS_INVALID_PARAMETER_4
 Le paramètre OpenOptions spécifie des options non valides.
STATUS_OBJECT_PATH_SYNTAX_BAD
 Le chemin d’accès du Registre dans les attributs d’objet n’est pas valide.
STATUS_OBJECT_NAME_NOT_FOUND
 Le nom de clé de Registre dans les attributs de l’objet est introuvable.
STATUS_OBJECT_TYPE_MISMATCH
 La clé de Registre nommée est un lien symbolique, mais le bit d’indicateur REG_OPTION_OPEN_LINK n’est pas défini dans OpenOptions.
STATUS_ACCESS_DENIED
 L’appelant ne disposait pas des droits d’accès nécessaires pour ouvrir un handle pour la clé de Registre nommée.
STATUS_INSUFFICIENT_RESOURCES
 Une opération d’allocation de mémoire a échoué.

Remarques

Cette routine fournit un handle avec lequel l’appelant peut accéder à une clé de Registre. Si la clé spécifiée n’existe pas, la routine retourne une erreur status valeur et ne fournit pas de handle de clé.

La routine ZwOpenKey est similaire à ZwOpenKeyEx , mais n’accepte pas de paramètre OpenOptions . Le paramètre OpenOptions de ZwOpenKeyEx permet à l’appelant d’ouvrir une clé qui est un lien symbolique ou d’ouvrir une clé pour les opérations de sauvegarde et de restauration. Un appel à ZwOpenKeyEx avec OpenOptions = 0 équivaut à un appel à ZwOpenKey.

Une fois que le handle pointé par KeyHandle n’est plus utilisé, le pilote doit appeler ZwClose pour le fermer.

ZwOpenKeyEx ignore les informations de sécurité dans la structure vers laquelle pointe le paramètre ObjectAttributes .

Si l’appelant en mode noyau n’est pas en cours d’exécution dans un contexte de thread système, il doit s’assurer que les handles qu’il crée sont des handles de noyau. Sinon, le handle est accessible par le processus dans lequel le pilote est en cours d’exécution. Pour plus d’informations, consultez Handles d’objet.

Pour plus d’informations sur l’utilisation des clés de Registre en mode noyau, consultez Utilisation du Registre dans un pilote.

Configuration requise

Condition requise Valeur
Client minimal pris en charge Disponible dans Windows 7 et versions ultérieures de Windows.
Plateforme cible Universal
En-tête wdm.h (inclure Wdm.h, Ntddk.h, Ntifs.h)
Bibliothèque NtosKrnl.lib
DLL NtosKrnl.exe
IRQL PASSIVE_LEVEL
Règles de conformité DDI HwStorPortProhibitedDDIs(storport),PowerIrpDDis(wdm)

Voir aussi

ACCESS_MASK

InitializeObjectAttributes

OBJECT_ATTRIBUTES

ZwClose

ZwOpenKey