ZwCreateKey, fonction (wdm.h)

Article
02/29/2024

La routine ZwCreateKey crée une clé de Registre ou en ouvre une existante.

Syntaxe

NTSYSAPI NTSTATUS ZwCreateKey(
  [out]           PHANDLE            KeyHandle,
  [in]            ACCESS_MASK        DesiredAccess,
  [in]            POBJECT_ATTRIBUTES ObjectAttributes,
                  ULONG              TitleIndex,
  [in, optional]  PUNICODE_STRING    Class,
  [in]            ULONG              CreateOptions,
  [out, optional] PULONG             Disposition
);

Paramètres

[out] KeyHandle

Pointeur vers une variable HANDLE qui reçoit un handle à la clé.

[in] DesiredAccess

Spécifie une valeur ACCESS_MASK qui détermine l’accès demandé à l’objet . En plus des droits d’accès définis pour tous les types d’objets (voir ACCESS_MASK), l’appelant peut spécifier un ou plusieurs des droits d’accès suivants, qui sont spécifiques aux répertoires d’objets :

Indicateur DesiredAccess	Permet à l’appelant d’effectuer cette opération
KEY_QUERY_VALUE	Lire les valeurs de clé.
KEY_SET_VALUE	Écrire des valeurs de clé.
KEY_CREATE_SUB_KEY	Créez des sous-clés pour la clé.
KEY_ENUMERATE_SUB_KEYS	Lisez les sous-clés de la clé.
KEY_CREATE_LINK	Créez un lien symbolique vers la clé. Cet indicateur n’est pas utilisé par les pilotes de périphérique et intermédiaires.
KEY_NOTIFY	Demandez à recevoir une notification lorsque le nom, la valeur ou les attributs de la clé changent. Pour plus d’informations, consultez ZwNotifyChangeKey.

L’appelant peut également spécifier l’une des constantes suivantes, qui combine plusieurs indicateurs ACCESS_MASK.

Constant	Se compose de ces indicateurs ACCESS_MASK
KEY_READ	STANDARD_RIGHTS_READ, KEY_QUERY_VALUE, KEY_ENUMERATE_SUB_KEYS et KEY_NOTIFY
KEY_WRITE	STANDARD_RIGHTS_WRITE, KEY_SET_VALUE et KEY_CREATE_SUB_KEY
KEY_EXECUTE	Identique à KEY_READ.
KEY_ALL_ACCESS	STANDARD_RIGHTS_ALL, KEY_QUERY_VALUE, KEY_SET_VALUE, KEY_CREATE_SUB_KEY, KEY_ENUMERATE_SUB_KEYS, KEY_NOTIFY et KEY_CREATE_LINK

[in] ObjectAttributes

Pointeur vers une structure OBJECT_ATTRIBUTES qui spécifie le nom de l’objet et d’autres attributs. Utilisez InitializeObjectAttributes pour initialiser cette structure. 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.

TitleIndex

Les pilotes de périphérique et intermédiaire définissent ce paramètre sur zéro.

[in, optional] Class

Pointeur vers une chaîne Unicode qui contient la classe d’objet de la clé. Ces informations sont utilisées par le gestionnaire de configuration.

[in] CreateOptions

Spécifie les options à appliquer lors de la création ou de l’ouverture d’une clé, spécifiées en tant que combinaison compatible des indicateurs suivants.

Indicateur CreateOptions	Description
REG_OPTION_VOLATILE	La clé n’est pas conservée lorsque le système est redémarré.
REG_OPTION_NON_VOLATILE	La clé est conservée lors du redémarrage du système.
REG_OPTION_CREATE_LINK	La clé nouvellement créée est un lien symbolique. Cet indicateur n’est pas utilisé par les pilotes de périphérique et intermédiaires.
REG_OPTION_BACKUP_RESTORE	La clé doit être créée ou 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 de périphérique et intermédiaires.

[out, optional] Disposition

Pointeur vers une variable qui reçoit une valeur indiquant si une nouvelle clé a été créée ou si une clé existante a été ouverte.

Valeur de destruction	Description
REG_CREATED_NEW_KEY	Une nouvelle clé a été créée.
REG_OPENED_EXISTING_KEY	Une clé existante a été ouverte.

Valeur retournée

ZwCreateKey retourne STATUS_SUCCESS en cas de réussite, ou le code d’erreur NTSTATUS approprié en cas d’échec.

Remarques

ZwCreateKey fournit un handle que l’appelant peut utiliser pour manipuler une clé de Registre. Pour plus d’informations, consultez Utilisation du Registre dans un pilote.

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

Il existe deux autres façons de spécifier le nom du fichier à créer ou à ouvrir avec ZwCreateKey :

En tant que chemin d’accès complet, fourni dans le membre ObjectName de l’entrée ObjectAttributes. Les chemins d’accès des clés de Registre commencent par \Registry.
En tant que chemin d’accès relatif à une autre clé de Registre, représenté par le handle dans le membre RootDirectory de l’entrée ObjectAttributes.

Si la clé spécifiée par ObjectAttributes n’existe pas, la routine tente de créer la clé. Pour que cette tentative aboutisse, la nouvelle clé doit être une sous-clé directe de la clé référencée par RootDirectory, et la clé à laquelle RootDirectory fait référence doit avoir été ouverte pour un accès KEY_CREATE_SUB_KEY.

Si la clé spécifiée existe déjà, elle est ouverte et sa valeur n’est affectée d’aucune façon.

Les attributs de sécurité spécifiés par ObjectAttributes lors de la création d’une clé déterminent si la propriété DesiredAccess spécifiée est accordée lors des appels ultérieurs à ZwCreateKey et ZwOpenKey.

Si l’appelant n’est pas en cours d’exécution dans un contexte de thread système, il doit s’assurer que tous les handles qu’il crée sont des handles privés. Sinon, le handle est accessible par le processus dans le contexte 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, consultez Utilisation du Registre dans un pilote.

Si l’appel à cette fonction se produit en mode utilisateur, vous devez utiliser le nom « NtCreateKey » au lieu de « ZwCreateKey ».

La routine NtCreateKey dans le noyau Windows n’est pas directement accessible aux pilotes en mode noyau.

Pour les appels provenant de pilotes en mode noyau, les versions NtXxx et ZwXxx d’une routine Windows Native System Services peuvent se comporter différemment dans la façon dont elles gèrent et interprètent les paramètres d’entrée. Pour plus d’informations sur la relation entre les versions NtXxx et ZwXxx d’une routine, consultez Using Nt and Zw Versions of the Native System Services Routines.

Configuration requise

Condition requise	Valeur
Plateforme cible	Universal
En-tête	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Bibliothèque	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Règles de conformité DDI	HwStorPortProhibitedDDIs(storport), IrqlZwPassive(wdm), PowerIrpDDis(wdm), ZwRegistryCreate(storport), ZwRegistryCreate(storport), ZwRegistryCreate(wdm), ZwRegistryOpen(wdm)