WdfDeviceQueryProperty-Funktion (wdfdevice.h)

Artikel
08/08/2023

[Gilt für KMDF und UMDF]

Die WdfDeviceQueryProperty-Methode ruft eine angegebene Geräteeigenschaft ab.

Syntax

NTSTATUS WdfDeviceQueryProperty(
  [in]  WDFDEVICE                Device,
  [in]  DEVICE_REGISTRY_PROPERTY DeviceProperty,
  [in]  ULONG                    BufferLength,
  [out] PVOID                    PropertyBuffer,
  [out] PULONG                   ResultLength
);

Parameter

[in] Device

Ein Handle für ein Framework-Geräteobjekt.

[in] DeviceProperty

Ein DEVICE_REGISTRY_PROPERTY typisierter Enumerator, der die abzurufende Geräteeigenschaft identifiziert.

[in] BufferLength

Die Größe des Puffers in Bytes, auf den von PropertyBuffer verwiesen wird.

[out] PropertyBuffer

Ein vom Aufrufer bereitgestellter Zeiger auf einen vom Aufrufer zugewiesenen Puffer, der die angeforderten Informationen empfängt. Der Zeiger kann NULL sein, wenn der BufferLength-Parameter 0 ist.

[out] ResultLength

Ein vom Aufrufer bereitgestellter Speicherort, der bei der Rückgabe die Größe der Informationen enthält, die die Methode in PropertyBuffer gespeichert hat. Wenn der Rückgabewert der Funktion STATUS_BUFFER_TOO_SMALL ist, erhält dieser Speicherort die erforderliche Puffergröße.

Rückgabewert

Wenn der Vorgang erfolgreich ist, gibt WdfDeviceQueryProperty STATUS_SUCCESS zurück. Weitere Rückgabewerte sind:

Rückgabecode	Beschreibung
STATUS_BUFFER_TOO_SMALL	Der bereitgestellte Puffer ist zu klein, um die Informationen zu empfangen.
STATUS_INVALID_PARAMETER_2	Der angegebene DeviceProperty-Wert ist ungültig.
STATUS_INVALID_DEVICE_REQUEST	Die Gerätetreiber haben die Eigenschaften des Geräts noch nicht gemeldet.

Die -Methode gibt möglicherweise andere NTSTATUS-Werte zurück.

Eine Fehlerüberprüfung tritt auf, wenn der Treiber ein ungültiges Objekthandle bereitstellt.

Hinweise

Vor dem Empfangen von Geräteeigenschaftendaten rufen Treiber in der Regel die WdfDeviceQueryProperty-Methode auf, nur um die erforderliche Puffergröße abzurufen. Bei einigen Eigenschaften kann sich die Datengröße zwischen der Rückgabe der erforderlichen Größe und dem erneuten Aufruf von WdfDeviceQueryProperty vom Treiber ändern. Daher sollten Treiber WdfDeviceQueryProperty in einer Schleife aufrufen, die ausgeführt wird, bis die Rückgabe status nicht STATUS_BUFFER_TOO_SMALL ist.

Es ist am besten , WdfDeviceQueryProperty nur zu verwenden, wenn die erforderliche Puffergröße bekannt ist und sich nicht ändert, da in diesem Fall der Treiber WdfDeviceQueryProperty nur einmal aufrufen muss. Wenn die erforderliche Puffergröße unbekannt ist oder variiert, sollte der Treiber WdfDeviceAllocAndQueryProperty aufrufen.

Alternativ können Sie WdfDeviceQueryPropertyEx verwenden, um auf Geräteeigenschaften zuzugreifen, die über das Unified-Eigenschaftenmodell verfügbar gemacht werden.

Beispiele

Im folgenden Codebeispiel wird die DevicePropertyBusTypeGuid-Eigenschaft eines Geräts abgerufen. Im Beispiel wird WdfDeviceQueryProperty anstelle von WdfDeviceAllocAndQueryProperty aufgerufen, da die Länge einer GUID bekannt ist.

GUID  busTypeGuid;
ULONG  resultLength = 0;
NTSTATUS  status;

status = WdfDeviceQueryProperty( 
                                device,
                                DevicePropertyBusTypeGuid,
                                sizeof(GUID),
                                (PVOID)&busTypeGuid,
                                &resultLength
                                );

Anforderungen

Anforderung	Wert
Zielplattform	Universell
KMDF-Mindestversion	1.0
UMDF-Mindestversion	2.0
Kopfzeile	wdfdevice.h (einschließen von Wdf.h)
Bibliothek	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
DDI-Complianceregeln	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

Weitere Informationen

WdfDeviceAllocAndQueryProperty

WdfFdoInitQueryProperty

Freigeben über