Share via


NET_BUFFER_LIST (Compact 7)

3/12/2014

The NET_BUFFER_LIST structure specifies a linked list of NET_BUFFER structures.

Syntax

typedef struct _NET_BUFFER_LIST {
  NET_BUFFER_LIST_HEADER  NetBufferListHeader;
  PNET_BUFFER_LIST_CONTEXT  Context;
  PNET_BUFFER_LIST  ParentNetBufferList;
  NDIS_HANDLE  NdisPoolHandle;
  DECLSPEC_ALIGN(MEMORY_ALLOCATION_ALIGNMENT)PVOID  NdisReserved[2];
  DECLSPEC_ALIGN(MEMORY_ALLOCATION_ALIGNMENT)PVOID  ProtocolReserved[4];
  DECLSPEC_ALIGN(MEMORY_ALLOCATION_ALIGNMENT)PVOID  MiniportReserved[2];
  PVOID  Scratch;
  NDIS_HANDLE  SourceHandle;
  ULONG  NblFlags;
  LONG  ChildRefCount;
  ULONG  Flags;
  NDIS_STATUS  Status;
  PVOID  NetBufferListInfo[MaxNetBufferListInfo];
} NET_BUFFER_LIST, *PNET_BUFFER_LIST;

Members

  • ParentNetBufferList
    If this NET_BUFFER_LIST structure is a clone of another NET_BUFFER_LIST structure, this member specifies a pointer to the parent NET_BUFFER_LIST structure. Otherwise, this parameter is NULL. A driver uses the NdisAllocateCloneNetBufferList function to create a clone.
  • NdisPoolHandle
    A pool handle that identifies the NET_BUFFER_LIST pool from which the NET_BUFFER_LIST structure was allocated.
  • NdisReserved
    Reserved for use by NDIS.
  • ProtocolReserved
    Reserved for use by protocol drivers.
  • MiniportReserved
    Reserved for use by miniport drivers.
  • Scratch
    Data that is defined by the current owner of the NET_BUFFER_LIST structure. The current owner, either NDIS or an NDIS driver, can use this member for their own purposes. When the NET_BUFFER_LIST structure is first allocated, this member is NULL. After the current owner relinquishes ownership, NDIS or another driver can overwrite this member.
  • SourceHandle
    A handle that identifies the driver that allocated the NET_BUFFER_LIST structure. NDIS uses SourceHandle to return the NET_BUFFER_LIST structure to that driver.
  • NblFlags
    This member contains flags that can be combined with a bitwise OR operation.

    Use the NdisTestNblFlag, NdisTestNblFlags, NdisSetNblFlag, and NdisClearNblFlag macros to access the flags.

    Intermediate drivers and filter drivers can set the following flags if they do not modify data that is associated with a NET_BUFFER_LIST. For example, if the data did not change, NDIS might reuse the original information from which the NET_BUFFER_LIST was created:

    • NDIS_NBL_FLAGS_SEND_READ_ONLY
      If set, the NET_BUFFER_LIST structure and its data are read-only for send operations.
    • NDIS_NBL_FLAGS_RECV_READ_ONLY
      If set, the NET_BUFFER_LIST structure and its data are read-only for receive operations.
    • A driver can set the following flags even if it does not split the associated Ethernet frame:

      • NDIS_NBL_FLAGS_IS_IPV4
        All the Ethernet frames in this NET_BUFFER_LIST structure are IPv4 frames. If this flag is set, the header-data split provider must not set the NDIS_NBL_FLAGS_IS_IPV6 flag.
      • NDIS_NBL_FLAGS_IS_IPV6
        All the Ethernet frames in this NET_BUFFER_LIST structure are IPv6 frames. If this flag is set, the header-data split provider must not set the NDIS_NBL_FLAGS_IS_IPV4 flag.
      • NDIS_NBL_FLAGS_IS_TCP
        All the Ethernet frames in this NET_BUFFER_LIST structure are TCP frames. If this flag is set, the header-data split provider must not set the NDIS_NBL_FLAGS_IS_UDP flag, and the provider must set the NDIS_NBL_FLAGS_IS_IPV4 flag or the NDIS_NBL_FLAGS_IS_IPV6 flag.
      • NDIS_NBL_FLAGS_IS_UDP
        All the Ethernet frames in this NET_BUFFER_LIST structure are UDP frames. If this flag is set, the header-data split provider must not set the NDIS_NBL_FLAGS_IS_TCP flag, and the provider must set the NDIS_NBL_FLAGS_IS_IPV4 flag or the NDIS_NBL_FLAGS_IS_IPV6 flag.
      • NDIS_NBL_FLAGS_IS_LOOPBACK_PACKET
        All the packets that are associated with this NET_BUFFER_LIST structure are loopback packets.

    If the header-data split provider does not split the associated Ethernet frame, the miniport driver must indicate the NET_BUFFER_LIST structure with the following flags cleared:

    • NDIS_NBL_FLAGS_HD_SPLIT
      The header and data are split in all the Ethernet frames that are associated with this NET_BUFFER_LIST structure.
    • NDIS_NBL_FLAGS_SPLIT_AT_UPPER_LAYER_PROTOCOL_HEADER
      All the Ethernet frames in this NET_BUFFER_LIST are split at the beginning of the upper layer protocol header. If this flag is set, the header-data split provider must set the NDIS_NBL_FLAGS_IS_IPV4 flag or the NDIS_NBL_FLAGS_IS_IPV6 flag. Also, the provider can set the NDIS_NBL_FLAGS_IS_TCP flag or the NDIS_NBL_FLAGS_IS_UDP flag, but the provider must not set the NDIS_NBL_FLAGS_SPLIT_AT_UPPER_LAYER_PROTOCOL_PAYLOAD flag.
    • NDIS_NBL_FLAGS_SPLIT_AT_UPPER_LAYER_PROTOCOL_PAYLOAD
      All the Ethernet frames in this NET_BUFFER_LIST structure are split at the beginning of the TCP or UDP payload. If this flag is set, the header-data split provider must set the NDIS_NBL_FLAGS_IS_IPV4 flag or the NDIS_NBL_FLAGS_IS_IPV6 flag. Also, the provider must set the NDIS_NBL_FLAGS_IS_TCP flag or the NDIS_NBL_FLAGS_IS_UDP flag, but the provider must not set the NDIS_NBL_FLAGS_SPLIT_AT_UPPER_LAYER_PROTOCOL_HEADER flag.
  • ChildRefCount
    If this NET_BUFFER_LIST structure has clones (is a parent), this member specifies the number of outstanding clones. Otherwise, this member is zero.
  • Flags
    Attributes of the NET_BUFFER_LIST structure. The following definitions specify a bitmask for a set of flags:

    • NBL_FLAGS_PROTOCOL_RESERVED
      This set is reserved for protocol drivers.
    • NBL_FLAGS_MINIPORT_RESERVED
      This set is reserved for miniport drivers.
    • NBL_FLAGS_SCRATCH
      The current owner of the NET_BUFFER_LIST structure, either NDIS or an NDIS driver, can use this set. When the current owner relinquishes ownership, NDIS or another driver can overwrite these flags.
    • NBL_FLAGS_NDIS_RESERVED
      This set is reserved for NDIS.
  • Status
    The completion status of a network data operation on this NET_BUFFER_LIST structure. Miniport drivers write this value before it calls the NdisMSendNetBufferListsComplete function. Miniport drivers specify one of the following values:

    • NDIS_STATUS_SUCCESS
      All the network data described by NET_BUFFER structures associated with this NET_BUFFER_LIST structure was successfully transmitted over the network.
    • NDIS_STATUS_INVALID_NET_BUFFER
      The size of the data in some NET_BUFFER structures associated with this NET_BUFFER_LIST structure was too large for the underlying network adapter.
    • NDIS_STATUS_RESOURCES
      The send request for this NET_BUFFER_LIST structure failed because of insufficient resources.
    • NDIS_STATUS_FAILURE
      This send request for this NET_BUFFER_LIST structure failed because of some reason other than those stated in the previous three values.
    • NDIS_STATUS_SEND_ABORTED
      NDIS called the MiniportCancelSendfunction to cancel the send operation for this NET_BUFFER_LIST structure.
    • NDIS_STATUS_RESET_IN_PROGRESS
      The miniport driver aborted the send request because of a reset.
    • NDIS_STATUS_PAUSED
      If a driver must reject send requests because it is paused, it sets the complete status in each affected NET_BUFFER_LIST to NDIS_STATUS_PAUSED.
  • NetBufferListInfo
    An array of values that contains information that is common to all NET_BUFFER structures in the list.

    Use the NDIS_NET_BUFFER_LIST_INFO enumeration values with the NET_BUFFER_LIST_INFO macro to set and get values in the NetBufferListInfo array.

Remarks

NDIS drivers can call any of the following functions to allocate and initialize a NET_BUFFER_LIST structure:

NdisAllocateNetBufferList

NdisAllocateNetBufferAndNetBufferList

NdisAllocateCloneNetBufferList

NdisAllocateFragmentNetBufferList

NdisAllocateReassembledNetBufferList

All NET_BUFFER structures associated with a NET_BUFFER_LIST structure have the attributes that are specified by the NetBufferListInfo and Context members.

When a driver calls the NdisSendNetBufferLists or NdisFSendNetBufferLists, it looses ownership of:

  • The specified NET_BUFFER_LIST structure.
  • The attached NET_BUFFER structures and MDLs.
  • Any attached NDIS_REQUEST_CONTROLs.
  • All NetBufferListInfo data that is associated with the NET_BUFFER_LIST structure.

The current owner of a list of NET_BUFFER_LIST structures can move a NET_BUFFER_LIST structure to another list. However, all NET_BUFFER structures associated with a NET_BUFFER_LIST structure should stay with the same NET_BUFFER_LIST structure. Only the driver that created the NET_BUFFER structures can move them to a different NET_BUFFER_LIST structure. The current owner cannot modify a NET_BUFFER structure's Next member.

A list of NET_BUFFER_LIST structures is a simple singly linked and NULL-terminated list. To move a NET_BUFFER_LIST structure to a different list, make appropriate updates to the Next members in both the source and destination lists.

To access members of the NET_BUFFER_LIST structure, use the following macros and functions:

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

Important For important legal information about TCP chimney offload, see Legal Information.

Requirements

Header

ndis.h

See Also

Reference

NDIS NET_BUFFER Structures
NDIS_NET_BUFFER_LIST_INFO
NdisAllocateCloneNetBufferList
NdisAllocateFragmentNetBufferList
NdisAllocateNetBufferList
NdisAllocateNetBufferAndNetBufferList
NdisAllocateReassembledNetBufferList
NdisCancelSendNetBufferLists
NdisClearNblFlag
NdisFreeNetBufferListContext
NdisGeneratePartialCancelId
NdisGetPoolFromNetBufferList
NdisAllocateNetBufferListContext
NdisSendNetBufferLists
NdisSetNblFlag
NdisTestNblFlags
NET_BUFFER
NET_BUFFER_LIST_CONTEXT
NET_BUFFER_LIST_CONTEXT_DATA_SIZE
NET_BUFFER_LIST_CONTEXT_DATA_START
NET_BUFFER_LIST_FIRST_NB
NET_BUFFER_LIST_FLAGS
NET_BUFFER_LIST_HEADER
NET_BUFFER_LIST_INFO
NET_BUFFER_LIST_MINIPORT_RESERVED
NET_BUFFER_LIST_NEXT_NBL
NET_BUFFER_LIST_PROTOCOL_RESERVED
NET_BUFFER_LIST_STATUS
NDIS TCP/IP Offload Structures