shRegQueryUSValueA 函数 (shlwapi.h)

  • 项目

检索与用户特定的子树 (HKEY_CURRENT_USER 或HKEY_LOCAL_MACHINE) 中打开的注册表子项关联的指定名称的类型和数据。

语法

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
);

参数

[in] hUSKey

类型： HUSKEY

当前打开的注册表子项的句柄，或以下预定义值之一。 子项必须已使用KEY_SET_VALUE访问权限打开。 有关详细信息，请参阅 注册表项安全和访问权限。

可以通过 SHRegOpenUSKey 函数获取此句柄。

HKEY_CLASSES_ROOT

HKEY_CURRENT_CONFIG

HKEY_CURRENT_USER

HKEY_LOCAL_MACHINE

HKEY_PERFORMANCE_DATA

HKEY_USERS

[in, optional] pszValue

类型： LPCTSTR

指向以 null 结尾的字符串的指针，该字符串包含要查询的值的名称。

[in, out, optional] pdwType

类型： LPDWORD*

指向变量的指针，该变量设置或接收键的值类型。 有关详细信息，请参阅 注册表数据类型。 此参数可以为 NULL。

[out, optional] pvData

类型： LPVOID*

指向接收值数据的缓冲区的指针。 如果不需要数据，此参数可以为 NULL 。

[in, out] pcbData

类型： LPDWORD*

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

[in] fIgnoreHKCU

类型： BOOL

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

[in, optional] pvDefaultData

类型： LPVOID*

指向默认数据的指针。

[in, optional] dwDefaultDataSize

类型：DWORD

默认数据的长度（以字节为单位）。

返回值

类型： LSTATUS

如果成功，则返回ERROR_SUCCESS，否则返回 Winerror.h 中定义的非零错误代码。 可以将 FormatMessage 函数与 FORMAT_MESSAGE_FROM_SYSTEM 标志一起使用，以检索错误的一般说明。

注解

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

如果只需读取单个值， 则 SHRegGetUSValue 将打开键并返回该值。 若要使用 SHRegQueryUSValue，必须先使用 SHRegOpenUSKey 打开密钥。 但是，打开密钥后，可以根据需要多次使用 SHRegQueryUSValue 。 如果需要从同一键检索多个值，则对 SHRegQueryUSValue 使用多次调用通常比 SHRegGetUSValue 更高效，因为该键只打开一次。

注意

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

要求

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