FILTER_RESTART Rückruffunktion (ndis.h)

Artikel
08/07/2023

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

Hinweis Sie müssen die Funktion mithilfe des typs FILTER_RESTART deklarieren. 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 des Filtermoduls, den der Filtertreiber neu starten soll. Der Filtertreiber hat diesen Kontextbereich in der FilterAttach-Funktion erstellt und initialisiert.

[in] RestartParameters

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

Rückgabewert

FilterRestart gibt einen der folgenden status Werte zurück:

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

Hinweise

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 FilterRestart in den Status Neustart.

Wenn NDIS FilterRestart aufruft, ein Filtertreiber:

Muss die Vorgänge abschließen, die erforderlich sind, um normale Sende- und Empfangsvorgänge neu zu starten.
Liest oder schreibt optional Konfigurationsparameter.
Optional werden Pufferpools neu zugeordnet.
Ändert optional die Neustartattribute, die im RestartAttributes-Element 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 ungleich NULL 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 werden OID-Anforderungen verwendet, um Informationen in den zugrunde liegenden Treibern abzufragen oder festzulegen. Filtertreiber sollten keine OID-Anforderungen für Informationen ausgeben, die bereits in der Liste der Neustartattribute angegeben sind.
Gibt NDIS_STATUS_SUCCESS oder einen Fehler status zurück.

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

Sollte keine medienspezifischen Attribute ändern, wenn die OID im Oid-Element 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 stellen Speicherplatz für die neuen Attribute bereit. Nach der Weitergabe der Neustartattribute an übergeordnete Treiber gibt NDIS den Attributespeicher 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, die die geänderten Informationen enthält. Nach der Weitergabe der Neustartattribute an übergeordnete Treiber gibt NDIS den Attributespeicher für Filtertreiber frei.
Sollte, wenn das Oid-Element in der NDIS_RESTART_ATTRIBUTES-Struktur stellen Sie OID_GEN_MINIPORT_RESTART_ATTRIBUTES sicher, dass 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 den Revisionsmember in der NDIS_OBJECT_HEADER-Struktur überprüfen, die im Headerelement 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 Struktur enthalten sind, die von NDIS bereitgestellt wurde, sollte der Filtertreiber auf übermäßig viele Treiber angewiesen sein, um OID-Anforderungen für die fehlenden Attribute auszugeben. Der Filtertreiber kann die Attribute ändern, wenn er die OID-Anforderung abschließt.
Wenn der Filtertreiber die Neustartattribute ändert, muss eine FilterOidRequest-Funktion bereitgestellt werden. Der Filtertreiber muss sicherstellen, dass die Informationen, die überlastende Treiber in den Neustartattributen erhalten, mit den Informationen übereinstimmen, die sie als Reaktion auf OID-Anforderungen erhalten.

Nachdem der Filtertreiber seine status zurückgibt oder die NdisFRestartComplete-Funktion aufruft, ist der Neustartvorgang abgeschlossen. Wenn der Vorgang erfolgreich abgeschlossen wurde, befindet sich das Filtermodul im Status Wird ausgeführt , und die normale Sende- und Empfangsverarbeitung wird fortgesetzt. Wenn der Neustartvorgang fehlgeschlagen ist, kehrt das Filtermodul in den Zustand Angehalten zurück .

NDIS ruft FilterRestart unter IRQL = PASSIVE_LEVEL auf.

Beispiele

Um eine FilterRestart-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 FilterRestart-Funktion mit dem Namen "MyRestart" zu definieren, verwenden Sie den typ FILTER_RESTART , 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 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_RESTART 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