IWDFUnifiedPropertyStore::GetPropertyData method (wudfddi.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 GetPropertyData method retrieves the current setting for a device property.
Syntax
HRESULT GetPropertyData(
[in] const DEVPROPKEY *PropertyKey,
[in] LCID Lcid,
[in] ULONG Flags,
[in] ULONG PropertyDataSize,
[out, optional] PVOID PropertyData,
[out] ULONG *PropertyDataRequiredSize,
[out] DEVPROPTYPE *PropertyType
);
Parameters
[in] PropertyKey
A pointer to a DEVPROPKEY structure that specifies the device property key.
[in] Lcid
Specifies a locale identifier. Set this parameter either to a language-specific LCID value or to LOCALE_NEUTRAL. The LOCALE_NEUTRAL LCID specifies that the property is language-neutral (that is, not specific to any language). Do not set this parameter to LOCALE_SYSTEM_DEFAULT or LOCALE_USER_DEFAULT. For more information about language-specific LCID values, see LCID Structure.
[in] Flags
Reserved for system use. Drivers should set this value to 0.
[in] PropertyDataSize
The size, in bytes, of the buffer that PropertyData points to.
[out, optional] PropertyData
A pointer to the device property data.
[out] PropertyDataRequiredSize
A pointer to a ULONG to receive the size of the property information that is returned in PropertyData.
[out] PropertyType
A pointer to a DEVPROPTYPE value. If GetPropertyData completes successfully, the method uses PropertyType to supply the type of data that is returned in the PropertyData buffer.
Return value
GetPropertyData returns S_OK if the operation succeeds. Otherwise, the method might return the following values.
| Return code | Description |
|---|---|
|
The framework's attempt to allocate memory failed. |
|
The PropertyDataRequiredSize parameter contains the size of the required buffer. |
|
If the driver specifies WdfPropertyStoreRootClassDeviceInterfaceKey, the requested interface must be one that the UMDF driver previously registered. |
|
The driver can request device interface property data only starting with Windows 8. |
This method might return one of the other values that Winerror.h contains.
Remarks
Framework-based drivers use the GetPropertyData method to retrieve device properties that are defined as part of the unified device property model.
In particular, you can use this method to retrieve a device's hardware key or an instance of a device interface class. When you call IWDFUnifiedPropertyStoreFactory::RetrieveUnifiedDevicePropertyStore, set the RootSpecifier parameter's RootClass member to WdfPropertyStoreRootClassHardwareKey or WdfPropertyStoreRootClassDeviceInterfaceKey.
If you specify WdfPropertyStoreRootClassHardwareKey, then when you call GetPropertyData, you must provide a custom DEVPROPKEY value in the PropertyKey parameter, and not a PnP-defined key. The value must have been previously set by calling SetPropertyData, a SetupDI device property function, or by using the INF AddProperty directive.
For more information about device properties, see Device Properties.
For more information about accessing the registry, see Using the Registry in UMDF-based Drivers.
Examples
For variable size properties, the driver should make two passes to retrieve the property data. First, the driver should pass a NULL buffer in the PropertyData parameter, and set PropertyDataSize to 0. Then, the driver should then allocate a buffer based on the PropertyDataRequiredSize returned and call GetPropertyData again, passing the allocated buffer.
The following example demonstrates this pattern.
HRESULT
GetFriendlyName(
_In_ IWDFUnifiedPropertyStore * pUnifiedPropertyStore
)
{
HRESULT hr = S_OK;
DEVPROPTYPE type;
ULONG requiredSize;
BYTE * friendlyNameBuffer = NULL;
ULONG friendlyNameBufferSize;
hr = pUnifiedPropertyStore->GetPropertyData(
&DEVPKEY_Device_FriendlyName,
0, //Lcid
0, //Flags
0, //BufferSize
NULL, //Buffer
&requiredSize,
&type
);
if (HRESULT_CODE(hr) != ERROR_INSUFFICIENT_BUFFER)
{
TraceEvents(
TRACE_LEVEL_ERROR,
TEST_TRACE_DEVICE,
"GetPropertyData failed: hr = %!HRESULT!",
hr
);
goto exit;
}
friendlyNameBufferSize = requiredSize;
friendlyNameBuffer = new BYTE[requiredSize];
if (NULL == friendlyNameBuffer)
{
hr = E_OUTOFMEMORY;
TraceEvents(
TRACE_LEVEL_ERROR,
TEST_TRACE_DEVICE,
"Out of memory while allocating property data buffer returning:”
“ %!HRESULT!",
hr
);
goto exit;
}
hr = pUnifiedPropertyStore->GetPropertyData(
&DEVPKEY_Device_FriendlyName,
0, //Lcid
0, //Flags
friendlyNameBufferSize,
friendlyNameBuffer,
&requiredSize,
&type
);
if (FAILED(hr))
{
TraceEvents(
TRACE_LEVEL_ERROR,
TEST_TRACE_DEVICE,
"GetPropertyData failed: hr = %!HRESULT!",
hr
);
goto exit;
}
if (type != DEVPROP_TYPE_STRING)
{
TraceEvents(
TRACE_LEVEL_ERROR,
TEST_TRACE_DEVICE,
"Expected type %d, actual type: %d",
DEVPROP_TYPE_STRING,
type
);
hr = E_UNEXPECTED;
goto exit;
}
exit:
delete [] friendlyNameBuffer;
friendlyNameBuffer = NULL;
return hr;
}
Requirements
| Requirement | Value |
|---|---|
| End of support | Unavailable in UMDF 2.0 and later. |
| Target Platform | Desktop |
| Minimum UMDF version | 1.11 |
| Header | wudfddi.h |
| DLL | WUDFx.dll |
See also
IWDFUnifiedPropertyStoreFactory