Función SHRegQueryUSValueA (shlwapi.h)

Recupera el tipo y los datos de un nombre especificado asociado a una subclave del Registro abierto en un subárbol específico del usuario (HKEY_CURRENT_USER o HKEY_LOCAL_MACHINE).

Sintaxis

LSTATUS SHRegQueryUSValueA(
  [in]                HUSKEY hUSKey,
  [in, optional]      LPCSTR pszValue,
  [in, out, optional] DWORD  *pdwType,
  [out, optional]     void   *pvData,
  [in, out]           DWORD  *pcbData,
  [in]                BOOL   fIgnoreHKCU,
  [in, optional]      void   *pvDefaultData,
  [in, optional]      DWORD  dwDefaultDataSize
);

Parámetros

[in] hUSKey

Tipo: HUSKEY

Identificador de una subclave del Registro abierta actualmente o uno de los siguientes valores predefinidos. La subclave debe haberse abierto con el derecho de acceso KEY_SET_VALUE. Para obtener más información, consulte Derechos de acceso y seguridad de clave del Registro.

Este identificador se puede obtener a través de la función SHRegOpenUSKey .

HKEY_CLASSES_ROOT

HKEY_CURRENT_CONFIG

HKEY_CURRENT_USER

HKEY_LOCAL_MACHINE

HKEY_PERFORMANCE_DATA

HKEY_USERS

[in, optional] pszValue

Tipo: LPCTSTR

Puntero a la cadena terminada en null que contiene el nombre del valor que se va a consultar.

[in, out, optional] pdwType

Tipo: LPDWORD*

Puntero a la variable que establece o recibe el tipo de valor de la clave. Para obtener más información, consulte Tipos de datos del Registro. Este parámetro puede ser NULL.

[out, optional] pvData

Tipo: LPVOID*

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

[in, out] pcbData

Tipo: LPDWORD*

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

[in] fIgnoreHKCU

Tipo: BOOL

Variable que especifica la clave que se va a buscar. Cuando se establece en TRUE, SHRegQueryUSValue omite HKEY_CURRENT_USER y devuelve el valor de la clave en HKEY_LOCAL_MACHINE.

[in, optional] pvDefaultData

Tipo: LPVOID*

Puntero a los datos predeterminados.

[in, optional] dwDefaultDataSize

Tipo: DWORD

Longitud, en bytes, de los datos predeterminados.

Valor devuelto

Tipo: LSTATUS

Devuelve ERROR_SUCCESS si se ejecuta correctamente o si 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

Cuando fIgnoreHKCU se establece en TRUE, SHRegQueryUSValue devuelve el valor de la clave en HKEY_LOCAL_MACHINE. Cuando se establece en FALSE, SHRegQueryUSValue primero intenta devolver el valor de la clave en HKEY_CURRENT_USER. Sin embargo, si la clave no se encuentra en HKEY_CURRENT_USER, el valor devuelve de la clave en HKEY_LOCAL_MACHINE. Si ninguna clave está presente o si se produce un error y dwDefaultDataSize no es cero, los datos predeterminados se copian en pvData y ERROR_SUCCESS devuelve. ERROR_SUCCESS devuelve datos predeterminados y no predeterminados, y no hay ninguna manera de distinguir qué valor copia en pvData. Para evitar el uso de datos predeterminados, establezca pvDefaultData en NULL y dwDefaultDataSize en cero.

Si solo necesita leer un valor único, SHRegGetUSValue abrirá la clave y devolverá el valor. Para usar SHRegQueryUSValue, primero debe abrir la clave con SHRegOpenUSKey. Sin embargo, una vez abierta la clave, puede usar SHRegQueryUSValue tantas veces como sea necesario. Si necesita recuperar más de un valor de la misma clave, el uso de varias llamadas a SHRegQueryUSValue suele ser más eficaz que SHRegGetUSValue, ya que la clave solo se abre una vez.

Nota

El encabezado shlwapi.h define SHRegQueryUSValue 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 2000 Professional, Windows XP [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows 2000 Server [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	shlwapi.h
Library	Shlwapi.lib
Archivo DLL	Shlwapi.dll (versión 4.71 o posterior)