Fonction RegQueryValueA (winreg.h)

Article
08/27/2023

Récupère les données associées à la valeur par défaut ou sans nom d’une clé de Registre spécifiée. Les données doivent être une chaîne terminée par null.

Note Cette fonction est fournie uniquement pour la compatibilité avec les versions 16 bits de Windows. Les applications doivent utiliser la fonction RegQueryValueEx .

Syntaxe

LSTATUS RegQueryValueA(
  [in]                HKEY   hKey,
  [in, optional]      LPCSTR lpSubKey,
  [out, optional]     LPSTR  lpData,
  [in, out, optional] PLONG  lpcbData
);

Paramètres

[in] hKey

Handle d’une clé de Registre ouverte. La clé doit avoir été ouverte avec le droit d’accès KEY_QUERY_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

[in, optional] lpSubKey

Nom de la sous-clé du paramètre hKey pour lequel la valeur par défaut est récupérée.

Les noms de clés ne respectent pas la casse.

Si ce paramètre a la valeur NULL ou pointe vers une chaîne vide, la fonction récupère la valeur par défaut de la clé identifiée par hKey.

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

[out, optional] lpData

Pointeur vers une mémoire tampon qui reçoit la valeur par défaut de la clé spécifiée.

Si lpValue a la valeur NULL et que lpcbValue n’a pas la valeur NULL, la fonction retourne ERROR_SUCCESS et stocke la taille des données, en octets, dans la variable pointée par lpcbValue. Cela permet à une application de déterminer la meilleure façon d’allouer une mémoire tampon pour les données de la valeur.

[in, out, optional] lpcbData

Pointeur vers une variable qui spécifie la taille de la mémoire tampon pointée vers le paramètre lpValue , en octets. Lorsque la fonction retourne, cette variable contient la taille des données copiées dans lpValue, y compris les caractères null de fin.

Si les données ont le type REG_SZ, REG_MULTI_SZ ou REG_EXPAND_SZ, cette taille inclut le ou les caractères null de fin. Pour plus d'informations, consultez la section Notes.

Si la mémoire tampon spécifiée lpValue n’est pas assez grande pour contenir les données, la fonction retourne ERROR_MORE_DATA et stocke la taille de mémoire tampon requise dans la variable pointée par lpcbValue. Dans ce cas, le contenu de la mémoire tampon lpValue n’est pas défini.

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 système.

Si la mémoire tampon lpValue est trop petite pour recevoir la valeur, la fonction retourne ERROR_MORE_DATA.

Remarques

Si la version ANSI de cette fonction est utilisée (soit en appelant explicitement RegQueryValueA , soit en ne définissant pas UNICODE avant d’inclure le fichier Windows.h), cette fonction convertit la chaîne Unicode stockée en chaîne ANSI avant de la copier dans la mémoire tampon spécifiée par le paramètre lpValue .

Si les données ont le type REG_SZ, REG_MULTI_SZ ou REG_EXPAND_SZ, la chaîne n’a peut-être pas été stockée avec les caractères de fin null appropriés. Par conséquent, même si la fonction retourne ERROR_SUCCESS, l’application doit s’assurer que la chaîne est correctement arrêtée avant de l’utiliser ; sinon, il peut remplacer une mémoire tampon. (Notez que REG_MULTI_SZ chaînes doivent avoir deux caractères de fin null.)

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.

Notes

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


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