IRegistryKey：：NewSubKey 方法 (portcls.h)

项目
02/29/2024

方法 NewSubKey 创建新的注册表子项，或在 IRegistryKey 对象表示的项下打开现有子项。

语法

NTSTATUS NewSubKey(
  [out]           IRegistryKey    **RegistrySubKey,
  [in]            PUNKNOWN        OuterUnknown,
  [in]            ACCESS_MASK     DesiredAccess,
  [in]            PUNICODE_STRING SubKeyName,
  [in]            ULONG           CreateOptions,
  [out, optional] PULONG          Disposition
);

参数

[out] RegistrySubKey

新子项的输出指针。此参数指向调用方分配的指针变量，该方法将指针写入到新的 IRegistryKey 对象。此对象表示正在打开或创建的子项。为此参数指定有效的非 NULL 指针值。

[in] OuterUnknown

指向需要聚合注册表项对象的对象的 IUnknown 接口的指针。此参数是可选的。如果不需要聚合，请将此参数指定为 NULL。

[in] DesiredAccess

指定调用方对正在打开或创建的子项所需的访问类型。此参数的类型为 ACCESS_MASK。有关更多信息，请参见下面的“备注”部分。

[in] SubKeyName

指向要分配给子项的名称的指针。此参数必须是指向 UNICODE_STRING 类型的已初始化结构的有效非 NULL 指针。

[in] CreateOptions

指示创建选项的标志。如果不需要，可以为零。如果 RegistryKeyType 的值为 GeneralRegistryKey，则此参数是必需的;否则，方法不使用此参数。有关更多信息，请参见下面的“备注”部分。

[out, optional] Disposition

处置值的输出指针。此参数指向调用方分配的 ULONG 变量，该方法在该变量中写入一个状态值，指示是创建新键还是打开了现有密钥。此参数是可选的，如果调用方不需要此参数，则可以将其指定为 NULL 。有关更多信息，请参见下面的“备注”部分。

返回值

NewSubKey如果调用通过 RegistrySubKey 参数成功输出有效的 IRegistryKey 指针，则返回STATUS_SUCCESS。否则，该方法将返回相应的错误代码。

注解

方法 NewSubKey 打开指定的注册表项（如果已存在），或者在注册表中创建新项（如果不存在）。方法通过 RegistrySubKey 参数输出指向新项的 IRegistryKey 接口的指针。方法还通过可选的 Disposition 参数输出状态值，以指示密钥是打开还是已创建。

DesiredAccess、CreateOptions 和 Disposition 参数采用为 PcNewRegistryKey 调用中具有相同名称的参数定义的值。

DesiredAccess 参数是一个访问控制掩码，用于指定调用方在通过 RegistrySubKey 对象访问子项时需要对子项拥有的访问控制类型。不应将此掩码与控制用户对注册表子项的访问) ACL (访问控制列表混淆。当 PcNewRegistryKey 函数或 IPort：：NewRegistryKey 方法创建 类型为 GeneralRegistryKey 的注册表项时， ObjectAttributes 参数指定密钥的属性，包括包含 ACL 的安全描述符。但是， NewSubKey 当方法创建新的注册表子项时，该子项只是从其父项继承 ACL。方法 NewSubKey 不提供指定不同于父键的 ACL 的方法。

RegistrySubKey 和 OuterUnknown 参数遵循 COM 对象的引用计数约定。