Función RegEnumKeyA (winreg.h)

Artículo
08/27/2023

Enumera las subclaves de la clave del Registro abierta especificada. La función recupera el nombre de una subclave cada vez que se llama.

Nota Esta función solo se proporciona por compatibilidad con versiones de 16 bits de Windows. Las aplicaciones deben usar la función RegEnumKeyEx .

Sintaxis

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

Parámetros

[in] hKey

Identificador de una clave del Registro abierta. La clave debe haberse abierto con el derecho de acceso KEY_ENUMERATE_SUB_KEYS. Para obtener más información, consulte Derechos de acceso y seguridad de clave del Registro.

Este identificador lo devuelve la función RegCreateKeyEx, RegCreateKeyTransacted, RegOpenKeyEx o RegOpenKeyTransacted . También puede ser una de las siguientes claves predefinidas:

HKEY_CLASSES_ROOT

HKEY_CURRENT_CONFIG

HKEY_CURRENT_USER

HKEY_LOCAL_MACHINE

HKEY_USERS

[in] dwIndex

Índice de la subclave de hKey que se va a recuperar. Este valor debe ser cero para la primera llamada a la función RegEnumKey y, a continuación, incrementarse para las llamadas posteriores.

Dado que las subclaves no están ordenadas, ninguna subclave nueva tendrá un índice arbitrario. Esto significa que la función puede devolver subclaves en cualquier orden.

[out] lpName

Puntero a un búfer que recibe el nombre de la subclave, incluido el carácter nulo de terminación. Esta función copia solo el nombre de la subclave, no la jerarquía de claves completa, en el búfer.

Para obtener más información, vea Límites de tamaño de elemento del Registro.

[in] cchName

Tamaño del búfer al que apunta el parámetro lpName , en TCHAR. Para determinar el tamaño de búfer necesario, use la función RegQueryInfoKey para determinar el tamaño de la subclave más grande para la clave identificada por el parámetro hKey .

Valor devuelto

Si la función se ejecuta correctamente, el valor devuelto es ERROR_SUCCESS.

Si se produce un error en la función, el valor devuelto es un código de error del sistema. Si no hay más subclaves disponibles, la función devuelve ERROR_NO_MORE_ITEMS.

Si el búfer lpName es demasiado pequeño para recibir el nombre de la clave, la función devuelve ERROR_MORE_DATA.

Comentarios

Para enumerar subclaves, una aplicación debe llamar inicialmente a la función RegEnumKey con el parámetro dwIndex establecido en cero. A continuación, la aplicación debe incrementar el parámetro dwIndex y llamar a la función RegEnumKey hasta que no haya más subclaves (lo que significa que la función devuelve ERROR_NO_MORE_ITEMS).

La aplicación también puede establecer dwIndex en el índice de la última clave de la primera llamada a la función y reducir el índice hasta que se enumera la subclave con el índice 0. Para recuperar el índice de la última subclave, use RegQueryInfoKey.

Mientras una aplicación usa la función RegEnumKey , no debe realizar llamadas a ninguna función de registro que pueda cambiar la clave que se está consultando.

Nota

El encabezado winreg.h define RegEnumKey como alias que selecciona automáticamente la versión ANSI o Unicode de esta función en función de la definición de la constante de preprocesador UNICODE. La combinación del uso del alias neutral de codificación con código que no es neutral de codificación puede dar lugar a errores de coincidencia que dan lugar a errores de compilación o tiempo de ejecución. Para obtener más información, vea Convenciones para prototipos de función.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows 2000 Professional [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows 2000 Server [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	winreg.h (incluye Windows.h)
Library	Advapi32.lib
Archivo DLL	Advapi32.dll