Función RegEnumValueA (winreg.h)

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.

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 claves del Registro.

Este identificador lo devuelve el RegCreateKeyEx, RegCreateKeyTransacted, RegOpenKeyExo función 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, se incrementará 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 un cadena terminadanull.

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

Para obtener más información, consulte 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 la función devuelve, la variable recibe el número de caracteres almacenados en el búfer, no incluida la terminación carácter null.

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 se 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 de 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, consulte Tipos de valor del Registro. El parámetro lpType puede ser NULL si no se requiere el código de tipo.

[out, optional] lpData

Puntero a un búfer que recibe los datos de la entrada de valor. Este parámetro puede ser null si no se necesitan los datos.

Si lpData es NULL y lpcbData no esNULL, 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 la función devuelve, la variable recibe el número de bytes almacenados en el búfer.

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

Si los datos tienen el tipo REG_SZ, REG_MULTI_SZ o REG_EXPAND_SZ, este tamaño incluye cualquier terminación carácter o caracteres nulos caracteres. Para obtener más información, vea 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, se ERROR_SUCCESS el valor devuelto.

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.

Observaciones

Para enumerar 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 disminuir 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 tipo REG_SZ, REG_MULTI_SZ o REG_EXPAND_SZ, es posible que la cadena no se haya almacenado con los caracteres-terminados 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 las cadenas de REG_MULTI_SZ deben tener dos caracteresnulos).)

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 Conventions for Function Prototypes.

Requisitos

Requisito	Valor
cliente mínimo admitido	Windows 2000 Professional [solo aplicaciones de escritorio]
servidor mínimo admitido	Windows 2000 Server [solo aplicaciones de escritorio]
de la plataforma de destino de	Windows
encabezado de	winreg.h (incluya Windows.h)
biblioteca de	Advapi32.lib
DLL de	Advapi32.dll

Consulte también

RegCreateKeyEx

regEnumKeyEx

RegOpenKeyEx

RegQueryInfoKey de

funciones del Registro

de información general del Registro de