FILTER_PAUSE Rückruffunktion (ndis.h)

Artikel
08/07/2023

NDIS ruft die FilterPause-Funktion eines Filtertreibers auf, um einen Pausenvorgang für das angegebene Filtermodul zu initiieren.

Hinweis Sie müssen die Funktion mithilfe des typs FILTER_PAUSE deklarieren. Weitere Informationen finden Sie im folgenden Abschnitt Beispiele.

Syntax

FILTER_PAUSE FilterPause;

NDIS_STATUS FilterPause(
  [in] NDIS_HANDLE FilterModuleContext,
  [in] PNDIS_FILTER_PAUSE_PARAMETERS PauseParameters
)
{...}

Parameter

[in] FilterModuleContext

Ein Handle für den Kontextbereich des Filtermoduls, den der Filtertreiber anhalten soll. Der Filtertreiber hat diesen Kontextbereich in der FilterAttach-Funktion erstellt und initialisiert.

[in] PauseParameters

Ein Zeiger auf eine NDIS_FILTER_PAUSE_PARAMETERS Struktur, die die Pausenparameter für das Filtermodul definiert.

Rückgabewert

Bei NDIS-Treibern kann eine Pausenanforderung nicht fehlschlagen. Der Filtertreiber sollte die NdisWriteEventLogEntry-Funktion zusammen mit Parametern aufrufen, die den Grund für auftretende Fehler angeben.

Rückgabecode	Beschreibung
NDIS_STATUS_SUCCESS	FilterPause hat das angegebene Filtermodul erfolgreich angehalten.
NDIS_STATUS_PENDING	Der Filtertreiber schließt die Anforderung asynchron mit einem Aufruf der NdisFPauseComplete-Funktion ab.

Hinweise

FilterPause ist eine erforderliche Funktion. NDIS kann FilterPause aufrufen, wenn sich das Filtermodul im Status Wird ausgeführt befindet. Das Filtermodul wechselt zu Beginn der Ausführung in der FilterPause-Funktion in den Zustand Anhalten.

Ein Filtertreiber führt die folgenden Vorgänge aus, wenn NDIS FilterPause aufruft:

Muss die aufrufen. NdisFSendNetBufferListsComplete-Funktion für alle in die Warteschlange eingereihten Sendepuffer, die von einem übergeordneten Treiber erstellt wurden.
Muss die aufrufen. NdisFReturnNetBufferLists-Funktion für alle in die Warteschlange eingereihten Empfangspuffer, die von einem zugrunde liegenden Treiber erstellt wurden.
Muss warten, bis NDIS alle ausstehenden Sendeanforderungen zurückgibt, die der Treiber an die FilterSendNetBufferListsComplete-Funktion .
Muss warten, bis NDIS alle ausstehenden Empfangsanzeigen zurückgibt, dass der Treiber vom FilterReturnNetBufferLists-Funktion .

Nachdem der Filtertreiber NDIS_STATUS_SUCCESS aus FilterPause zurückgibt oder die NdisFPauseComplete-Funktion aufruft , ist der Pausenvorgang abgeschlossen. Das Filtermodul befindet sich im Zustand Angehalten .

Im Zustand Anhalten oder Angehalten sollte ein Filtertreiber weiterhin OID-Anforderungen oder status Anzeigen verarbeiten. Der Treiber sollte Aufrufe seiner FilterSendNetBufferLists-Funktion . Der Treiber kann Aufrufe an seine FilterReceiveNetBufferLists-Funktion . Der Treiber kann jedoch keine Puffer übergeben, die er erstellt hat. Der Treiber darf keine Empfangsanzeigen erstellen oder Anforderungen senden.

Im Zustand Angehalten darf das Filtermodul keine Sendeanforderungen oder Empfangsanzeigen generieren.

NDIS ruft die FilterRestart-Funktion auf, um eine Neustartanforderung für ein Filtermodul im Zustand Angehalten zu initiieren.

NDIS ruft FilterPause bei IRQL = PASSIVE_LEVEL auf.

Beispiele

Um eine FilterPause-Funktion zu definieren, müssen Sie zunächst eine Funktionsdeklaration bereitstellen, die den Typ der von Ihnen definierten 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 FilterPause-Funktion mit dem Namen "MyPause" zu definieren, verwenden Sie den typ FILTER_PAUSE , wie in diesem Codebeispiel gezeigt:

FILTER_PAUSE MyPause;

Implementieren Sie dann Ihre Funktion wie folgt:

_Use_decl_annotations_
NDIS_STATUS
 MyPause(
    NDIS_HANDLE  FilterModuleContext,
    PNDIS_FILTER_PAUSE_PARAMETERS  FilterPauseParameters
    )
  {...}

Der FILTER_PAUSE Funktionstyp ist in der Headerdatei Ndis.h 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_PAUSE 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