NET_BUFFER_LIST - NtDoc
Native API online documentation, based on the System Informer
(formerly Process Hacker) phnt
headers
// nbl.h
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;
View the official Windows Driver Kit DDI referenceNo description available.
The NET_BUFFER_LIST structure specifies a linked list of NET_BUFFER structures.
NextThe next NET_BUFFER_LIST structure in the chain.
Drivers should not access this member directly. Instead, they should call the NET_BUFFER_LIST_NEXT_NBL macro.
FirstNetBufferThe first NET_BUFFER on this NET_BUFFER_LIST.
Drivers should not access this member directly. Instead, they should call the NET_BUFFER_LIST_FIRST_NB macro.
LinkReserved for NDIS.
NetBufferListHeaderA NET_BUFFER_LIST_HEADER structure.
ContextA 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
NET_BUFFER_LIST_CONTEXT_DATA_START
NET_BUFFER_LIST_CONTEXT_DATA_SIZE
ParentNetBufferListIf 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.
NdisPoolHandleA pool handle that identifies the NET_BUFFER_LIST pool from which the NET_BUFFER_LIST structure was allocated.
NdisReservedReserved for use by NDIS.
ProtocolReservedReserved for use by protocol drivers.
MiniportReservedReserved for use by miniport drivers.
ScratchData 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.
SourceHandleA handle that NDIS provided to the driver in a binding or attaching operation by using one of the following driver-supplied routines:
NDIS uses SourceHandle to return the NET_BUFFER_LIST structure to the driver that sent the NET_BUFFER_LIST structure.
NblFlagsThis 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.
If set, the NET_BUFFER_LIST structure and its data are read-only for send operations.
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:
All of 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.
All of 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.
All of 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.
All of 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.
All of 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:
The header and data are split in all of the Ethernet frames that are associated with this NET_BUFFER_LIST structure.
All of 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.
All of 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.
ChildRefCountIf this NET_BUFFER_LIST structure has clones (is a parent), this member specifies the number of outstanding clones. Otherwise, this member is zero.
FlagsAttributes of the NET_BUFFER_LIST structure. The following definitions specify a bit mask for a set of flags:
This set is reserved for protocol drivers.
Note Starting with NDIS 6.30, two additional bits are available for protocol use: 0x00000003. A NDIS 6.30 protocol may use these bits if and only if NdisGetVersion returns a value greater than or equal to NDIS_RUNTIME_VERSION_630. Protocols must not use these bits on earlier versions of NDIS, because prior to 6.30, NDIS uses them internally.
This set is reserved for miniport drivers.
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.
This set is reserved for NDIS.
StatusThe 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:
All the network data described by NET_BUFFER structures associated with this NET_BUFFER_LIST structure was successfully transmitted over the network.
The size of the data in some NET_BUFFER structures associated with this NET_BUFFER_LIST structure was too large for the underlying NIC.
The send request for this NET_BUFFER_LIST structure failed due to insufficient resources.
This send request for this NET_BUFFER_LIST structure failed due to some reason other than those stated in the previous three values.
NDIS called the MiniportCancelSend function to cancel the send operation for this NET_BUFFER_LIST structure.
The miniport driver aborted the send request due to a reset.
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.
NdisReserved2Reserved for NDIS.
NetBufferListInfoAn array of values containing information that is common to all NET_BUFFER structures in the list. This information is often referred to as "out-of-band (OOB) data."
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.
NDIS drivers can call any of the following functions to allocate and initialize a NET_BUFFER_LIST structure:
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 function, it loses ownership of:
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_MINIPORT_RESERVED
NET_BUFFER_LIST_CONTEXT_DATA_START
NET_BUFFER_LIST_CONTEXT_DATA_SIZE
NET_BUFFER_LIST_PROTOCOL_RESERVED
For more information on how to use net buffers, see NET_BUFFER Architecture.
NET_BUFFER_LIST_CONTEXT_DATA_SIZE
NET_BUFFER_LIST_CONTEXT_DATA_START
NET_BUFFER_LIST_MINIPORT_RESERVED
NET_BUFFER_LIST_PROTOCOL_RESERVED
NdisAllocateCloneNetBufferList
NdisAllocateFragmentNetBufferList
NdisAllocateNetBufferAndNetBufferList
NdisAllocateNetBufferListContext
NdisAllocateReassembledNetBufferList