SHRegGetUSValueA 函数 (shlwapi.h)

从特定于用户的子树 (HKEY_CURRENT_USER 或HKEY_LOCAL_MACHINE) 的注册表子项中检索值。

语法

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

参数

[in] pszSubKey

类型： LPCTSTR

指向以 null 结尾的字符串的指针，其子项的名称相对于 HKEY_LOCAL_MACHINE 和 HKEY_CURRENT_USER。 例如：“Software\MyCompany\MyProduct”。

[in, optional] pszValue

类型： LPCTSTR

指向具有值名称的以 null 结尾的字符串的指针。 此值可以为 NULL。

[in, out, optional] pdwType

类型： DWORD*

指向 DWORD 的指针，该 DWORD 接收存储在检索到的值中的数据类型。 使用默认值时，输入 pdwType 是默认值的类型。 有关可能的值，请参阅 注册表数据类型。 如果不需要类型信息，则此参数可以为 NULL。

[out, optional] pvData

类型： void*

指向接收值数据的缓冲区的指针。

[in, out, optional] pcbData

类型： DWORD*

指向变量的指针，该变量指定 pvData 指向的缓冲区的大小（以字节为单位）。 当 SHRegGetUSValue 返回时，将包含复制到 pvData 的数据的大小。

[in] fIgnoreHKCU

类型： BOOL

一个变量，指定要在哪个键下查找。 如果设置为 TRUE，SHRegGetUSValue 将忽略HKEY_CURRENT_USER，并从HKEY_LOCAL_MACHINE下的键返回值。

[in, optional] pvDefaultData

类型： void*

指向接收值默认数据的缓冲区的指针。

[in] dwDefaultDataSize

类型：DWORD

pvDefaultData 指向的缓冲区的长度（以字节为单位）。

返回值

类型： LSTATUS

如果成功，则返回ERROR_SUCCESS，否则返回 Winerror.h 中定义的非零错误代码。 可以使用带有 FORMAT_MESSAGE_FROM_SYSTEM 标志的 FormatMessage 函数来检索错误的泛型说明。

注解

当 fIgnoreHKCU 设置为 TRUE 时， SHRegGetUSValue 从 HKEY_LOCAL_MACHINE下的键返回值。 设置为 FALSE 时， SHRegGetUSValue 首先尝试从 HKEY_CURRENT_USER下的键返回值。 但是，如果在 HKEY_CURRENT_USER 下找不到该键，则会从 HKEY_LOCAL_MACHINE下的键返回该值。 如果两个键都不存在，或者发生错误并且 dwDefaultDataSize 为非零，则默认数据将复制到 pvData，ERROR_SUCCESS 返回。 ERROR_SUCCESS返回默认和非默认数据，并且无法区分将哪个值复制到 pvData。 若要防止使用默认数据，请将 pvDefaultData 设置为 NULL ，将 dwDefaultDataSize 设置为零。

每次使用时，此函数都会打开密钥。 如果代码涉及从同一键获取一系列值，则使用 SHRegOpenUSKey 打开密钥一次，然后使用 SHRegQueryUSValue 检索数据会更有效。

注意

shlwapi.h 标头将 SHRegGetUSValue 定义为别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。 将非特定编码别名的使用与非非特定编码的代码混合使用可能会导致不匹配，从而导致编译或运行时错误。 有关详细信息，请参阅 函数原型的约定。

要求

要求	值
最低受支持的客户端	Windows 2000 专业版、Windows XP [仅限桌面应用]
最低受支持的服务器	Windows 2000 Server [仅限桌面应用]
目标平台	Windows
标头	shlwapi.h
Library	Shlwapi.lib
DLL	Shlwapi.dll (版本 4.71 或更高版本)