Fonction RegSetValueExA (winreg.h)

Article
08/27/2023

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

Syntaxe

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

Paramètres

[in] hKey

Handle d’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é de la clé de Registre et droits d’accès.

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

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 supplémentaires 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 a la valeur NULL ou une chaîne vide, « », la fonction définit le type et les données pour la valeur sans nom ou par défaut de la clé.

Pour plus d’informations, consultez Limites de taille des éléments du 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ée vers 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 terminée par null. Avec le type de données REG_MULTI_SZ, la chaîne doit être terminée par deux caractères null .

Notez lpData indiquant qu’une valeur null est valide. Toutefois, si c’est le cas, cbData doit être défini sur « 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 doit inclure la taille du ou des caractères null de fin.

Valeur retournée

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 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 sous forme de 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 ne doivent pas être placés dans le Registre.

Si dwType est le type REG_SZ, REG_MULTI_SZ ou REG_EXPAND_SZ 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 d’être 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 Virtualisation du Registre 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.

Notes

L’en-tête winreg.h définit RegSetValueEx comme un 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.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 2000 Professionnel [applications de bureau uniquement]
Serveur minimal pris en charge	Windows 2000 Server [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	winreg.h (inclure Windows.h)
Bibliothèque	Advapi32.lib
DLL	Advapi32.dll