WdfIoTargetQueryTargetProperty-Funktion (wdfiotarget.h)

Artikel
02/27/2024

[Gilt nur für KMDF]

Die WdfIoTargetQueryTargetProperty-Methode ruft eine angegebene Geräteeigenschaft für ein angegebenes E/A-Ziel ab.

Syntax

NTSTATUS WdfIoTargetQueryTargetProperty(
  [in]            WDFIOTARGET              IoTarget,
  [in]            DEVICE_REGISTRY_PROPERTY DeviceProperty,
  [in]            ULONG                    BufferLength,
  [out, optional] PVOID                    PropertyBuffer,
  [out]           PULONG                   ResultLength
);

Parameter

[in] IoTarget

Ein Handle für ein lokales oder Remote-E/A-Zielobjekt, das aus einem vorherigen Aufruf von WdfDeviceGetIoTarget oder WdfIoTargetCreate oder von einer Methode abgerufen wurde, die von einem spezialisierten E/A-Ziel bereitgestellt wird.

[in] DeviceProperty

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

[in] BufferLength

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

[out, optional] PropertyBuffer

Ein Zeiger auf einen vom Aufrufer zugewiesenen Puffer, der die angeforderten Geräteeigenschafteninformationen empfängt. Dieser Zeiger kann NULL sein, wenn BufferLength 0 ist.

[out] ResultLength

Ein Zeiger auf einen Speicherort, der bei der Rückgabe die Größe (in Bytes) der Informationen enthält, die WdfIoTargetQueryTargetProperty im Puffer gespeichert hat, auf den PropertyBuffer verweist. Wenn WdfIoTargetQueryTargetProperty STATUS_BUFFER_TOO_SMALL zurückgibt, empfängt dieser Speicherort die erforderliche Puffergröße.

Rückgabewert

WdfIoTargetQueryTargetProperty gibt STATUS_SUCCESS zurück, wenn der Vorgang erfolgreich ist. Andernfalls gibt diese Methode möglicherweise einen der folgenden Werte zurück:

Rückgabecode	Beschreibung
STATUS_BUFFER_TOO_SMALL	Der Puffer, auf den der PropertyBuffer-Parameter verweist, war zu klein, um die angeforderten Informationen zu empfangen.
STATUS_INVALID_PARAMETER_2	Der Wert, den der deviceProperty-Parameter angegeben hat, war ungültig.
STATUS_INVALID_DEVICE_REQUEST	Die Gerätetreiber haben die Eigenschaften des Geräts noch nicht gemeldet.

Diese Methode kann auch andere NTSTATUS-Werte zurückgeben.

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

Hinweise

Bevor Treiber Geräteeigenschaftendaten empfangen, rufen sie in der Regel die WdfIoTargetQueryTargetProperty-Methode auf, 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 WdfIoTargetQueryTargetProperty ändern. Daher sollten Treiber WdfIoTargetQueryTargetProperty in einer Schleife aufrufen, die ausgeführt wird, bis die Rückgabe status nicht STATUS_BUFFER_TOO_SMALL ist.

Anstatt WdfIoTargetQueryTargetProperty aufzurufen, kann Ihr Treiber WdfIoTargetAllocAndQueryTargetProperty aufrufen, wodurch ein Puffer zugewiesen und die Eigenschafteninformationen im Puffer platziert werden.

Weitere Informationen zu WdfIoTargetQueryTargetProperty finden Sie unter Abrufen von Informationen zu einem allgemeinen E/A-Ziel.

Weitere Informationen zu E/A-Zielen finden Sie unter Verwenden von E/A-Zielen.

Beispiele

Im folgenden Codebeispiel wird die DevicePropertyUINumber-Eigenschaft eines Geräts abgerufen. Im Beispiel wird WdfIoTargetQueryTargetProperty anstelle von WdfIoTargetAllocAndQueryTargetProperty aufgerufen, da die Länge einer UI-Nummer bekannt ist.

ULONG targetUINumber, resultLength;
NTSTATUS status;

status = WdfIoTargetQueryTargetProperty(
                                        target,
                                        DevicePropertyUINumber,
                                        sizeof(targetNumber),
                                        &targetUINumber,
                                        &resultLength
                                        );

Anforderungen

Anforderung	Wert
Zielplattform	Universell
KMDF-Mindestversion	1.0
Kopfzeile	wdfiotarget.h (einschließen von Wdf.h)
Bibliothek	Wdf01000.sys (siehe Versionierung der Frameworkbibliothek.)
IRQL	PASSIVE_LEVEL
DDI-Complianceregeln	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)