Funzione RegEnumValueA (winreg.h)

Articolo
11/20/2024

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 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_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 nullstringa con terminazione.

Questo buffer deve essere sufficientemente grande da includere il carattere di terminazione null.

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 termina, la variabile riceve il numero di caratteri archiviati nel buffer, senza includere il carattere di terminazione null.

Se il buffer specificato da lpValueName non è sufficientemente grande da contenere i dati, la funzione restituisce ERROR_MORE_DATA e le dimensioni del buffer nella variabile a cui punta lpValueName non vengono modificate. 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, è presente 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 possibili codici di tipo, 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 di 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 viene restituita, 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, questa dimensione include qualsiasi carattere o carattere null terminazione . Per altre informazioni, vedere Osservazioni.

Se il buffer specificato da 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 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 altri 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.

Osservazioni

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

L'applicazione può anche impostare dwIndex sull'indice dell'ultimo valore nella prima chiamata alla funzione e decrementare 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 funzioni del Registro di sistema che potrebbero modificare la chiave sottoposta a query.

Se i dati hanno il REG_SZ, REG_MULTI_SZ o il tipo di REG_EXPAND_SZ, è possibile che la stringa non sia stata archiviata con il nullcaratteri di terminazione. 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 le stringhe di REG_MULTI_SZ devono avere due -caratteri di terminazione.

Per determinare le dimensioni massime 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.

Esempi

Per un esempio, vedere Enumerating Registry Subkeys.

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