IWDFUnifiedPropertyStore::GetPropertyData-Methode (wudfddi.h)

Artikel
08/08/2023

[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 für neuere 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 GetPropertyData-Methode ruft die aktuelle Einstellung für eine Geräteeigenschaft ab.

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

Parameter

[in] PropertyKey

Ein Zeiger auf eine DEVPROPKEY-Struktur , die den Geräteeigenschaftenschlü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. nicht sprachspezifisch). 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

Ist für das System reserviert. Treiber sollten diesen Wert auf 0 festlegen.

[in] PropertyDataSize

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

[out, optional] PropertyData

Ein Zeiger auf die Geräteeigenschaftendaten.

[out] PropertyDataRequiredSize

Ein Zeiger auf eine ULONG, um die Größe der Eigenschafteninformationen zu erhalten, die in PropertyData zurückgegeben werden.

[out] PropertyType

Ein Zeiger auf einen DEVPROPTYPE-Wert . Wenn GetPropertyData erfolgreich abgeschlossen wurde, verwendet die Methode PropertyType , um den Datentyp anzugeben, der im PropertyData-Puffer zurückgegeben wird.

Rückgabewert

GetPropertyData 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_NT(STATUS_BUFFER_TOO_SMALL)	Der Parameter PropertyDataRequiredSize enthält die Größe des erforderlichen Puffers.
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 Geräteschnittstelleneigenschaftendaten erst ab Windows 8 anfordern.

Diese Methode gibt möglicherweise einen der anderen Werte zurück, die Winerror.h enthält.

Hinweise

Frameworkbasierte Treiber verwenden die GetPropertyData-Methode , um Geräteeigenschaften abzurufen, 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 abzurufen. 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 GetPropertyData 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-Anweisung festgelegt worden sein.

Weitere Informationen zu Geräteeigenschaften finden Sie unter Geräteeigenschaften.

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

Beispiele

Bei Variablengrößeneigenschaften sollte der Treiber zwei Durchläufe vornehmen, um die Eigenschaftendaten abzurufen. Zunächst sollte der Treiber einen NULL-Puffer im PropertyData-Parameter übergeben und PropertyDataSize auf 0 festlegen. Anschließend sollte der Treiber einen Puffer basierend auf dem zurückgegebenen PropertyDataRequiredSize zuordnen und GetPropertyData erneut aufrufen, wobei der zugewiesene Puffer übergeben wird.

Dieses Muster wird im folgenden Beispiel veranschaulicht.

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

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