Fonction ZwSetValueKey (wdm.h)

Article
03/08/2023

La routine ZwSetValueKey crée ou remplace l’entrée de valeur d’une clé de Registre.

Syntaxe

NTSYSAPI NTSTATUS ZwSetValueKey(
  [in]           HANDLE          KeyHandle,
  [in]           PUNICODE_STRING ValueName,
  [in, optional] ULONG           TitleIndex,
  [in]           ULONG           Type,
  [in, optional] PVOID           Data,
  [in]           ULONG           DataSize
);

Paramètres

[in] KeyHandle

Gérez la clé de Registre pour laquelle écrire une entrée de valeur. Ce handle est créé par un appel réussi à ZwCreateKey ou ZwOpenKey.

[in] ValueName

Pointeur vers le nom de l’entrée de valeur pour laquelle les données doivent être écrites. Ce paramètre peut être un pointeur NULL si l’entrée de valeur n’a pas de nom. Si une chaîne de nom est spécifiée et que le nom donné n’est pas unique par rapport à sa clé contenante, les données d’une entrée de valeur existante sont remplacées.

[in, optional] TitleIndex

Ce paramètre est réservé. Les pilotes d’appareil et intermédiaires doivent définir ce paramètre sur zéro.

[in] Type

L’un des types de données définis par le système suivants à écrire :

Valeur de type	Signification
REG_BINARY	Données binaires dans tout formulaire.
REG_DWORD	Valeur numérique de 4 octets.
REG_DWORD_LITTLE_ENDIAN	Valeur numérique de 4 octets avec l’octet le moins significatif à l’adresse la plus basse. Identique à REG_DWORD.
REG_DWORD_BIG_ENDIAN	Valeur numérique de 4 octets avec l’octet le moins significatif à l’adresse la plus élevée.
REG_EXPAND_SZ	Chaîne Unicode terminée par null qui contient des références non expirées à des variables d’environnement, telles que « %PATH% ».
REG_LINK	Chaîne Unicode qui nomme un lien symbolique. Ce type n’est pas pertinent pour les pilotes d’appareil et intermédiaires.
REG_MULTI_SZ	Tableau de chaînes terminées par null, terminées par un autre zéro.
REG_NONE	Données sans type particulier.
REG_SZ	Chaîne Unicode terminée par null.
REG_RESOURCE_LIST	Liste des ressources matérielles d’un pilote de périphérique, utilisée par le pilote ou l’un des périphériques physiques qu’il contrôle, dans l’arborescence \ResourceMap
REG_RESOURCE_REQUIREMENTS_LIST	Liste d’un pilote de périphérique des ressources matérielles possibles qu’il ou l’un des appareils physiques qu’il contrôle peut utiliser, à partir desquels le système écrit un sous-ensemble dans l’arborescence \ResourceMap
REG_FULL_RESOURCE_DESCRIPTOR	Liste des ressources matérielles qu’un appareil physique utilise, détecte et écrit dans l’arborescence \HardwareDescription par le système

Les pilotes de périphérique ne doivent pas tenter d’appeler ZwSetValueKey pour écrire explicitement des entrées de valeur dans une sous-clé de la clé \Registry...\ResourceMap . Seul le système peut écrire des entrées de valeur dans l’arborescence \Registry...\HardwareDescription .

[in, optional] Data

Pointeur vers une mémoire tampon allouée à l’appelant qui contient les données de l’entrée de valeur.

[in] DataSize

Spécifie la taille, en octets, de la mémoire tampon de données . Si Type est REG_XXX_SZ, cette valeur doit inclure de l’espace pour les zéros de fin.

Valeur retournée

ZwSetValueKey retourne STATUS_SUCCESS si l’opération réussit. Sinon, cette routine peut retourner l’une des valeurs suivantes :

Code de retour	Description
STATUS_ACCESS_DENIED	L’appelant n’a pas l’accès approprié à la valeur du Registre.
STATUS_INVALID_HANDLE	Le handle n'est pas valide.

Remarques

Le KeyHandle passé à ZwSetValueKey doit avoir été ouvert avec l’indicateur DesiredAccess KEY_SET_VALUE défini pour que cet appel réussisse. Pour obtenir une description des valeurs possibles pour DesiredAccess, consultez ZwCreateKey.

Si la clé donnée n’a pas d’entrée de valeur existante avec un nom correspondant au ValueName donné, ZwSetValueKey crée une entrée de valeur avec le nom donné. S’il existe un nom d’entrée de valeur correspondant, cette routine remplace l’entrée de valeur d’origine pour le ValueName donné. Ainsi, ZwSetValueKey conserve un nom unique pour chaque entrée de valeur d’une clé particulière. Bien que chaque nom d’entrée de valeur soit unique à sa clé contenante, de nombreuses clés différentes dans le Registre peuvent avoir des entrées de valeur portant les mêmes noms.

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 « NtSetValueKey » au lieu de « ZwSetValueKey ».

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 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 Utilisation des versions Nt et Zw des routines des services système natifs.

Configuration requise

Condition requise	Valeur
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),IrqlZwPassive(wdm), PowerIrpDDis(wdm), ZwRegistryCreate(storport),ZwRegistryCreate(storport), ZwRegistryCreate(wdm), ZwRegistryOpen(storport), ZwRegistryOpen(storport), ZwRegistryOpen(wdm)