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.
Este parámetro también puede incluir uno o varios de los valores siguientes.
| Valor | Significado |
|---|---|
|
No expanda automáticamente las cadenas de entorno si el valor es de tipo REG_EXPAND_SZ. |
|
Si pvData no es NULL, establezca el contenido del búfer en ceros en caso de error. |
|
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. |
|
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 |