IoOpenDeviceRegistryKey function

The IoOpenDeviceRegistryKey routine returns a handle to a device-specific or a driver-specific registry key for a particular device instance.

Syntax

NTSTATUS IoOpenDeviceRegistryKey(
  PDEVICE_OBJECT DeviceObject,
  ULONG          DevInstKeyType,
  ACCESS_MASK    DesiredAccess,
  PHANDLE        DeviceRegKey
);

Parameters

DeviceObject

Pointer to the PDO of the device instance for which the registry key is to be opened.

DevInstKeyType

Specifies flags indicating whether to open a device-specific hardware key or a driver-specific software key. The flags also indicate whether the key is relative to the current hardware profile. For more information about hardware and software keys, see Registry Keys for Drivers and Introduction to Registry Keys for Drivers.

The flags are defined as follows:

PLUGPLAY_REGKEY_DEVICE

Open the Device Parameters subkey under the device's hardware key (see HKLM\SYSTEM\CurrentControlSet\Enum Registry Tree), a device-specific registry subkey that contains information about the device. The key is located under the key for the device instance specified by DeviceObject. This flag cannot be specified with PLUGPLAY_REGKEY_DRIVER.

PLUGPLAY_REGKEY_DRIVER

Open a software key for storing driver-specific information. This flag cannot be specified with PLUGPLAY_REGKEY_DEVICE.

A driver's software key is also called its driver key because the registry contains a software key for each driver. The registry contains a list of all of the device classes, and each driver's software key resides under its device class entry. The system stores information about each driver under its software key. For more information about software keys, see The HKLM\SYSTEM\CurrentControlSet\Control Tree.

PLUGPLAY_REGKEY_CURRENT_HWPROFILE

Note: Hardware profiles are deprecated and state should not be stored relative to a hardware profile.

Open a key relative to the current hardware profile for device or driver information. This allows the driver to access configuration information that is hardware-profile-specific. The caller must specify either PLUGPLAY_REGKEY_DEVICE or PLUGPLAY_REGKEY_DRIVER with this flag. For more information, see HKLM\SYSTEM\CurrentControlSet\HardwareProfiles Registry Tree.

DesiredAccess

Specifies the ACCESS_MASK value that represents the access the caller needs to the key. See the ZwCreateKey routine for a description of each KEY_XXX access right.

DeviceRegKey

Pointer to a caller-allocated buffer that, on successful return, contains a handle to the requested registry key.

Return Value

IoOpenDeviceRegistryKey returns STATUS_SUCCESS if the call was successful. Possible error return values include the following.

Return code Description
STATUS_INVALID_PARAMETER
Possibly indicates that the caller specified an illegal set of DevInstKeyType flags.
STATUS_INVALID_DEVICE_REQUEST
Possibly indicates that the DeviceObject is not a valid PDO.

Remarks

The driver must call ZwClose to close the handle returned from this routine when access is no longer required.

The registry keys opened by this routine are nonvolatile.

User-mode setup applications can access these registry keys by using device installation functions such as SetupDiOpenDevRegKey. An example of a user-mode setup applications would be a class installer, a Win32 DLL that performs installation operations for devices in a particular Device Setup Class.

To create registry keys, use INF AddReg directives in an INF file or use SetupDiCreateDevRegKey in a setup application.

Callers of IoOpenDeviceRegistryKey must be running at IRQL = PASSIVE_LEVEL in the context of a system thread.

Requirements

   
Minimum supported client Available starting with Windows 2000.
Target Platform Universal
Header wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Library NtosKrnl.lib
DLL NtosKrnl.exe
IRQL PASSIVE_LEVEL (see Remarks section)
DDI compliance rules PowerIrpDDis, HwStorPortProhibitedDDIs

See Also

Introduction to Registry Keys for Drivers

ACCESS_MASK

ZwCreateKey   ZwClose