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.

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 e diritti di accesso delle chiavi del Registro di sistema.

Questo handle viene restituito dalla funzione RegCreateKeyEx, RegCreateKeyTransacted, RegOpenKeyEx o 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 codici di tipo possibili, vedere Tipi di valore del Registro di sistema. Il parametro lpType può essere NULL se il codice di tipo non è obbligatorio.

[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 viene restituita, questa variabile contiene le dimensioni dei dati copiati in lpData.

Il parametro lpcbData può essere NULL solo se lpData è NULL.

Se i dati hanno il tipo di REG_SZ, REG_MULTI_SZ o REG_EXPAND_SZ, queste dimensioni includono qualsiasi carattere o carattere Null di terminazione a meno che i dati non siano stati archiviati senza di essi. Per altre informazioni, vedere la sezione Osservazioni.

Se il buffer specificato dal 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 lpData non è definito.

Se lpData è NULL e lpcbData è diverso da 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 cambiare da una chiamata a quella successiva. In questo caso, è necessario aumentare le dimensioni del buffer e chiamare nuovamente RegQueryValueEx passando le dimensioni aggiornate del buffer nel parametro lpcbData . Ripetere questa operazione fino a quando la funzione non riesce. È necessario mantenere una variabile separata per tenere traccia delle dimensioni del buffer, perché il valore restituito da lpcbData è imprevedibile.

Se il valore del Registro di sistema lpValueName 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 viene 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 del Registro di sistema lpValueName non esiste, la funzione restituisce ERROR_FILE_NOT_FOUND.

Commenti

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 REG_SZ, REG_MULTI_SZ o REG_EXPAND_SZ tipo, è possibile che la stringa non sia stata archiviata con i caratteri null di terminazione appropriati. 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 Null di terminazione. Un modo in cui un'applicazione può garantire che la stringa venga terminata correttamente consiste nell'usare RegGetValue, che aggiunge caratteri Null terminanti, se necessario.

Se i dati hanno il tipo REG_SZ, REG_MULTI_SZ o REG_EXPAND_SZ e la versione ANSI di questa funzione viene usata (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 impostato sull'handle HKEY_PERFORMANCE_DATA e una stringa di valore di un oggetto specificato, la struttura dei dati restituita a volte include oggetti non richiesto. Non sorprendete; si tratta di un comportamento normale. Quando si chiama la funzione RegQueryValueEx , è sempre consigliabile eseguire la procedura dettagliata per cercare l'oggetto richiesto.

Si noti che le operazioni che accedono a determinate chiavi del Registro di sistema vengono reindirizzate. Per altre informazioni, vedere Virtualizzazione del Registro di sistema e dati dell'applicazione a 32 bit e a 64 bit nel Registro di sistema.

Esempio

Assicurarsi di reinizializzare il valore a cui punta il parametro lpcbData 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);
}

Requisiti

Vedi anche

ExpandEnvironmentStrings

RegCreateKeyEx

RegEnumKeyEx

RegEnumValue

RegGetValue

Regopenkeyex

RegQueryInfoKey

Funzioni del Registro di sistema

Panoramica del Registro di sistema