FILTER_ATTACH Rückruffunktion (ndis.h)

Artikel
08/07/2023

NDIS ruft die FilterAttach-Funktion eines Filtertreibers auf, um die Datenstrukturen eines Filtermoduls zuzuordnen und zu initialisieren.

Hinweis Sie müssen die Funktion mit dem FILTER_ATTACH-Typ deklarieren. Weitere Informationen finden Sie im folgenden Abschnitt Beispiele.

Syntax

FILTER_ATTACH FilterAttach;

NDIS_STATUS FilterAttach(
  [in] NDIS_HANDLE NdisFilterHandle,
  [in] NDIS_HANDLE FilterDriverContext,
  [in] PNDIS_FILTER_ATTACH_PARAMETERS AttachParameters
)
{...}

Parameter

[in] NdisFilterHandle

Ein NDIS-Handle, das ein Filtermodul identifiziert. Der Filtertreiber muss dieses Handle speichern. Das Handle ist in nachfolgenden Aufrufen von NdisFXxx-Funktionen erforderlich.

[in] FilterDriverContext

Der Handle, den der Treiber an den übergeben hat NdisFRegisterFilterDriver-Funktion , die den Treiberkontextbereich identifiziert.

[in] AttachParameters

Ein Zeiger auf einen NDIS_FILTER_ATTACH_PARAMETERS Struktur, die die Initialisierungsparameter für das Filtermodul definiert.

Rückgabewert

FilterAttach gibt einen der folgenden status Werte zurück:

Rückgabecode	Beschreibung
NDIS_STATUS_SUCCESS	FilterAttach hat datenstrukturen für dieses Filtermodul erfolgreich zugeordnet und initialisiert.
NDIS_STATUS_RESOURCES	Fehler bei FilterAttach aufgrund unzureichender Ressourcen.
NDIS_STATUS_FAILURE	FilterAttach gibt NDIS_STATUS_FAILURE zurück, wenn keiner der vorherigen Werte zutrifft. Der Filtertreiber sollte die NdisWriteEventLogEntry-Funktion zusammen mit Parametern aufrufen, die den Grund für den Fehler angeben.

Hinweise

FilterAttach ist eine erforderliche Funktion. NDIS ruft die FilterAttach-Funktion eines Filtertreibers auf, wenn sich das angegebene Filtermodul im Status "Getrennt" befindet. NDIS kann FilterAttach jederzeit aufrufen, nachdem der Aufruf der FilterSetOptions-Funktion zurückgegeben wurde.

Zu Beginn der Ausführung in FilterAttach wechselt das Filtermodul in den Zustand Anfügen .

Filtertreiber sollten unnötige OID-Abfragen vermeiden. Verwenden Sie stattdessen die Informationen in NDIS_FILTER_ATTACH_PARAMETERS, sofern verfügbar, Informationen zu zugrunde liegenden Treibern abzurufen.

Ein Filtertreiber führt die folgenden Vorgänge aus, wenn NDIS FilterAttach aufruft.

Erstellt einen Kontextbereich für das Filtermodul und ordnet Pufferpools und alle anderen Ressourcen zu.
Ruft die NdisFSetAttributes-Funktion zusammen mit dem NdisFilterHandle auf, das NDIS an FilterAttach übergeben hat. Der FilterModuleContext-Parameter von NdisFSetAttributes gibt den Kontextbereich des Filtertreibers für dieses Filtermodul an. NDIS übergibt diesen Kontextbereich an die FilterXxx-Funktionen des Filtertreibers.
Liest optional Konfigurationsparameter aus der Registrierung.
Wenn die vorherigen Vorgänge erfolgreich abgeschlossen wurden, wechselt das Filtermodul in den Zustand Angehalten .
Wenn bei den vorherigen Vorgängen ein Fehler aufgetreten ist, muss der Filtertreiber alle Ressourcen freigeben, die er in der FilterAttach-Funktion zugewiesen hat, und das Filtermodul in den Status "Getrennt" zurückgeben.
Gibt NDIS_STATUS_SUCCESS oder einen entsprechenden Fehlercode zurück.

Ein Filtertreiber sollte keine Sendeanforderungen stellen, empfangene Daten angeben, OID-Anforderungen stellen oder status Hinweise aus dem Anfügenden Zustand vornehmen.

NDIS ruft die FilterDetach-Funktion eines Filtertreibers auf, um alle Ressourcen freizugeben, die einem Filtermodul zugeordnet sind, und das Filtermodul in den Status "Getrennt" zurückzusetzen.

NDIS ruft FilterAttach unter IRQL = PASSIVE_LEVEL auf.

Beispiele

Um eine FilterAttach-Funktion zu definieren, müssen Sie zunächst eine Funktionsdeklaration bereitstellen, die den Typ der zu definierenden Funktion identifiziert. Windows stellt eine Reihe von Funktionstypen für Treiber bereit. 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 Anforderung zum Schreiben von Treibern für das Windows-Betriebssystem.

Um beispielsweise eine FilterAttach-Funktion mit dem Namen "MyAttach" zu definieren, verwenden Sie den FILTER_ATTACH-Typ , wie in diesem Codebeispiel gezeigt:

FILTER_ATTACH MyAttach;

Implementieren Sie dann Ihre Funktion wie folgt:

_Use_decl_annotations_
NDIS_STATUS
 MyAttach(
    NDIS_HANDLE  NdisFilterHandle,
    NDIS_HANDLE  FilterDriverContext,
    PNDIS_FILTER_ATTACH_PARAMETERS  AttachParameters
    )
  {...}

Der FILTER_ATTACH Funktionstyp ist in der Headerdatei Ndis.h definiert. Um Fehler beim Ausführen der Codeanalysetools genauer zu identifizieren, fügen Sie der Funktionsdefinition die Use_decl_annotations Anmerkung hinzu. Die Use_decl_annotations Anmerkung stellt sicher, dass die Anmerkungen verwendet werden, die auf den FILTER_ATTACH 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 (einschließlich Ndis.h)
IRQL	PASSIVE_LEVEL