Funzione RegQueryValueA (winreg.h)

Articolo
08/27/2023

Recupera i dati associati al valore predefinito o senza nome di una chiave del Registro di sistema specificata. I dati devono essere una stringa con terminazione null.

Nota Questa funzione viene fornita solo per la compatibilità con le versioni a 16 bit di Windows. Le applicazioni devono usare la funzione RegQueryValueEx .

Sintassi

LSTATUS RegQueryValueA(
  [in]                HKEY   hKey,
  [in, optional]      LPCSTR lpSubKey,
  [out, optional]     LPSTR  lpData,
  [in, out, optional] PLONG  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 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_USERS

[in, optional] lpSubKey

Nome della sottochiave del parametro hKey per cui viene recuperato il valore predefinito.

I nomi delle chiavi non sono distinzione tra maiuscole e minuscole.

Se questo parametro è NULL o punta a una stringa vuota, la funzione recupera il valore predefinito per la chiave identificata da hKey.

Per altre informazioni, vedere Limiti delle dimensioni degli elementi del Registro di sistema.

[out, optional] lpData

Puntatore a un buffer che riceve il valore predefinito della chiave specificata.

Se lpValue è NULL e lpcbValue non è NULL, la funzione restituisce ERROR_SUCCESS e archivia le dimensioni dei dati, in byte, nella variabile a cui punta lpcbValue. Ciò consente a un'applicazione di determinare il modo migliore per allocare un buffer per i dati del valore.

[in, out, optional] lpcbData

Puntatore a una variabile che specifica le dimensioni del buffer a cui punta il parametro lpValue , in byte. Quando la funzione restituisce, questa variabile contiene le dimensioni dei dati copiati in lpValue, incluse eventuali caratteri null terminanti.

Se i dati hanno il REG_SZ, REG_MULTI_SZ o REG_EXPAND_SZ tipo, queste dimensioni includono qualsiasi carattere o caratteri null terminanti. Per altre informazioni, vedere la sezione Osservazioni.

Se il buffer specificato lpValue non è sufficiente per contenere i dati, la funzione restituisce ERROR_MORE_DATA e archivia le dimensioni del buffer necessarie nella variabile a cui punta lpcbValue. In questo caso, il contenuto del buffer lpValue 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 lpValue è troppo piccolo per ricevere il valore, la funzione restituisce ERROR_MORE_DATA.

Commenti

Se viene usata la versione ANSI di questa funzione (chiamando in modo esplicito RegQueryValueA 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 specificato dal parametro lpValue .

Se i dati hanno il REG_SZ, REG_MULTI_SZ o REG_EXPAND_SZ tipo, la stringa potrebbe non essere stata archiviata con i caratteri null-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-terminazione.

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.

Nota

L'intestazione winreg.h definisce RegQueryValue come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante preprocessore UNICODE. La combinazione dell'utilizzo dell'alias di codifica neutrale con il codice che non è neutrale dalla codifica può causare errori di corrispondenza che causano errori di compilazione o runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzione.

Requisiti


Client minimo supportato	Windows 2000 Professional [solo app desktop]
Server minimo supportato	Windows 2000 Server [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	winreg.h (include Windows.h)
Libreria	Advapi32.lib
DLL	Advapi32.dll