IRegistryKey：：NewSubKey 方法（portcls.h）

项目
02/07/2025

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

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

[in] CreateOptions

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

[out, optional] Disposition

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

返回值

如果调用成功通过 RegistrySubKey 参数输出有效的 IRegistryKey 指针，则 NewSubKey 返回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 对象的引用计数约定。