通过

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 值，则此参数必须指向具有密钥的有效 ObjectName 字符串OBJECT_ATTRIBUTES类型的有效初始化系统结构;否则，该方法不使用此参数。 有关详细信息，请参阅以下“备注”部分。

CreateOptions

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

Disposition

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

返回值

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

言论

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 函数，只是必须在 PcNewRegistryKey 调用中显式指定设备对象和端口对象，但只是在 NewRegistryKey 调用中隐含。 PcNewRegistryKey 通常由适配器驱动程序调用。 微型端口驱动程序通常改为调用 NewRegistryKey。

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

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

要求

要求 价值
标头 portcls.h
IRQL PASSIVE_LEVEL

另请参阅

IPort