IWDFUnifiedPropertyStore：：SetPropertyData 方法 (wudfddi.h)

项目
02/27/2024

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

SetPropertyData 方法修改设备属性的当前设置。

语法

HRESULT SetPropertyData(
  [in]           const DEVPROPKEY *PropertyKey,
  [in]           LCID             Lcid,
  [in]           ULONG            Flags,
  [in]           DEVPROPTYPE      PropertyType,
  [in]           ULONG            PropertyDataSize,
  [in, optional] PVOID            PropertyData
);

参数

[in] PropertyKey

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

[in] Lcid

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

[in] Flags

保留。驱动程序应将此值设置为 0。

[in] PropertyType

指向 DEVPROPTYPE 值的指针，该值指定 PropertyData 缓冲区中提供的数据类型。

[in] PropertyDataSize

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

[in, optional] PropertyData

指向设备属性数据的指针。将此参数设置为 NULL 可删除指定的属性。

返回值

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

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

此方法可能会返回与 Winerror.h 包含的其他值之一对应的 HRESULT 类型值。

注解

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

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

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

如果驱动程序指定 WdfPropertyStoreRootClassDeviceInterfaceKey，则请求的接口必须是 UMDF 驱动程序以前在运行时注册的接口。

如果驱动程序在其 INF 文件中注册接口，则还必须在 INF 中设置关联的属性。

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

示例

HRESULT
SetFriendlyName(
    _In_ IWDFUnifiedPropertyStore * pUnifiedPropertyStore
    )
{
    HRESULT hr = S_OK;
    WCHAR friendlyName[] = L"UMDF OSR USB Fx2 Test Device";

    hr = pUnifiedPropertyStore->SetPropertyData(
            &DEVPKEY_Device_FriendlyName,
            0, //Lcid
            0, //Flags
            DEVPROP_TYPE_STRING, //Type
            sizeof(friendlyName),
            friendlyName
            );

    if (FAILED(hr))
    {
        TraceEvents(
            TRACE_LEVEL_ERROR,
            TEST_TRACE_DEVICE,             
            "SetPropertyData failed: hr = %!HRESULT!",
            hr
            );
        goto exit;
    }

exit:
    return hr;
}