PcNewRegistryKey function (portcls.h)
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.
Syntax
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
);
Parameters
[out] 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.
[in, optional] 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.
[in] RegistryKeyType
Specifies the type of registry key that the caller wants to create or open. For more information, see the following Remarks section.
[in] 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. For more information, see the following Remarks section.
[in, optional] 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. For more information, see the following Remarks section.
[in, optional] SubDevice
Specifies the aspect of the device that is to be offered to clients. Adapter drivers must assign the value NULL to this parameter.
[in, optional] 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. For more information, see the following Remarks section.
[in, optional] CreateOptions
Specifies the create options. Can be zero if none are desired. If RegistryKeyType is not GeneralRegistryKey, the PcNewRegistryKey function ignores this parameter. For more information, see the following Remarks section.
[out, optional] Disposition
Pointer to a variable that receives a value indicating whether 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. For more information, see the following Remarks section.
Return value
PcNewRegistryKey returns STATUS_SUCCESS if the call was successful. Otherwise, it returns an appropriate error code.
Remarks
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 Plug and Play 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.
| RegistryKeyType value | Meaning |
|---|---|
| GeneralRegistryKey | Provide generic access to any key type. Open the specified key if it already exists or create the key if it does not. |
| DeviceRegistryKey | Open an existing key containing device-specific information. The key is located under the key for the device instance specified by DeviceObject. |
| DriverRegistryKey | Open an existing key containing driver-specific information. |
| HwProfileRegistryKey | Open an existing key relative to the current hardware profile containing device or driver information. This allows the driver to access configuration information that is hardware-profile-specific. |
| DeviceInterfaceRegistryKey | Not used with PcNewRegistryKey. See IPort::NewRegistryKey for details. |
For a RegistryKeyType value of GeneralRegistryKey, the caller must provide a valid ObjectAttributes parameter value, and the CreateOptions and Disposition parameters are optional. For any other RegistryKeyType value, the caller must provide a valid DeviceObject parameter value, and the CreateOptions and Disposition parameters are not used.
The ObjectAttributes parameter points to an opaque structure of type OBJECT_ATTRIBUTES that contains object attributes such as key name and security descriptor. Use the InitializeObjectAttributes macro to initialize the structure. In the Attributes parameter for this macro, set the OBJ_KERNEL_HANDLE flag unless you intend to allow non-secure, user-mode applications to have read/write access to the registry key.
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 access control list (ACL) 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 Plug and Play 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.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | The PortCls system driver implements the PcNewRegistryKey function in Microsoft Windows 98/Me and in Windows 2000 and later operating systems. |
| Target Platform | Universal |
| Header | portcls.h (include Portcls.h) |
| Library | Portcls.lib |
| IRQL | PASSIVE_LEVEL |