FILTER_RESTART Rückruffunktion (ndis.h)

Artikel
02/07/2025

Die FilterRestart--Funktion initiiert einen Neustartvorgang für das angegebene Filtermodul.

Note You must declare the function by using the FILTER_RESTART type. Weitere Informationen finden Sie im folgenden Abschnitt "Beispiele".

Syntax

FILTER_RESTART FilterRestart;

NDIS_STATUS FilterRestart(
  [in] NDIS_HANDLE FilterModuleContext,
  [in] PNDIS_FILTER_RESTART_PARAMETERS RestartParameters
)
{...}

Parameter

[in] FilterModuleContext

Ein Handle für den Kontextbereich für das Filtermodul, das vom Filtertreiber neu gestartet werden soll. Der Filtertreiber hat diesen Kontextbereich in der FilterAttach-Funktion erstellt und initialisiert.

[in] RestartParameters

Ein Zeiger auf einen NDIS_FILTER_RESTART_PARAMETERS Struktur, die die Neustartparameter für das Filtermodul definiert.

Rückgabewert

FilterRestart- gibt einen der folgenden Statuswerte zurück:

Rückgabecode	Beschreibung
NDIS_STATUS_SUCCESS	FilterRestart das angegebene Filtermodul erfolgreich neu gestartet.
NDIS_STATUS_PENDING	Der Filtertreiber schließt die Anforderung asynchron mit einem Aufruf des NdisFRestartComplete Funktion ab, nachdem der Neustartvorgang abgeschlossen wurde.
NDIS_STATUS_RESOURCES	FilterRestart aufgrund unzureichender Ressourcen fehlgeschlagen.
NDIS_STATUS_FAILURE	Keines der vorherigen Statuswerte gilt. Der Filtertreiber sollte die NdisWriteEventLogEntry Funktion zusammen mit Parametern aufrufen, die den Grund für den Fehler angeben.

Bemerkungen

FilterRestart- ist eine erforderliche Funktion für Filtertreiber. NDIS kann FilterRestart- aufrufen, wenn sich ein Filtermodul im Zustand Angehalten befindet. Das Filtermodul wechselt zu Beginn der Ausführung von FilterRestartin den Zustand Neustarten.

Wenn NDIS FilterRestart-aufruft, ist ein Filtertreiber:

Muss die Vorgänge ausführen, die zum Neustart normaler Sende- und Empfangsvorgänge erforderlich sind.
Optional werden Konfigurationsparameter gelesen oder geschrieben.
Optional werden Pufferpools neu lociert.
Ändert optional die Neustartattribute, die im RestartAttributes Member des NDIS_FILTER_RESTART_PARAMETERS Struktur. Wenn der Zeiger in RestartAttributesNULL-ist, sollte der Filtertreiber die Liste der Neustartattribute nicht ändern oder hinzufügen. Wenn der Zeiger in RestartAttributes nichtNULL-ist, verweist er auf die erste NDIS_RESTART_ATTRIBUTES Struktur in der Liste der Neustartattribute. Wenn ein Filtertreiber nicht neu gestartet wird, sollte er keine Attribute ändern.
Optional verwendet OID-Anforderungen zum Abfragen oder Festlegen von Informationen in den zugrunde liegenden Treibern. Filtertreiber sollten keine OID-Anforderungen für Informationen ausgeben, die bereits in der Liste der Neustartattribute enthalten sind.
Gibt NDIS_STATUS_SUCCESS oder einen Fehlerstatus zurück.

Wenn ein Filtertreiber die Liste der Neustartattribute ändert, wird der Filtertreiber:

Sollte keine medienspezifischen Attribute ändern, wenn sie das OID nicht im Oid Member des NDIS_RESTART_ATTRIBUTES Struktur.
Kann der Liste der Neustartattribute neue medienspezifische Attribute hinzufügen. In diesem Fall muss der Filtertreiber eine neue NDIS_RESTART_ATTRIBUTES Struktur zuordnen , z. B. mit der NdisAllocateMemoryWithTagPriority Funktion und bieten Speicherplatz für die neuen Attribute. Nachdem NDIS die Neustartattribute an übermäßig viele Treiber verteilt hat, gibt NDIS den Speicher der Attribute für Filtertreiber frei.
Kann die medienspezifischen Attribute in der Liste der Neustartattribute ändern. Wenn der Filtertreiber mehr Speicherplatz benötigt, kann er die NDIS_RESTART_ATTRIBUTES Struktur mit der NdisFreeMemory Funktion freigeben und eine neue Struktur zuweisen, um die geänderten Informationen zu enthalten. Nachdem NDIS die Neustartattribute an übermäßig viele Treiber verteilt hat, gibt NDIS den Speicher der Attribute für Filtertreiber frei.
Sollte, wenn das Oid Mitglied in der NDIS_RESTART_ATTRIBUTES Struktur ist OID_GEN_MINIPORT_RESTART_ATTRIBUTES, stellen Sie sicher, dass die NDIS_RESTART_GENERAL_ATTRIBUTES Struktur enthält die Informationen, die der Filtertreiber benötigt. Um sicherzustellen, dass die NDIS_RESTART_GENERAL_ATTRIBUTES-Struktur die erforderlichen Informationen enthält, sollten Sie das element Revision in der struktur NDIS_OBJECT_HEADER überprüfen, die im Header Member der NDIS_RESTART_GENERAL_ATTRIBUTES Struktur angegeben ist.
Hinweis Ein Filtertreiber kann jedes Element in der NDIS_RESTART_GENERAL_ATTRIBUTES Struktur ändern. Wenn einige Attribute, die der Filtertreiber ändern soll, nicht in der Überarbeitung der von NDIS bereitgestellten Struktur enthalten sind, sollte der Filtertreiber auf Überlying-Treiber angewiesen sein, um OID-Anforderungen für die fehlenden Attribute auszuweisen. Der Filtertreiber kann die Attribute ändern, wenn sie die OID-Anforderung abgeschlossen hat.
Muss, wenn der Filtertreiber Neustartattribute ändert, eine FilterOidRequest--Funktion bereitstellen. Der Filtertreiber muss sicherstellen, dass die Informationen, die übermäßig viele Treiber in den Neustartattributen erhalten, mit den Informationen konsistent sind, die sie als Reaktion auf OID-Anforderungen erhalten.

Nachdem der Filtertreiber seinen Status zurückgibt oder den NdisFRestartComplete--Funktion aufruft, ist der Neustartvorgang abgeschlossen. Wenn der Vorgang erfolgreich abgeschlossen wurde, befindet sich das Filtermodul in der Ausführung Zustand und die normale Sende- und Empfangsverarbeitung wird fortgesetzt. Wenn der Neustartvorgang fehlgeschlagen ist, kehrt das Filtermodul zum Zustand Angehaltenen zurück.

NDIS ruft FilterRestart- bei IRQL = PASSIVE_LEVEL auf.

beispiele für

Um eine FilterRestart--Funktion zu definieren, müssen Sie zuerst eine Funktionsdeklaration bereitstellen, die den Typ der Funktion identifiziert, die Sie definieren. Windows stellt eine Reihe von Funktionstypen für Treiber bereit. Durch das Deklarieren einer Funktion mithilfe der Funktionstypen 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 FilterRestart--Funktion zu definieren, die den Namen "MyRestart" hat, verwenden Sie den FILTER_RESTART Typ, wie in diesem Codebeispiel gezeigt:

FILTER_RESTART MyRestart;

Implementieren Sie dann Ihre Funktion wie folgt:

_Use_decl_annotations_
NDIS_STATUS
 MyRestart(
    NDIS_HANDLE  FilterModuleContext,
    PNDIS_FILTER_RESTART_PARAMETERS  FilterRestartParameters
    )
  {...}

Der FILTER_RESTART Funktionstyp wird in der Ndis.h-Headerdatei 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 FILTER_RESTART 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 NDIS-Treiber.

Informationen zu Use_decl_annotationsfinden Sie unter Annotating Function Behavior.

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Unterstützt in NDIS 6.0 und höher.
Zielplattform-	Fenster
Header-	ndis.h (include Ndis.h)
IRQL-	PASSIVE_LEVEL