IoOpenDeviceRegistryKey function (wdm.h)
The IoOpenDeviceRegistryKey routine returns a handle to a registry state location for a particular device instance.
Syntax
NTSTATUS IoOpenDeviceRegistryKey(
[in] PDEVICE_OBJECT DeviceObject,
[in] ULONG DevInstKeyType,
[in] ACCESS_MASK DesiredAccess,
[out] PHANDLE DeviceRegKey
);
Parameters
[in] DeviceObject
Pointer to the physical device object (PDO) of the device instance for which the registry state location is to be opened.
[in] 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 Introduction to Registry Keys for Drivers.
The flags are defined as follows:
PLUGPLAY_REGKEY_DEVICE
Open the device's hardware key, a device-specific registry state location that contains information about the device. This flag cannot be specified with PLUGPLAY_REGKEY_DRIVER.
PLUGPLAY_REGKEY_DRIVER
Open the device's software key, a device-specific registry state location for storing driver-specific information. This flag cannot be specified with PLUGPLAY_REGKEY_DEVICE.
PLUGPLAY_REGKEY_CURRENT_HWPROFILE
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.
[in] 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.
[out] DeviceRegKey
Pointer to a caller-allocated buffer that, on successful return, contains a handle to the requested registry state location.
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 or provided a DeviceObject that 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 CM_Open_DevNode_Key or device information functions such as SetupDiOpenDevRegKey or SetupDiCreateDevRegKey.
To pre-populate state in these registry state locations at driver package installation time, use INF AddReg directives in an INF file.
Callers of IoOpenDeviceRegistryKey must be running at IRQL = PASSIVE_LEVEL in the context of a system thread.
Requirements
| Requirement | Value |
|---|---|
| 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 | HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm) |