NET_BUFFER_LIST-Struktur (ndis/nbl.h)

Artikel
08/07/2023

Die NET_BUFFER_LIST-Struktur gibt eine verknüpfte Liste von NET_BUFFER-Strukturen an.

Syntax

typedef struct _NET_BUFFER_LIST {
  union {
    struct {
      NET_BUFFER_LIST *Next;
      NET_BUFFER      *FirstNetBuffer;
    };
    SLIST_HEADER           Link;
    NET_BUFFER_LIST_HEADER NetBufferListHeader;
  };
  NET_BUFFER_LIST_CONTEXT *Context;
  NET_BUFFER_LIST         *ParentNetBufferList;
  NDIS_HANDLE             NdisPoolHandle;
  PVOID                   NdisReserved[2];
  PVOID                   ProtocolReserved[4];
  PVOID                   MiniportReserved[2];
  PVOID                   Scratch;
  NDIS_HANDLE             SourceHandle;
  ULONG                   NblFlags;
  LONG                    ChildRefCount;
  ULONG                   Flags;
  union {
    NDIS_STATUS Status;
    ULONG       NdisReserved2;
  };
  PVOID                   NetBufferListInfo[MaxNetBufferListInfo];
} NET_BUFFER_LIST, *PNET_BUFFER_LIST;

Member

Next

Die nächste NET_BUFFER_LIST Struktur in der Kette.

Treiber sollten nicht direkt auf dieses Element zugreifen. Stattdessen sollte das Makro NET_BUFFER_LIST_NEXT_NBL aufgerufen werden.

FirstNetBuffer

Die erste NET_BUFFER zu diesem NET_BUFFER_LIST.

Treiber sollten nicht direkt auf dieses Element zugreifen. Stattdessen sollte das Makro NET_BUFFER_LIST_FIRST_NB aufgerufen werden.

Link

Reserviert für NDIS.

NetBufferListHeader

Eine NET_BUFFER_LIST_HEADER-Struktur .

Context

Ein Zeiger auf eine NET_BUFFER_LIST_CONTEXT-Struktur . Protokoll- und Miniporttreiber verwenden diese Struktur, um Informationen zur NET_BUFFER_LIST-Struktur zu speichern. Die in der NET_BUFFER_LIST_CONTEXT-Struktur gespeicherten Informationen sind für NDIS und andere Treiber im Stapel undurchsichtig.

Verwenden Sie die folgenden Funktionen und Makros, um auf Daten in der NET_BUFFER_LIST_CONTEXT-Struktur zuzugreifen:

NdisAllocateNetBufferListContext NdisFreeNetBufferListContext NET_BUFFER_LIST_CONTEXT_DATA_START NET_BUFFER_LIST_CONTEXT_DATA_SIZE

ParentNetBufferList

Wenn diese NET_BUFFER_LIST-Struktur ein Klon einer anderen NET_BUFFER_LIST-Struktur ist, gibt dieses Element einen Zeiger auf die übergeordnete NET_BUFFER_LIST-Struktur an. Andernfalls ist dieser Parameter NULL. Ein Treiber verwendet die NdisAllocateCloneNetBufferList-Funktion zum Erstellen eines Klons.

NdisPoolHandle

Ein Poolhandle, das den NET_BUFFER_LIST Pool identifiziert, aus dem die NET_BUFFER_LIST-Struktur zugeordnet wurde.

NdisReserved[2]

Reserviert für die Verwendung durch NDIS.

ProtocolReserved[4]

Reserviert für die Verwendung durch Protokolltreiber.

MiniportReserved[2]

Reserviert für die Verwendung durch Miniporttreiber.

Scratch

Daten, die vom aktuellen Besitzer der NET_BUFFER_LIST-Struktur definiert werden. Der aktuelle Besitzer, entweder NDIS oder ein NDIS-Treiber, kann diesen Member für seine eigenen Zwecke verwenden. Wenn die NET_BUFFER_LIST-Struktur anfänglich zugeordnet wird, ist dieser Member NULL. Nachdem der aktuelle Besitzer den Besitz aufgegeben hat, kann NDIS oder ein anderer Treiber dieses Member überschreiben.

SourceHandle

Ein Handle, das NDIS dem Treiber in einem Bindungs- oder Anfügenvorgang mithilfe einer der folgenden vom Treiber bereitgestellten Routinen bereitgestellt hat:

NDIS verwendet SourceHandle , um die NET_BUFFER_LIST-Struktur an den Treiber zurückzugeben, der die NET_BUFFER_LIST-Struktur gesendet hat.

NblFlags

Dieser Member enthält Flags, die mit einer bitweisen OR-Operation kombiniert werden können.

Verwenden Sie die Makros NdisTestNblFlag, NdisTestNblFlags, NdisSetNblFlag und NdisClearNblFlag , um auf die Flags zuzugreifen.

Zwischentreiber und Filtertreiber können die folgenden Flags festlegen, wenn sie keine Daten ändern, die einem NET_BUFFER_LIST zugeordnet sind. Wenn sich die Daten beispielsweise nicht geändert haben, kann NDIS die ursprünglichen Informationen wiederverwenden, aus denen die NET_BUFFER_LIST erstellt wurde.

NDIS_NBL_FLAGS_SEND_READ_ONLY

Wenn festgelegt, sind die NET_BUFFER_LIST-Struktur und die zugehörigen Daten schreibgeschützt für Sendevorgänge.

NDIS_NBL_FLAGS_RECV_READ_ONLY

Wenn festgelegt, sind die NET_BUFFER_LIST-Struktur und die zugehörigen Daten für Empfangsvorgänge schreibgeschützt.

Ein Treiber kann die folgenden Flags auch dann festlegen, wenn er den zugeordneten Ethernet-Frame nicht teilt:

NDIS_NBL_FLAGS_IS_IPV4

Alle Ethernet-Frames in dieser NET_BUFFER_LIST-Struktur sind IPv4-Frames. Wenn dieses Flag festgelegt ist, darf der Anbieter für die Aufteilung von Headerdaten das flag NDIS_NBL_FLAGS_IS_IPV6 nicht festlegen.

NDIS_NBL_FLAGS_IS_IPV6

Alle Ethernet-Frames in dieser NET_BUFFER_LIST-Struktur sind IPv6-Frames. Wenn dieses Flag festgelegt ist, darf der Anbieter für die Aufteilung von Headerdaten das flag NDIS_NBL_FLAGS_IS_IPV4 nicht festlegen.

NDIS_NBL_FLAGS_IS_TCP

Alle Ethernet-Frames in dieser NET_BUFFER_LIST-Struktur sind TCP-Frames. Wenn dieses Flag festgelegt ist, darf der Anbieter für die Aufteilung von Headerdaten nicht das NDIS_NBL_FLAGS_IS_UDP-Flag festlegen, und der Anbieter muss das NDIS_NBL_FLAGS_IS_IPV4-Flag oder das NDIS_NBL_FLAGS_IS_IPV6-Flag festlegen.

NDIS_NBL_FLAGS_IS_UDP

Alle Ethernet-Frames in dieser NET_BUFFER_LIST-Struktur sind UDP-Frames. Wenn dieses Flag festgelegt ist, darf der Anbieter für die Aufteilung von Headerdaten nicht das NDIS_NBL_FLAGS_IS_TCP-Flag festlegen, und der Anbieter muss das NDIS_NBL_FLAGS_IS_IPV4-Flag oder das NDIS_NBL_FLAGS_IS_IPV6-Flag festlegen.

NDIS_NBL_FLAGS_IS_LOOPBACK_PACKET

Alle Pakete, die dieser NET_BUFFER_LIST-Struktur zugeordnet sind, sind Loopbackpakete.

Wenn der Header-Daten-Split-Anbieter den zugeordneten Ethernet-Frame nicht aufteilt, muss der Miniporttreiber die NET_BUFFER_LIST-Struktur mit den folgenden Flags angeben:

NDIS_NBL_FLAGS_HD_SPLIT

Der Header und die Daten werden in alle Ethernet-Frames aufgeteilt, die dieser NET_BUFFER_LIST-Struktur zugeordnet sind.

NDIS_NBL_FLAGS_SPLIT_AT_UPPER_LAYER_PROTOCOL_HEADER

Alle Ethernet-Frames in diesem NET_BUFFER_LIST werden am Anfang des Protokollheaders der oberen Ebene aufgeteilt. Wenn dieses Flag festgelegt ist, muss der Anbieter für die Aufteilung von Headerdaten das flag NDIS_NBL_FLAGS_IS_IPV4 oder das flag NDIS_NBL_FLAGS_IS_IPV6 festlegen. Außerdem kann der Anbieter das NDIS_NBL_FLAGS_IS_TCP-Flag oder das NDIS_NBL_FLAGS_IS_UDP-Flag festlegen, aber der Anbieter darf das NDIS_NBL_FLAGS_SPLIT_AT_UPPER_LAYER_PROTOCOL_PAYLOAD-Flag nicht festlegen.

NDIS_NBL_FLAGS_SPLIT_AT_UPPER_LAYER_PROTOCOL_PAYLOAD

Alle Ethernet-Frames in dieser NET_BUFFER_LIST-Struktur werden am Anfang der TCP- oder UDP-Nutzlast aufgeteilt. Wenn dieses Flag festgelegt ist, muss der Anbieter für die Aufteilung von Headerdaten das flag NDIS_NBL_FLAGS_IS_IPV4 oder das flag NDIS_NBL_FLAGS_IS_IPV6 festlegen. Außerdem muss der Anbieter das NDIS_NBL_FLAGS_IS_TCP-Flag oder das NDIS_NBL_FLAGS_IS_UDP-Flag festlegen, aber der Anbieter darf das NDIS_NBL_FLAGS_SPLIT_AT_UPPER_LAYER_PROTOCOL_HEADER-Flag nicht festlegen.

ChildRefCount

Wenn diese NET_BUFFER_LIST-Struktur über Klone verfügt (ist ein übergeordnetes Element), gibt dieses Element die Anzahl der ausstehenden Klone an. Andernfalls ist dieser Member null.

Flags

Attribute der NET_BUFFER_LIST-Struktur. Die folgenden Definitionen geben eine Bitmaske für eine Reihe von Flags an:

NBL_FLAGS_PROTOCOL_RESERVED

Dieser Satz ist für Protokolltreiber reserviert.

Hinweis Ab NDIS 6.30 stehen zwei zusätzliche Bits für die Protokollverwendung zur Verfügung: 0x00000003. Ein NDIS 6.30-Protokoll kann diese Bits nur verwenden, wenn NdisGetVersion einen Wert zurückgibt, der größer oder gleich NDIS_RUNTIME_VERSION_630 ist. Protokolle dürfen diese Bits nicht in früheren Versionen von NDIS verwenden, da sie vor Version 6.30 von NDIS intern verwendet werden.

NBL_FLAGS_MINIPORT_RESERVED

Dieser Satz ist für Miniporttreiber reserviert.

NBL_FLAGS_SCRATCH

Der aktuelle Besitzer der NET_BUFFER_LIST-Struktur, entweder NDIS oder ein NDIS-Treiber, kann diesen Satz verwenden. Wenn der aktuelle Besitzer den Besitz aufgibt, kann NDIS oder ein anderer Treiber diese Flags überschreiben.

NBL_FLAGS_NDIS_RESERVED

Dieser Satz ist für NDIS reserviert.

Status

Der endgültige Abschluss status eines Netzwerkdatenvorgangs für diese NET_BUFFER_LIST-Struktur. Miniporttreiber schreiben diesen Wert vor dem Aufrufen der NdisMSendNetBufferListsComplete-Funktion . Miniport-Treiber geben einen der folgenden Werte an:

NDIS_STATUS_SUCCESS

Alle Netzwerkdaten, die von NET_BUFFER Strukturen beschrieben werden, die dieser NET_BUFFER_LIST-Struktur zugeordnet sind, wurden erfolgreich über das Netzwerk übertragen.

NDIS_STATUS_INVALID_LENGTH

Die Größe der Daten in einigen NET_BUFFER Strukturen, die dieser NET_BUFFER_LIST-Struktur zugeordnet sind, war für die zugrunde liegende Netzwerkkarte zu groß.

NDIS_STATUS_RESOURCES

Die Sendeanforderung für diese NET_BUFFER_LIST-Struktur ist aufgrund unzureichender Ressourcen fehlgeschlagen.

NDIS_STATUS_FAILURE

Diese Sendeanforderung für diese NET_BUFFER_LIST Struktur ist aus einem anderen Grund als den in den vorherigen drei Werten angegebenen grund fehlgeschlagen.

NDIS_STATUS_SEND_ABORTED

NDIS hat die MiniportCancelSend-Funktion aufgerufen, um den Sendevorgang für diese NET_BUFFER_LIST-Struktur abzubrechen.

NDIS_STATUS_RESET_IN_PROGRESS

Der Miniporttreiber hat die Sendeanforderung aufgrund eines Zurücksetzens abgebrochen.

NDIS_STATUS_PAUSED

Wenn ein Treiber Sendeanforderungen ablehnen muss, weil er angehalten wird, legt er die vollständige status in jedem betroffenen NET_BUFFER_LIST auf NDIS_STATUS_PAUSED fest.

NdisReserved2

Reserviert für NDIS.

NetBufferListInfo[MaxNetBufferListInfo]

Ein Array von Werten, die Informationen enthalten, die allen NET_BUFFER Strukturen in der Liste gemeinsam sind. Diese Informationen werden häufig als Out-of-Band-Daten (OOB) bezeichnet.

Verwenden Sie die Schaltfläche NDIS_NET_BUFFER_LIST_INFO Enumerationswerte mit dem NET_BUFFER_LIST_INFO Makro, um Werte im NetBufferListInfo-Array festzulegen und abzurufen.

Hinweise

NDIS-Treiber können eine der folgenden Funktionen aufrufen, um eine NET_BUFFER_LIST Struktur zuzuordnen und zu initialisieren:

NdisAllocateNetBufferList

NdisAllocateNetBufferAndNetBufferList NdisAllocateCloneNetBufferList NdisAllocateFragmentNetBufferList NdisAllocateReassembledNetBufferList

Alle NET_BUFFER Strukturen, die einer NET_BUFFER_LIST-Struktur zugeordnet sind, verfügen über die Attribute, die von den Elementen NetBufferListInfo und Context angegeben werden.

Wenn ein Treiber die Funktion NdisSendNetBufferLists oder NdisFSendNetBufferLists aufruft , verliert er den Besitz von:

Die angegebene NET_BUFFER_LIST-Struktur.
Die angefügten NET_BUFFER Strukturen und MDLs.
Alle angefügten NDIS_REQUEST_CONTROLs.
Alle NetBufferListInfo-Daten , die der NET_BUFFER_LIST-Struktur zugeordnet sind.

Der aktuelle Besitzer einer Liste von NET_BUFFER_LIST-Strukturen kann eine NET_BUFFER_LIST-Struktur in eine andere Liste verschieben. Alle NET_BUFFER Strukturen, die einer NET_BUFFER_LIST-Struktur zugeordnet sind, sollten jedoch bei der gleichen NET_BUFFER_LIST-Struktur bleiben. Nur der Treiber, der die NET_BUFFER-Strukturen erstellt hat, kann sie in eine andere NET_BUFFER_LIST-Struktur verschieben. Der aktuelle Besitzer kann das Nächste Element einer NET_BUFFER Struktur nicht ändern.

Eine Liste mit NET_BUFFER_LIST Strukturen ist eine einfache, singly verknüpfte und NULL-beendete Liste. Um eine NET_BUFFER_LIST-Struktur in eine andere Liste zu verschieben, führen Sie entsprechende Aktualisierungen für die Nächsten Member in der Quell- und Zielliste durch.

Verwenden Sie die folgenden Makros und Funktionen, um auf Elemente der NET_BUFFER_LIST-Struktur zuzugreifen:

NET_BUFFER_LIST_NEXT_NBL

NET_BUFFER_LIST_FIRST_NB

NET_BUFFER_LIST_FLAGS

NET_BUFFER_LIST_MINIPORT_RESERVED NET_BUFFER_LIST_CONTEXT_DATA_START NET_BUFFER_LIST_CONTEXT_DATA_SIZE

NET_BUFFER_LIST_INFO

NET_BUFFER_LIST_STATUS

NET_BUFFER_LIST_PROTOCOL_RESERVED NdisGetPoolFromNetBufferList

Weitere Informationen zur Verwendung von Netzpuffern finden Sie unter NET_BUFFER-Architektur.