IWDFUnifiedPropertyStore：：GetPropertyData 方法 (wudfddi.h)

项目
08/08/2023

[警告： UMDF 2 是最新版本的 UMDF，取代了 UMDF 1。所有新的 UMDF 驱动程序都应使用 UMDF 2 编写。未向 UMDF 1 添加新功能，并且较新版本的 Windows 10 上对 UMDF 1 的支持有限。通用 Windows 驱动程序必须使用 UMDF 2。有关详细信息，请参阅使用 UMDF 入门。]

GetPropertyData 方法检索设备属性的当前设置。

语法

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
);

参数

[in] PropertyKey

指向指定设备属性键的 DEVPROPKEY 结构的指针。

[in] Lcid

指定区域设置标识符。将此参数设置为特定于语言的 LCID 值或LOCALE_NEUTRAL。 LOCALE_NEUTRAL LCID 指定属性是非特定语言 (，不特定于任何语言) 。不要将此参数设置为LOCALE_SYSTEM_DEFAULT或LOCALE_USER_DEFAULT。有关特定于语言的 LCID 值的详细信息，请参阅 LCID 结构。

[in] Flags

预留给系统使用。驱动程序应将此值设置为 0。

[in] PropertyDataSize

PropertyData 指向的缓冲区的大小（以字节为单位）。

[out, optional] PropertyData

指向设备属性数据的指针。

[out] PropertyDataRequiredSize

指向 ULONG 的指针，用于接收 PropertyData 中返回的属性信息的大小。

[out] PropertyType

指向 DEVPROPTYPE 值的指针。如果 GetPropertyData 成功完成，该方法使用 PropertyType 提供 PropertyData 缓冲区中返回的数据类型。

返回值

如果操作成功，GetPropertyData 将返回S_OK。否则，该方法可能会返回以下值。

返回代码	说明
E_OUTOFMEMORY	框架分配内存的尝试失败。
HRESULT_FROM_NT (STATUS_BUFFER_TOO_SMALL)	PropertyDataRequiredSize 参数包含所需缓冲区的大小。
HRESULT_FROM_WIN32 (ERROR_INVALID_PARAMETER)	如果驱动程序指定 WdfPropertyStoreRootClassDeviceInterfaceKey，则请求的接口必须是 UMDF 驱动程序之前注册的接口。
HRESULT_FROM_WIN32 (STATUS_NOT_SUPPORTED)	驱动程序只能从Windows 8开始请求设备接口属性数据。

此方法可能会返回 Winerror.h 包含的其他值之一。

注解

基于框架的驱动程序使用 GetPropertyData 方法检索定义为统一设备属性模型的一部分的设备属性。

具体而言，可以使用此方法检索设备的硬件密钥或设备接口类的实例。调用 IWDFUnifiedPropertyStoreFactory：：RetrieveUnifiedDevicePropertyStore 时，将 RootSpecifier 参数的 RootClass 成员设置为 WdfPropertyStoreRootClassHardwareKey 或 WdfPropertyStoreRootClassDeviceInterfaceKey。

如果指定 WdfPropertyStoreRootClassHardwareKey，则在调用 GetPropertyData 时，必须在 PropertyKey 参数中提供自定义 DEVPROPKEY 值，而不是 PnP 定义的键。该值必须以前通过调用 SetPropertyData、 SetupDI 设备属性函数或使用 INF AddProperty 指令进行设置。

有关设备属性的详细信息，请参阅设备属性。

有关访问注册表的详细信息，请参阅在基于 UMDF 的驱动程序中使用注册表。

示例

对于可变大小属性，驱动程序应进行两次传递以检索属性数据。首先，驱动程序应在 PropertyData 参数中传递 NULL 缓冲区，并将 PropertyDataSize 设置为 0。然后，驱动程序应根据返回的 PropertyDataRequiredSize 分配缓冲区，并再次调用 GetPropertyData ，传递分配的缓冲区。

下面的示例对此模式进行了演示。

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;
}