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 claves 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 de

Puntero al cadena terminada en nullque 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 no se necesitan los datos.

[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 de

Variable que especifica la clave en la 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 de

Longitud, en bytes, de los datos predeterminados.

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

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 no se encuentra la clave 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 es distinto de cero, los datos predeterminados se copian en pvData y ERROR_SUCCESS devuelven. ERROR_SUCCESS devuelve para los datos predeterminados y no predeterminados, y no hay forma 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 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 2000 Professional, Windows XP [solo aplicaciones de escritorio]
servidor mínimo admitido	Windows 2000 Server [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 4.71 o posterior)