Funzione RegGetValueA (winreg.h)

Articolo
11/20/2024

Recupera il tipo e i dati per il valore del Registro di sistema specificato.

Sintassi

LSTATUS RegGetValueA(
  [in]                HKEY    hkey,
  [in, optional]      LPCSTR  lpSubKey,
  [in, optional]      LPCSTR  lpValue,
  [in, optional]      DWORD   dwFlags,
  [out, optional]     LPDWORD pdwType,
  [out, optional]     PVOID   pvData,
  [in, out, optional] LPDWORD pcbData
);

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] lpSubKey

Percorso di una chiave del Registro di sistema relativa alla chiave specificata dal parametro hkey . Il valore del Registro di sistema verrà recuperato da questa sottochiave.

Il percorso non fa distinzione tra maiuscole e minuscole.

Se questo parametro è NULL o una stringa vuota, "", il valore verrà letto dalla chiave specificata da hkey stessa.

[in, optional] lpValue

Nome del valore del Registro di sistema.

Se questo parametro è null o una stringa vuota, "", la funzione recupera il tipo e i dati per il valore predefinito o senza nome della chiave, se presente. Le chiavi non hanno automaticamente un valore senza nome o predefinito e i valori senza nome possono essere di qualsiasi tipo.

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

[in, optional] dwFlags

Flag che limitano il tipo di dati del valore su cui eseguire query. Se il tipo di dati del valore non soddisfa questi criteri, la funzione ha esito negativo. Questo parametro può essere uno o più dei valori seguenti.

Valore	Significato
RRF_RT_ANY 0x0000ffff	Nessuna restrizione del tipo.
RRF_RT_DWORD 0x00000018	Limitare il tipo a RRF_RT_REG_BINARY a 32 bit \| RRF_RT_REG_DWORD.
RRF_RT_QWORD 0x00000048	Limitare il tipo a RRF_RT_REG_BINARY a 64 bit \| RRF_RT_REG_QWORD.
RRF_RT_REG_BINARY 0x00000008	Limitare il tipo a REG_BINARY.
RRF_RT_REG_DWORD 0x00000010	Limitare il tipo a REG_DWORD.
RRF_RT_REG_EXPAND_SZ 0x00000004	Limitare il tipo a REG_EXPAND_SZ.
RRF_RT_REG_MULTI_SZ 0x00000020	Limitare il tipo a REG_MULTI_SZ.
RRF_RT_REG_NONE 0x00000001	Limitare il tipo a REG_NONE.
RRF_RT_REG_QWORD 0x00000040	Limitare il tipo a REG_QWORD.
RRF_RT_REG_SZ 0x00000002	Limitare il tipo a REG_SZ.

Questo parametro può includere anche uno o più dei valori seguenti.

Valore	Significato
RRF_NOEXPAND 0x10000000	Non espandere automaticamente le stringhe di ambiente se il valore è di tipo REG_EXPAND_SZ.
RRF_ZEROONFAILURE 0x20000000	Se pvData non è NULL, impostare il contenuto del buffer su zero in caso di errore.
RRF_SUBKEY_WOW6464KEY 0x00010000	Se lpSubKey non è null, aprire la sottochiave che lpSubKey specifica con i diritti di accesso KEY_WOW64_64KEY. Per informazioni su questi diritti di accesso, vedere sicurezza delle chiavi del Registro di sistema e diritti di accesso. Non è possibile specificare RRF_SUBKEY_WOW6464KEY in combinazione con RRF_SUBKEY_WOW6432KEY.
RRF_SUBKEY_WOW6432KEY 0x00020000	Se lpSubKey non è NULL, aprire la sottochiave che lpSubKey specifica con i diritti di accesso KEY_WOW64_32KEY. Per informazioni su questi diritti di accesso, vedere sicurezza delle chiavi del Registro di sistema e diritti di accesso. Non è possibile specificare RRF_SUBKEY_WOW6432KEY in combinazione con RRF_SUBKEY_WOW6464KEY.

[out, optional] pdwType

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. Questo parametro può essere null se il tipo non è obbligatorio.

[out, optional] pvData

Puntatore a un buffer che riceve i dati del valore. Questo parametro può essere null se i dati non sono necessari.

Se i dati sono una stringa, la funzione controlla la presenza di un carattere di terminazione null. Se non viene trovato, la stringa viene archiviata con un carattere di terminazione null null se il buffer è sufficientemente grande per contenere il carattere aggiuntivo. In caso contrario, la funzione ha esito negativo e restituisce ERROR_MORE_DATA.

[in, out, optional] pcbData

Puntatore a una variabile che specifica le dimensioni del buffer a cui punta il parametro pvData in byte. Quando la funzione termina, questa variabile contiene le dimensioni dei dati copiati in pvData.

Il parametro pcbData può essere NULL solo se pvData è NULL.

Se i dati hanno il REG_SZ, REG_MULTI_SZ o REG_EXPAND_SZ tipo, questa dimensione include qualsiasi carattere o carattere null terminazione . Per altre informazioni, vedere Osservazioni.

Se il buffer specificato da parametro pvData 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 pcbData. In questo caso, il contenuto del buffer pvData è zero se dwFlags specifica RRF_ZEROONFAILURE e non definito in caso contrario.

Se pvData è NULLe pcbData non èNULL, la funzione restituisce ERROR_SUCCESS e archivia le dimensioni dei dati, in byte, nella variabile a cui punta pcbData. 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 pvData non è sufficiente per contenere tutti i dati restituiti, la funzione restituisce ERROR_MORE_DATA e il valore restituito tramite il parametro pcbData 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 RegGetValue passando nuovamente le dimensioni aggiornate del buffer nel parametro pcbData. 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 pcbData è imprevedibile.

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 pvData è troppo piccolo per ricevere il valore, la funzione restituisce ERROR_MORE_DATA.

Se il valore del Registro di sistema lpValue non esiste, la funzione restituisce ERROR_FILE_NOT_FOUND.

Se dwFlags specifica una combinazione di RRF_SUBKEY_WOW6464KEY e RRF_SUBKEY_WOW6432KEY, la funzione restituisce ERROR_INVALID_PARAMETER.

Osservazioni

Un'applicazione chiama in genere RegEnumValue per determinare i nomi dei valori e quindi RegGetValue per recuperare i dati per i nomi.

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 RegGetValueA 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 pvData.

Quando si chiama questa funzione con hkey impostata sull'handle 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. È consigliabile prevedere sempre di esaminare la struttura dei dati restituita 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 Registry Virtualization e dati dell'applicazione a 32 bit e a 64 bit nel Registro di sistema.

Per compilare un'applicazione che usa questa funzione, definire _WIN32_WINNT come 0x0600 o versione successiva. Per altre informazioni, vedere Uso delle intestazioni di Windows.

Nota

L'intestazione winreg.h definisce RegGetValue 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 Vista, Windows XP Professional x64 Edition
server minimo supportato	Windows Server 2008, Windows Server 2003 con SP1
piattaforma di destinazione	Finestre
intestazione	winreg.h (include Windows.h)
libreria	Advapi32.lib
dll	Advapi32.dll