WDF_PROPERTY_STORE_ROOT structure (wudfddi_types.h)
[Warning: UMDF 2 is the latest version of UMDF and supersedes UMDF 1. All new UMDF drivers should be written using UMDF 2. No new features are being added to UMDF 1 and there is limited support for UMDF 1 on newer versions of Windows 10. Universal Windows drivers must use UMDF 2. For more info, see Getting Started with UMDF.]
The WDF_PROPERTY_STORE_ROOT structure contains information that identifies a UMDF property store.
Syntax
typedef struct _WDF_PROPERTY_STORE_ROOT {
ULONG LengthCb;
WDF_PROPERTY_STORE_ROOT_CLASS RootClass;
union {
struct {
PCWSTR ServiceName;
} HardwareKey;
struct {
LPCGUID InterfaceGUID;
PCWSTR ReferenceString;
} DeviceInterfaceKey;
struct {
PCWSTR LegacyMapName;
} LegacyHardwareKey;
} Qualifier;
} WDF_PROPERTY_STORE_ROOT, *PWDF_PROPERTY_STORE_ROOT;
Members
LengthCb
The length, in bytes, of this structure.
RootClass
A WDF_PROPERTY_STORE_ROOT_CLASS-typed value that identifies a property store.
Qualifier
Qualifier.HardwareKey
Qualifier.HardwareKey.ServiceName
A pointer to a NULL-terminated character string that identifies a driver-specific subkey under a device's hardware key in the registry. For more information about this member, see the following Remarks section.
Qualifier.DeviceInterfaceKey
Qualifier.DeviceInterfaceKey.InterfaceGUID
A pointer to a GUID that identifies a device interface. The driver must have previously called IWDFDevice::CreateDeviceInterface to register the device interface.
Qualifier.DeviceInterfaceKey.ReferenceString
A pointer to a NULL-terminated character string that identifies a reference string for a device interface. The driver must specify this member if it specified a reference string when it called IWDFDevice::CreateDeviceInterface. Otherwise, this member must be NULL.
Qualifier.LegacyHardwareKey
Qualifier.LegacyHardwareKey.LegacyMapName
A pointer to a NULL-terminated character string that identifies a subkey under the HKEY_LOCAL_MACHINE\HARDWARE\DEVICEMAP key in the registry. This key is used by only a few older drivers.
Remarks
The WDF_PROPERTY_STORE_ROOT structure is used as input to IWDFPropertyStoreFactory::RetrieveDevicePropertyStore and IWDFUnifiedPropertyStoreFactory::RetrieveUnifiedDevicePropertyStore.
UMDF property stores represent registry keys that drivers can access. Before your driver calls one of the above methods, it must initialize the WDF_PROPERTY_STORE_ROOT structure. The driver must zero the structure and then set the LengthCb member to the structure's length.
To open a software key, your driver must:
- Set the structure's LengthCb member to the structure size.
- Set the structure's RootClass member to WdfPropertyStoreRootClassSoftwareKey.
- Set the structure's LengthCb member to the structure size.
- Set the structure's RootClass member to WdfPropertyStoreRootClassHardwareKey.
-
Set a value for the Qualifier.HardwareKey.ServiceName member. This value must be one of the following:
- WDF_PROPERTY_STORE_HARDWARE_KEY_ROOT, to open the \Device Parameters subkey under the device's hardware key. The driver can obtain only read access to this subkey.
- WDF_PROPERTY_STORE_HARDWARE_KEY_DEFAULT, to open a subkey that matches the driver's service name, under the \Device Parameters subkey. The driver can obtain read or write access to this subkey. The driver can optionally create the subkey if it does not exist.
- A driver-supplied character string, to open a subkey with a name that matches the character string, under the \Device Parameters subkey. The driver can obtain read or write access to this subkey. The driver can optionally create the subkey if it does not exist.
If your driver creates a subkey under a device's hardware key, it is best to specify WDF_PROPERTY_STORE_HARDWARE_KEY_DEFAULT because UMDF creates a subkey that matches the driver's service name. Use of this name ensures that each driver creates a uniquely named subkey. The driver must not specify WDF or WUDF as the subkey name.
- Set the structure's LengthCb member to the structure size.
- Set the structure's RootClass member to WdfPropertyStoreRootClassDeviceInterfaceKey.
- Set the Qualifier.DeviceInterfaceKey.InterfaceGUID member to the GUID that the driver specified to a previous call to IWDFDevice::CreateDeviceInterface.
- Set the Qualifier.DeviceInterfaceKey.ReferenceString member to the reference string that the driver specified to a previous call to IWDFDevice::CreateDeviceInterface, or NULL if the driver did not specify a reference string.
To open the DEVICEMAP key, your driver must:
- Set the structure's LengthCb member to the structure size.
- Set the structure's RootClass member to WdfPropertyStoreRootClassLegacyHardwareKey.
- Set the Qualifier.LegacyHardwareKey.LegacyMapName member to a character string that specifies a subkey under the HKEY_LOCAL_MACHINE\HARDWARE\DEVICEMAP key in the registry.
For more information about these registry keys, see Using the Registry in UMDF-based Drivers.
Requirements
Requirement | Value |
---|---|
Minimum UMDF version | 1.9 |
Header | wudfddi_types.h (include Wudfddi.h) |