WdfDeviceAllocAndQueryProperty-Funktion (wdfdevice.h)

Artikel
08/08/2023

[Gilt für KMDF und UMDF]

Die WdfDeviceAllocAndQueryProperty-Methode weist einen Puffer zu und ruft eine angegebene Geräteeigenschaft ab.

Syntax

NTSTATUS WdfDeviceAllocAndQueryProperty(
  [in]           WDFDEVICE                Device,
  [in]           DEVICE_REGISTRY_PROPERTY DeviceProperty,
  [in]           POOL_TYPE                PoolType,
  [in, optional] PWDF_OBJECT_ATTRIBUTES   PropertyMemoryAttributes,
  [out]          WDFMEMORY                *PropertyMemory
);

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

Ein POOL_TYPE typisiertes Enumerator, der den Typ des zu zuweisenden Arbeitsspeichers angibt.

[in, optional] PropertyMemoryAttributes

Ein Zeiger auf eine vom Aufrufer zugewiesene WDF_OBJECT_ATTRIBUTES Struktur, die Objektattribute für das Speicherobjekt beschreibt, das die Funktion ordnet. 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

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

Rückgabecode	Beschreibung
STATUS_INVALID_PARAMETER oder 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

Die WdfDeviceAllocAndQueryProperty-Methode bestimmt die Menge an Arbeitsspeicher, die erforderlich ist, um die angeforderte Geräteeigenschaft zu speichern. Sie 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.

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

Beispiele

Im folgenden Codebeispiel wird eine WDF_OBJECT_ATTRIBUTES-Struktur mit Attributen für das Frameworkspeicherobjekt initialisiert, das das Framework für die angeforderte Eigenschaft erstellt. Anschließend ruft das Beispiel WdfDeviceAllocAndQueryProperty auf, um die DevicePropertyPhysicalDeviceObjectName-Eigenschaft abzurufen. Nachdem WdfDeviceAllocAndQueryProperty zurückgegeben wurde, kann der Treiber WdfMemoryGetBuffer aufrufen, um einen Zeiger auf den Puffer zu erhalten, der die Namenszeichenfolge enthält.

WDF_OBJECT_ATTRIBUTES  attributes;
NTSTATUS  status;
WDFDEVICE  device;
WDFMEMORY  memory;

WDF_OBJECT_ATTRIBUTES_INIT(&attributes);
attributes.ParentObject = device;

status = WdfDeviceAllocAndQueryProperty(device,
                                        DevicePropertyPhysicalDeviceObjectName,
                                        NonPagedPool,
                                        &attributes,
                                        &memory
                                        );
if (!NT_SUCCESS(status)) {
    return STATUS_UNSUCCESSFUL;
}

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

WdfDeviceQueryProperty

Freigeben über