IWDFPropertyStoreFactory::RetrieveDevicePropertyStore method (wudfddi.h)

Article
10/21/2021

[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 RetrieveDevicePropertyStore method retrieves a property store interface that drivers can use to access the registry.

Syntax

HRESULT RetrieveDevicePropertyStore(
  [in]  PWDF_PROPERTY_STORE_ROOT          RootSpecifier,
  [in]  WDF_PROPERTY_STORE_RETRIEVE_FLAGS Flags,
  [in]  REGSAM                            DesiredAccess,
  [in]  PCWSTR                            SubkeyPath,
  [out] IWDFNamedPropertyStore2           **PropertyStore,
  [out] WDF_PROPERTY_STORE_DISPOSITION    *Disposition
);

Parameters

[in] RootSpecifier

The address of a driver-allocated WDF_PROPERTY_STORE_ROOT structure. The driver fills in this structure to identify the property store that RetrieveDevicePropertyStore retrieves.

[in] Flags

A WDF_PROPERTY_STORE_RETRIEVE_FLAGS-typed flag that specifies whether UMDF should create a specified registry entry if it does not exist, and whether the new entry should be deleted when Windows restarts.

[in] DesiredAccess

A REGSAM-typed bit mask that specifies the types of access to the registry that you want your driver to have. The REGSAM type is defined in Winreg.h, and is described in the Windows SDK at REGSAM. The bit mask must not specify GENERIC_WRITE, KEY_CREATE_SUB_KEY, or WRITE_DAC access. (Although the driver cannot specify KEY_CREATE_SUB_KEY, its call to RetrieveDevicePropertyStore can create a subkey.)

[in] SubkeyPath

A pointer to a caller-supplied character string that represents the name of a subkey located under the registry key that the RootSpecifier parameter specifies. This parameter is optional and can be NULL. See more information in Remarks.

[out] PropertyStore

The address of a location that receives a pointer to an IWDFNamedPropertyStore2 interface. The driver uses this interface to access values in the registry.

[out] Disposition

The address of a location that receives a WDF_PROPERTY_STORE_DISPOSITION-typed value.

Return value

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

Return code	Description
E_INVALIDARG	The caller provided an invalid input argument.
E_OUTOFMEMORY	An attempt to allocate memory failed.

This method might return one of the other values that Winerror.h contains

Remarks

Your driver can call RetrieveDevicePropertyStore to obtain access to the driver's software key, the current device's hardware key, keys for the device interfaces that the current device supports, or the DEVICEMAP key.

If you supply the SubkeyPath parameter, you must use a unique name, such as the driver's service name. A driver might use a subkey to store device-specific information.

For more information about using RetrieveDevicePropertyStore to access the registry, see Using the Registry in UMDF-based Drivers.

Examples

The following code example retrieves the value that is assigned to the PortName entry under a device's hardware key.

IWDFPropertyStoreFactory *pPropertyStoreFactory = NULL;
WDF_PROPERTY_STORE_ROOT RootSpecifier;
IWDFNamedPropertyStore2 * pHardwarePropertyStore2 = NULL;
PROPVARIANT comPortPV;
WCHAR portName[] = L"PortName";
HRESULT hr;
...
//
// Get the property store factory interface.
//
hr = m_FxDevice->QueryInterface(IID_PPV_ARGS(&pPropertyStoreFactory));
if (FAILED(hr))
{
    goto Exit;
}
//
//Initialize the WDF_PROPERTY_STORE_ROOT structure. We want to open the 
// \Device Parameters subkey under the device's hardware key.
//
RtlZeroMemory(&RootSpecifier,
              sizeof(WDF_PROPERTY_STORE_ROOT));
RootSpecifier.LengthCb = sizeof(WDF_PROPERTY_STORE_ROOT);
RootSpecifier.RootClass = WdfPropertyStoreRootClassHardwareKey;
RootSpecifier.Qualifier.HardwareKey.ServiceName = WDF_PROPERTY_STORE_HARDWARE_KEY_ROOT;

//
// Get the property store interface for the hardware key of the
// device that m_FxDevice represents.
//
hr = pPropertyStoreFactory->RetrieveDevicePropertyStore(
                                           &RootSpecifier,
                                           WdfPropertyStoreNormal,
                                           KEY_QUERY_VALUE,
                                           NULL,
                                           &pHardwarePropertyStore2,
                                           NULL
                                           );
if (FAILED(hr))
{
    goto Exit;
}

//
// Get the value of the "PortName" entry, which is stored under 
// the device's \Device Parameters subkey.
//
PropVariantInit(&comPortPV);
hr = pHardwarePropertyStore2->GetNamedValue(portName,
                                            &comPortPV);
if (FAILED(hr))
{
   goto Exit;
}
...
Exit:
    SAFE_RELEASE(pHardwarePropertyStore2);
    SAFE_RELEASE(pPropertyStoreFactory);
...

Requirements

Requirement	Value
End of support	Unavailable in UMDF 2.0 and later.
Target Platform	Desktop
Minimum UMDF version	1.9
Header	wudfddi.h (include Wudfddi.h)
DLL	WUDFx.dll