FILTER_RETURN_NET_BUFFER_LISTS Rückruffunktion (ndis.h)

Artikel
03/01/2024

NDIS ruft die FilterReturnNetBufferLists-Funktion auf, um eine verknüpfte Liste von NET_BUFFER_LIST Strukturen und zugeordneten Daten an einen Filtertreiber zurückzugeben.

Hinweis Sie müssen die Funktion mit dem typ FILTER_RETURN_NET_BUFFER_LISTS deklarieren. Weitere Informationen finden Sie im folgenden Abschnitt Beispiele.

Syntax

FILTER_RETURN_NET_BUFFER_LISTS FilterReturnNetBufferLists;

void FilterReturnNetBufferLists(
  [in] NDIS_HANDLE FilterModuleContext,
  [in] PNET_BUFFER_LIST NetBufferLists,
  [in] ULONG ReturnFlags
)
{...}

Parameter

[in] FilterModuleContext

Ein Handle für den Kontextbereich für das Filtermodul. Der Filtertreiber hat diesen Kontextbereich in der FilterAttach-Funktion erstellt und initialisiert.

[in] NetBufferLists

Eine verknüpfte Liste von NET_BUFFER_LIST Strukturen, die der Filtertreiber durch Aufrufen der NdisFIndicateReceiveNetBufferLists-Funktion . Die Liste kann NET_BUFFER_LIST Strukturen aus mehreren Aufrufen von NdisFIndicateReceiveNetBufferLists enthalten.

[in] ReturnFlags

NDIS-Flags, die mit einem OR-Vorgang kombiniert werden können. Um alle Flags zu löschen, legen Sie dieses Element auf 0 (null) fest. Diese Funktion unterstützt die folgenden Flags:

NDIS_RETURN_FLAGS_DISPATCH_LEVEL

Gibt an, dass die aktuelle IRQL DISPATCH_LEVEL ist. Weitere Informationen zu diesem Flag finden Sie unter Dispatch IRQL Tracking.For more information about this flag, see Dispatch IRQL Tracking.

NDIS_RETURN_FLAGS_SWITCH_SINGLE_SOURCE

Wenn dieses Flag festgelegt ist, stammen alle Pakete in einer verknüpften Liste von NET_BUFFER_LIST Strukturen vom gleichen erweiterbaren Hyper-V-Switch-Quellport.

Weitere Informationen finden Sie unter Hyper-V Extensible Switch Send and Receive Flags.For more information, see Hyper-V Extensible Switch Send and Receive Flags.

Hinweis Wenn jedes Paket in der verknüpften Liste der NET_BUFFER_LIST-Strukturen denselben Quellport verwendet, sollte die Erweiterung das flag NDIS_RECEIVE_FLAGS_SWITCH_SINGLE_SOURCE im ReceiveFlags-Parameter von FilterReceiveNetBufferLists festlegen, wenn sie die Anforderung sendet.

Rückgabewert

Keine

Bemerkungen

FilterReturnNetBufferLists ist eine optionale Funktion. Wenn ein Filtertreiber keine Empfangsanzeigen filtert, kann er den Einstiegspunkt für diese Funktion auf NULL festlegen, wenn er die NdisFRegisterFilterDriver-Funktion .

Der Filtertreiber kann die NdisSetOptionalHandlers-Funktion aus der FilterSetModuleOptions-Funktion aufrufen, um eine FilterReturnNetBufferLists-Funktion für ein Filtermodul anzugeben.

Hinweis Ein Filtertreiber, der keine FilterReturnNetBufferLists-Funktion bereitstellt, kann die nicht aufrufen. NdisFIndicateReceiveNetBufferLists-Funktion , um eine Empfangsanzeige zu initiieren.

Hinweis Ein Filtertreiber, der eine FilterReturnNetBufferLists-Funktion bereitstellt, muss eine FilterStatus-Funktion bereitstellen.

Wenn NDIS FilterReturnNetBufferLists aufruft, erhält der Filtertreiber den Besitz der NET_BUFFER_LIST-Strukturen und der zugeordneten Daten wieder.

Wenn ein zugrunde liegender Treiber die Empfangsanzeige initiiert hat, sollte der Filtertreiber die NdisFReturnNetBufferLists-Funktion , um die Empfangsanzeige abzuschließen.

Wenn der Filtertreiber von der Empfangsanzeige stammt, kann FilterReturnNetBufferLists entweder die NET_BUFFER_LIST-Strukturen und die zugehörigen Daten freigeben oder sie für die Wiederverwendung in einem nachfolgenden Aufruf von NdisFIndicateReceiveNetBufferLists vorbereiten.

Ein Filtertreiber sollte die von diesem initiierten Empfangsanzeigen nachverfolgen und sicherstellen, dass er nicht NdisFReturnNetBufferLists aufruft , wenn NDIS FilterReturnNetBufferLists aufruft.

NDIS ruft FilterReturnNetBufferLists unter IRQL <= DISPATCH_LEVEL auf.

Beispiele

Um eine FilterReturnNetBufferLists-Funktion zu definieren, müssen Sie zunächst eine Funktionsdeklaration bereitstellen, die den Typ der zu definierenden 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 FilterReturnNetBufferLists-Funktion mit dem Namen "MyReturnNetBufferLists" zu definieren, verwenden Sie den typ FILTER_RETURN_NET_BUFFER_LISTS , wie in diesem Codebeispiel gezeigt:

FILTER_RETURN_NET_BUFFER_LISTS MyReturnNetBufferLists;

Implementieren Sie dann Ihre Funktion wie folgt:

_Use_decl_annotations_
VOID
 MyReturnNetBufferLists(
    NDIS_HANDLE  FilterModuleContext,
    PNET_BUFFER_LIST  NetBufferLists,
    ULONG  ReturnFlags
    )
  {...}

Der FILTER_RETURN_NET_BUFFER_LISTS 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_RETURN_NET_BUFFER_LISTS 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	<= DISPATCH_LEVEL