Funzione RegEnumKeyExA (winreg.h)

Articolo
11/20/2024

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 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 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 di terminazione null. La funzione copia solo il nome della sottochiave, non la gerarchia di chiavi completa, nel buffer.

Se la funzione non riesce, nessuna informazione viene copiata 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 di terminazione null. Se la funzione ha esito positivo, la variabile a cui punta lpcchName contiene il numero di caratteri archiviati nel buffer, senza includere il carattere di terminazione null.

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 di terminazione null. Se la funzione ha esito positivo, lpcchClass contiene il numero di caratteri archiviati nel buffer, senza includere il carattere di terminazione null. Questo parametro può essere null solo se lpClass è NULL.

[out, optional] lpftLastWriteTime

Puntatore a 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 è ERROR_SUCCESS.

Se la funzione ha esito negativo, il valore restituito è un codice di errore di sistema . Se non sono disponibili altre 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.

Osservazioni

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 altre 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 Registry Virtualization 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.

Esempi

Per un esempio, vedere Enumerating Registry Subkeys.

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