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 de
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 de
Puntero a un cadena terminada en nullque especifica la ruta de acceso relativa de clave hkey a la subclave para recuperar el valor. Este parámetro puede ser
[in] pszValue
Tipo: LPCTSTR de
Puntero a un cadena terminada en nullque 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
Una o varias de las marcas srRF de
[in, out] pdwType
Tipo: LPDWORD de
Puntero a un DWORD que recibe el tipo de datos almacenados en el valor recuperado. Cuando se usan valores predeterminados, el pdwType de entrada es el tipo del valor predeterminado. Para conocer los valores posibles, consulte tipos de datos del Registro. Si no se establece la marca SRRF_NOEXPAND, los tipos de REG_EXPAND_SZ 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 de
Puntero a un búfer que recibe los datos del valor. Este parámetro puede ser null si no se necesitan los datos. Por ejemplo, si solo estaba probando para la existencia de un valor, los datos de valor específicos serían superfluos.
[in, out] pcbData
Tipo: LPDWORD de
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 se puede 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. |
| No NULL | ERROR_SUCCESS | Número exacto de bytes escritos en pvData. |
| No 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 de
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.
Observaciones
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 nulo-terminación de REG_SZ, REG_EXPAND_SZ y datos de REG_MULTI_SZ garantizados.
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 el null de la cadena-termination. Por ejemplo, si pvData no es NULL, los datos devueltos en ese búfer se nuloterminado. Si pcbData no es null, el tamaño del búfer al que apunta incluye los bytes necesarios para contener el carácter de nulo de terminación.
A menos que se establezca la marca 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 de
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ámetroLa 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 SRRF_NOEXPAND. Las condiciones siguientes dan como resultado 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 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 XP con SP2 [solo aplicaciones de escritorio] |
| servidor mínimo admitido | Windows Server 2003 [solo aplicaciones de escritorio] |
| de la plataforma de destino de |
Windows |
| encabezado de |
shlwapi.h |
| biblioteca de |
Shlwapi.lib |
| DLL de |
Shlwapi.dll (versión 6.0 o posterior) |