pcNewRegistryKey 函数 (portcls.h)

项目
02/29/2024

PcNewRegistryKey 函数打开或创建新的注册表项，并创建一个 IRegistryKey 对象来表示该密钥。调用方通过此对象访问密钥。

语法

PORTCLASSAPI NTSTATUS PcNewRegistryKey(
  [out]           PREGISTRYKEY       *OutRegistryKey,
  [in, optional]  PUNKNOWN           OuterUnknown,
  [in]            ULONG              RegistryKeyType,
  [in]            ACCESS_MASK        DesiredAccess,
  [in, optional]  PVOID              DeviceObject,
  [in, optional]  PVOID              SubDevice,
  [in, optional]  POBJECT_ATTRIBUTES ObjectAttributes,
  [in, optional]  ULONG              CreateOptions,
  [out, optional] PULONG             Disposition
);

参数

[out] OutRegistryKey

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

[in, optional] OuterUnknown

指向需要聚合 OutRegistryKey 对象的对象的 IUnknown 接口的指针。除非需要聚合，否则请将此参数设置为 NULL。

[in] RegistryKeyType

指定调用方要创建或打开的注册表项的类型。有关更多信息，请参见下面的“备注”部分。

[in] DesiredAccess

指定访问控制掩码。此参数是 ACCESS_MASK 类型的结构。它指示调用方请求对要打开或创建的注册表项的访问类型。有关更多信息，请参见下面的“备注”部分。

[in, optional] DeviceObject

指向适配器驱动程序的设备对象的指针。此指针将强制转换为类型 PVOID。如果 RegistryKeyType 是 GeneralRegistryKey 以外的任何值，则此参数必须指向 DEVICE_OBJECT 类型的有效初始化系统结构。如果 RegistryKeyType 的值为 GeneralRegistryKey，则 PcNewRegistryKey 函数不使用此参数。有关更多信息，请参见下面的“备注”部分。

[in, optional] SubDevice

指定要提供给客户端的设备方面。适配器驱动程序必须将值 NULL 分配给此参数。

[in, optional] ObjectAttributes

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

[in, optional] CreateOptions

指定创建选项。如果不需要，可以为零。如果 RegistryKeyType 不是 GeneralRegistryKey， 则 PcNewRegistryKey 函数将忽略此参数。有关更多信息，请参见下面的“备注”部分。

[out, optional] Disposition

指向变量的指针，该变量接收一个值，该值指示是创建键还是打开了现有键。此参数是可选的，可以指定为 NULL。如果 RegistryKeyType 是 除 GeneralRegistryKey 以外的任何值， 则 PcNewRegistryKey 函数将忽略此参数。有关更多信息，请参见下面的“备注”部分。

返回值

如果调用成功，PcNewRegistryKey 将返回STATUS_SUCCESS。否则，它将返回相应的错误代码。

注解

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

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

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

RegistryKeyType 值	含义
GeneralRegistryKey	提供对任何密钥类型的泛型访问。如果指定的项已存在，请打开该键，如果不存在，则创建该键。
DeviceRegistryKey	打开包含设备特定信息的现有密钥。该密钥位于 DeviceObject 指定的设备实例的键下。
DriverRegistryKey	打开包含驱动程序特定信息的现有密钥。
HwProfileRegistryKey	打开与包含设备或驱动程序信息的当前硬件配置文件相关的现有密钥。这允许驱动程序访问特定于硬件配置文件的配置信息。
DeviceInterfaceRegistryKey	不与 PcNewRegistryKey 一起使用。有关详细信息，请参阅 IPort：：NewRegistryKey 。

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

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

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

如果密钥属于除 GeneralRegistryKey 以外的任何类型，则该密钥将保留即插即用在设备枚举期间创建密钥时分配给该密钥的 ACL。

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

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

要求

要求	值
最低受支持的客户端	PortCls 系统驱动程序在 Microsoft Windows 98/Me 以及 Windows 2000 及更高版本的操作系统中实现 PcNewRegistryKey 函数。
目标平台	通用
标头	portcls.h (包括 Portcls.h)
Library	Portcls.lib
IRQL	PASSIVE_LEVEL