RegGetValueA 函数（winreg.h）

项目
11/20/2024

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

语法

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，请打开 lpSubKey 使用KEY_WOW64_64KEY访问权限指定的子项。有关这些访问权限的信息，请参阅注册表项安全和访问权限。不能将 RRF_SUBKEY_WOW6464KEY 与 RRF_SUBKEY_WOW6432KEY结合使用。
RRF_SUBKEY_WOW6432KEY 0x00020000	如果未 NULLlpSubKey，则打开 lpSubKey 使用KEY_WOW64_32KEY访问权限指定的子项。有关这些访问权限的信息，请参阅注册表项安全和访问权限。不能将 RRF_SUBKEY_WOW6432KEY 与 RRF_SUBKEY_WOW6464KEY结合使用。

[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，并将所需的缓冲区大小存储在指向的变量中。在这种情况下，如果 dwFlags 指定RRF_ZEROONFAILURE且未定义，则 pvData 缓冲区的内容为零。

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

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

返回值

如果函数成功，则返回值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 版本
支持的最低服务器	Windows Server 2008、Windows Server 2003 SP1
目标平台	窗户
标头	winreg.h （包括 Windows.h）
库	Advapi32.lib
DLL	Advapi32.dll