IPort：：NewRegistryKey 方法 (portcls.h)

NewRegistryKey 方法打开现有注册表项或在注册表中创建新注册表项。 方法创建一个注册表项对象来表示该键，并将对此对象的引用输出给调用方。 然后，调用方通过对象的 IRegistryKey 接口访问密钥。

语法

NTSTATUS NewRegistryKey(
  PREGISTRYKEY       *OutRegistryKey,
  PUNKNOWN           OuterUnknown,
  ULONG              RegistryKeyType,
  ACCESS_MASK        DesiredAccess,
  POBJECT_ATTRIBUTES ObjectAttributes,
  ULONG              CreateOptions,
  PULONG             Disposition
);

参数

OutRegistryKey

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

OuterUnknown

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

RegistryKeyType

指定调用方请求访问的注册表项的类型。 有关更多信息，请参见下面的“备注”部分。

DesiredAccess

一个访问控制掩码，指定调用方对密钥所需的访问类型。 此参数的类型为 ACCESS_MASK。 有关更多信息，请参见下面的“备注”部分。

ObjectAttributes

指向正在创建或打开的键的对象属性的指针。 如果 RegistryKeyType 具有值 GeneralRegistryKey，则此参数必须指向类型为 OBJECT_ATTRIBUTES 的有效初始化系统结构，并且该键具有有效的 ObjectName 字符串;否则， 方法不使用此参数。 有关更多信息，请参见下面的“备注”部分。

CreateOptions

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

Disposition

指向调用方分配的 ULONG 变量的指针，该方法在该变量中写入一个状态值，指示是创建新键还是打开了现有密钥。 此参数是可选的，如果调用方不需要状态值，则可以指定为 NULL。 仅当 RegistryKeyType 具有值 GeneralRegistryKey 时， 方法才使用此参数。 方法不对任何其他键类型使用 参数。 有关更多信息，请参见下面的“备注”部分。

返回值

如果调用成功，此方法返回包含STATUS_SUCCESS的 NTSTATUS。 否则，该方法将返回相应的错误代码。

注解

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

如果 RegistryKeyType 参数具有值 GeneralRegistryKey，则 NewRegistryKey 方法打开现有注册表项或在注册表中创建新项，如该方法通过 Disposition 参数输出的值所示。 如果键类型是除 GeneralRegistryKey 以外的任何值，则该方法将打开先前在即插即用设备枚举期间创建的现有密钥。

调用方应将 RegistryKeyType 参数设置为下表所示的枚举值之一。

RegistryKeyType 值	含义
GeneralRegistryKey	提供对任何密钥类型的泛型访问。 如果密钥存在，则打开该密钥，否则将创建该密钥。
DeviceRegistryKey	打开包含设备特定信息的现有密钥。
DriverRegistryKey	打开包含驱动程序特定信息的现有密钥。
HwProfileRegistryKey	打开与当前硬件配置文件相关的现有密钥，以获取设备或驱动程序信息。 这允许驱动程序访问特定于硬件配置文件的配置信息。
DeviceInterfaceRegistryKey	打开包含特定设备接口实例信息的现有注册表项。

对于 GeneralRegistryKey 的 RegistryKeyType 值，调用方必须提供有效的 ObjectAttributes 参数值，并且 CreateOptions 和 Disposition 参数是可选的。 对于任何其他 RegistryKeyType 值，调用方必须提供有效的 DeviceObject 参数值，并且不使用 CreateOptions 和 Disposition 参数。

ObjectAttributes 参数指向OBJECT_ATTRIBUTES类型的不透明结构，该结构包含密钥名称和安全描述符等对象属性。 使用 InitializeObjectAttributes 宏初始化 结构。 在此宏的 Attributes 参数中，设置 OBJ_KERNEL_HANDLE 标志，除非你打算允许非安全的用户模式应用程序具有对注册表项的读/写访问权限。

DesiredAccess 参数是访问控制掩码。 它指定调用方在通过 OutRegistryKey 对象访问新注册表项时需要对新注册表项拥有的访问控制类型。 不应将此掩码与控制用户对注册表项的访问) ACL (访问控制列表混淆。 调用 NewRegistryKey 以创建 GeneralRegistryKey 类型的注册表项时，ObjectAttributes 参数指定密钥的属性，包括包含 ACL 的安全描述符。 但是，如果键类型为 GeneralRegistryKey，并且 ObjectAttributes 结构中的安全描述符指针为 NULL 或安全描述符中的 ACL 指针为 NULL，则调用创建的新密钥将默认继承父键的 ACL。

如果密钥的类型不是 GeneralRegistryKey，则该密钥将保留即插即用在设备枚举期间创建密钥时分配给该密钥的 ACL。

NewRegistryKey 方法类似于 PcNewRegistryKey 函数，不同之处在于设备对象和 port 对象必须在 PcNewRegistryKey 调用中显式指定，但只是在 NewRegistryKey 调用中隐含。 PcNewRegistryKey 通常由适配器驱动程序调用。 微型端口驱动程序通常改为调用 NewRegistryKey。

通过调用 NewRegistryKey 或 PcNewRegistryKey 创建或打开注册表项后，可以使用 IRegistryKey：：NewSubKey 方法在该注册表项下创建子项。

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

要求

要求	值
Header	portcls.h
IRQL	PASSIVE_LEVEL

另请参阅

IPort