PROTOCOL_RECEIVE_NET_BUFFER_LISTS Rückruffunktion (ndis.h)

Artikel
08/07/2023

Die Prozesse der ProtocolReceiveNetBufferLists-Funktion erhalten Hinweise von zugrunde liegenden Treibern.

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

Syntax

PROTOCOL_RECEIVE_NET_BUFFER_LISTS ProtocolReceiveNetBufferLists;

void ProtocolReceiveNetBufferLists(
  [in] NDIS_HANDLE ProtocolBindingContext,
  [in] PNET_BUFFER_LIST NetBufferLists,
  [in] NDIS_PORT_NUMBER PortNumber,
  [in] ULONG NumberOfNetBufferLists,
  [in] ULONG ReceiveFlags
)
{...}

Parameter

[in] ProtocolBindingContext

Ein Handle für einen Kontextbereich, den der Protokolltreiber zugewiesen hat, um Zustandsinformationen für eine Bindung zu verwalten. Dieses Handle wurde in einem vorherigen Aufruf der NdisOpenAdapterEx-Funktion an NDIS übergeben.

[in] NetBufferLists

Eine verknüpfte Liste NET_BUFFER_LIST Strukturen, die der zugrunde liegende Treiber zugeordnet hat. Jede NET_BUFFER_LIST Struktur ist normalerweise einer NET_BUFFER Struktur zugeordnet.

[in] PortNumber

Eine Portnummer, die einen Miniportadapterportport identifiziert. Die Standardportnummer eines Miniportadapters ist 0. Protokolltreiber, die keine Miniportadapterports verwenden, sollten diesen Parameter ignorieren.

[in] NumberOfNetBufferLists

Die Anzahl der NET_BUFFER_LIST Strukturen, die sich in der verknüpften Liste der Strukturen in NetBufferLists befinden.

[in] ReceiveFlags

Flags, die Attribute für den Sendevorgang definieren. Die Flags können mit einem OR-Vorgang kombiniert werden. Um alle Flags zu löschen, legen Sie diesen Member auf 0 fest. Diese Funktion unterstützt die folgenden Flags:

NDIS_RECEIVE_FLAGS_DISPATCH_LEVEL

Gibt an, dass die aktuelle IRQL DISPATCH_LEVEL ist. Weitere Informationen zu diesem Flag finden Sie unter Dispatch IRQL Tracking.

NDIS_RECEIVE_FLAGS_RESOURCES

Gibt an, dass NDIS den Besitz der NET_BUFFER_LIST-Strukturen und aller angefügten NET_BUFFER Strukturen sofort nach der Rückgabe des Aufrufs von ProtocolReceiveNetBufferLists zurückgibt.

NDIS_RECEIVE_FLAGS_SINGLE_ETHER_TYPE

Gibt an, dass alle NET_BUFFER_LIST-Strukturen in der Liste von NetBufferLists denselben Protokolltyp (EtherType) aufweisen.

NDIS_RECEIVE_FLAGS_SINGLE_VLAN

Gibt an, dass alle NET_BUFFER_LIST Strukturen in der Liste unter NetBufferLists zum gleichen VLAN gehören.

NDIS_RECEIVE_FLAGS_PERFECT_FILTERED

Gibt an, dass alle NET_BUFFER_LIST-Strukturen in der Liste unter NetBufferLists nur Daten enthalten, die dem Paketfilter und der Multicastliste entsprechen, die dem Miniportadapter zugewiesen sind.

NDIS_RECEIVE_FLAGS_SINGLE_QUEUE

Gibt an, dass alle NET_BUFFER_LIST-Strukturen in der Liste von NetBufferLists derselben VM-Warteschlange angehören. Ein Miniporttreiber muss dieses Flag für alle Empfangsanzeigen in einer Warteschlange festlegen, wenn das NDIS_RECEIVE_QUEUE_PARAMETERS_PER_QUEUE_RECEIVE_INDICATION-Flag im Flags-Element des NDIS_RECEIVE_QUEUE_PARAMETERS Struktur, wenn diese Warteschlange zugewiesen wurde.

NDIS_RECEIVE_FLAGS_SHARED_MEMORY_INFO_VALID

Gibt an, dass alle NET_BUFFER_LIST-Strukturen in der Liste unter NetBufferLists gültige Shared Memory-Informationen enthalten. Wenn dieses Flag für eine empfangene NET_BUFFER_LIST festgelegt wird, behandelt NDIS die Informationen des freigegebenen Speichers als gültig. Wenn dieses Flag nicht festgelegt ist, ignorieren NDIS und Treiber die Informationen zum freigegebenen Speicher. Beispielsweise können Zwischentreiber, die Paketdaten ändern, dieses Flag verwenden, um zu bestimmen, ob Daten kopiert werden sollen. Miniporttreiber können das Flag verwenden, um zu bestimmen, wie der Arbeitsspeicher freigegeben werden soll, der einer VM-Warteschlange zugeordnet ist, wenn eine Warteschlange gelöscht wird.

NDIS_RECEIVE_FLAGS_MORE_NBLS

Reserviert.

Rückgabewert

Keine

Bemerkungen

ProtocolReceiveNetBufferLists ist eine erforderliche Funktion für Protokolltreiber. NDIS ruft ProtocolReceiveNetBufferLists auf, nachdem ein gebundener Miniporttreiber die NdisMIndicateReceiveNetBufferLists-Funktion . Ein Aufruf von ProtocolReceiveNetBufferLists kann auch als Ergebnis eines Loopbacks erfolgen.

Wenn das NDIS_RECEIVE_FLAGS_RESOURCES-Flag im ReceiveFlags-Parameter nicht festgelegt ist, behält der Protokolltreiber den Besitz der NET_BUFFER_LIST Strukturen, bis er die NdisReturnNetBufferLists-Funktion .

Wenn NDIS das NDIS_RECEIVE_FLAGS_RESOURCES-Flag festlegt, kann der Protokolltreiber die NET_BUFFER_LIST Struktur und die zugeordneten Ressourcen nicht beibehalten. Der Satz NDIS_RECEIVE_FLAGS_RESOURCES Flags gibt an, dass ein zugrunde liegender Treiber für Empfangsressourcen knapp wird. In diesem Fall sollte die ProtocolReceiveNetBufferLists-Funktion die empfangenen Daten in den protokollseitig zugewiesenen Speicher kopieren und so schnell wie möglich zurückgeben.

Hinweis Wenn das NDIS_RECEIVE_FLAGS_RESOURCES-Flag festgelegt ist, muss der Protokolltreiber den ursprünglichen Satz von NET_BUFFER_LIST Strukturen in der verknüpften Liste beibehalten. Wenn dieses Flag beispielsweise festgelegt ist, kann der Treiber die Strukturen verarbeiten und sie einzeln im Stapel angeben, aber bevor die Funktion zurückgibt, muss sie die ursprüngliche verknüpfte Liste wiederherstellen.

Auf einem Multiprozessorsystem kann diese Funktion auf mehreren Prozessoren gleichzeitig ausgeführt werden. Wenden Sie den Schutz (z. B. Mithilfe von Spinsperren) auf kritische Datenstrukturen an, auf die von ProtocolReceiveNetBufferLists zugegriffen wird.

NDIS ruft ProtocolReceiveNetBufferLists unter IRQL<= DISPATCH_LEVEL auf.

Beispiele

Um eine ProtocolReceiveNetBufferLists-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 ProtocolReceiveNetBufferLists-Funktion mit dem Namen "MyReceiveNetBufferLists" zu definieren, verwenden Sie den typ PROTOCOL_RECEIVE_NET_BUFFER_LISTS , wie in diesem Codebeispiel gezeigt:

PROTOCOL_RECEIVE_NET_BUFFER_LISTS MyReceiveNetBufferLists;

Implementieren Sie dann Ihre Funktion wie folgt:

_Use_decl_annotations_
VOID
 MyReceiveNetBufferLists(
    NDIS_HANDLE  ProtocolBindingContext,
    PNET_BUFFER_LIST  NetBufferLists,
    NDIS_PORT_NUMBER  PortNumber,
    ULONG  NumberOfNetBufferLists,
    ULONG ReceiveFlags
    )
  {...}

Der PROTOCOL_RECEIVE_NET_BUFFER_LISTS 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 PROTOCOL_RECEIVE_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 (einschließlich Ndis.h)
IRQL	<= DISPATCH_LEVEL