Windows Driver Kit: Network Devices and Protocols
NET_BUFFER_LIST
The NET_BUFFER_LIST structure specifies a linked list of NET_BUFFER structures.
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
- NetBufferListHeader
- A NET_BUFFER_LIST_HEADER structure.
- Context
- A pointer to a NET_BUFFER_LIST_CONTEXT structure. Protocol and miniport drivers use this structure to store information about the NET_BUFFER_LIST structure. Information stored in the NET_BUFFER_LIST_CONTEXT structure is opaque to NDIS and other drivers in the stack.
- Use the following functions and macros to access data in the NET_BUFFER_LIST_CONTEXT structure:
- NdisAllocateNetBufferListContext
NdisFreeNetBufferListContext
NET_BUFFER_LIST_CONTEXT_DATA_START
NET_BUFFER_LIST_CONTEXT_DATA_SIZE
- 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 initially 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
- 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 bit mask 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 final completion status of a network data operation on this NET_BUFFER_LIST structure. Miniport drivers write this value before calling 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_LENGTH
- The size of the data in some NET_BUFFER structures associated with this NET_BUFFER_LIST structure was too large for the underlying NIC.
- NDIS_STATUS_RESOURCES
- The send request for this NET_BUFFER_LIST structure failed due to insufficient resources.
- NDIS_STATUS_FAILURE
- This send request for this NET_BUFFER_LIST structure failed due to some reason other than those stated in the previous three values.
- NDIS_STATUS_SEND_ABORTED
- NDIS called the MiniportCancelSend function to cancel the send operation for this NET_BUFFER_LIST structure.
- NDIS_STATUS_RESET_IN_PROGRESS
- The miniport driver aborted the send request due to 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 containing 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.
Comments
NDIS drivers can call any of the following functions to allocate and initialize a NET_BUFFER_LIST structure:
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 NdisFSendNetBufferListsfunction, 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:
For more information on how to use net buffers, see NET_BUFFER Architecture.
Requirements
Versions: Supported for NDIS 6.1 drivers in Windows Server 2008. (Added flags and macros to the NblFlags member.) Supported for NDIS 6.0 drivers in and Windows Vista.
Headers: Declared in Ndis.h. Include Ndis.h.
See Also
NDIS_NET_BUFFER_LIST_INFO, NdisAllocateCloneNetBufferList, NdisAllocateFragmentNetBufferList, NdisAllocateNetBufferList, NdisAllocateNetBufferAndNetBufferList, NdisAllocateReassembledNetBufferList, NdisCancelSendNetBufferLists,
NdisClearNblFlag,
NdisFreeNetBufferListContext, NdisGeneratePartialCancelId, NdisGetPoolFromNetBufferList, NdisAllocateNetBufferListContext, NdisSendNetBufferLists,
NdisSetNblFlag, NdisTestNblFlag, 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