IWDFUnifiedPropertyStore：：SetPropertyData 方法 (wudfddi.h)

發行項
02/27/2024

[警告： UMDF 2 是最新版的 UMDF，並取代 UMDF 1。所有新的UMDF驅動程式都應該使用UMDF 2撰寫。未將新功能新增至 UMDF 1，且較新版本的 #D1AD5391F80B84C3EA1D18CF3813ACA1D 上，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。否則，方法可能會傳回下列值。

傳回碼	Description
E_OUTOFMEMORY	架構嘗試配置記憶體失敗。
HRESULT_FROM_WIN32 (ERROR_INVALID_PARAMETER)	如果驅動程式指定 WdfPropertyStoreRootClassDeviceInterfaceKey，要求的介面必須是 UMDF 驅動程式先前註冊的介面。
HRESULT_FROM_WIN32 (STATUS_NOT_SUPPORTED)	驅動程式只能從 Windows 8 開始修改裝置介面屬性數據。

這個方法可能會傳回 HRESULT 類型的值，對應到 Winerror.h 所包含的其中一個其他值。

備註

架構型驅動程式會使用 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;
}