EVT_WDF_DEVICE_PROCESS_QUERY_INTERFACE_REQUEST Rückruffunktion (wdfqueryinterface.h)

Artikel
03/05/2024

[Gilt nur für KMDF]

Die EvtDeviceProcessQueryInterfaceRequest-Ereignisrückruffunktion eines Treibers untersucht die Anforderung eines anderen Treibers auf Zugriff auf eine vom Treiber definierte Schnittstelle, bevor das Framework die Schnittstelle an den anfordernden Treiber übergibt.

Syntax

EVT_WDF_DEVICE_PROCESS_QUERY_INTERFACE_REQUEST EvtWdfDeviceProcessQueryInterfaceRequest;

NTSTATUS EvtWdfDeviceProcessQueryInterfaceRequest(
  [in]      WDFDEVICE Device,
  [in]      LPGUID InterfaceType,
  [in, out] PINTERFACE ExposedInterface,
  [in, out] PVOID ExposedInterfaceSpecificData
)
{...}

Parameter

[in] Device

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

[in] InterfaceType

Ein Zeiger auf die GUID, die die vom Treiber definierte Schnittstelle identifiziert.

[in, out] ExposedInterface

Ein Zeiger auf eine INTERFACE-Struktur , die die vom Treiber definierte Schnittstelle beschreibt und vom Treiber bereitgestellt wurde, der Zugriff auf die Schnittstelle anfordert.

[in, out] ExposedInterfaceSpecificData

Ein Zeiger auf zusätzliche, optionale, treiberdefinierte schnittstellenspezifische Informationen. Frameworkbasierte Treiber geben diesen Wert an, indem beim Aufrufen von WdfFdoQueryForInterface ein Parameterwert vom TypInterfaceSpecificData bereitgestellt wird, der nicht NULL ist.

Rückgabewert

Wenn die Rückruffunktion EvtDeviceProcessQueryInterfaceRequest eine von ihr unterstützte GUID empfängt und die Funktion keine Fehler auftritt, muss sie STATUS_SUCCESS oder einen anderen status Wert zurückgeben, für den NT_SUCCESS(status) gleich TRUE ist. Das Framework übergibt die Anforderung weiterhin im Stapel, um festzustellen, ob zusätzliche Treiber auch die Schnittstelle unterstützen.

Die Rückruffunktion EvtDeviceProcessQueryInterfaceRequest muss STATUS_NOT_SUPPORTED zurückgeben, wenn sie feststellt, dass die Schnittstelle in einem bestimmten Fall nicht verarbeitet wird. Das Framework übergibt die Anforderung weiterhin im Stapel, um festzustellen, ob ein anderer Treiber die Schnittstelle unterstützt. Weitere Informationen zu dieser Situation finden Sie im abschnitt "Hinweise".

Wenn für die Rückruffunktion ein Fehler auftritt, muss sie einen status Wert zurückgeben, für den NT_SUCCESS(status) gleich FALSE ist. Das Framework schlägt die Anforderung des anderen Treibers für die Schnittstelle fehl und übergibt die Anforderung nicht über den Stapel.

Hinweise

Frameworkbasierte Treiber registrieren eine EvtDeviceProcessQueryInterfaceRequest-Ereignisrückruffunktion , indem sie WdfDeviceAddQueryInterface aufrufen.

Wenn die vom Treiber definierte Schnittstelle nur die unidirektionale Kommunikation unterstützt und den ImportInterface-Member der WDF_QUERY_INTERFACE_CONFIG-Struktur , die die Schnittstelle beschreibt, auf FALSE festlegt, ist die Rückruffunktion EvtDeviceProcessQueryInterfaceRequest optional. Wenn ein anderer Treiber WdfFdoQueryForInterface aufruft, kopiert das Framework die vom Treiber definierten Schnittstellenwerte in die INTERFACE-Struktur des anfordernden Treibers und ruft dann die Rückruffunktion auf. Für die unidirektionale Kommunikation müssen Sie eine Rückruffunktion nur bereitstellen, wenn der Treiber die Schnittstellenwerte überprüfen und möglicherweise ändern soll, bevor das Framework sie an den anfordernden Treiber zurückgibt.

Ihr Treiber muss eine EvtDeviceProcessQueryInterfaceRequest-Ereignisrückruffunktion bereitstellen, wenn der Treiber eine Schnittstelle definiert, die bidirektionale Kommunikation unterstützt (und das ImportInterface-Element der WDF_QUERY_INTERFACE_CONFIG-Struktur auf TRUE festlegt). Die Rückruffunktion ist erforderlich, da, wenn ImportInterfaceTRUE ist und ein anderer Treiber WdfFdoQueryForInterface aufruft, das Framework die vom Treiber definierte Schnittstelle nicht in die Schnittstellenstruktur des anfordernden Treibers kopiert. Stattdessen muss die Rückruffunktion die Schnittstellenstruktur des anfordernden Treibers aktualisieren.

Die Rückruffunktion kann die Schnittstelle ändern. Insbesondere kann es:

Ändern Sie einen beliebigen Wert in einem beliebigen Member der Schnittstelle.
Ordnen Sie einen dynamischen instance spezifischen Kontext zu, indem Sie den Context-Member der INTERFACE-Struktur ändern.

Das Framework ruft die EvtDeviceProcessQueryInterfaceRequest-Rückruffunktionen Ihres Treibers nur für GUIDs auf, die der Treiber durch Aufrufen von WdfDeviceAddQueryInterface registriert hat. Daher verwenden diese Rückruffunktionen nicht den STATUS_NOT_SUPPORTED Rückgabewert, um unerwartete GUIDs zu melden. Stattdessen sollte eine EvtDeviceProcessQueryInterfaceRequest-Rückruffunktion STATUS_NOT_SUPPORTED zurückgeben, wenn sie feststellt, dass die Schnittstelle in einem bestimmten Fall nicht verarbeitet wird. Basierend auf daten, die der anfordernde Treiber bereitstellt, kann Ihr Treiber beispielsweise bestimmen, dass die Schnittstellenanforderung von einem Treiber auf niedrigerer Ebene verarbeitet werden soll. Der STATUS_NOT_SUPPORTED Rückgabewerts informiert das Framework darüber, dass Ihr Treiber die Schnittstellenanforderung nicht verarbeitet, aber möglicherweise ein Treiber auf niedrigerer Ebene.

Weitere Informationen zu treiberdefinierte Schnittstellen finden Sie unter Verwenden Driver-Defined Schnittstellen.

Beispiele

Um eine EvtDeviceProcessQueryInterfaceRequest-Rückruffunktion zu definieren, müssen Sie zunächst eine Funktionsdeklaration bereitstellen, die den Typ der Rückruffunktion identifiziert, die Sie definieren. Windows bietet eine Reihe von Rückruffunktionstypen für Treiber. Das Deklarieren einer Funktion mithilfe der Rückruffunktionstypen hilft der Codeanalyse für Treiber, der statischen Treiberüberprüfung (Static Driver Verifier , SDV) und anderen Überprüfungstools, Fehler zu finden, und es ist eine Voraussetzung für das Schreiben von Treibern für das Windows-Betriebssystem.

Um beispielsweise eine EvtDeviceProcessQueryInterfaceRequest-Rückruffunktion namens MyDeviceProcessQueryInterfaceRequest zu definieren, verwenden Sie den typ EVT_WDF_DEVICE_PROCESS_QUERY_INTERFACE_REQUEST , wie in diesem Codebeispiel gezeigt:

EVT_WDF_DEVICE_PROCESS_QUERY_INTERFACE_REQUEST  MyDeviceProcessQueryInterfaceRequest;

Implementieren Sie dann Ihre Rückruffunktion wie folgt:

_Use_decl_annotations_
NTSTATUS
 MyDeviceProcessQueryInterfaceRequest (
    WDFDEVICE  Device,
    LPGUID  InterfaceType,
    PINTERFACE  ExposedInterface,
    PVOID  ExposedInterfaceSpecificData
    )
  {...}

Der EVT_WDF_DEVICE_PROCESS_QUERY_INTERFACE_REQUEST Funktionstyp ist in der WdfQueryInterface.h-Headerdatei definiert. Um Fehler beim Ausführen der Codeanalysetools genauer zu identifizieren, müssen Sie der Funktionsdefinition die anmerkung Use_decl_annotations hinzufügen. Die Use_decl_annotations-Anmerkung stellt sicher, dass die Anmerkungen verwendet werden, die auf den EVT_WDF_DEVICE_PROCESS_QUERY_INTERFACE_REQUEST Funktionstyp in der Headerdatei angewendet werden. Weitere Informationen zu den Anforderungen für Funktionsdeklarationen finden Sie unter Deklarieren von Funktionen mithilfe von Funktionsrollentypen für KMDF-Treiber. Informationen zu Use_decl_annotations finden Sie unter Verhalten von Funktionen mit Anmerkungen.