PROTOCOL_CO_RECEIVE_NET_BUFFER_LISTS Rückruffunktion (ndis.h)

Artikel
02/29/2024

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

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

Syntax

PROTOCOL_CO_RECEIVE_NET_BUFFER_LISTS ProtocolCoReceiveNetBufferLists;

void ProtocolCoReceiveNetBufferLists(
  [in] NDIS_HANDLE ProtocolBindingContext,
  [in] NDIS_HANDLE ProtocolVcContext,
  [in] PNET_BUFFER_LIST NetBufferLists,
  [in] ULONG NumberOfNetBufferLists,
  [in] ULONG ReceiveFlags
)
{...}

Parameter

[in] ProtocolBindingContext

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

[in] ProtocolVcContext

Ein Handle für einen vom Protokolltreiber zugewiesenen Kontextbereich, in dem dieser Treiber die Laufzeitstatusinformationen pro virtueller Verbindung (VC) verwaltet. Ein Client oder ein eigenständiger Aufruf-Manager hat dieses Handle entweder beim Aufrufen der NdisCoCreateVc-Funktion oder über seine ProtocolCoCreateVc-Funktion bereitgestellt.

[in] NetBufferLists

Eine verknüpfte Liste von NET_BUFFER_LIST Strukturen, die vom zugrunde liegenden Treiber zugewiesen wurden. Jede NET_BUFFER_LIST-Struktur ist in der Regel einer NET_BUFFER-Struktur zugeordnet.

[in] NumberOfNetBufferLists

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

[in] ReceiveFlags

Flags, die Attribute für den Sendevorgang definieren. Die Flags können mit einer bitweisen OR-Operation kombiniert werden. Um alle Flags zu löschen, legen Sie diesen Parameter auf 0 (null) fest. ProtocolCoReceiveNetBufferLists unterstützt die folgenden Flags:

NDIS_RECEIVE_FLAGS_DISPATCH_LEVEL

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

NDIS_RECEIVE_FLAGS_RESOURCES

NDIS gibt den Besitz der NET_BUFFER_LIST-Strukturen und aller angefügten NET_BUFFER-Strukturen zurück, unmittelbar nach dem Aufruf von ProtocolCoReceiveNetBufferLists .

Rückgabewert

Keine

Bemerkungen

Die ProtocolCoReceiveNetBufferLists-Funktion ist für CoNDIS-Protokolltreiber erforderlich. NDIS ruft ProtocolCoReceiveNetBufferLists auf, nachdem ein gebundener Miniporttreiber den aufruft. NdisMCoIndicateReceiveNetBufferLists-Funktion . Ein Aufruf von ProtocolCoReceiveNetBufferLists kann auch als Ergebnis eines Loopbacks erfolgen.

Wenn das NDIS_RECEIVE_FLAGS_RESOURCES-Flag im CoReceiveFlags-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. NDIS_RECEIVE_FLAGS_RESOURCES gibt an, dass ein zugrunde liegender Treiber über geringe Empfangsressourcen verfügt. In diesem Fall sollte die ProtocolCoReceiveNetBufferLists-Funktion die empfangenen Daten in den vom Protokoll zugewiesenen Speicher kopieren und so schnell wie möglich zurückgeben.

Auf einem Multiprozessorsystem kann ProtocolCoReceiveNetBufferLists gleichzeitig auf mehreren Prozessoren ausgeführt werden. Wenden Sie in dieser Situation schutz (z. B. Spinsperren) auf kritische Datenstrukturen an, auf die ProtocolCoReceiveNetBufferLists zugreift.

NDIS ruft ProtocolCoReceiveNetBufferLists unter IRQL<= DISPATCH_LEVEL auf.

Beispiele

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

PROTOCOL_CO_RECEIVE_NET_BUFFER_LISTS MyCoReceiveNetBufferLists;

Implementieren Sie dann Ihre Funktion wie folgt:

_Use_decl_annotations_
VOID
 MyCoReceiveNetBufferLists(
    NDIS_HANDLE  ProtocolBindingContext,
    NDIS_HANDLE  ProtocolVcContext,
    INPNET_BUFFER_LIST  NetBufferLists,
    ULONG  NumberOfNetBufferLists,
    ULONG  ReceiveFlags
    )
  {...}

Der PROTOCOL_CO_RECEIVE_NET_BUFFER_LISTS 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 PROTOCOL_CO_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 (include Ndis.h)
IRQL	<= DISPATCH_LEVEL