IWDFUnifiedPropertyStore::SetPropertyData-Methode (wudfddi.h)

Artikel
03/01/2024

[Warnung: UMDF 2 ist die neueste Version von UMDF und ersetzt UMDF 1. Alle neuen UMDF-Treiber sollten mit UMDF 2 geschrieben werden. UMDF 1 werden keine neuen Features hinzugefügt, und die Unterstützung für UMDF 1 in neueren Versionen von Windows 10 ist eingeschränkt. Universelle Windows-Treiber müssen UMDF 2 verwenden. Weitere Informationen finden Sie unter Erste Schritte mit UMDF.]

Die SetPropertyData-Methode ändert die aktuelle Einstellung einer Geräteeigenschaft.

Syntax

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

Parameter

[in] PropertyKey

Ein Zeiger auf eine DEVPROPKEY-Struktur , die den Geräteeigenschaftsschlüssel angibt.

[in] Lcid

Gibt einen Gebietsschemabezeichner an. Legen Sie diesen Parameter entweder auf einen sprachspezifischen LCID-Wert oder auf LOCALE_NEUTRAL fest. Der LOCALE_NEUTRAL LCID gibt an, dass die Eigenschaft sprachneutral ist (d. a. keine sprachspezifische). Legen Sie diesen Parameter nicht auf LOCALE_SYSTEM_DEFAULT oder LOCALE_USER_DEFAULT fest. Weitere Informationen zu sprachspezifischen LCID-Werten finden Sie unter LCID-Struktur.

[in] Flags

Reserviert. Treiber sollten diesen Wert auf 0 festlegen.

[in] PropertyType

Ein Zeiger auf einen DEVPROPTYPE-Wert , der den Typ der Daten angibt, die im PropertyData-Puffer bereitgestellt werden.

[in] PropertyDataSize

Die Größe des Puffers in Bytes, auf den PropertyData verweist.

[in, optional] PropertyData

Ein Zeiger auf die Geräteeigenschaftendaten. Legen Sie diesen Parameter auf NULL fest, um die angegebene Eigenschaft zu löschen.

Rückgabewert

SetPropertyData gibt S_OK zurück, wenn der Vorgang erfolgreich ist. Andernfalls gibt die Methode möglicherweise die folgenden Werte zurück.

Rückgabecode	Beschreibung
E_OUTOFMEMORY	Fehler beim Versuch des Frameworks, Arbeitsspeicher zuzuweisen.
HRESULT_FROM_WIN32 (ERROR_INVALID_PARAMETER)	Wenn der Treiber WdfPropertyStoreRootClassDeviceInterfaceKey angibt, muss die angeforderte Schnittstelle eine sein, die der UMDF-Treiber zuvor registriert hat.
HRESULT_FROM_WIN32 (STATUS_NOT_SUPPORTED)	Der Treiber kann Eigenschaftendaten der Geräteschnittstelle erst ab Windows 8 ändern.

Diese Methode gibt möglicherweise einen HRESULT-typisierten Wert zurück, der einem der anderen Werte entspricht, die Winerror.h enthält.

Hinweise

Frameworkbasierte Treiber verwenden die SetPropertyData-Methode , um Geräteeigenschaften zu ändern, die als Teil des einheitlichen Geräteeigenschaftenmodells definiert sind.

Insbesondere können Sie diese Methode verwenden, um den Hardwareschlüssel eines Geräts oder einen instance einer Geräteschnittstellenklasse zu ändern. Wenn Sie IWDFUnifiedPropertyStoreFactory::RetrieveUnifiedDevicePropertyStore aufrufen, legen Sie das RootClass-Element des RootSpecifier-Parameters auf WdfPropertyStoreRootClassHardwareKey oder WdfPropertyStoreRootClassDeviceInterfaceKey fest.

Wenn Sie WdfPropertyStoreRootClassHardwareKey angeben, müssen Sie beim Aufrufen von SetPropertyData im PropertyKey-Parameter einen benutzerdefinierten DEVPROPKEY-Wert und keinen PnP-definierten Schlüssel angeben. Der Wert muss zuvor durch Aufrufen von SetPropertyData, einer SetupDI-Geräteeigenschaftsfunktion oder mithilfe der INF-AddProperty-Direktive festgelegt worden sein.

Wenn der Treiber WdfPropertyStoreRootClassDeviceInterfaceKey angibt, muss die angeforderte Schnittstelle eine sein, die der UMDF-Treiber zuvor zur Laufzeit registriert hat.

Wenn der Treiber eine Schnittstelle in seiner INF-Datei registriert, muss er auch zugeordnete Eigenschaften im INF festlegen.

Weitere Informationen zum Zugriff auf die Registrierung finden Sie unter Verwenden der Registrierung in UMDF-basierten Treibern.

Beispiele

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

Anforderungen

Anforderung	Wert
Ende des Supports	In UMDF 2.0 und höher nicht verfügbar.
Zielplattform	Desktop
UMDF-Mindestversion	1.11
Kopfzeile	wudfddi.h
DLL	WUDFx.dll