Auf Englisch lesen

Freigeben über


FILTER_ATTACH Rückruffunktion (ndis.h)

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

Hinweis Sie müssen die Funktion mithilfe des FILTER_ATTACH Typs 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 NdisF-Xxx--Funktionen erforderlich.

[in] FilterDriverContext

Das Handle, das der Treiber an die 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 Statuswerte zurück:

Rückgabecode Beschreibung
NDIS_STATUS_SUCCESS
FilterAttach erfolgreich zugeordnete und initialisierte Datenstrukturen für dieses Filtermodul.
NDIS_STATUS_RESOURCES
FilterAttach aufgrund unzureichender Ressourcen fehlgeschlagen.
NDIS_STATUS_FAILURE
FilterAttach gibt NDIS_STATUS_FAILURE zurück, wenn keine der vorherigen Werte gilt. Der Filtertreiber sollte die NdisWriteEventLogEntry Funktion zusammen mit Parametern aufrufen, die den Grund für den Fehler angeben.

Bemerkungen

FilterAttach eine erforderliche Funktion ist. NDIS ruft die FilterAttach- funktion eines Filtertreibers auf, wenn sich das angegebene Filtermodul im Zustand Getrennten 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 vermeiden, unnötige OID-Abfragen auszugeben. Verwenden Sie stattdessen die Informationen in NDIS_FILTER_ATTACH_PARAMETERS, wenn verfügbar, Informationen zu zugrunde liegenden Treibern zu erhalten.

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

  • Erstellt einen Kontextbereich für das Filtermodul und weist Pufferpools und andere Ressourcen zu.
  • Ruft die NdisFSetAttributes Funktion zusammen mit dem NdisFilterHandle- auf, den 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 ihm in der FilterAttach--Funktion zugeordnet wurden, und das Filtermodul an den Zustand Getrennten zurückgeben.
  • Gibt NDIS_STATUS_SUCCESS oder einen geeigneten Fehlercode zurück.
Ein Filtertreiber sollte keine Anforderungen senden, empfangene Daten angeben, OID-Anforderungen stellen oder Statusanzeigen vom Anfügen Zustands machen.

NDIS ruft die FilterDetach--Funktion eines Filtertreibers auf, um alle Ressourcen freizugeben, die einem Filtermodul zugeordnet sind, und das Filtermodul an den Zustand Getrennten zurückzugeben.

NDIS ruft FilterAttach- bei IRQL = PASSIVE_LEVEL auf.

beispiele für

Um eine FilterAttach--Funktion zu definieren, müssen Sie zuerst eine Funktionsdeklaration angeben, 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 FilterAttach--Funktion zu definieren, die den Namen "MyAttach" hat, 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 wird in der Headerdatei Ndis.h 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_ATTACH 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

Siehe auch

FilterDetach-

FilterSetOptions-

NDIS_FILTER_ATTACH_PARAMETERS

NdisFRegisterFilterDriver-

NdisFSetAttributes

NdisWriteEventLogEntry