Funzione RegEnumKeyExA (winreg.h)

Articolo
03/11/2023

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

Sintassi

LSTATUS RegEnumKeyExA(
  [in]                HKEY      hKey,
  [in]                DWORD     dwIndex,
  [out]               LPSTR     lpName,
  [in, out]           LPDWORD   lpcchName,
                      LPDWORD   lpReserved,
  [in, out]           LPSTR     lpClass,
  [in, out, optional] LPDWORD   lpcchClass,
  [out, optional]     PFILETIME lpftLastWriteTime
);

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_PERFORMANCE_DATA

HKEY_USERS

[in] dwIndex

Indice della sottochiave da recuperare. Questo parametro deve essere zero per la prima chiamata alla funzione RegEnumKeyEx 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. La funzione copia solo il nome della sottochiave, non la gerarchia di chiavi completa, nel buffer.

Se la funzione ha esito negativo, non viene copiata alcuna informazione nel buffer.

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

[in, out] lpcchName

Puntatore a una variabile che specifica le dimensioni del buffer specificato dal parametro lpName , in caratteri. Questa dimensione deve includere il carattere Null di terminazione. Se la funzione ha esito positivo, la variabile a cui punta lpcchName contiene il numero di caratteri archiviati nel buffer, senza includere il carattere Null di terminazione.

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 .

lpReserved

Questo parametro è riservato e deve essere NULL.

[in, out] lpClass

Puntatore a un buffer che riceve la classe definita dall'utente della sottochiave enumerata. Questo parametro può essere NULL.

[in, out, optional] lpcchClass

Puntatore a una variabile che specifica le dimensioni del buffer specificato dal parametro lpClass , in caratteri. Le dimensioni devono includere il carattere Null di terminazione. Se la funzione ha esito positivo, lpcchClass contiene il numero di caratteri archiviati nel buffer, senza includere il carattere null di terminazione. Questo parametro può essere NULL solo se lpClass è NULL.

[out, optional] lpftLastWriteTime

Puntatore alla struttura FILETIME che riceve l'ora dell'ultima scrittura della sottochiave enumerata. Questo parametro può essere NULL.

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 RegEnumKeyEx con il parametro dwIndex impostato su zero. L'applicazione deve quindi incrementare il parametro dwIndex e chiamare RegEnumKeyEx 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 sottochiave nella prima chiamata alla funzione e decrementare l'indice fino a quando non viene enumerata la sottochiave con l'indice 0. Per recuperare l'indice dell'ultima sottochiave, usare la funzione RegQueryInfoKey .

Mentre un'applicazione usa la funzione RegEnumKeyEx , non deve effettuare chiamate ad alcuna funzione di registrazione che potrebbe modificare la chiave da enumerare.

Si noti che le operazioni che accedono a determinate chiavi del Registro di sistema vengono reindirizzate. Per altre informazioni, vedere Virtualizzazione del Registro di sistema e dati dell'applicazione a 32 bit e a 64 bit nel Registro di sistema.

Nota

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

Esempio

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

Nota

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