Funzione RegEnumKeyW (winreg.h)

Articolo
03/08/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 RegEnumKeyW(
  [in]  HKEY   hKey,
  [in]  DWORD  dwIndex,
  [out] LPWSTR 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 e diritti di accesso delle chiavi del Registro di sistema.

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 di terminazione. 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 viene 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ù sottochiavi( 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 decrementare l'indice fino a quando non viene enumerata la sottochiave con indice 0. Per recuperare l'indice dell'ultima sottochiave, usare RegQueryInfoKey.

Anche se un'applicazione usa la funzione RegEnumKey , non deve effettuare chiamate ad alcuna funzione di registrazione che potrebbe modificare la chiave su cui viene eseguita la 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 del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice che non è indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzioni.

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