Funzione RegEnumValueA (winreg.h)

Articolo
08/27/2023

Enumera i valori per la chiave del Registro di sistema aperta specificata. La funzione copia un nome di valore indicizzato e un blocco di dati per la chiave ogni volta che viene chiamato.

Sintassi

LSTATUS RegEnumValueA(
  [in]                HKEY    hKey,
  [in]                DWORD   dwIndex,
  [out]               LPSTR   lpValueName,
  [in, out]           LPDWORD lpcchValueName,
                      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 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_USERS

[in] dwIndex

Indice del valore da recuperare. Questo parametro deve essere zero per la prima chiamata alla funzione RegEnumValue e quindi essere incrementato per le chiamate successive.

Poiché i valori non sono ordinati, qualsiasi nuovo valore avrà un indice arbitrario. Ciò significa che la funzione può restituire valori in qualsiasi ordine.

[out] lpValueName

Puntatore a un buffer che riceve il nome del valore come stringa con terminazione Null.

Questo buffer deve essere abbastanza grande per includere il carattere Null terminante.

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

[in, out] lpcchValueName

Puntatore a una variabile che specifica le dimensioni del buffer a cui punta il parametro lpValueName , in caratteri. Quando la funzione restituisce, la variabile riceve il numero di caratteri archiviati nel buffer, non incluso il carattere Null di terminazione.

Se il buffer specificato da lpValueName non è sufficiente per contenere i dati, la funzione restituisce ERROR_MORE_DATA e la dimensione del buffer nella variabile a cui punta lpValueName non viene modificata. In questo caso, il contenuto di lpcchValueName non è definito.

I nomi dei valori del Registro di sistema sono limitati a 32.767 byte. La versione ANSI di questa funzione considera questo parametro come valore SHORT . Pertanto, se si specifica un valore maggiore di 32.767 byte, esiste un overflow e la funzione può restituire ERROR_MORE_DATA.

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 per la voce del valore. Questo parametro può essere NULL se i dati non sono necessari.

Se lpData è NULL e lpcbData non è NULL, la funzione 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.

[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 restituisce, la variabile riceve il numero di byte archiviati nel buffer.

Questo parametro può essere NULL solo se lpData è NULL.

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 da lpData non è sufficiente per 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 di lpData 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 non sono disponibili più valori, la funzione restituisce ERROR_NO_MORE_ITEMS.

Se il buffer specificato da lpValueName o lpData è troppo piccolo per ricevere il valore, la funzione restituisce ERROR_MORE_DATA.

Commenti

Per enumerare i valori, un'applicazione deve inizialmente chiamare la funzione RegEnumValue con il parametro dwIndex impostato su zero. L'applicazione deve quindi aumentare dwIndex e chiamare la funzione RegEnumValue fino a quando non sono presenti più valori (fino a quando la funzione restituisce ERROR_NO_MORE_ITEMS).

L'applicazione può anche impostare dwIndex sull'indice dell'ultimo valore nella prima chiamata alla funzione e decrerere l'indice fino a quando non viene enumerato il valore con indice 0. Per recuperare l'indice dell'ultimo valore, usare la funzione RegQueryInfoKey .

Durante l'uso di RegEnumValue, un'applicazione non deve chiamare alcuna funzione del Registro di sistema che potrebbe modificare la chiave sottoposta a query.

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.

Per determinare la dimensione massima del nome e dei buffer di dati, usare la funzione RegQueryInfoKey .

Nota

Nelle versioni legacy di Windows, questa API viene esposta anche da kernel32.dll.

Esempio

Per un esempio, vedere Enumerazione delle sottochiave del Registro di sistema.

Nota

L'intestazione winreg.h definisce RegEnumValue 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