RegCreateKeyExA 函数 (winreg.h)

创建指定的注册表项。 如果该键已存在,则函数将打开它。 请注意,键名称不区分大小写。

若要对密钥执行事务处理注册表操作,请调用 RegCreateKeyTransacted 函数。

备份或还原系统状态(包括系统文件和注册表配置单元)的应用程序应使用 卷影复制服务 而不是注册表功能。

语法

LSTATUS RegCreateKeyExA(
  [in]            HKEY                        hKey,
  [in]            LPCSTR                      lpSubKey,
                  DWORD                       Reserved,
  [in, optional]  LPSTR                       lpClass,
  [in]            DWORD                       dwOptions,
  [in]            REGSAM                      samDesired,
  [in, optional]  const LPSECURITY_ATTRIBUTES lpSecurityAttributes,
  [out]           PHKEY                       phkResult,
  [out, optional] LPDWORD                     lpdwDisposition
);

参数

[in] hKey

打开的注册表项的句柄。 调用过程必须具有对密钥KEY_CREATE_SUB_KEY访问权限。 有关详细信息,请参阅 注册表项安全和访问权限

根据注册表项的安全描述符检查密钥创建访问权限,而不是获取句柄时指定的访问掩码。 因此,即使使用 KEY_READ samDesired 打开了 hKey,也可以在修改注册表的操作中使用(如果其安全描述符允许)。

此句柄由 RegCreateKeyExRegOpenKeyEx 函数返回,也可以是以下 预定义键之一

HKEY_CLASSES_ROOT
HKEY_CURRENT_CONFIG
HKEY_CURRENT_USER
HKEY_LOCAL_MACHINE
HKEY_USERS

[in] lpSubKey

此函数打开或创建的子项的名称。 指定的子项必须是由 hKey 参数标识的键的子项;注册表树中最多可以有 32 个级别。 有关密钥名称的详细信息,请参阅注册表结构。

如果 lpSubKey 是指向空字符串的指针,则 phkResult 接收由 hKey指定的键的新句柄。

此参数不能 NULL

Reserved

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

[in, optional] lpClass

此键的用户定义类类型。 可以忽略此参数。 此参数可以 NULL

[in] dwOptions

此参数可以是下列值之一。

价值 意义
REG_OPTION_BACKUP_RESTORE
0x00000004L
如果设置了此标志,该函数将忽略 samDesired 参数,并尝试使用备份或还原密钥所需的访问权限打开密钥。 如果调用线程启用了SE_BACKUP_NAME特权,则会使用ACCESS_SYSTEM_SECURITY打开密钥,并KEY_READ访问权限。 如果调用线程启用了SE_RESTORE_NAME特权,从 Windows Vista 开始,则会使用 ACCESS_SYSTEM_SECURITY、DELETE 和 KEY_WRITE 访问权限打开密钥。 如果启用这两个权限,则密钥具有这两个权限的组合访问权限。 有关详细信息,请参阅 使用特殊特权运行。
REG_OPTION_CREATE_LINK
0x00000002L
注意,仅当 绝对 必要时,注册表符号链接才应用于应用程序兼容性。
 
此键是符号链接。 目标路径分配给键的 L“SymbolicLinkValue”值。 目标路径必须是绝对注册表路径。
REG_OPTION_NON_VOLATILE
0x00000000L
此键不可变;这是默认值。 信息存储在文件中,并在重新启动系统时保留。 RegSaveKey 函数保存不可变的键。
REG_OPTION_VOLATILE
0x00000001L
函数创建的所有键都是可变的。 信息存储在内存中,在卸载相应的注册表配置单元时不会保留。 对于 HKEY_LOCAL_MACHINE,仅当系统启动完全关闭时,才会发生这种情况。 对于由 RegLoadKey 函数加载的注册表项,执行相应的 RegUnLoadKey 时会发生此情况。 RegSaveKey 函数不会保存易失键。 对于已存在的键,将忽略此标志。
注意 用户选择的关闭时,快速启动关闭是系统的默认行为。
 

[in] samDesired

一个掩码,指定要创建的密钥的访问权限。 有关详细信息,请参阅 注册表项安全和访问权限

[in, optional] lpSecurityAttributes

指向 SECURITY_ATTRIBUTES 结构的指针,该结构确定返回的句柄是否可以由子进程继承。 如果 lpSecurityAttributesNULL,则无法继承句柄。

lpSecurityDescriptor 结构成员为新密钥指定安全描述符。 如果 lpSecurityAttributesNULL,则该密钥将获取默认的安全描述符。 密钥的默认安全描述符中的 ACL 继承自其直接父密钥。

[out] phkResult

指向接收已打开或创建的键句柄的变量的指针。 如果密钥不是预定义的注册表项之一,请使用句柄后调用 RegCloseKey 函数。

[out, optional] lpdwDisposition

指向接收以下处置值之一的变量的指针。

价值 意义
REG_CREATED_NEW_KEY
0x00000001L
密钥不存在且已创建。
REG_OPENED_EXISTING_KEY
0x00000002L
密钥已存在,并且只是打开而不更改。
 

如果 lpdwDispositionNULL,则不返回处置信息。

返回值

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

如果函数失败,则返回值为 Winerror.h 中定义的非零错误代码。 可以将 FormatMessage 函数与FORMAT_MESSAGE_FROM_SYSTEM标志一起使用,以获取错误的泛型说明。

言论

RegCreateKeyEx 函数创建的键没有值。 应用程序可以使用 RegSetValueEx 函数设置键值。

RegCreateKeyEx 函数在指定路径中创建所有缺失的键。 应用程序可以利用此行为一次性创建多个密钥。 例如,应用程序可以通过为 lpSubKey 参数指定以下格式的字符串,创建与上述三个子项相同的四个级别:

子项1\subkey2\subkey3\subkey4

请注意,如果路径中的现有密钥拼写错误,则此行为将导致创建不需要的密钥。

应用程序无法创建直接子级 HKEY_USERSHKEY_LOCAL_MACHINE的密钥。 应用程序可以在较低级别的 HKEY_USERSHKEY_LOCAL_MACHINE 树中创建子项。

如果服务或应用程序模拟不同的用户,请不要将此函数用于 HKEY_CURRENT_USER。 而是调用 RegOpenCurrentUser 函数。

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

注意

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

要求

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

另请参阅

RegCloseKey

RegDeleteKey

RegOpenKeyEx

RegSaveKey

注册表函数

注册表概述

SECURITY_ATTRIBUTES