WdfDeviceOpenDevicemapKey function (wdfdevice.h)

[Applies to KMDF and UMDF]

The WdfDeviceOpenDevicemapKey method opens the DEVICEMAP key and creates a framework registry-key object that represents the registry key.

Syntax

NTSTATUS WdfDeviceOpenDevicemapKey(
  [in]           WDFDEVICE              Device,
  [in]           PCUNICODE_STRING       KeyName,
  [in]           ACCESS_MASK            DesiredAccess,
  [in, optional] PWDF_OBJECT_ATTRIBUTES KeyAttributes,
  [out]          WDFKEY                 *Key
);

Parameters

[in] Device

A handle to a framework device object.

[in] KeyName

A pointer to a UNICODE_STRING structure that specifies the name of the subkey to open under DEVICEMAP.

[in] DesiredAccess

An ACCESS_MASK-typed value that specifies access rights that the driver is requesting for the specified registry key.

A KMDF driver typically requests KEY_READ, KEY_WRITE, or KEY_READ | KEY_WRITE.

A UMDF driver typically requests KEY_READ or KEY_SET_VALUE.

[in, optional] KeyAttributes

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.

[out] Key

A pointer to a location that receives a handle to the new registry-key object. The

Return value

WdfDeviceOpenDevicemapKey returns STATUS_SUCCESS if the operation succeeds. Otherwise, the method might return one of the following values:

Return code Description
STATUS_INVALID_DEVICE_REQUEST

WdfDeviceOpenDevicemapKey was not called at IRQL = PASSIVE_LEVEL.

STATUS_INVALID_PARAMETER
An invalid parameter was specified. For UMDF, this return value can indicate insufficient access rights.
STATUS_INSUFFICIENT_RESOURCES
A registry-key object could not be allocated.
STATUS_OBJECT_NAME_NOT_FOUND
The specified registry key does not exist.
 

For a list of other return values that the WdfDeviceOpenDevicemapKey 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

The registry contains a HKEY_LOCAL_MACHINE\HARDWARE\DEVICEMAP key that some drivers for older technologies, such as serial and parallel ports, use. If your driver supports a technology that uses the DEVICEMAP key, the driver can access subkeys and values under the key by calling WdfDeviceOpenDevicemapKey.

WdfDeviceOpenDevicemapKey returns a volatile Key. This means that the information is not preserved when the corresponding registry hive is unloaded.

When the driver has finished using the registry key that it opened with WdfDeviceOpenDevicemapKey, 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.

Requirements

Requirement Value
Target Platform Universal
Minimum KMDF version 1.15
Minimum UMDF version 2.15
Header wdfdevice.h (include Wdf.h)
Library Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL PASSIVE_LEVEL

See also

WdfDeviceOpenRegistryKey

WdfFdoInitOpenRegistryKey