Funzione RegEnumKeyA (winreg.h)

Articolo
08/27/2023

Enumera le sottochiavi della chiave del Registro di sistema aperta specificata. La funzione recupera il nome di una sottochiave ogni volta che viene chiamata.

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

Sintassi

LSTATUS RegEnumKeyA(
  [in]  HKEY  hKey,
  [in]  DWORD dwIndex,
  [out] LPSTR lpName,
  [in]  DWORD cchName
);

Parametri

[in] hKey

Handle per una chiave del Registro di sistema aperta. La chiave deve essere stata aperta con il diritto di accesso KEY_ENUMERATE_SUB_KEYS. 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] dwIndex

Indice della sottochiave di hKey da recuperare. Questo valore deve essere zero per la prima chiamata alla funzione RegEnumKey e quindi incrementato per le chiamate successive.

Poiché le sottochiavi non sono ordinate, qualsiasi nuova sottochiave avrà un indice arbitrario. Ciò significa che la funzione può restituire sottochiavi in qualsiasi ordine.

[out] lpName

Puntatore a un buffer che riceve il nome della sottochiave, incluso il carattere null terminante. Questa funzione copia solo il nome della sottochiave, non la gerarchia di chiavi completa, nel buffer.

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

[in] cchName

Dimensioni del buffer a cui punta il parametro lpName , in TCHAR. Per determinare le dimensioni del buffer necessarie, usare la funzione RegQueryInfoKey per determinare le dimensioni della sottochiave più grande per la chiave identificata dal parametro hKey .

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ù sottochiavi, la funzione restituisce ERROR_NO_MORE_ITEMS.

Se il buffer lpName è troppo piccolo per ricevere il nome della chiave, la funzione restituisce ERROR_MORE_DATA.

Commenti

Per enumerare le sottochiavi, un'applicazione deve inizialmente chiamare la funzione RegEnumKey con il parametro dwIndex impostato su zero. L'applicazione deve quindi incrementare il parametro dwIndex e chiamare la funzione RegEnumKey fino a quando non sono presenti più sottochiave (ovvero la funzione restituisce ERROR_NO_MORE_ITEMS).

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

Mentre un'applicazione usa la funzione RegEnumKey , non deve effettuare chiamate a alcuna funzione di registrazione che potrebbe modificare la chiave in esecuzione una query.

Nota

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

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