EVT_WDF_DEVICE_PROCESS_QUERY_INTERFACE_REQUEST Rückruffunktion (wdfqueryinterface.h)

[Gilt nur für KMDF]

Die Rückruffunktion eines Treibers evtDeviceProcessQueryInterfaceRequest überprüft 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 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 ohne NULLInterfaceSpecificData bereitgestellt wird.

Rückgabewert

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

Die Rückruffunktion EvtDeviceProcessQueryInterfaceRequest muss STATUS_NOT_SUPPORTED zurückgeben, wenn sie bestimmt, dass die Schnittstelle für einen bestimmten Fall nicht verwendet wird. Das Framework übergibt die Anforderung weiterhin 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 entspricht. 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 von WdfDeviceAddQueryInterface.

Wenn die vom Treiber definierte Schnittstelle nur die einmalige Kommunikation unterstützt und das ImportInterface-Element der WDF_QUERY_INTERFACE_CONFIG-Struktur festlegt, die die Schnittstelle mit FALSE beschreibt, ist die EvtDeviceProcessQueryInterfaceRequest-Rückruffunktion optional. Wenn ein anderer Treiber WdfFdoQueryForInterface aufruft, kopiert das Framework die vom Treiber definierten Schnittstellenwerte in die ANFORDERUNGsschnittstellenstruktur und ruft dann die Rückruffunktion auf. Für eine unidirektionale Kommunikation müssen Sie nur eine Rückruffunktion bereitstellen, wenn der Treiber die Schnittstellenwerte untersuchen und ä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 die zweidirektionale Kommunikation unterstützt (und das ImportInterface-Element der WDF_QUERY_INTERFACE_CONFIG-Struktur auf TRUE festlegt). Die Rückruffunktion ist erforderlich, da das Framework, wenn "ImportInterface" WAHR ist und ein anderer Treiber WdfFdoQueryForInterface aufruft, nicht die vom Treiber definierte Schnittstelle in die Anforderungsschnittstellenstruktur kopiert. Stattdessen muss die Rückruffunktion die Anforderungsschnittstellenstruktur aktualisieren.

Die Rückruffunktion kann die Schnittstelle ändern. Insbesondere kann folgendes möglich sein:

  • Ändern Sie einen beliebigen Wert in einem beliebigen Element der Schnittstelle.
  • Weisen Sie einen dynamischen instanzspezifischen Kontext zu, indem Sie das Kontextelement 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 bestimmt, dass die Schnittstelle für einen bestimmten Fall nicht verarbeitet wird. Basierend auf Daten, die der angeforderte Treiber bereitstellt, kann Ihr Treiber beispielsweise bestimmen, dass ein Treiber auf niedrigerer Ebene die Schnittstellenanforderung serviceieren soll. Der STATUS_NOT_SUPPORTED Rückgabewert informiert das Framework, dass der Treiber die Schnittstellenanforderung nicht gewartet, aber ein Treiber auf niedrigerer Ebene kann es serviceieren.

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

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. Das Deklarieren einer Funktion mithilfe der Rückruffunktionstypen hilft der Codeanalyse für Treiber, statische Treiberüberprüfung (SDV) und anderen Überprüfungstools, Fehler zu finden, und es ist eine Anforderung zum Schreiben von Treibern für das Windows-Betriebssystem.

Um beispielsweise eine EvtDeviceProcessQueryInterfaceRequest-Rückruffunktion zu definieren, die " MyDeviceProcessQueryInterfaceRequest" heiß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 Kopfzeilendatei 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_annotations finden Sie unter Annotating Function Behavior.

Anforderungen

   
Zielplattform Universell
KMDF-Mindestversion 1.0
Header wdfqueryinterface.h (include Wdf.h)
IRQL PASSIVE_LEVEL

Weitere Informationen

SCHNITTSTELLE

WDF_QUERY_INTERFACE_CONFIG

WdfDeviceAddQueryInterface

WdfFdoQueryForInterface