RegQueryValueExA, fonction (winreg.h)
Récupère le type et les données pour le nom de valeur spécifié associé à une clé de Registre ouverte.
Avertissement
Si la valeur interrogée est une chaîne (REG_SZ, REG_MULTI_SZ et REG_EXPAND_SZ), il n’est PAS garanti que la valeur retournée se termine par null. Utilisez la fonction RegGetValue si vous souhaitez vous assurer que les valeurs de chaîne retournées sont terminées par la valeur Null. Vous trouverez plus d’informations dans les remarques ci-dessous.
Syntaxe
LSTATUS RegQueryValueExA(
[in] HKEY hKey,
[in, optional] LPCSTR lpValueName,
LPDWORD lpReserved,
[out, optional] LPDWORD lpType,
[out, optional] LPBYTE lpData,
[in, out, optional] LPDWORD 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_PERFORMANCE_DATA
- HKEY_PERFORMANCE_NLSTEXT
- HKEY_PERFORMANCE_TEXT
- HKEY_USERS
[in, optional] lpValueName
Nom de la valeur de Registre.
Si lpValueName 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.
Si lpValueName spécifie une valeur qui ne figure pas dans le Registre, la fonction retourne ERROR_FILE_NOT_FOUND.
Les clés n’ont pas automatiquement de valeur sans nom ou par défaut. Les valeurs sans nom peuvent être de n’importe quel type. Pour plus d’informations, consultez Limites de taille des éléments de registre.
lpReserved
Ce paramètre est réservé et doit être NULL.
[out, optional] lpType
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 du Registre. Le paramètre lpType peut être NULL si le code de type n’est pas requis.
[out, optional] lpData
Pointeur vers une mémoire tampon qui reçoit les données de la valeur. Ce paramètre peut être NULL si les données ne sont pas requises.
[in, out, optional] lpcbData
Pointeur vers une variable qui spécifie la taille de la mémoire tampon vers laquelle pointe le paramètre lpData , en octets. Lorsque la fonction retourne, cette variable contient la taille des données copiées dans lpData.
Le paramètre lpcbData peut être NULL uniquement si lpData a la valeur NULL.
Si les données ont le type REG_SZ, REG_MULTI_SZ ou REG_EXPAND_SZ, cette taille inclut les caractères null de fin, sauf si les données ont été stockées sans eux. Pour plus d'informations, consultez la section Notes.
Si la mémoire tampon spécifiée par le paramètre lpData n’est pas suffisamment 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 lpcbData. Dans ce cas, le contenu de la mémoire tampon lpData n’est pas défini.
Si lpData a la valeur NULL et lpcbData n’est pas NULL, la fonction retourne ERROR_SUCCESS et stocke la taille des données, en octets, dans la variable pointée par lpcbData. 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 lpData n’est pas assez grande pour contenir toutes les données retournées, RegQueryValueEx retourne ERROR_MORE_DATA et la valeur retournée via le paramètre lpcbData 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 RegQueryValueEx en passant la taille de mémoire tampon mise à jour dans le paramètre lpcbData . 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 lpcbData est imprévisible.
Si la valeur de Registre lpValueName n’existe pas, RegQueryValueEx retourne ERROR_FILE_NOT_FOUND et la valeur retournée par le biais du paramètre lpcbData n’est pas définie.
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 lpData est trop petite pour recevoir les données, la fonction retourne ERROR_MORE_DATA.
Si la valeur de Registre lpValueName n’existe pas, la fonction retourne ERROR_FILE_NOT_FOUND.
Remarques
Une application appelle généralement RegEnumValue pour déterminer les noms de valeur, puis RegQueryValueEx 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, la chaîne n’a peut-être pas été stockée avec les caractères Null de fin appropriés. Par conséquent, même si la fonction retourne ERROR_SUCCESS, l’application doit s’assurer que la chaîne est correctement terminée avant de l’utiliser ; dans le cas contraire, il peut remplacer une mémoire tampon. (Notez que les chaînes REG_MULTI_SZ doivent avoir deux caractères null de fin.) Une façon pour une application de s’assurer que la chaîne est correctement terminée consiste à utiliser RegGetValue, qui ajoute des caractères null de fin si nécessaire.
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 RegQueryValueExA , 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 lpData pointe.
Lors de l’appel de la fonction RegQueryValueEx 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 contient parfois des objets non interrogés. Ne soyez pas surpris; il s’agit d’un comportement normal. Lorsque vous appelez la fonction RegQueryValueEx , 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.
Exemples
Veillez à réinitialiser la valeur pointée par le paramètre lpcbData chaque fois que vous appelez cette fonction. Cela est très important lorsque vous appelez cette fonction dans une boucle, comme dans l’exemple de code suivant.
#include <windows.h>
#include <malloc.h>
#include <stdio.h>
#define TOTALBYTES 8192
#define BYTEINCREMENT 4096
void main()
{
DWORD BufferSize = TOTALBYTES;
DWORD cbData;
DWORD dwRet;
PPERF_DATA_BLOCK PerfData = (PPERF_DATA_BLOCK) malloc( BufferSize );
cbData = BufferSize;
printf("\nRetrieving the data...");
dwRet = RegQueryValueEx( HKEY_PERFORMANCE_DATA,
TEXT("Global"),
NULL,
NULL,
(LPBYTE) PerfData,
&cbData );
while( dwRet == ERROR_MORE_DATA )
{
// Get a buffer that is big enough.
BufferSize += BYTEINCREMENT;
PerfData = (PPERF_DATA_BLOCK) realloc( PerfData, BufferSize );
cbData = BufferSize;
printf(".");
dwRet = RegQueryValueEx( HKEY_PERFORMANCE_DATA,
TEXT("Global"),
NULL,
NULL,
(LPBYTE) PerfData,
&cbData );
}
if( dwRet == ERROR_SUCCESS )
printf("\n\nFinal buffer size is %d\n", BufferSize);
else printf("\nRegQueryValueEx failed (%d)\n", dwRet);
}
Notes
L’en-tête winreg.h définit RegQueryValueEx 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 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 |