WdfDeviceAddQueryInterface-Funktion (wdfqueryinterface.h)

Artikel
02/27/2024

[Gilt nur für KMDF]

Die WdfDeviceAddQueryInterface-Methode erstellt eine vom Treiber definierte Schnittstelle, die von anderen Treibern abgefragt und verwendet werden kann.

Syntax

NTSTATUS WdfDeviceAddQueryInterface(
  [in] WDFDEVICE                   Device,
  [in] PWDF_QUERY_INTERFACE_CONFIG InterfaceConfig
);

Parameter

[in] Device

Ein Handle für ein Framework-Geräteobjekt.

[in] InterfaceConfig

Ein Zeiger auf eine vom Treiber zugewiesene WDF_QUERY_INTERFACE_CONFIG Struktur, die die Schnittstelle beschreibt.

Rückgabewert

WdfDeviceAddQueryInterface 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_DEVICE_REQUEST	Die Methode wurde mit dem falschen IRQL aufgerufen.
STATUS_INVALID_PARAMETER	Ein Eingabeparameter (möglicherweise einschließlich Membern der WDF_QUERY_INTERFACE_CONFIG-Struktur) war ungültig.
STATUS_INFO_LENGTH_MISMATCH	Die Größe der WDF_QUERY_INTERFACE_CONFIG-Struktur war falsch.
STATUS_INSUFFICIENT_RESOURCES	Es war nicht genügend Arbeitsspeicher vorhanden.

Eine Liste mit zusätzlichen Rückgabewerten finden Sie unter Fehler beim Erstellen von Frameworkobjekten.

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

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

Hinweise

Hinweis

WdfDeviceAddQueryInterface kann für ein Steuerungsgerät nicht aufgerufen werden.

Treiber, die treiberdefinierte Schnittstellen erstellen, rufen in der Regel WdfDeviceAddQueryInterface innerhalb einer Rückruffunktion evtDriverDeviceAdd oder EvtDevicePrepareHardware auf.

Nachdem ein Treiber WdfDeviceAddQueryInterface aufgerufen hat , um eine vom Treiber definierte Schnittstelle zu erstellen, kann ein anderer frameworkbasierter Treiber auf die Schnittstelle zugreifen, indem er WdfFdoQueryForInterface aufruft.

Weitere Informationen zu vom Treiber definierten Schnittstellen finden Sie unter Verwenden Driver-Defined Schnittstellen.

Beispiele

Das folgende Codebeispiel stammt aus dem Toaster-Beispielbustreiber. In diesem Beispiel wird eine vom Treiber definierte Schnittstelle erstellt, die die TOASTER_INTERFACE_STANDARD Struktur des Toasterbeispiels verwendet.

typedef struct _TOASTER_INTERFACE_STANDARD {
 INTERFACE  InterfaceHeader;
  PTOASTER_GET_CRISPINESS_LEVEL  GetCrispinessLevel;
  PTOASTER_SET_CRISPINESS_LEVEL  SetCrispinessLevel;
  PTOASTER_IS_CHILD_PROTECTED  IsSafetyLockEnabled;
} TOASTER_INTERFACE_STANDARD, *PTOASTER_INTERFACE_STANDARD;

TOASTER_INTERFACE_STANDARD  ToasterInterface;
WDF_QUERY_INTERFACE_CONFIG  qiConfig;

//
// Initialize the ToasterInterface structure.
//
RtlZeroMemory(
              &ToasterInterface,
              sizeof(ToasterInterface)
              );

ToasterInterface.InterfaceHeader.Size = sizeof(ToasterInterface);
ToasterInterface.InterfaceHeader.Version = 1;
ToasterInterface.InterfaceHeader.Context = (PVOID)hChild;

ToasterInterface.InterfaceHeader.InterfaceReference =
        WdfDeviceInterfaceReferenceNoOp;
ToasterInterface.InterfaceHeader.InterfaceDereference =
        WdfDeviceInterfaceDereferenceNoOp;

ToasterInterface.GetCrispinessLevel = Bus_GetCrispinessLevel;
ToasterInterface.SetCrispinessLevel = Bus_SetCrispinessLevel;
ToasterInterface.IsSafetyLockEnabled = Bus_IsSafetyLockEnabled;

//
// Initialize the qiConfig structure.
//
WDF_QUERY_INTERFACE_CONFIG_INIT(
                                &qiConfig,
                                (PINTERFACE)&ToasterInterface,
                                &GUID_TOASTER_INTERFACE_STANDARD,
                                NULL
                                );

//
// Create the interface.
//
status = WdfDeviceAddQueryInterface(
                                    hChild,
                                    &qiConfig
                                    );
if (!NT_SUCCESS(status)) {
    return status;
}

Anforderungen

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