ZwCreateKey, fonction (wdm.h)
La routine ZwCreateKey crée une clé de Registre ou ouvre une clé de Registre 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 vers la clé.
[in] DesiredAccess
Spécifie une valeur ACCESS_MASK qui détermine l’accès demandé à l’objet. Outre les 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 de procéder ainsi |
---|---|
KEY_QUERY_VALUE | Lire les valeurs de clé. |
KEY_SET_VALUE | Écrivez 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édiaire. |
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 de 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ée 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 lorsque le système est redémarré. |
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édiaire. |
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édiaire. |
[out, optional] Disposition
Pointeur vers une variable qui reçoit une valeur indiquant si une nouvelle clé a été créée ou une clé existante ouverte.
valeur de de disposition |
Description |
---|---|
REG_CREATED_NEW_KEY | Une nouvelle clé a été créée. |
REG_OPENED_EXISTING_KEY | Une clé existante a été ouverte. |
Valeur de retour
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 unde pilote.
Une fois que le handle pointé par KeyHandle n’est plus utilisé, le pilote doit appeler ZwClose pour le fermer.
Il existe deux 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 ObjectName membre 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ée par le handle dans le RootDirectory membre 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 réussisse, la nouvelle clé doit être une sous-clé directe de la clé référencée par RootDirectory, et la clé que RootDirectory fait référence doit avoir été ouverte pour KEY_CREATE_SUB_KEY accès.
Si la clé spécifiée existe déjà, elle est ouverte et sa valeur n’est pas affectée d’une manière quelconque.
Les attributs de sécurité spécifiés par ObjectAttributes lorsqu’une clé est créée déterminent si le DesiredAccess spécifié est accordé lors des appels suivants à 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 les handles qu’il crée sont des handles privés. Sinon, le handle est accessible par le processus dans lequel le pilote est en cours d’exécution. Pour plus d’informations, consultez Descripteurs d’objets.
Pour plus d’informations sur l’utilisation des clés de Registre, consultez Utilisation du Registre dans unde 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 à partir de pilotes en mode noyau, les versions NtXxx et ZwXxx d’une routine Windows Native System Services peuvent se comporter différemment de 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.
Exigences
Exigence | Valeur |
---|---|
plateforme cible | Universel |
d’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) |
Voir aussi
à l’aide de versions Nt et Zw des routines natives des services système