Funzione RegQueryValueExA (winreg.h)
Recupera il tipo e i dati per il nome di valore specificato associato a una chiave del Registro di sistema aperta.
Avvertimento
Se il valore sottoposto a query è una stringa (REG_SZ, REG_MULTI_SZ e REG_EXPAND_SZ) il valore restituito non è garantito che venga terminato null. Usare la funzione
Sintassi
LSTATUS RegQueryValueExA(
[in] HKEY hKey,
[in, optional] LPCSTR lpValueName,
LPDWORD lpReserved,
[out, optional] LPDWORD lpType,
[out, optional] LPBYTE lpData,
[in, out, optional] LPDWORD lpcbData
);
Parametri
[in] hKey
Handle per una chiave del Registro di sistema aperta. La chiave deve essere stata aperta con il diritto di accesso KEY_QUERY_VALUE. Per altre informazioni, vedere sicurezza delle chiavi del Registro di sistema e diritti di accesso.
Questo handle viene restituito dal RegCreateKeyEx, RegCreateKeyTransacted, RegOpenKeyExo funzione RegOpenKeyTransacted. Può anche essere una delle chiavi predefinite seguenti:
- 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
Nome del valore del Registro di sistema.
Se lpValueName è NULL o una stringa vuota, "", la funzione recupera il tipo e i dati per il valore predefinito o senza nome della chiave, se presente.
Se lpValueName specifica un valore non presente nel Registro di sistema, la funzione restituisce ERROR_FILE_NOT_FOUND.
Le chiavi non hanno automaticamente un valore senza nome o predefinito. I valori senza nome possono essere di qualsiasi tipo. Per altre informazioni, vedere Limiti delle dimensioni degli elementi del Registro di sistema .
lpReserved
Questo parametro è riservato e deve essere NULL.
[out, optional] lpType
Puntatore a una variabile che riceve un codice che indica il tipo di dati archiviati nel valore specificato. Per un elenco dei possibili codici di tipo, vedere Tipi di valore del Registro di sistema. Il parametro lpType
[out, optional] lpData
Puntatore a un buffer che riceve i dati del valore. Questo parametro può essere null se i dati non sono necessari.
[in, out, optional] lpcbData
Puntatore a una variabile che specifica le dimensioni del buffer a cui punta il parametro lpData, in byte. Quando la funzione termina, questa variabile contiene le dimensioni dei dati copiati in lpData.
Il parametro lpcbData
Se i dati hanno il REG_SZ, REG_MULTI_SZ o REG_EXPAND_SZ tipo, questa dimensione include qualsiasi carattere null carattere o caratteri, a meno che i dati non siano stati archiviati senza di essi. Per altre informazioni, vedere Osservazioni.
Se il buffer specificato da parametro lpData non è sufficientemente grande da contenere i dati, la funzione restituisce ERROR_MORE_DATA e archivia le dimensioni del buffer necessarie nella variabile a cui punta lpcbData. In questo caso, il contenuto del buffer di lpData non è definito.
Se lpData è NULLe lpcbData non èNULL, la funzione restituisce ERROR_SUCCESS e archivia le dimensioni dei dati, in byte, nella variabile a cui punta lpcbData. Ciò consente a un'applicazione di determinare il modo migliore per allocare un buffer per i dati del valore.
Se hKey specifica HKEY_PERFORMANCE_DATA e il buffer lpData non è sufficientemente grande da contenere tutti i dati restituiti, RegQueryValueEx restituisce ERROR_MORE_DATA e il valore restituito tramite il parametro lpcbData non è definito. Ciò è dovuto al fatto che le dimensioni dei dati sulle prestazioni possono variare da una chiamata a quella successiva. In questo caso, è necessario aumentare le dimensioni del buffer e chiamare
Se il valore lpValueName del Registro di sistema non esiste, RegQueryValueEx restituisce ERROR_FILE_NOT_FOUND e il valore restituito tramite il parametro lpcbData non è definito.
Valore restituito
Se la funzione ha esito positivo, il valore restituito è ERROR_SUCCESS.
Se la funzione ha esito negativo, il valore restituito è un codice di errore di sistema .
Se il buffer lpData è troppo piccolo per ricevere i dati, la funzione restituisce ERROR_MORE_DATA.
Se il valore lpValueName del Registro di sistema non esiste, la funzione restituisce ERROR_FILE_NOT_FOUND.
Osservazioni
Un'applicazione chiama in genere RegEnumValue per determinare i nomi dei valori e quindi RegQueryValueEx per recuperare i dati per i nomi.
Se i dati hanno il tipo REG_SZ, REG_MULTI_SZ o REG_EXPAND_SZ, è possibile che la stringa non sia stata archiviata con la terminazione corretta caratteri null. Pertanto, anche se la funzione restituisce ERROR_SUCCESS, l'applicazione deve assicurarsi che la stringa venga terminata correttamente prima di usarla; in caso contrario, può sovrascrivere un buffer. Si noti che REG_MULTI_SZ stringhe devono avere due caratteri di null
Se i dati hanno il REG_SZ, REG_MULTI_SZ o REG_EXPAND_SZ tipo e viene usata la versione ANSI di questa funzione (chiamando in modo esplicito RegQueryValueExA o non definendo UNICODE prima di includere il file Windows.h), questa funzione converte la stringa Unicode archiviata in una stringa ANSI prima di copiarla nel buffer a cui punta lpData.
Quando si chiama la funzione RegQueryValueEx con hKey impostata sull'handle di HKEY_PERFORMANCE_DATA e una stringa di valore di un oggetto specificato, la struttura dei dati restituita a volte include oggetti non richieste. Non essere sorpreso; questo comportamento è normale. Quando si chiama la funzione di
Si noti che le operazioni che accedono a determinate chiavi del Registro di sistema vengono reindirizzate. Per altre informazioni, vedere Registry Virtualization e dati dell'applicazione a 32 bit e a 64 bit nel Registro di sistema.
Esempi
Assicurarsi di reinizializzare il valore a cui punta il lpcbData parametro ogni volta che si chiama questa funzione. Questo è molto importante quando si chiama questa funzione in un ciclo, come nell'esempio di codice seguente.
#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);
}
Nota
L'intestazione winreg.h definisce RegQueryValueEx come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice non indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere convenzioni di per i prototipi di funzioni.
Fabbisogno
| Requisito | Valore |
|---|---|
| client minimo supportato | Windows 2000 Professional [solo app desktop] |
| server minimo supportato | Windows 2000 Server [solo app desktop] |
| piattaforma di destinazione | Finestre |
| intestazione |
winreg.h (include Windows.h) |
| libreria |
Advapi32.lib |
| dll | Advapi32.dll |