WdfIoTargetQueryTargetProperty-Funktion (wdfiotarget.h)
[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 |
|---|---|
|
Der Puffer, auf den der PropertyBuffer-Parameter verweist, war zu klein, um die angeforderten Informationen zu empfangen. |
|
Der Wert, den der deviceProperty-Parameter angegeben hat, war ungültig. |
|
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) |