IWDFUnifiedPropertyStore::GetPropertyData-Methode (wudfddi.h)

[Warnung: UMDF 2 ist die neueste Version von UMDF und ersetzt UMDF 1. Alle neuen UMDF-Treiber sollten mithilfe von UMDF 2 geschrieben werden. Es werden keine neuen Features zu UMDF 1 hinzugefügt, und es gibt eingeschränkte Unterstützung für UMDF 1 für neuere Versionen von Windows 10. Universelle Windows-Treiber müssen UMDF 2 verwenden. Weitere Informationen finden Sie unter Začínáme 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äteeigenschaftsschlüssel angibt.

[in] Lcid

Gibt einen Gebietsschemabezeichner an. Legen Sie diesen Parameter entweder auf einen sprachspezifischen LCID-Wert oder auf LOCALE_NEUTRAL fest. Die LOCALE_NEUTRAL LCID gibt an, dass die Eigenschaft sprachneutral ist (d. h. nicht für jede Sprache spezifisch). 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, in Bytes.

[out, optional] PropertyData

Ein Zeiger auf die Geräteeigenschaftsdaten.

[out] PropertyDataRequiredSize

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

[out] PropertyType

Ein Zeiger auf einen DEVPROPTYPE-Wert . Wenn GetPropertyData erfolgreich abgeschlossen ist, 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 zuvor vom UMDF-Treiber registriert wurde.
HRESULT_FROM_WIN32 (STATUS_NOT_SUPPORTED)
Der Treiber kann Geräteschnittstelleneigenschaftendaten nur ab Windows 8 anfordern.
 

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

Bemerkungen

Frameworkbasierte Treiber verwenden die GetPropertyData-Methode , um Geräteeigenschaften abzurufen, die als Teil des einheitlichen Geräteeigenschaftsmodells definiert sind.

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

Wenn Sie WdfPropertyStoreRootClassHardwareKey angeben, müssen Sie beim Aufrufen von GetPropertyData einen benutzerdefinierten DEVPROPKEY-Wert im PropertyKey-Parameter und nicht einen 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.

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

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

Beispiele

Bei Variablengrößeneigenschaften sollte der Treiber zwei Übergänge erstellen, um die Eigenschaftendaten abzurufen. Zuerst sollte der Treiber einen NULL-Puffer im PropertyData-Parameter übergeben und PropertyDataSize auf 0 festlegen. Anschließend sollte der Treiber einen Puffer basierend auf der zurückgegebenen PropertyDataRequiredSize-Eigenschaft zuweisen und GetPropertyData erneut aufrufen und den zugeordneten Puffer übergeben.

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

   
Ende des Supports Nicht verfügbar in UMDF 2.0 und höher.
Zielplattform Power BI Desktop
UMDF-Mindestversion 1.11
Header wudfddi.h
DLL WUDFx.dll

Weitere Informationen

IWDFUnifiedPropertyStore

IWDFUnifiedPropertyStoreFactory

RetrieveUnifiedDevicePropertyStore

SetPropertyData

WDF_PROPERTY_STORE_ROOT

WDF_PROPERTY_STORE_ROOT_CLASS