WDF_QUERY_INTERFACE_CONFIG-Struktur (wdfqueryinterface.h)

Artikel
08/08/2023

[Gilt nur für KMDF]

Die WDF_QUERY_INTERFACE_CONFIG-Struktur beschreibt eine vom Treiber definierte Schnittstelle.

Syntax

typedef struct _WDF_QUERY_INTERFACE_CONFIG {
  ULONG                                          Size;
  PINTERFACE                                     Interface;
  const GUID                                     *InterfaceType;
  BOOLEAN                                        SendQueryToParentStack;
  PFN_WDF_DEVICE_PROCESS_QUERY_INTERFACE_REQUEST EvtDeviceProcessQueryInterfaceRequest;
  BOOLEAN                                        ImportInterface;
} WDF_QUERY_INTERFACE_CONFIG, *PWDF_QUERY_INTERFACE_CONFIG;

Member

Size

Die Größe (in Bytes) dieser Struktur.

Interface

Ein Zeiger auf eine INTERFACE-Struktur , die die vom Treiber definierte Schnittstelle beschreibt.

InterfaceType

Ein Zeiger auf die GUID, die die Schnittstelle identifiziert.

Hinweis

Wenn Sie eine neue Version einer vorhandenen Schnittstelle einführen, erstellen Sie eine neue GUID, anstatt die Felder Größe oder Version der INTERFACE-Struktur zu überarbeiten. Weitere Informationen finden Sie unter Verwenden Driver-Defined Schnittstellen.

SendQueryToParentStack

Wenn TRUE, und wenn Ihr Treiber ein Geräteobjekt angibt, das ein physisches Geräteobjekt (PDO) darstellt, wenn WdfDeviceAddQueryInterface aufgerufen wird, sendet das Framework Anforderungen für die Schnittstelle an den oberen Rand des Treiberstapels des übergeordneten Geräts. Wenn dieser Member FALSE ist oder das Geräteobjekt kein PDO darstellt, sendet das Framework keine Anforderungen an den Stapel des übergeordneten Geräts. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".

EvtDeviceProcessQueryInterfaceRequest

Ein Zeiger auf die EvtDeviceProcessQueryInterfaceRequest-Ereignisrückruffunktion Ihres Treibers, die aufgerufen wird, wenn ein anderer Treiber die Schnittstelle anfordert.

ImportInterface

Wenn true, unterstützt die Schnittstelle die bidirektionale Kommunikation zwischen Ihrem Treiber und Treibern, die die Schnittstelle anfordern.

Wenn dieser Member FALSE ist, unterstützt die Schnittstelle die unidirektionale Kommunikation zwischen Ihrem Treiber und Treibern, die die Schnittstelle anfordern.

Hinweise

Die WDF_QUERY_INTERFACE_CONFIG-Struktur wird als Eingabe für die WdfDeviceAddQueryInterface-Methode verwendet.

Für jede treiberdefinierte Schnittstelle, die ihr Treiber exportiert, müssen Sie eine WDF_QUERY_INTERFACE_CONFIG Struktur zuordnen, die die Schnittstelle darstellt. Andere Treiber können den Zugriff auf die Schnittstelle anfordern, indem sie WdfFdoQueryForInterface aufrufen.

Wenn Ihre Schnittstelle die bidirektionale Kommunikation zwischen dem anfordernden Treiber und Ihrem Treiber unterstützen soll, legen Sie den ImportInterface-Member auf TRUE fest. Wenn ImportInterfaceTRUE ist, kann die vom anfordernden Treiber bereitgestellte Struktur Daten enthalten, die Ihr Treiber lesen kann. In diesem Fall:

Die Rückruffunktion EvtDeviceProcessQueryInterfaceRequest ist erforderlich, und sie muss die Schnittstellenstruktur initialisieren, die der anfordernde Treiber bereitstellt.
Da die Rückruffunktion EvtDeviceProcessQueryInterfaceRequest die Schnittstelle zum anfordernden Treiber bereitstellt, kann das Schnittstellenelementvon WDF_QUERY_INTERFACE_CONFIGNULL sein. Wenn Sie einen Nicht-NULL-Zeiger bereitstellen, überprüft das Framework, ob die Vom anfordernden Treiber bereitgestellten Größen- und Versionswerte gleich oder größer als die Werte in Ihrer registrierten INTERFACE-Struktur sind. Wenn einer dieser Werte kleiner ist, lehnt das Framework die Anforderung ab. Wenn Sie keinen Wert für Interface angeben, muss Ihre EvtDeviceProcessQueryInterfaceRequest-Rückruffunktion diese Werte überprüfen.

Wenn Ihre Schnittstelle nur eine unidirektionale Kommunikation zwischen Ihrem Treiber und dem anfordernden Treiber unterstützen soll, legen Sie ImportInterfaceauf FALSE fest. Die Vom anfordernden Treiber bereitgestellte Schnittstellenstruktur kann nur daten empfangen, die Ihr Treiber bereitstellt. In diesem Fall:

Die Rückruffunktion EvtDeviceProcessQueryInterfaceRequest ist optional.
Das Interface-Element darf nicht NULL sein. Das Framework überprüft, ob die VOM anfordernden Treiber bereitgestellten GUID-, Größen- und Versionswerte mit den von Ihnen angegebenen übereinstimmen, und das Framework lehnt die Anforderung ab, wenn die Werte nicht übereinstimmen. Wenn die Werte gültig sind, initialisiert das Framework die Schnittstellenstruktur, die der anfordernde Treiber bereitstellt, indem die Werte verwendet werden, die Sie für Interface angeben.

Darüber hinaus kann das Interface-ElementNULL sein, wenn der Wert des SendQueryToParentStack-MembersTRUE ist.

Wenn das Interface-Element nicht NULL ist, kopiert das Framework den Wert in den internen Speicherplatz. Daher kann der Treiber die INTERFACE-Struktur im lokalen temporären Speicherplatz zuordnen.

Wenn Ihr Treiber WdfDeviceAddQueryInterface aufruft, kann er die Schnittstelle einem Frameworkgeräteobjekt zuordnen, das entweder ein funktionales Geräteobjekt (Functional Device Object, FDO) oder ein physisches Geräteobjekt (PDO) darstellt. Wenn der Treiber die Schnittstelle einem PDO zuordnet, kann er das SendQueryToParentStack-Element der WDF_QUERY_INTERFACE_CONFIG-Struktur auf TRUE festlegen. Wenn das Framework eine Anforderung für die Schnittstelle abfängt, überprüft es den SendQueryToParentStack-Member , und wenn es auf TRUE festgelegt ist, sendet das Framework die Anforderung an den oberen Rand des Treiberstapels des übergeordneten PDO. Infolgedessen wird die Anforderung auf zwei Treiberstapel übertragen: erstens der Stapel, der den Treiber enthält, der die Schnittstelle anfordert, und zweitens den Stapel des übergeordneten Geräts der Schnittstelle.

Das Framework stellt zwei Verweis-/Dereference-Methoden bereit, die Sie mit Ihren Schnittstellen verwenden können, indem Sie deren Adressen für die Member InterfaceReference und InterfaceDereference der INTERFACE-Struktur angeben. Weitere Informationen zu diesen Methoden finden Sie unter WdfDeviceInterfaceReferenceNoOp und WdfDeviceInterfaceDereferenceNoOp.

Treiber sollten diese Struktur initialisieren, indem sie WDF_QUERY_INTERFACE_CONFIG_INIT aufrufen.

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