Función RegEnumValueA (winreg.h)

Artículo
03/08/2023

Enumera los valores de la clave del Registro abierta especificada. La función copia un nombre de valor indexado y un bloque de datos para la clave cada vez que se llama a él.

Sintaxis

LSTATUS RegEnumValueA(
  [in]                HKEY    hKey,
  [in]                DWORD   dwIndex,
  [out]               LPSTR   lpValueName,
  [in, out]           LPDWORD lpcchValueName,
                      LPDWORD lpReserved,
  [out, optional]     LPDWORD lpType,
  [out, optional]     LPBYTE  lpData,
  [in, out, optional] LPDWORD lpcbData
);

Parámetros

[in] hKey

Identificador de una clave del Registro abierta. La clave debe haberse abierto con el derecho de acceso KEY_QUERY_VALUE. 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_PERFORMANCE_DATA

HKEY_USERS

[in] dwIndex

Índice del valor que se va a recuperar. Este parámetro debe ser cero para la primera llamada a la función RegEnumValue y, a continuación, incrementarse para las llamadas posteriores.

Dado que los valores no están ordenados, ningún nuevo valor tendrá un índice arbitrario. Esto significa que la función puede devolver valores en cualquier orden.

[out] lpValueName

Puntero a un búfer que recibe el nombre del valor como una cadena terminada en NULL.

Este búfer debe ser lo suficientemente grande como para incluir el carácter nulo de terminación.

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

[in, out] lpcchValueName

Puntero a una variable que especifica el tamaño del búfer al que apunta el parámetro lpValueName , en caracteres. Cuando se devuelve la función, la variable recibe el número de caracteres almacenados en el búfer, sin incluir el carácter nulo de terminación.

Si el búfer especificado por lpValueName no es lo suficientemente grande como para contener los datos, la función devuelve ERROR_MORE_DATA y el tamaño del búfer en la variable a la que apunta lpValueName no cambia. En este caso, el contenido de lpcchValueName no está definido.

Los nombres de valor del Registro están limitados a 32 767 bytes. La versión ANSI de esta función trata este parámetro como un valor SHORT . Por lo tanto, si especifica un valor mayor que 32 767 bytes, hay un desbordamiento y la función puede devolver ERROR_MORE_DATA.

lpReserved

Este parámetro está reservado y debe ser NULL.

[out, optional] lpType

Puntero a una variable que recibe un código que indica el tipo de datos almacenados en el valor especificado. Para obtener una lista de los posibles códigos de tipo, vea Tipos de valor del Registro. El parámetro lpType puede ser NULL si el código de tipo no es necesario.

[out, optional] lpData

Puntero a un búfer que recibe los datos de la entrada de valor. Este parámetro puede ser NULL si los datos no son necesarios.

Si lpData es NULL y lpcbData no es NULL, la función almacena el tamaño de los datos, en bytes, en la variable a la que apunta lpcbData. Esto permite a una aplicación determinar la mejor manera de asignar un búfer para los datos.

[in, out, optional] lpcbData

Puntero a una variable que especifica el tamaño del búfer al que apunta el parámetro lpData , en bytes. Cuando se devuelve la función, la variable recibe el número de bytes almacenados en el búfer.

Este parámetro solo puede ser NULL si lpData es NULL.

Si los datos tienen el REG_SZ, REG_MULTI_SZ o REG_EXPAND_SZ tipo, este tamaño incluye cualquier carácter o carácter nulo de terminación. Para obtener más información, vea la sección Comentarios.

Si el búfer especificado por lpData no es lo suficientemente grande como para contener los datos, la función devuelve ERROR_MORE_DATA y almacena el tamaño de búfer necesario en la variable a la que apunta lpcbData. En este caso, el contenido de lpData no está definido.

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 valores disponibles, la función devuelve ERROR_NO_MORE_ITEMS.

Si el búfer especificado por lpValueName o lpData es demasiado pequeño para recibir el valor, la función devuelve ERROR_MORE_DATA.

Comentarios

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

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

Al usar RegEnumValue, una aplicación no debe llamar a ninguna función del Registro que pueda cambiar la clave que se está consultando.

Si los datos tienen el REG_SZ, REG_MULTI_SZ o REG_EXPAND_SZ tipo, es posible que la cadena no se haya almacenado con los caracteres de terminación null adecuados. Por lo tanto, incluso si la función devuelve ERROR_SUCCESS, la aplicación debe asegurarse de que la cadena finaliza correctamente antes de usarla; de lo contrario, puede sobrescribir un búfer. (Tenga en cuenta que REG_MULTI_SZ cadenas deben tener dos caracteres de terminación NULL).

Para determinar el tamaño máximo de los búferes de nombres y datos, use la función RegQueryInfoKey .

Nota

En versiones heredadas de Windows, esta API también se expone mediante kernel32.dll.

Ejemplos

Para obtener un ejemplo, vea Enumerar subclaves del Registro.

Nota

El encabezado winreg.h define RegEnumValue 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


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