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访问权限。 有关详细信息，请参阅 注册表项安全和访问权限。

针对注册表项的安全描述符（而不是获取句柄时指定的访问掩码）检查密钥创建的访问权限。 因此，即使 hKey 是使用 samDesired KEY_READ 打开的，它也可用于修改注册表的操作（如果其安全描述符允许）。

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

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 结构的指针，该结构确定是否可由子进程继承返回的句柄。 如果 lpSecurityAttributes 为 NULL，则无法继承句柄。

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

[out] phkResult

一个变量的指针，此变量指向已打开或已创建的项的句柄。 如果该键不是预定义的注册表项之一，请在使用完句柄后调用 RegCloseKey 函数。

[out, optional] lpdwDisposition

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

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

如果 lpdwDisposition 为 NULL，则不返回任何处置信息。

返回值

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

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

注解

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

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

subkey1\subkey2\subkey3\subkey4

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

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

如果服务或应用程序模拟不同的用户，请不要将此函数与 HKEY_CURRENT_USER一起使用。 请改为调用 RegOpenCurrentUser 函数。

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

注意

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

要求

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

另请参阅

RegCloseKey

RegDeleteKey

RegOpenKeyEx

RegSaveKey

注册表函数

注册表概述

SECURITY_ATTRIBUTES