RegCreateKeyTransactedA 函数 (winreg.h)

  • 项目

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

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

语法

LSTATUS RegCreateKeyTransactedA(
  [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]            HANDLE                      hTransaction,
                  PVOID                       pExtendedParemeter
);

参数

[in] hKey

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

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

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

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

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

[out] phkResult

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

[out, optional] lpdwDisposition

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

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

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

[in] hTransaction

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

pExtendedParemeter

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

返回值

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

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

注解

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

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

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

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

subkey1\subkey2\subkey3\subkey4

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

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

注意

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

要求

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

另请参阅

RegCloseKey

RegDeleteKeyTransacted

RegOpenKeyTransacted

RegSaveKey

注册表函数

注册表概述

SECURITY_ATTRIBUTES