RegSetValueExA 函数 (winreg.h)

项目
08/27/2023

设置注册表项下指定值的数据和类型。

语法

LSTATUS RegSetValueExA(
  [in]           HKEY       hKey,
  [in, optional] LPCSTR     lpValueName,
                 DWORD      Reserved,
  [in]           DWORD      dwType,
  [in]           const BYTE *lpData,
  [in]           DWORD      cbData
);

参数

[in] hKey

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

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

HKEY_CLASSES_ROOT

HKEY_CURRENT_CONFIG

HKEY_CURRENT_USER

HKEY_LOCAL_MACHINE

HKEY_USERS

此函数的 Unicode 版本支持以下附加预定义键：

HKEY_PERFORMANCE_TEXT
HKEY_PERFORMANCE_NLSTEXT

[in, optional] lpValueName

要设置的值的名称。如果键中尚不存在具有此名称的值，则函数会将其添加到键中。

如果 lpValueName 为 NULL 或空字符串“”，则该函数将设置键的未命名值或默认值的类型和数据。

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

注册表项没有默认值，但它们可以有一个未命名的值，该值可以是任何类型的。

Reserved

此参数是保留的，必须为零。

[in] dwType

lpData 参数指向的数据类型。有关可能类型的列表，请参阅注册表值类型。

[in] lpData

要存储的数据。

对于基于字符串的类型（如 REG_SZ），字符串必须以 null 结尾。对于 REG_MULTI_SZ 数据类型，字符串必须以两个 null 字符结尾。

注意 lpData 指示 null 值有效，但是，如果是这种情况， cbData 必须设置为“0”。

[in] cbData

lpData 参数指向的信息的大小（以字节为单位）。如果数据的类型为 REG_SZ、REG_EXPAND_SZ 或 REG_MULTI_SZ， 则 cbData 必须包含终止 null 字符的大小。

返回值

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

如果函数失败，则返回值为 Winerror.h 中定义的非零错误代码。可以将 FormatMessage 函数与 FORMAT_MESSAGE_FROM_SYSTEM 标志结合使用来获取错误的常规说明。

注解

值大小受可用内存的限制。但是，在注册表中存储较大的值可能会影响其性能。 (超过 2,048 字节的长值) 应存储为文件，文件的位置存储在注册表中。

应用程序元素（如图标、位图和可执行文件）应存储为文件，而不是放置在注册表中。

如果 dwType 是REG_SZ、REG_MULTI_SZ或REG_EXPAND_SZ类型，并且此函数的 ANSI 版本通过显式调用 RegSetValueExA 或未在将 Windows.h 文件) 之前未定义 UNICODE 来 (使用，则 lpData 参数指向的数据必须是 ANSI 字符串。字符串在存储到注册表中之前会转换为 Unicode。

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

请考虑使用 RegSetKeyValue 函数，该函数提供了一种更方便的方式来设置注册表项的值。

注意

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

要求

要求	值
最低受支持的客户端	Windows 2000 Professional [仅限桌面应用]
最低受支持的服务器	Windows 2000 Server [仅限桌面应用]
目标平台	Windows
标头	winreg.h (包括 Windows.h)
Library	Advapi32.lib
DLL	Advapi32.dll