WdfDeviceOpenRegistryKey method
[Applies to KMDF and UMDF]
The WdfDeviceOpenRegistryKey method opens a device's hardware key or a driver's software key in the registry and creates a framework registry-key object that represents the registry key.
Syntax
NTSTATUS WdfDeviceOpenRegistryKey( [in] WDFDEVICE Device, [in] ULONG DeviceInstanceKeyType, [in] ACCESS_MASK DesiredAccess, [in, optional] PWDF_OBJECT_ATTRIBUTES KeyAttributes, [out] WDFKEY *Key );
Parameters
- Device [in]
-
A handle to a framework device object.
- DeviceInstanceKeyType [in]
-
The driver sets the PLUGPLAY_REGKEY_DEVICE flag to open the Device Parameters subkey under the device's hardware key, or it sets the PLUGPLAY_REGKEY_DRIVER flag to open the driver's software key. If a KMDF driver also sets the PLUGPLAY_REGKEY_CURRENT_HWPROFILE flag, WdfFdoInitOpenRegistryKey opens the copy of the hardware or software key that is in the current hardware profile. A UMDF driver sets PLUGPLAY_REGKEY_DRIVER to open the driver's software key for read-only access, or PLUGPLAY_REGKEY_DRIVER | WDF_REGKEY_DRIVER_SUBKEY to open the ServiceName subkey for read/write access. Similarly, a UMDF driver sets PLUGPLAY_REGKEY_DEVICE to open the device's hardware key for read-only access, or PLUGPLAY_REGKEY_DEVICE | WDF_REGKEY_DEVICE_SUBKEY to open the ServiceName subkey for read/write access.
- DesiredAccess [in]
-
An ACCESS_MASK-typed value that specifies access rights that the driver is requesting for the specified registry key. A KMDF driver typically requests STANDARD_RIGHTS_ALL, but a UMDF driver needs to be more specific. If opening the device's hardware key or the driver's software key, a UMDF driver should choose KEY_READ. If opening subkeys for read/write access, you can use KEY_READ | KEY_SET_VALUE. See additional info for UMDF drivers in the Return values section.
For a list of access rights that drivers typically use for registry keys, see Opening a Handle to a Registry-Key Object. Your driver must ask for only the types of access that it needs. For example, the driver must not ask for KEY_ALL_ACCESS if it will only read the registry key.
- KeyAttributes [in, optional]
-
A pointer to a WDF_OBJECT_ATTRIBUTES structure that contains driver-supplied attributes for the new registry-key object. This parameter is optional and can be WDF_NO_OBJECT_ATTRIBUTES.
- Key [out]
-
A pointer to a location that receives a handle to the new registry-key object.
Return value
WdfDeviceOpenRegistryKey returns STATUS_SUCCESS if the operation succeeds. Otherwise, the method might return one of the following values:
| Return code | Description |
|---|---|
|
WdfDeviceOpenRegistryKey was not called at IRQL = PASSIVE_LEVEL. |
|
An invalid parameter was specified. |
|
A registry-key object could not be allocated. |
|
The system denied the specified access rights. A UMDF driver receives this return code if it specifies one of the following access rights:
Because the above values are invalid for UMDF drivers, universal flags such as GENERIC_ALL and STANDARD_RIGHTS_ALL also cause WdfDeviceOpenRegistryKey to fail with this return value. |
|
The specified registry key does not exist. |
For a list of other return values that the WdfDeviceOpenRegistryKey method might return, see Framework Object Creation Errors.
The method might return other NTSTATUS values.
A bug check occurs if the driver supplies an invalid object handle.
Remarks
If your driver must open a hardware or software key before it has called WdfDeviceCreate, it must call WdfFdoInitOpenRegistryKey instead of WdfDeviceOpenRegistryKey.
When the driver has finished using the registry key that it opened with WdfDeviceOpenRegistryKey, the driver must call WdfRegistryClose.
For more information about the registry, hardware and software keys, and registry objects, see Using the Registry in Framework-Based Drivers.
Examples
For code examples that use WdfDeviceOpenRegistryKey, see WdfRegistryCreateKey, WdfRegistryOpenKey, and WdfRegistryQueryValue.
Requirements
|
Minimum KMDF version | 1.0 |
|---|---|
|
Minimum UMDF version | 2.0 |
|
Header |
|
|
Library |
|
|
IRQL | PASSIVE_LEVEL |
|
DDI compliance rules | AccessHardwareKey, DriverCreate, KmdfIrql, KmdfIrql2 |
See also
