RegQueryValueExW, fonction (winreg.h)
Récupère le type et les données du 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), la valeur retournée n’est pas garantie d’être terminée par null. Utilisez la fonction RegGetValue si vous souhaitez vous assurer que les valeurs de chaîne retournées sont terminées par null. Vous trouverez plus d’informations dans les remarques ci-dessous.
Syntaxe
LSTATUS RegQueryValueExW(
[in] HKEY hKey,
[in, optional] LPCWSTR lpValueName,
LPDWORD lpReserved,
[out, optional] LPDWORD lpType,
[out, optional] LPBYTE lpData,
[in, out, optional] LPDWORD lpcbData
);
Paramètres
[in] hKey
Handle vers 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é 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_PERFORMANCE_DATA
- HKEY_PERFORMANCE_NLSTEXT
- HKEY_PERFORMANCE_TEXT
- HKEY_USERS
[in, optional] lpValueName
Nom de la valeur de Registre.
Si lpValueName est NULL ou une chaîne vide, « », la fonction récupère le type et les données de la valeur non nommée ou par défaut de la clé, le cas échéant.
Si lpValueName spécifie une valeur qui n’est pas dans le Registre, la fonction retourne ERROR_FILE_NOT_FOUND.
Les clés n’ont pas automatiquement de valeur non nommée ou par défaut. Les valeurs non nommées 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 de Registre. Le paramètre
[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 pointée par le paramètre lpData, en octets. Lorsque la fonction est retournée, cette variable contient la taille des données copiées dans lpData.
Le paramètre
Si les données ont la REG_SZ, REG_MULTI_SZ ou REG_EXPAND_SZ type, cette taille inclut toute fin caractère ou caractères null, sauf si les données ont été stockées sans eux. Pour plus d’informations, consultez Remarques.
Si la mémoire tampon spécifiée par 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
Si lpData est NULL et lpcbData n’est pasNULL, 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
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 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 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 valeurs, puis RegQueryValueEx pour récupérer les données des noms.
Si les données ont la REG_SZ, REG_MULTI_SZ ou REG_EXPAND_SZ type, la chaîne n’a peut-être pas été stockée avec la fin appropriée caractères null. 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 les chaînes REG_MULTI_SZ doivent avoir deux caractères
Si les données ont la REG_SZ, REG_MULTI_SZ ou REG_EXPAND_SZ type, et que la version ANSI de cette fonction est utilisée (en appelant explicitement RegQueryValueExA ou 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 pointée par lpData.
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 comporte parfois des objets non demandé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 Registry Virtualization et données d’application 32 bits et 64 bits dans le registre.
Exemples
Vérifiez que vous réinitialisez 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);
}
Note
L’en-tête winreg.h définit RegQueryValueEx 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 |