RegSetValueExW, fonction (winreg.h)

Article
11/20/2024

Définit les données et le type d’une valeur spécifiée sous une clé de Registre.

Syntaxe

LSTATUS RegSetValueExW(
  [in]           HKEY       hKey,
  [in, optional] LPCWSTR    lpValueName,
                 DWORD      Reserved,
  [in]           DWORD      dwType,
  [in]           const BYTE *lpData,
  [in]           DWORD      cbData
);

Paramètres

[in] hKey

Handle vers une clé de Registre ouverte. La clé doit avoir été ouverte avec le droit d’accès KEY_SET_VALUE. Pour plus d’informations, consultez sécurité des clés de Registre et droits d’accès.

Ce handle est retourné par le RegCreateKeyEx, RegCreateKeyTransacted, RegOpenKeyExou fonction RegOpenKeyTransacted. Il peut également s’agir de l’une des clés prédéfinies:

HKEY_CLASSES_ROOT

HKEY_CURRENT_CONFIG

HKEY_CURRENT_USER

HKEY_LOCAL_MACHINE

HKEY_USERS

La version Unicode de cette fonction prend en charge les clés prédéfinies suivantes :

HKEY_PERFORMANCE_TEXT
HKEY_PERFORMANCE_NLSTEXT

[in, optional] lpValueName

Nom de la valeur à définir. Si une valeur portant ce nom n’est pas déjà présente dans la clé, la fonction l’ajoute à la clé.

Si lpValueName est NULL ou une chaîne vide, « », la fonction définit le type et les données de la valeur sans nom ou par défaut de la clé.

Pour plus d’informations, consultez Limites de taille des éléments de Registre.

Les clés de Registre n’ont pas de valeurs par défaut, mais elles peuvent avoir une valeur sans nom, qui peut être de n’importe quel type.

Reserved

Ce paramètre est réservé et doit être égal à zéro.

[in] dwType

Type de données pointé par le paramètre lpData. Pour obtenir la liste des types possibles, consultez Types de valeurs de Registre.

[in] lpData

Données à stocker.

Pour les types basés sur des chaînes, tels que REG_SZ, la chaîne doit être null-terminated. Avec le type de données REG_MULTI_SZ, la chaîne doit être arrêtée avec deux caractères null.

Remarque lpData indiquant qu’une valeur de null est valide. Toutefois, si c’est le cas, cbData doit avoir la valeur « 0 ».

[in] cbData

Taille des informations pointées par le paramètre lpData , en octets. Si les données sont de type REG_SZ, REG_EXPAND_SZ ou REG_MULTI_SZ, cbData doivent inclure la taille de l'caractère ou des caractères null null.

Valeur de retour

Si la fonction réussit, la valeur de retour est ERROR_SUCCESS.

Si la fonction échoue, la valeur de retour est un code d’erreur différent de zéro défini dans Winerror.h. Vous pouvez utiliser la fonction FormatMessage avec l’indicateur de FORMAT_MESSAGE_FROM_SYSTEM pour obtenir une description générique de l’erreur.

Remarques

Les tailles de valeur sont limitées par la mémoire disponible. Toutefois, le stockage de valeurs volumineuses dans le Registre peut affecter ses performances. Les valeurs longues (plus de 2 048 octets) doivent être stockées en tant que fichiers, avec les emplacements des fichiers stockés dans le Registre.

Les éléments d’application tels que les icônes, les bitmaps et les fichiers exécutables doivent être stockés en tant que fichiers et non placés dans le Registre.

Si dwType est le REG_SZ, REG_MULTI_SZ ou REG_EXPAND_SZ type et que la version ANSI de cette fonction est utilisée (soit en appelant explicitement RegSetValueExA, soit en ne définissant pas UNICODE avant d’inclure le fichier Windows.h), les données pointées par le paramètre lpData doivent être une chaîne de caractères ANSI. La chaîne est convertie en Unicode avant qu’elle ne soit stockée dans le Registre.

Notez que les opérations qui accèdent à certaines clés de Registre sont redirigées. Pour plus d’informations, consultez Registry Virtualization et données d’application 32 bits et 64 bits dans le registre.

Envisagez d’utiliser la fonction RegSetKeyValue, qui offre un moyen plus pratique de définir la valeur d’une clé de Registre.

Note

L’en-tête winreg.h définit RegSetValueEx comme alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. Le mélange de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.

Exigences

Exigence	Valeur
client minimum pris en charge	Windows 2000 Professionnel [applications de bureau uniquement]
serveur minimum pris en charge	Windows 2000 Server [applications de bureau uniquement]
plateforme cible	Windows
d’en-tête	winreg.h (inclure Windows.h)
bibliothèque	Advapi32.lib
DLL	Advapi32.dll