WdfFdoInitOpenRegistryKey method
[Applies to KMDF and UMDF]
The WdfFdoInitOpenRegistryKey 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 WdfFdoInitOpenRegistryKey( [in] PWDFDEVICE_INIT DeviceInit, [in] ULONG DeviceInstanceKeyType, [in] ACCESS_MASK DesiredAccess, [in, optional] PWDF_OBJECT_ATTRIBUTES KeyAttributes, [out] WDFKEY *Key );
Parameters
- DeviceInit [in]
-
A pointer to a WDFDEVICE_INIT structure that the driver obtained from its EvtDriverDeviceAdd callback function.
- 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, set to 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.
- 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
WdfFdoInitOpenRegistryKey returns STATUS_SUCCESS if the operation succeeds. Otherwise, the method might return one of the following values:
| Return code | Description |
|---|---|
|
WdfFdoInitOpenRegistryKey was not called at IRQL = PASSIVE_LEVEL. |
|
An invalid parameter was specified, or the driver did not obtain the WDFDEVICE_INIT structure from its EvtDriverDeviceAdd callback function. |
|
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 WdfFdoInitOpenRegistryKey to fail with this return value. |
|
The specified registry key does not exist. |
For a list of other return values that the WdfFdoInitOpenRegistryKey method might return, see Framework Object Creation Errors.
The method might also return other NTSTATUS values.
Remarks
The driver must call WdfFdoInitOpenRegistryKey before calling WdfDeviceCreate. For more information about calling WdfDeviceCreate, see Creating a Framework Device Object.
For more information about the WdfFdoInitOpenRegistryKey method, see Creating Device Objects in a Function Driver.
or more information about the registry, hardware and software keys, and registry objects, see Using the Registry in Framework-Based Drivers.
Examples
The following code example opens a device's hardware key, with read access.
WDFKEY key;
NTSTATUS status;
status = WdfFdoInitOpenRegistryKey(
DeviceInit,
PLUGPLAY_REGKEY_DEVICE,
GENERIC_READ,
WDF_NO_OBJECT_ATTRIBUTES,
&key
);
if (!NT_SUCCESS(status)) {
return status;
}
Requirements
|
Minimum KMDF version | 1.0 |
|---|---|
|
Minimum UMDF version | 2.0 |
|
Header |
|
|
Library |
|
|
IRQL | PASSIVE_LEVEL |
|
DDI compliance rules | DeviceInitAPI, DriverCreate, KmdfIrql, KmdfIrql2 |
See also
