Función RegQueryValueA (winreg.h)

Artículo
08/27/2023

Recupera los datos asociados al valor predeterminado o sin nombre de una clave del Registro especificada. Los datos deben ser una cadena terminada en null.

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

Sintaxis

LSTATUS RegQueryValueA(
  [in]                HKEY   hKey,
  [in, optional]      LPCSTR lpSubKey,
  [out, optional]     LPSTR  lpData,
  [in, out, optional] PLONG  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_USERS

[in, optional] lpSubKey

Nombre de la subclave del parámetro hKey para el que se recupera el valor predeterminado.

Los nombres de clave no distinguen mayúsculas de minúsculas.

Si este parámetro es NULL o apunta a una cadena vacía, la función recupera el valor predeterminado de la clave identificada por hKey.

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

[out, optional] lpData

Puntero a un búfer que recibe el valor predeterminado de la clave especificada.

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

[in, out, optional] lpcbData

Puntero a una variable que especifica el tamaño del búfer al que apunta el parámetro lpValue , en bytes. Cuando se devuelve la función, esta variable contiene el tamaño de los datos copiados en lpValue, incluidos los caracteres NULOs de terminación.

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 lpValue 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 lpcbValue. En este caso, el contenido del búfer lpValue 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 el búfer lpValue es demasiado pequeño para recibir el valor, la función devuelve ERROR_MORE_DATA.

Comentarios

Si se usa la versión ANSI de esta función (ya sea llamando explícitamente a RegQueryValueA o no definiendo UNICODE antes de incluir el archivo Windows.h), esta función convierte la cadena Unicode almacenada en una cadena ANSI antes de copiarla en el búfer especificado por el parámetro lpValue .

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

Tenga en cuenta que las operaciones que acceden a determinadas claves del Registro se redirigen. Para obtener más información, consulte Virtualización del Registro y datos de aplicación de 32 y 64 bits en el Registro.

Nota:

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