PcNewRegistryKey

The PcNewRegistryKey function opens or creates a new registry key and creates an IRegistryKey object to represent the key. The caller accesses the key through this object.

PORTCLASSAPI NTSTATUS NTAPI
  PcNewRegistryKey(
    OUT PREGISTRYKEY  *OutRegistryKey,
    IN PUNKNOWN  OuterUnknown  OPTIONAL,
    IN ULONG  RegistryKeyType,
    IN ACCESS_MASK  DesiredAccess,
    IN PVOID  DeviceObject  OPTIONAL,
    IN PVOID  SubDevice  OPTIONAL,
    IN POBJECT_ATTRIBUTES  ObjectAttributes  OPTIONAL,
    IN ULONG  CreateOptions  OPTIONAL,
    OUT PULONG  Disposition  OPTIONAL
    );

Parameters

OutRegistryKey

Output pointer to the registry-key object created by this function. This parameter points to a caller-allocated pointer variable into which the function outputs the pointer to the IRegistryKey object. The object represents the registry key being opened or created. Specify a valid, non-NULL pointer value for this parameter.

OuterUnknown

Pointer to the IUnknown interface of an object that needs to aggregate the OutRegistryKey object. Unless aggregation is required, set this parameter to NULL.

RegistryKeyType

Specifies the type of registry key that the caller wants to create or open. See the following Comments section.

DesiredAccess

Specifies an access-control mask. This parameter is a structure of type ACCESS_MASK. It indicates the type of access that the caller is requesting to the registry key that is to be opened or created. See the following Comments section.

DeviceObject

Pointer to the adapter driver's device object. This pointer is cast to type PVOID. If RegistryKeyType is any value other than GeneralRegistryKey, this parameter must point to a valid, initialized system structure of type DEVICE_OBJECT. If the value of RegistryKeyType is GeneralRegistryKey, the PcNewRegistryKey function does not use this parameter. See the following Comments section.

SubDevice

Specifies the aspect of the device that is to be offered to clients. Adapter drivers must assign the value NULL to this parameter. See the following Comments section.

ObjectAttributes

Pointer to the object attributes of the key being created or opened. If RegistryKeyType has the value GeneralRegistryKey, this parameter must point to a valid, initialized system structure of type OBJECT_ATTRIBUTES with a valid ObjectName string for the key; otherwise, the function does not use this parameter. See the following Comments section.

CreateOptions

Specifies the create options. Can be zero if none are desired. If RegistryKeyType is not GeneralRegistryKey, the PcNewRegistryKey function ignores this parameter. See the following Comments section.

Disposition

Pointer to a variable that receives a value indicating whether or not a key was created or an existing key was opened. This parameter is optional and can be specified as NULL. If RegistryKeyType is any value other than GeneralRegistryKey, the PcNewRegistryKey function ignores this parameter. See the following Comments section.

Return Value

PcNewRegistryKey returns STATUS_SUCCESS if the call was successful. Otherwise, it returns an appropriate error code.

Headers

Declared in portcls.h. Include portcls.h.

Comments

If the RegistryKeyType parameter's value is GeneralRegistryKey, then the PcNewRegistryKey function either opens an existing key or creates a new key in the registry, as indicated by the value that the function outputs through the Disposition parameter. If the key is of any type other than GeneralRegistryKey, then the function opens an already existing key that was previously created during PnP device enumeration.

The DesiredAccess, ObjectAttributes, CreateOptions, and Disposition parameters take on the values that are defined for the parameters with the same names in the ZwCreateKey call.

The RegistryKeyType parameter should be set to one of the enumeration values shown in the following table.

For a RegistryKeyType value of GeneralRegistryKey, the caller must provide valid ObjectAttributes and CreateOptions parameter values. For any other RegistryKeyType value, the caller must provide a valid DeviceObject parameter value.

The DesiredAccess parameter is an access-control mask. It specifies the type of access control that the caller needs to have to the new registry key when accessing it through the OutRegistryKey object. This mask should not be confused with the ACL (access control list) that controls access by users to the registry key. When calling PcNewRegistryKey to create a registry key of type GeneralRegistryKey, the ObjectAttributes parameter specifies the key's attributes, including a security descriptor that contains the ACL. However, if the new key is of type GeneralRegistryKey and either the security descriptor pointer in the ObjectAttributes structure is NULL or the ACL pointer in the security descriptor is NULL, then the new key will inherit the parent key’s ACL by default.

If the key is of any type other than GeneralRegistryKey, then the key retains the ACL that PnP assigned to the key when it was created during device enumeration.

The PcNewRegistryKey function is similar to the IPort::NewRegistryKey method except that the device object and port object must be explicitly specified in a PcNewRegistryKey call but are simply implied in a NewRegistryKey call. PcNewRegistryKey is used primarily by adapter drivers. Miniport drivers typically call NewRegistryKey instead.

The OutRegistryKey and OuterUnknown parameters follow the reference-counting conventions for COM objects.

See Also

IRegistryKey, ACCESS_MASK, DEVICE_OBJECT, OBJECT_ATTRIBUTES, ZwCreateKey, IPort::NewRegistryKey