Compartir a través de


Función RegGetValueA (winreg.h)

Recupera el tipo y los datos del valor del Registro especificado.

Sintaxis

LSTATUS RegGetValueA(
  [in]                HKEY    hkey,
  [in, optional]      LPCSTR  lpSubKey,
  [in, optional]      LPCSTR  lpValue,
  [in, optional]      DWORD   dwFlags,
  [out, optional]     LPDWORD pdwType,
  [out, optional]     PVOID   pvData,
  [in, out, optional] LPDWORD pcbData
);

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_PERFORMANCE_NLSTEXT
HKEY_PERFORMANCE_TEXT
HKEY_USERS

[in, optional] lpSubKey

Ruta de acceso de una clave del Registro relativa a la clave especificada por el parámetro hkey . El valor del Registro se recuperará de esta subclave.

La ruta de acceso no distingue mayúsculas de minúsculas.

Si este parámetro es NULL o una cadena vacía, "", el valor se leerá de la clave especificada por hkey .

[in, optional] lpValue

Nombre del valor del Registro.

Si este parámetro es NULL o una cadena vacía, "", la función recupera el tipo y los datos del valor predeterminado o sin nombre de la clave, si existe. Las claves no tienen automáticamente un valor sin nombre o predeterminado, y los valores sin nombre pueden ser de cualquier tipo.

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

[in, optional] dwFlags

Marcas que restringen el tipo de datos de valor que se va a consultar. Si el tipo de datos del valor no cumple estos criterios, se produce un error en la función. Este parámetro puede ser uno o más de los siguientes valores.

Valor Significado
RRF_RT_ANY
0x0000ffff
Sin restricción de tipos.
RRF_RT_DWORD
0x00000018
Restricción del tipo a RRF_RT_REG_BINARY de 32 bits | RRF_RT_REG_DWORD.
RRF_RT_QWORD
0x00000048
Restricción del tipo a RRF_RT_REG_BINARY de 64 bits | RRF_RT_REG_QWORD.
RRF_RT_REG_BINARY
0x00000008
Restrinja el tipo a REG_BINARY.
RRF_RT_REG_DWORD
0x00000010
Restrinja el tipo a REG_DWORD.
RRF_RT_REG_EXPAND_SZ
0x00000004
Restrinja el tipo a REG_EXPAND_SZ.
RRF_RT_REG_MULTI_SZ
0x00000020
Restrinja el tipo a REG_MULTI_SZ.
RRF_RT_REG_NONE
0x00000001
Restrinja el tipo a REG_NONE.
RRF_RT_REG_QWORD
0x00000040
Restrinja el tipo a REG_QWORD.
RRF_RT_REG_SZ
0x00000002
Restrinja el tipo a REG_SZ.
 

Este parámetro también puede incluir uno o varios de los valores siguientes.

Valor Significado
RRF_NOEXPAND
0x10000000
No expanda automáticamente las cadenas de entorno si el valor es de tipo REG_EXPAND_SZ.
RRF_ZEROONFAILURE
0x20000000
Si pvData no es NULL, establezca el contenido del búfer en ceros en caso de error.
RRF_SUBKEY_WOW6464KEY
0x00010000
Si lpSubKey no es NULL, abra la subclave que lpSubKey especifica con los derechos de acceso KEY_WOW64_64KEY. Para obtener información sobre estos derechos de acceso, consulte Derechos de acceso y seguridad de clave del Registro.

No se puede especificar RRF_SUBKEY_WOW6464KEY en combinación con RRF_SUBKEY_WOW6432KEY.

RRF_SUBKEY_WOW6432KEY
0x00020000
Si lpSubKey no es NULL, abra la subclave que lpSubKey especifica con los derechos de acceso KEY_WOW64_32KEY. Para obtener información sobre estos derechos de acceso, consulte Derechos de acceso y seguridad de clave del Registro.

No se puede especificar RRF_SUBKEY_WOW6432KEY en combinación con RRF_SUBKEY_WOW6464KEY.

[out, optional] pdwType

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. Este parámetro puede ser NULL si el tipo no es necesario.

[out, optional] pvData

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

Si los datos son una cadena, la función comprueba si hay un carácter nulo de terminación. Si no se encuentra alguno, la cadena se almacena con un terminador NULL si el búfer es lo suficientemente grande como para acomodar el carácter adicional. De lo contrario, se produce un error en la función y devuelve ERROR_MORE_DATA.

[in, out, optional] pcbData

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

El parámetro pcbData solo puede ser NULL si pvData 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 caracteres nulos de terminación. Para obtener más información, vea la sección Comentarios.

Si el búfer especificado por el parámetro pvData 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 pcbData. En este caso, el contenido del búfer pvData es cero si dwFlags especifica RRF_ZEROONFAILURE y sin definir en caso contrario.

Si pvData es NULL y pcbData 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 pcbData. Esto permite a una aplicación determinar la mejor manera de asignar un búfer para los datos del valor.

Si hKey especifica HKEY_PERFORMANCE_DATA y el búfer pvData no es lo suficientemente grande como para contener todos los datos devueltos, la función devuelve ERROR_MORE_DATA y el valor devuelto a través del parámetro pcbData no está definido. Esto se debe a que el tamaño de los datos de rendimiento puede cambiar de una llamada a la siguiente. En este caso, debe aumentar el tamaño del búfer y llamar a RegGetValue de nuevo pasando el tamaño del búfer actualizado en el parámetro pcbData . Repita esta acción hasta que la función se realice correctamente. Debe mantener una variable independiente para realizar un seguimiento del tamaño del búfer, ya que el valor devuelto por pcbData es impredecible.

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 pvData es demasiado pequeño para recibir el valor, la función devuelve ERROR_MORE_DATA.

Si el valor del registro lpValue no existe, la función devuelve ERROR_FILE_NOT_FOUND.

Si dwFlags especifica una combinación de RRF_SUBKEY_WOW6464KEY y RRF_SUBKEY_WOW6432KEY, la función devuelve ERROR_INVALID_PARAMETER.

Comentarios

Normalmente, una aplicación llama a RegEnumValue para determinar los nombres de valor y, a continuación, RegGetValue para recuperar los datos de los nombres.

Si los datos tienen el REG_SZ, REG_MULTI_SZ o REG_EXPAND_SZ tipo y se usa la versión ANSI de esta función (ya sea llamando explícitamente a RegGetValueA 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 al que apunta pvData.

Al llamar a esta función con hkey establecida en el identificador HKEY_PERFORMANCE_DATA y una cadena de valor de un objeto especificado, la estructura de datos devuelta a veces tiene objetos no consultados. No se sorprenda; este es un comportamiento normal. Siempre debe esperar recorrer la estructura de datos devuelta para buscar el objeto solicitado.

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.

Para compilar una aplicación que usa esta función, defina _WIN32_WINNT como 0x0600 o posterior. Para obtener más información, vea Usar los encabezados de Windows.

Nota

El encabezado winreg.h define RegGetValue 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 provocar discrepancias que dan lugar a errores de compilación o en tiempo de ejecución. Para obtener más información, vea Convenciones para prototipos de función.

Requisitos

   
Cliente mínimo compatible Windows Vista, Windows XP Professional x64 Edition
Servidor mínimo compatible Windows Server 2008, Windows Server 2003 con SP1
Plataforma de destino Windows
Encabezado winreg.h (incluye Windows.h)
Library Advapi32.lib
Archivo DLL Advapi32.dll

Consulte también

RegCreateKeyEx

RegEnumKeyEx

RegEnumValue

RegOpenKeyEx

RegQueryInfoKey

Funciones del Registro

Introducción al Registro