RegCreateKeyTransactedW 函数 (winreg.h)

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

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

语法

LSTATUS RegCreateKeyTransactedW(
  [in]            HKEY                        hKey,
  [in]            LPCWSTR                     lpSubKey,
                  DWORD                       Reserved,
  [in, optional]  LPWSTR                      lpClass,
  [in]            DWORD                       dwOptions,
  [in]            REGSAM                      samDesired,
  [in, optional]  const LPSECURITY_ATTRIBUTES lpSecurityAttributes,
  [out]           PHKEY                       phkResult,
  [out, optional] LPDWORD                     lpdwDisposition,
  [in]            HANDLE                      hTransaction,
                  PVOID                       pExtendedParemeter
);

参数

[in] hKey

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

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

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

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特权,则会使用ACCESS_SYSTEM_SECURITY打开密钥,并KEY_WRITE访问权限。 如果启用这两个权限,则密钥具有这两个权限的组合访问权限。 有关详细信息,请参阅 使用特殊特权运行。
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,则不返回处置信息。

[in] hTransaction

活动事务的句柄。 此句柄由 CreateTransaction 函数返回。

pExtendedParemeter

此参数是保留的,必须 NULL

返回值

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

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

言论

使用此函数创建密钥时,将处理对密钥的后续操作。 如果在提交事务之前对密钥执行非事务处理操作,则会回滚该事务。 提交或回滚事务后,必须使用 RegCreateKeyTransactedRegOpenKeyTransacted 重新打开密钥,以便执行其他操作。 有关事务的详细信息,请参阅 内核事务管理器

请注意,不会自动处理此密钥的子项上的后续操作。 因此,RegDeleteKeyEx 不执行事务处理删除操作。 请改用 RegDeleteKeyTransacted 函数来执行事务处理删除操作。

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

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

子项1\subkey2\subkey3\subkey4

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

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

注意

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

要求

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

另请参阅

RegCloseKey

RegDeleteKeyTransacted

RegOpenKeyTransacted

RegSaveKey

注册表函数

注册表概述

SECURITY_ATTRIBUTES