RegGetValueA 函数 (winreg.h)

  • 项目

检索指定注册表值的类型和数据。

语法

LSTATUS RegGetValueA(
  [in]                HKEY    hkey,
  [in, optional]      LPCSTR  lpSubKey,
  [in, optional]      LPCSTR  lpValue,
  [in, optional]      DWORD   dwFlags,
  [out, optional]     LPDWORD pdwType,
  [out, optional]     PVOID   pvData,
  [in, out, optional] LPDWORD pcbData
);

参数

[in] hkey

打开的注册表项的句柄。 密钥必须已使用KEY_QUERY_VALUE访问权限打开。 有关详细信息，请参阅 注册表项安全和访问权限。

此句柄由 RegCreateKeyEx、 RegCreateKeyTransacted、 RegOpenKeyEx 或 RegOpenKeyTransacted 函数返回。 它也可以是以下 预定义键之一：

HKEY_CLASSES_ROOT
HKEY_CURRENT_CONFIG
HKEY_CURRENT_USER
HKEY_LOCAL_MACHINE
HKEY_PERFORMANCE_DATA
HKEY_PERFORMANCE_NLSTEXT
HKEY_PERFORMANCE_TEXT
HKEY_USERS

[in, optional] lpSubKey

相对于 hkey 参数指定的项的注册表项的路径。 将从此子项检索注册表值。

路径不区分大小写。

如果此参数为 NULL 或空字符串“”，则将从 hkey 本身指定的键中读取该值。

[in, optional] lpValue

注册表值的名称。

如果此参数为 NULL 或空字符串“”，则该函数将检索键的未命名值或默认值的类型和数据（如果有）。 键不会自动具有未命名值或默认值，且未命名的值可以是任何类型的。

有关详细信息，请参阅 注册表元素大小限制。

[in, optional] dwFlags

限制要查询的值的数据类型的标志。 如果值的数据类型不符合此条件，则函数将失败。 此参数可使用以下一个或多个值。

值 含义
RRF_RT_ANY
0x0000ffff
 无类型限制。
RRF_RT_DWORD
0x00000018
 将类型限制为 32 位RRF_RT_REG_BINARY |RRF_RT_REG_DWORD。
RRF_RT_QWORD
0x00000048
 将类型限制为 64 位RRF_RT_REG_BINARY |RRF_RT_REG_QWORD。
RRF_RT_REG_BINARY
0x00000008
 将类型限制为REG_BINARY。
RRF_RT_REG_DWORD
0x00000010
 将类型限制为REG_DWORD。
RRF_RT_REG_EXPAND_SZ
0x00000004
 将类型限制为REG_EXPAND_SZ。
RRF_RT_REG_MULTI_SZ
0x00000020
 将类型限制为REG_MULTI_SZ。
RRF_RT_REG_NONE
0x00000001
 将类型限制为REG_NONE。
RRF_RT_REG_QWORD
0x00000040
 将类型限制为REG_QWORD。
RRF_RT_REG_SZ
0x00000002
 将类型限制为REG_SZ。
 

此参数还可以包含以下一个或多个值。

值 含义
RRF_NOEXPAND
0x10000000
 如果值的类型为 REG_EXPAND_SZ，则不要自动展开环境字符串。
RRF_ZEROONFAILURE
0x20000000
 如果 pvData 不为 NULL，请在失败时将缓冲区的内容设置为零。
RRF_SUBKEY_WOW6464KEY
0x00010000
 如果 lpSubKey 不为 NULL，请使用KEY_WOW64_64KEY访问权限打开 lpSubKey 指定的子项。 有关这些访问权限的信息，请参阅 注册表项安全性和访问权限。

不能与 RRF_SUBKEY_WOW6432KEY 一起指定 RRF_SUBKEY_WOW6464KEY。
RRF_SUBKEY_WOW6432KEY
0x00020000
 如果 lpSubKey 不为 NULL，请使用KEY_WOW64_32KEY访问权限打开 lpSubKey 指定的子项。 有关这些访问权限的信息，请参阅 注册表项安全性和访问权限。

不能与 RRF_SUBKEY_WOW6464KEY 一起指定 RRF_SUBKEY_WOW6432KEY。

[out, optional] pdwType

指向变量的指针，该变量接收指示存储在指定值中的数据类型的代码。 有关可能的类型代码的列表，请参阅 注册表值类型。 如果类型不是必需的，此参数可以为 NULL 。

[out, optional] pvData

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

如果数据是字符串，则该函数会检查终止 null 字符。 如果未找到该字符串，则如果缓冲区足够大，足以容纳多余字符，则会使用 null 终止符存储字符串。 否则，函数将失败并返回ERROR_MORE_DATA。

[in, out, optional] pcbData

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

仅当 pvData 为 NULL 时，该参数才能为 NULL。

如果数据具有REG_SZ、REG_MULTI_SZ或REG_EXPAND_SZ类型，则此大小包括任何终止 null 字符或字符。 有关详细信息，请参阅“备注”。

如果 pvData 参数指定的缓冲区不够大，无法容纳数据，则函数将返回ERROR_MORE_DATA并将所需的缓冲区大小存储在 由ERROR_MORE_DATA data 指向的变量中。 在这种情况下，如果 dwFlags 指定RRF_ZEROONFAILURE，则 pvData 缓冲区的内容为零，否则为未定义。

如果 pvData 为 NULL，且 ERROR_SUCCESS 为非 NULL，则该函数将返回，并将数据的大小（以字节为单位）存储在 由data 指向的变量中。 这使应用程序能够确定为值的数据分配缓冲区的最佳方式。

如果 hKey 指定 HKEY_PERFORMANCE_DATA 并且 pvData 缓冲区不够大，无法包含所有返回的数据，则函数将返回ERROR_MORE_DATA并且未定义通过 ERROR_MORE_DATA 参数返回的值。 这是因为性能数据的大小可以从一次调用更改为下一个调用。 在这种情况下，必须增加缓冲区大小，并再次调用 RegGetValue ，以传递更新的缓冲区大小在 Data 参数中。 重复此操作，直到函数成功。 你需要维护一个单独的变量来跟踪缓冲区大小，因为 由印刷板数据 返回的值是不可预知的。

返回值

如果函数成功，则返回值为 ERROR_SUCCESS。

如果函数失败，则返回值为 系统错误代码。

如果 pvData 缓冲区太小而无法接收值，则函数将返回ERROR_MORE_DATA。

如果 lpValue 注册表值不存在，则函数将返回ERROR_FILE_NOT_FOUND。

如果 dwFlags 同时指定 RRF_SUBKEY_WOW6464KEY 和 RRF_SUBKEY_WOW6432KEY的组合，则函数将返回ERROR_INVALID_PARAMETER。

注解

应用程序通常调用 RegEnumValue 来确定值名称，然后 调用 RegGetValue 来检索名称的数据。

如果数据具有REG_SZ、REG_MULTI_SZ或REG_EXPAND_SZ类型，并且此函数的 ANSI 版本通过显式调用 RegGetValueA 或在将 Windows.h 文件) 之前未定义 UNICODE 来 (使用，则此函数会将存储的 Unicode 字符串转换为 ANSI 字符串，然后再将其复制到 pvData 指向的缓冲区。

调用此函数时，如果 hkey 设置为 HKEY_PERFORMANCE_DATA 句柄和指定对象的值字符串，则返回的数据结构有时具有未请求的对象。 不要感到惊讶：这是正常行为。 应始终希望遍历返回的数据结构以查找请求的对象。

请注意，将重定向访问某些注册表项的操作。 有关详细信息，请参阅 注册表虚拟化 和 注册表中的 32 位和 64 位应用程序数据。

若要编译使用此函数的应用程序，请将_WIN32_WINNT定义为 0x0600 或更高版本。 有关详细信息，请参阅 使用 Windows 标头。

注意

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

要求

   
最低受支持的客户端 Windows Vista、Windows XP Professional x64 Edition
最低受支持的服务器 Windows Server 2008、Windows Server 2003 SP1
目标平台 Windows
标头 winreg.h (包括 Windows.h)
Library Advapi32.lib
DLL Advapi32.dll

请参阅

RegCreateKeyEx

RegEnumKeyEx

RegEnumValue

RegOpenKeyEx

RegQueryInfoKey

注册表函数

注册表概述