WdfIoTargetAllocAndQueryTargetProperty-Funktion (wdfiotarget.h)

Artikel
02/27/2024

[Gilt nur für KMDF]

Die WdfIoTargetAllocAndQueryTargetProperty-Methode weist einen Puffer zu und ruft eine angegebene Geräteeigenschaft für ein angegebenes E/A-Ziel ab.

Syntax

NTSTATUS WdfIoTargetAllocAndQueryTargetProperty(
  [in]           WDFIOTARGET              IoTarget,
  [in]           DEVICE_REGISTRY_PROPERTY DeviceProperty,
  [in]           POOL_TYPE                PoolType,
  [in, optional] PWDF_OBJECT_ATTRIBUTES   PropertyMemoryAttributes,
  [out]          WDFMEMORY                *PropertyMemory
);

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] PoolType

Ein POOL_TYPE typisierter Wert, der den Typ des zuzuweisenden Arbeitsspeichers angibt.

[in, optional] PropertyMemoryAttributes

Ein Zeiger auf eine vom Aufrufer zugewiesene WDF_OBJECT_ATTRIBUTES Struktur, die Objektattribute für das Speicherobjekt beschreibt, das von der Funktion zugeordnet wird. Dieser Parameter ist optional und kann WDF_NO_OBJECT_ATTRIBUTES werden.

[out] PropertyMemory

Ein Zeiger auf einen WDFMEMORY-typisierten Speicherort, der ein Handle für ein Frameworkspeicherobjekt empfängt.

Rückgabewert

WdfIoTargetAllocAndQueryTargetProperty 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_INVALID_PARAMETER oder STATUS_INVALID_PARAMETER_2	Der Wert, den der angegebene 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

Die WdfIoTargetAllocAndQueryTargetProperty-Methode bestimmt die Menge an Arbeitsspeicher, die erforderlich ist, um die angeforderte Geräteeigenschaft zu speichern. Diese Methode weist genügend Arbeitsspeicher zu, um die Daten zu speichern, und gibt ein Handle an ein Frameworkspeicherobjekt zurück, das den zugeordneten Arbeitsspeicher beschreibt. Um auf die Daten zuzugreifen, kann Ihr Treiber WdfMemoryGetBuffer aufrufen.

Weitere Informationen zu WdfIoTargetAllocAndQueryTargetProperty 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 WdfIoTargetAllocAndQueryTargetProperty aufgerufen, um die DevicePropertyFriendlyName-Eigenschaft abzurufen. Nachdem WdfIoTargetAllocAndQueryTargetProperty zurückgegeben wurde, kann der Treiber WdfMemoryGetBuffer aufrufen, um einen Zeiger auf den Puffer zu erhalten, der die Namenszeichenfolge enthält.

WDFMEMORY  targetName;
NTSTATUS  status;

status = WdfIoTargetAllocAndQueryTargetProperty(
                                                Target,
                                                DevicePropertyFriendlyName,
                                                NonPagedPool,
                                                WDF_NO_OBJECT_ATTRIBUTES,
                                                &targetName
                                                );

Anforderungen

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