WdfDeviceQueryProperty-Funktion (wdfdevice.h)

Artikel
02/07/2025

[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 zu einem Framework-Geräteobjekt.

[in] DeviceProperty

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

[in] BufferLength

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

[out] PropertyBuffer

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

[out] ResultLength

Ein vom Aufrufer bereitgestellter Speicherort, der im Gegenzug 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 Treiber des Geräts haben die Eigenschaften des Geräts noch nicht gemeldet.

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

Wenn der Treiber ein ungültiges Objekthandle bereitstellt, tritt eine Fehlerüberprüfung auf.

Bemerkungen

Vor dem Empfangen von Geräteeigenschaftendaten rufen Treiber in der Regel die WdfDeviceQueryProperty Methode auf, um die erforderliche Puffergröße abzurufen. Bei einigen Eigenschaften kann sich die Datengröße ändern, wenn die erforderliche Größe zurückgegeben wird, und wenn der Treiber WdfDeviceQueryProperty erneut aufruft. Daher sollten Treiber WdfDeviceQueryProperty- in einer Schleife aufrufen, die ausgeführt wird, bis der Rückgabestatus nicht STATUS_BUFFER_TOO_SMALL ist.

Es empfiehlt sich, WdfDeviceQueryProperty- nur zu verwenden, wenn die erforderliche Puffergröße bekannt und unveränderlich ist, da in diesem Fall der Treiber WdfDeviceQueryProperty- nur einmal aufrufen muss. Wenn die erforderliche Puffergröße unbekannt ist oder variiert, sollte der Treiber WdfDeviceAllocAndQueryPropertyaufrufen.

Alternativ können Sie WdfDeviceQueryPropertyEx- verwenden, um auf Geräteeigenschaften zuzugreifen, die über das Unified Property Model 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-	Universal
Minimale KMDF-Version	1.0
Mindest-UMDF-Version	2.0
Header-	wdfdevice.h (einschließen Wdf.h)
Library	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL-	PASSIVE_LEVEL
DDI-Complianceregeln	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

Siehe auch

WdfDeviceAllocAndQueryProperty

WdfFdoInitQueryProperty

Freigeben über