Función SHRegGetValueA (shlwapi.h)

[SHRegGetValue puede modificarse o no estar disponible en versiones posteriores del sistema operativo o del producto. Use RegGetValue en su lugar.]

Recupera un valor del Registro.

Sintaxis

LSTATUS SHRegGetValueA(
  [in]      HKEY   hkey,
  [in]      LPCSTR pszSubKey,
  [in]      LPCSTR pszValue,
  [in]      SRRF   srrfFlags,
  [in, out] DWORD  *pdwType,
  [out]     void   *pvData,
  [in, out] DWORD  *pcbData
);

Parámetros

[in] hkey

Tipo: HKEY

Identificador de la clave abierta actualmente o cualquiera de los siguientes valores predefinidos.

HKEY_CLASSES_ROOT

HKEY_CURRENT_CONFIG

HKEY_CURRENT_USER

HKEY_LOCAL_MACHINE

HKEY_PERFORMANCE_DATA

HKEY_USERS

[in] pszSubKey

Tipo: LPCTSTR

Puntero a una cadena terminada en null que especifica la ruta de acceso relativa de hkey a la subclave de la que se va a recuperar el valor. Este parámetro puede ser NULL o una cadena vacía, en cuyo caso los datos se recuperan de la ubicación hkey .

[in] pszValue

Tipo: LPCTSTR

Puntero a una cadena terminada en null que contiene el nombre del valor. Este parámetro puede ser NULL o una cadena vacía, en cuyo caso los datos se recuperan del valor Predeterminado.

[in] srrfFlags

Tipo: SRRF

Una o varias de las marcas SRRF que restringen los datos que se van a recuperar. Se debe especificar al menos un valor de restricción de tipo (SRRF_RT).

[in, out] pdwType

Tipo: LPDWORD

Puntero a un DWORD que recibe el tipo de datos almacenados en el valor recuperado. Cuando se usan valores predeterminados, la entrada pdwType es el tipo del valor predeterminado. Para conocer los valores posibles, consulte Tipos de datos del Registro. Si no se establece la marca de SRRF_NOEXPAND, REG_EXPAND_SZ tipos se expanden automáticamente y se devuelven como REG_SZ. Si no se requiere información de tipo, este parámetro puede ser NULL.

[out] pvData

Tipo: LPVOID

Puntero a un búfer que recibe los datos del valor. Este parámetro puede ser NULL si los datos no son necesarios. Por ejemplo, si estuviera probando solo para la existencia de un valor, los datos de valor específicos serían superfluos.

[in, out] pcbData

Tipo: LPDWORD

Puntero a un DWORD que, en la entrada, contiene el tamaño del búfer de datos de destino pvData, en bytes. Este valor solo puede ser NULL si pvData es NULL. Al salir, pcbData apunta a uno de estos valores.

pvData	Valor devuelto	pcbData
NULL	ERROR_SUCCESS	Tamaño en bytes suficiente para contener los datos del Registro. Tenga en cuenta que no se garantiza que sea el tamaño preciso, sino solo un tamaño suficiente.
Distinto de NULL	ERROR_SUCCESS	Número exacto de bytes escritos en pvData.
Distinto de NULL	ERROR_MORE_DATA	Tamaño en bytes necesarios para contener todos los datos. Tenga en cuenta que no se garantiza que sea el tamaño preciso, sino solo un tamaño suficiente.

Valor devuelto

Tipo: LSTATUS

Devuelve ERROR_SUCCESS si se ejecuta correctamente o un código de error distinto de cero definido en Winerror.h de lo contrario. Puede usar la función FormatMessage con la marca FORMAT_MESSAGE_FROM_SYSTEM para recuperar una descripción genérica del error.

Comentarios

SHRegGetValue proporciona comprobación de tipos de datos, comprobación del modo de arranque, expansión automática de datos de REG_EXPAND_SZ y terminación nula garantizada de REG_SZ, REG_EXPAND_SZ y datos de REG_MULTI_SZ.

La clave identificada por hkey debe haberse abierto con KEY_QUERY_VALUE acceso de seguridad. Si pszSubKey no es NULL o una cadena vacía, esa clave también debe poder abrirse con KEY_QUERY_VALUE acceso de seguridad en el contexto de llamada actual.

Si el tipo de datos es REG_SZ, REG_EXPAND_SZ o REG_MULTI_SZ, los datos devueltos incluyen o tienen en cuenta la terminación null de la cadena. Por ejemplo, si pvData no es NULL, los datos devueltos en ese búfer terminan en null. Si pcbData no es NULL, el tamaño del búfer que apunta a incluye los bytes necesarios para contener el carácter nulo de terminación.

A menos que se establezca la marca de SRRF_NOEXPAND, los datos de cadena de tipo REG_EXPAND_SZ se expanden automáticamente antes de devolverse. El tipo de cadena expandida se notifica en pdwType como REG_SZ, el parámetro pcbData apunta al número de bytes escritos para la cadena expandida y el búfer al que apunta pvData contiene la versión expandida de la cadena.

Notas de rendimiento

Si pszSubKey no es NULL o una cadena vacía, esa clave se abre y cierra con esta función cada vez que se accede a ella. Si la aplicación debe recuperar una serie de valores de la misma subclave, verá un mejor rendimiento abriendo la clave mediante RegOpenKeyEx antes de llamar a SHRegGetValue. Use la clave devuelta en el parámetro phkResult de RegOpenKeyEx como parámetro hkey de esta función, con pszSubKey establecido en NULL.

La posibilidad de una llamada adicional al Registro para leer o volver a leer los datos existe cuando el tipo de datos es REG_EXPAND_SZ y no se ha establecido la marca de SRRF_NOEXPAND. Las condiciones siguientes dan lugar a esa llamada adicional.

• pvData es NULL, pcbData no es NULL. Aunque no se recuperan los datos, el Registro debe leerse para obtener la cadena y esa cadena expandida para determinar el tamaño necesario del búfer de datos.
• pvData no es NULL, pero es demasiado pequeño para contener los datos. Los datos se vuelven a leer para obtener la cadena completa, la cadena se expande y se determina el tamaño total necesario.

Nota

El encabezado shlwapi.h define SHRegGetValue 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 neutro 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

Requisito	Value
Cliente mínimo compatible	Windows XP con SP2 [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2003 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	shlwapi.h
Library	Shlwapi.lib
Archivo DLL	Shlwapi.dll (versión 6.0 o posterior)

Consulte también

RegQueryValueEx