RegSetValueExA 函数（winreg.h）

项目
11/20/2024

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

语法

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

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

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

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

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

Reserved

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

[in] dwType

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

[in] lpData

要存储的数据。

对于基于字符串的类型（如REG_SZ），字符串必须 null-terminated。使用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，还是未定义 UNICODE，则 lpData 参数指向的数据必须是 ANSI 字符串。字符串在存储在注册表中之前转换为 Unicode。

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

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

注意

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

要求

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