shRegGetValueA 函数 (shlwapi.h)

项目
08/26/2023

[SHRegGetValue 在操作系统或产品的后续版本中可能已更改或不可用。使用 RegGetValue 代替它。]

检索注册表值。

语法

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

参数

[in] hkey

类型： HKEY

当前打开的键或以下任何预定义值的句柄。

HKEY_CLASSES_ROOT

HKEY_CURRENT_CONFIG

HKEY_CURRENT_USER

HKEY_LOCAL_MACHINE

HKEY_PERFORMANCE_DATA

HKEY_USERS

[in] pszSubKey

类型： LPCTSTR

指向以 null 结尾的字符串的指针，该字符串指定从 hkey 到要从中检索值的子项的相对路径。此参数可以是 NULL 或空字符串，在这种情况下，将从 hkey 位置检索数据。

[in] pszValue

类型： LPCTSTR

指向包含值名称的 以 null 结尾的字符串的指针。此参数可以是 NULL 或空字符串，在这种情况下，将从默认值检索数据。

[in] srrfFlags

类型： SRRF

限制要检索的数据的一个或多个 SRRF 标志。必须至少指定一个类型限制 (SRRF_RT) 值。

[in, out] pdwType

类型： LPDWORD

指向 DWORD 的指针，该 DWORD 接收存储在检索的值中的数据类型。使用默认值时，输入 pdwType 是默认值的类型。有关可能的值，请参阅注册表数据类型。如果未设置SRRF_NOEXPAND标志，则REG_EXPAND_SZ类型会自动展开并作为REG_SZ返回。如果不需要类型信息，则此参数可以为 NULL。

[out] pvData

类型： LPVOID

指向接收值数据的缓冲区的指针。如果不需要数据，此参数可以为 NULL 。例如，如果只测试某个值是否存在，则特定值数据将是多余的。

[in, out] pcbData

类型： LPDWORD

指向 DWORD 的指针，该 DWORD 在输入时包含目标数据缓冲区 pvData 的大小（以字节为单位）。仅当 pvData 为 NULL 时，此值才能为 NULL。退出时， 该参数 将指向以下值之一。

pvData	返回值	pcbData
NULL	ERROR_SUCCESS	大小（以字节为单位，足以保存注册表数据）。请注意，这不保证是精确的大小，而只能是足够的大小。
非 NULL	ERROR_SUCCESS	写入 pvData 的确切字节数。
非 NULL	ERROR_MORE_DATA	保存整个数据所需的大小（以字节为单位）。请注意，这不保证是精确的大小，而只能是足够的大小。

返回值

类型： LSTATUS

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

注解

SHRegGetValue 提供数据类型检查、启动模式检查、REG_EXPAND_SZ数据的自动扩展，以及保证REG_SZ、REG_EXPAND_SZ和REG_MULTI_SZ数据的 null 终止。

hkey 标识的密钥必须已使用KEY_QUERY_VALUE安全访问权限打开。如果 pszSubKey 不为 NULL 或空字符串，则还必须能够在当前调用上下文中使用 KEY_QUERY_VALUE 安全访问权限打开该密钥。

如果数据类型为REG_SZ、REG_EXPAND_SZ或REG_MULTI_SZ，则返回的任何数据包括或考虑字符串的 null 终止。例如，如果 pvData 不为 NULL，则在该缓冲区中返回的数据以 null 结尾。如果 正确值 不为 NULL，则它指向的缓冲区大小包括保存终止 null 字符所需的字节数。

除非设置了SRRF_NOEXPAND标志，否则REG_EXPAND_SZ类型的字符串数据在返回前会自动展开。在 pdwType 中，扩展字符串的类型报告为REG_SZ， 而REG_SZ为 扩展字符串写入的字节数， pvData 指向的缓冲区包含字符串的扩展版本。

性能说明

如果 pszSubKey 不为 NULL 或为空字符串，则每次访问该键时，此函数都会打开和关闭该键。如果应用程序必须从同一子项中检索一系列值，在调用 SHRegGetValue 之前，使用 RegOpenKeyEx 打开该键将得到更好的性能。使用 RegOpenKeyEx 的 phkResult 参数中返回的键作为此函数中的 hkey 参数，并将 pszSubKey 设置为 NULL。

当数据类型为REG_EXPAND_SZ且尚未设置SRRF_NOEXPAND标志时，可能会对注册表进行额外的调用来读取或重新读取数据。以下条件会导致该附加调用。

pvData 为 NULL， 而 pvcData 不为 NULL。虽然未检索数据，但必须读取注册表才能获取字符串和该字符串，以确定所需的数据缓冲区大小。
pvData 不为 NULL，但太小而无法保存数据。重新读取数据以获取完整的字符串，扩展字符串，并确定所需的总大小。

注意

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

要求

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

另请参阅

RegQueryValueEx

通过