IWDFUnifiedPropertyStore::GetPropertyData-Methode (wudfddi.h)
[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 |
|---|---|
|
Fehler beim Versuch des Frameworks, Arbeitsspeicher zuzuweisen. |
|
Der Parameter PropertyDataRequiredSize enthält die Größe des erforderlichen Puffers. |
|
Wenn der Treiber WdfPropertyStoreRootClassDeviceInterfaceKey angibt, muss die angeforderte Schnittstelle eine sein, die der UMDF-Treiber zuvor registriert hat. |
|
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 |
Weitere Informationen
IWDFUnifiedPropertyStoreFactory