FILTER_NET_PNP_EVENT Rückruffunktion (ndis.h)

Artikel
02/29/2024

NDIS ruft die FilterNetPnPEvent-Funktion eines Filtertreibers auf, um den Treiber über PnP- (Network Plug & Play) und Energieverwaltungsereignisse zu benachrichtigen.

Hinweis Sie müssen die Funktion mit dem typ FILTER_NET_PNP_EVENT deklarieren. Weitere Informationen finden Sie im folgenden Abschnitt Beispiele.

Syntax

FILTER_NET_PNP_EVENT FilterNetPnpEvent;

NDIS_STATUS FilterNetPnpEvent(
  [in] NDIS_HANDLE FilterModuleContext,
  [in] PNET_PNP_EVENT_NOTIFICATION NetPnPEventNotification
)
{...}

Parameter

[in] FilterModuleContext

Ein Handle für den Kontextbereich für das Filtermodul. Der Filtertreiber hat diesen Kontextbereich in der FilterAttach-Funktion erstellt und initialisiert.

[in] NetPnPEventNotification

Ein Zeiger auf eine NET_PNP_EVENT_NOTIFICATION Struktur, die das PnP-Ereignis oder das Energieverwaltungsereignis beschreibt, das dem Filtertreiber angezeigt wird.

Rückgabewert

FilterNetPnPEvent kann eine der folgenden Aktionen zurückgeben:

Rückgabecode	Beschreibung
NDIS_STATUS_SUCCESS	Der Treiber hat das PnP-Ereignis erfolgreich verarbeitet.
NDIS_STATUS_FAILURE	Fehler beim Treiber beim PnP-Ereignis.

Der Rückgabewert ist nur dann signifikant, wenn das weitergegebene Ereignis ein NetEventQueryPower - oder ein NetEventQueryRemove-Ereignis ist. Für alle anderen weitergegebenen Ereignisse ist der Rückgabewert immer NDIS_STATUS_SUCCESS.

Hinweise

FilterNetPnPEvent ist eine optionale Funktion. Wenn ein Filtertreiber keine Netzwerk-PnP-Ereignisse verarbeitet, kann er den Einstiegspunkt für diese Funktion auf NULL festlegen, wenn er die NdisFRegisterFilterDriver-Funktion .

FilterNetPnPEvent ähnelt der ProtocolNetPnPEvent-Funktion eines Protokolltreibers. Ein Filtertreiber kann diese Benachrichtigungen an übergeordnete Treiber weiterleiten, oder er kann sie selbst behandeln und nicht weiterleiten. Um eine Benachrichtigung weiterzuleiten, rufen Sie die Funktion NdisFNetPnPEvent auf. Verwechseln Sie diese Funktion nicht mit der FilterDevicePnPEventNotify-Funktion , die Benachrichtigungen filtert, die nach unten im Stapel an zugrunde liegende Treiber weitergeleitet werden.

NDIS ruft FilterNetPnPEvent auf, um einen Filtertreiber über ein PnP- oder Power Management-Ereignis zu benachrichtigen, das für eine zugrunde liegende NIC ausgegeben wurde. NDIS ruft die FilterNetPnPEvent-Funktion jedes Filtertreibers auf, der eine NIC übergibt, und ruft dann die ProtocolNetPnPEvent-Funktion jedes überlappenden Protokolltreibers auf.

Wenn ein Filtermodul in einen Treiberstapel eingefügt oder daraus gelöscht wird, können sich die Merkmale des Stapels ändern. NDIS sendet ein PnP-Ereignis an alle betroffenen Protokollbindungen und Filtermodule, um sie über diese Änderung zu benachrichtigen. Filtertreiber sollten solche Änderungen angemessen behandeln.

NDIS ruft FilterNetPnPEvent unter IRQL = PASSIVE_LEVEL auf.

Beispiele

Um eine FilterNetPnPEvent-Funktion zu definieren, müssen Sie zunächst eine Funktionsdeklaration bereitstellen, die den Typ der zu definierenden Funktion identifiziert. Windows bietet eine Reihe von Funktionstypen für Treiber. Das Deklarieren einer Funktion mithilfe der Funktionstypen 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 FilterNetPnPEvent-Funktion mit dem Namen "MyNetPnPEvent" zu definieren, verwenden Sie den typ FILTER_NET_PNP_EVENT , wie in diesem Codebeispiel gezeigt:

FILTER_NET_PNP_EVENT MyNetPnPEvent;

Implementieren Sie dann Ihre Funktion wie folgt:

_Use_decl_annotations_
NDIS_STATUS
 MyNetPnPEvent(
    NDIS_HANDLE  FilterModuleContext,
    PNET_PNP_EVENT_NOTIFICATION  NetPnPEvent
    )
  {...}

Der FILTER_NET_PNP_EVENT Funktionstyp ist in der Ndis.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 FILTER_NET_PNP_EVENT 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 NDIS-Treiber.

Informationen zu Use_decl_annotations finden Sie unter Verhalten von Funktionen mit Anmerkungen.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Unterstützt in NDIS 6.0 und höher.
Zielplattform	Windows
Kopfzeile	ndis.h (include Ndis.h)
IRQL	PASSIVE_LEVEL