EVT_WDF_DEVICE_PROCESS_QUERY_INTERFACE_REQUEST Rückruffunktion (wdfqueryinterface.h)

Artikel
07/16/2024

[Gilt nur für KMDF]

Die EvtDeviceProcessQueryInterfaceRequest Ereignisrückruffunktion eines Treibers untersucht die Anforderung eines anderen Treibers für den Zugriff auf eine treiberdefinierte 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 zu einem 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 treiberdefinierte 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 WdfFdoQueryForInterfaceein nichtNULL-InterfaceSpecificData-parameterwert angegeben wird.

Rückgabewert

Wenn die EvtDeviceProcessQueryInterfaceRequest Rückruffunktion eine von ihr unterstützte GUID empfängt und wenn die Funktion keine Fehler aufweist, muss sie STATUS_SUCCESS oder einen anderen Statuswert zurückgeben, für den NT_SUCCESS(Status) TRUEentspricht. Das Framework übergibt weiterhin die Anforderung nach unten, um festzustellen, ob zusätzliche Treiber auch die Schnittstelle unterstützen.

Die EvtDeviceProcessQueryInterfaceRequest Rückruffunktion muss STATUS_NOT_SUPPORTED zurückgeben, wenn festgestellt wird, dass die Schnittstelle für einen bestimmten Fall nicht gewartet wird. Das Framework übergibt weiterhin die Anforderung nach unten, um festzustellen, ob ein anderer Treiber die Schnittstelle unterstützt. Weitere Informationen zu dieser Situation finden Sie im folgenden Abschnitt "Hinweise".

Wenn bei der Rückruffunktion ein Fehler auftritt, muss ein Statuswert zurückgegeben werden, für den NT_SUCCESS(Status) FALSE-ist. Das Framework schlägt die Anforderung des anderen Treibers für die Schnittstelle fehl und übergibt die Anforderung nicht an den Stapel.

Bemerkungen

Frameworkbasierte Treiber registrieren eine EvtDeviceProcessQueryInterfaceRequest Ereignisrückruffunktion durch Aufrufen WdfDeviceAddQueryInterface.

Wenn die vom Treiber definierte Schnittstelle nur unidirektionale Kommunikation unterstützt und das ImportInterface Element der WDF_QUERY_INTERFACE_CONFIG-Struktur festlegt, das die Schnittstelle zu FALSE-beschreibt, ist die EvtDeviceProcessQueryInterfaceRequest Rückruffunktion optional. Wenn ein anderer Treiber WdfFdoQueryForInterfaceaufruft, kopiert das Framework die treiberdefinierte Schnittstellenwerte in die INTERFACE Struktur des anfordernden Treibers und ruft dann die Rückruffunktion auf. Für eine 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 Member der WDF_QUERY_INTERFACE_CONFIG Struktur auf TRUEfestgelegt). Die Rückruffunktion ist erforderlich, da, wenn ImportInterface-TRUE- ist und ein anderer Treiber WdfFdoQueryForInterfaceaufruft, kopiert das Framework die vom Treiber definierte Schnittstelle nicht in die Anforderungstreiberschnittstellenstruktur. Stattdessen muss die Rückruffunktion die Schnittstellenstruktur des anfordernden Treibers aktualisieren.

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

Ändern Sie einen beliebigen Wert in einem beliebigen Element der Schnittstelle.
Weisen Sie einen dynamischen instanzspezifischen Kontext zu, indem Sie das Context Member der INTERFACE Struktur ändern.

Das Framework ruft die EvtDeviceProcessQueryInterfaceRequest Rückruffunktionen Ihres Treibers nur für GUIDs auf, die der Treiber registriert hat, indem WdfDeviceAddQueryInterfaceaufgerufen wird. 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 ermittelt wird, dass die Schnittstelle für einen bestimmten Fall nicht behandelt wird. Basierend auf daten, die der anfordernde Treiber bereitstellt, kann Ihr Treiber beispielsweise feststellen, dass ein Treiber auf niedrigerer Ebene die Schnittstellenanforderung bedienen soll. Der STATUS_NOT_SUPPORTED Rückgabewert informiert das Framework darüber, dass ihr Treiber die Schnittstellenanforderung nicht gewartet, aber ein Treiber auf niedrigerer Ebene kann es warten.

Weitere Informationen zu treiberdefinierten Schnittstellen finden Sie unter Using Driver-Defined Interfaces.

Beispiele

Um eine EvtDeviceProcessQueryInterfaceRequest Rückruffunktion zu definieren, müssen Sie zuerst eine Funktionsdeklaration bereitstellen, die den Typ der rückruffunktion identifiziert, die Sie definieren. Windows stellt eine Reihe von Rückruffunktionstypen für Treiber bereit. Durch das Deklarieren einer Funktion mithilfe der Rückruffunktionstypen können Codeanalyse für Treiber, statische Treiberüberprüfung (SDV) und andere Überprüfungstools Fehler finden, und es ist eine Anforderung zum Schreiben von Treibern für das Windows-Betriebssystem.

Um beispielsweise eine EvtDeviceProcessQueryInterfaceRequest Rückruffunktion zu definieren, die MyDeviceProcessQueryInterfaceRequestheißt, verwenden Sie den EVT_WDF_DEVICE_PROCESS_QUERY_INTERFACE_REQUEST Typ, wie in diesem Codebeispiel gezeigt:

EVT_WDF_DEVICE_PROCESS_QUERY_INTERFACE_REQUEST  MyDeviceProcessQueryInterfaceRequest;

Implementieren Sie dann die 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 wird in der Headerdatei WdfQueryInterface.h definiert. Um Fehler genauer zu identifizieren, wenn Sie die Codeanalysetools ausführen, müssen Sie der Funktionsdefinition die Use_decl_annotations Anmerkung hinzufügen. Die Use_decl_annotations Anmerkung stellt sicher, dass die Anmerkungen, die auf den Funktionstyp EVT_WDF_DEVICE_PROCESS_QUERY_INTERFACE_REQUEST in der Headerdatei angewendet werden, verwendet 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_annotationsfinden Sie unter Annotating Function Behavior.