RegGetValueA, fonction (winreg.h)
Récupère le type et les données pour la valeur de Registre spécifiée.
Syntaxe
LSTATUS RegGetValueA(
[in] HKEY hkey,
[in, optional] LPCSTR lpSubKey,
[in, optional] LPCSTR lpValue,
[in, optional] DWORD dwFlags,
[out, optional] LPDWORD pdwType,
[out, optional] PVOID pvData,
[in, out, optional] LPDWORD pcbData
);
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_PERFORMANCE_DATA
- HKEY_PERFORMANCE_NLSTEXT
- HKEY_PERFORMANCE_TEXT
- HKEY_USERS
[in, optional] lpSubKey
Chemin d’accès d’une clé de Registre par rapport à la clé spécifiée par le paramètre hkey . La valeur du Registre sera récupérée à partir de cette sous-clé.
Le chemin d’accès ne respecte pas la casse.
Si ce paramètre a la valeur NULL ou une chaîne vide, « », la valeur est lue à partir de la clé spécifiée par hkey elle-même.
[in, optional] lpValue
Nom de la valeur du Registre.
Si ce paramètre a la valeur NULL ou une chaîne vide, « », la fonction récupère le type et les données de la valeur sans nom ou par défaut de la clé, le cas échéant. Les clés n’ont pas automatiquement une valeur sans nom ou par défaut, et les valeurs sans nom peuvent être de n’importe quel type.
Pour plus d’informations, consultez Limites de taille des éléments du Registre.
[in, optional] dwFlags
Indicateurs qui limitent le type de données de la valeur à interroger. Si le type de données de la valeur ne répond pas à ce critère, la fonction échoue. Ce paramètre peut être une ou plusieurs des valeurs suivantes.
Ce paramètre peut également inclure une ou plusieurs des valeurs suivantes.
| Valeur | Signification |
|---|---|
|
Ne développez pas automatiquement les chaînes d’environnement si la valeur est de type REG_EXPAND_SZ. |
|
Si pvData n’a pas la valeur NULL, définissez le contenu de la mémoire tampon sur zéros en cas d’échec. |
|
Si lpSubKey n’a pas la valeur NULL, ouvrez la sous-clé spécifiée par lpSubKey avec les droits d’accès KEY_WOW64_64KEY.
Pour plus d’informations sur ces droits d’accès, consultez Sécurité de la clé de registre et droits d’accès.
Vous ne pouvez pas spécifier RRF_SUBKEY_WOW6464KEY en combinaison avec RRF_SUBKEY_WOW6432KEY. |
|
Si lpSubKey n’a pas la valeur NULL, ouvrez la sous-clé spécifiée par lpSubKey avec les droits d’accès KEY_WOW64_32KEY.
Pour plus d’informations sur ces droits d’accès, consultez Sécurité de la clé de registre et droits d’accès.
Vous ne pouvez pas spécifier RRF_SUBKEY_WOW6432KEY en combinaison avec RRF_SUBKEY_WOW6464KEY. |
[out, optional] pdwType
Pointeur vers une variable qui reçoit un code indiquant le type de données stockées dans la valeur spécifiée. Pour obtenir la liste des codes de type possibles, consultez Types de valeurs de registre. Ce paramètre peut avoir la valeur NULL si le type n’est pas obligatoire.
[out, optional] pvData
Pointeur vers une mémoire tampon qui reçoit les données de la valeur. Ce paramètre peut avoir la valeur NULL si les données ne sont pas requises.
Si les données sont une chaîne, la fonction recherche un caractère null de fin. Si l’une d’elles est introuvable, la chaîne est stockée avec une terminaison null si la mémoire tampon est suffisamment grande pour prendre en charge le caractère supplémentaire. Sinon, la fonction échoue et retourne ERROR_MORE_DATA.
[in, out, optional] pcbData
Pointeur vers une variable qui spécifie la taille de la mémoire tampon pointée par le paramètre pvData , en octets. Lorsque la fonction retourne, cette variable contient la taille des données copiées dans pvData.
Le paramètre pcbData ne peut être NULL que si pvData a la valeur NULL.
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 par le paramètre pvData 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 pcbData. Dans ce cas, le contenu de la mémoire tampon pvData est égal à zéro si dwFlags spécifie RRF_ZEROONFAILURE et non défini dans le cas contraire.
Si pvData a la valeur NULL et que pcbData 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 pcbData. Cela permet à une application de déterminer la meilleure façon d’allouer une mémoire tampon pour les données de la valeur.
Si hKey spécifie HKEY_PERFORMANCE_DATA et que la mémoire tampon pvData n’est pas assez grande pour contenir toutes les données retournées, la fonction retourne ERROR_MORE_DATA et la valeur retournée par le paramètre pcbData n’est pas définie. En effet, la taille des données de performances peut changer d’un appel à l’autre. Dans ce cas, vous devez augmenter la taille de la mémoire tampon et appeler à nouveau RegGetValue en passant la taille de mémoire tampon mise à jour dans le paramètre pcbData . Répétez cette opération jusqu’à ce que la fonction réussisse. Vous devez conserver une variable distincte pour effectuer le suivi de la taille de la mémoire tampon, car la valeur retournée par pcbData est imprévisible.
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 pvData est trop petite pour recevoir la valeur, la fonction retourne ERROR_MORE_DATA.
Si la valeur de Registre lpValue n’existe pas, la fonction retourne ERROR_FILE_NOT_FOUND.
Si dwFlags spécifie une combinaison de RRF_SUBKEY_WOW6464KEY et de RRF_SUBKEY_WOW6432KEY, la fonction retourne ERROR_INVALID_PARAMETER.
Remarques
Une application appelle généralement RegEnumValue pour déterminer les noms de valeur, puis RegGetValue pour récupérer les données des noms.
Si les données ont 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 RegGetValueA , 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 vers laquelle pvData pointe.
Lors de l’appel de cette fonction avec hkey défini sur le handle HKEY_PERFORMANCE_DATA et une chaîne de valeur d’un objet spécifié, la structure de données retournée a parfois des objets non interrogés. Ne soyez pas surpris; il s’agit d’un comportement normal. Vous devez toujours vous attendre à parcourir la structure de données retournée pour rechercher l’objet demandé.
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.
Pour compiler une application qui utilise cette fonction, définissez _WIN32_WINNT comme 0x0600 ou version ultérieure. Pour plus d’informations, consultez Utilisation des en-têtes Windows.
Notes
L’en-tête winreg.h définit RegGetValue en tant qu’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. La combinaison 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 Vista, Windows XP Professionnel Édition x64 |
| Serveur minimal pris en charge | Windows Server 2008, Windows Server 2003 avec SP1 |
| Plateforme cible | Windows |
| En-tête | winreg.h (inclure Windows.h) |
| Bibliothèque | Advapi32.lib |
| DLL | Advapi32.dll |