PcNewRegistryKey 函数 （portcls.h）
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 的值，则此参数必须指向具有有效 ObjectName 字符串的 OBJECT_ATTRIBUTES 类型的有效初始化系统结构;否则，该函数不使用此参数。 有关详细信息，请参阅以下“备注”部分。
[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 方法，但设备对象和端口对象必须在 PcNewRegistryKey 调用中显式指定，但只是在 NewRegistryKey 调用中隐含。 PcNewRegistryKey 主要用于适配器驱动程序。 微型端口驱动程序通常改为调用 NewRegistryKey。
OutRegistryKey 和 OuterUnknown 参数遵循 COM 对象的 引用计数约定。
要求
| 要求 | 价值 |
|---|---|
| 最低支持的客户端 | PortCls 系统驱动程序在 Microsoft Windows 98/Me 和 Windows 2000 及更高版本的作系统中实现 PcNewRegistryKey 函数。 |
| 目标平台 | 普遍 |
| 标头 | portcls.h （包括 Portcls.h） |
| 库 | Portcls.lib |
| IRQL | PASSIVE_LEVEL |