PROTOCOL_RECEIVE_NET_BUFFER_LISTS callback function (ndis.h)

Article
10/21/2021

The ProtocolReceiveNetBufferLists function processes receive indications from underlying drivers.

Note You must declare the function by using the PROTOCOL_RECEIVE_NET_BUFFER_LISTS type. For more information, see the following Examples section.

Syntax

PROTOCOL_RECEIVE_NET_BUFFER_LISTS ProtocolReceiveNetBufferLists;

void ProtocolReceiveNetBufferLists(
  [in] NDIS_HANDLE ProtocolBindingContext,
  [in] PNET_BUFFER_LIST NetBufferLists,
  [in] NDIS_PORT_NUMBER PortNumber,
  [in] ULONG NumberOfNetBufferLists,
  [in] ULONG ReceiveFlags
)
{...}

Parameters

[in] ProtocolBindingContext

A handle to a context area that the protocol driver allocated to maintain state information for a binding. This handle was passed to NDIS in a previous call to the NdisOpenAdapterEx function.

[in] NetBufferLists

A linked list of NET_BUFFER_LIST structures that the underlying driver allocated. Each NET_BUFFER_LIST structure is usually associated with one NET_BUFFER structure.

[in] PortNumber

A port number that identifies a miniport adapter port. The default port number of a miniport adapter is zero. Protocol drivers that do not use miniport adapter ports should ignore this parameter.

[in] NumberOfNetBufferLists

The number of NET_BUFFER_LIST structures that are in the linked list of structures at NetBufferLists .

[in] ReceiveFlags

Flags that define attributes for the send operation. The flags can be combined with an OR operation. To clear all the flags, set this member to zero. This function supports the following flags:

NDIS_RECEIVE_FLAGS_DISPATCH_LEVEL

Specifies that the current IRQL is DISPATCH_LEVEL. For more information about this flag, see Dispatch IRQL Tracking.

NDIS_RECEIVE_FLAGS_RESOURCES

Specifies that NDIS reclaims ownership of the NET_BUFFER_LIST structures and any attached NET_BUFFER structures immediately after the call to ProtocolReceiveNetBufferLists returns.

NDIS_RECEIVE_FLAGS_SINGLE_ETHER_TYPE

Specifies that all of the NET_BUFFER_LIST structures in the list at NetBufferLists have the same protocol type (EtherType).

NDIS_RECEIVE_FLAGS_SINGLE_VLAN

Specifies that all of the NET_BUFFER_LIST structures in the list at NetBufferLists belong to the same VLAN.

NDIS_RECEIVE_FLAGS_PERFECT_FILTERED

Specifies that all of the NET_BUFFER_LIST structures in the list at NetBufferLists include only data that matches the packet filter and multicast list that are assigned to the miniport adapter.

NDIS_RECEIVE_FLAGS_SINGLE_QUEUE

Specifies that all the NET_BUFFER_LIST structures in the list at NetBufferLists belong to the same VM queue. A miniport driver must set this flag for all receive indications on a queue if the NDIS_RECEIVE_QUEUE_PARAMETERS_PER_QUEUE_RECEIVE_INDICATION flag was set in the Flags member of the NDIS_RECEIVE_QUEUE_PARAMETERS structure when that queue was allocated.

NDIS_RECEIVE_FLAGS_SHARED_MEMORY_INFO_VALID

Specifies that all the NET_BUFFER_LIST structures in the list at NetBufferLists contain shared memory information that is valid. When this flag is set on a received NET_BUFFER_LIST, NDIS treats the shared memory information as valid. When this flag is not set, NDIS and drivers ignore the shared memory information. For example, intermediate drivers that modify packet data can use this flag to determine if data should be copied. Miniport drivers can use the flag to determine how to free the memory that is associated with a VM queue when a queue is deleted.

NDIS_RECEIVE_FLAGS_MORE_NBLS

Reserved.

Return value

None

Remarks

ProtocolReceiveNetBufferLists is a required function for protocol drivers. NDIS calls ProtocolReceiveNetBufferLists after a bound miniport driver calls the NdisMIndicateReceiveNetBufferLists function. A call to ProtocolReceiveNetBufferLists can also occur as a result of a loopback.

If the NDIS_RECEIVE_FLAGS_RESOURCES flag in the ReceiveFlags parameter is not set, the protocol driver retains ownership of the NET_BUFFER_LIST structures until it calls the NdisReturnNetBufferLists function.

If NDIS sets the NDIS_RECEIVE_FLAGS_RESOURCES flag the protocol driver cannot retain the NET_BUFFER_LIST structure and associated resources. The set NDIS_RECEIVE_FLAGS_RESOURCES flag indicates that an underlying driver is running low on receive resources. In this case, the ProtocolReceiveNetBufferLists function should copy the received data into protocol-allocated storage and return as quickly as possible.

Note If the NDIS_RECEIVE_FLAGS_RESOURCES flag is set, the protocol driver must retain the original set of NET_BUFFER_LIST structures in the linked list. For example, when this flag is set the driver might process the structures and indicate them up the stack one at a time but before the function returns it must restore the original linked list.

On a multiprocessor system, this function can execute concurrently on more than one processor. Apply protection (for example, use spin locks) to critical data structures that are accessed by ProtocolReceiveNetBufferLists.

NDIS calls ProtocolReceiveNetBufferLists at IRQL<= DISPATCH_LEVEL.

Examples

To define a ProtocolReceiveNetBufferLists function, you must first provide a function declaration that identifies the type of function you're defining. Windows provides a set of function types for drivers. Declaring a function using the function types helps Code Analysis for Drivers, Static Driver Verifier (SDV), and other verification tools find errors, and it's a requirement for writing drivers for the Windows operating system.

For example, to define a ProtocolReceiveNetBufferLists function that is named "MyReceiveNetBufferLists", use the PROTOCOL_RECEIVE_NET_BUFFER_LISTS type as shown in this code example:

PROTOCOL_RECEIVE_NET_BUFFER_LISTS MyReceiveNetBufferLists;

Then, implement your function as follows:

_Use_decl_annotations_
VOID
 MyReceiveNetBufferLists(
    NDIS_HANDLE  ProtocolBindingContext,
    PNET_BUFFER_LIST  NetBufferLists,
    NDIS_PORT_NUMBER  PortNumber,
    ULONG  NumberOfNetBufferLists,
    ULONG ReceiveFlags
    )
  {...}

The PROTOCOL_RECEIVE_NET_BUFFER_LISTS function type is defined in the Ndis.h header file. To more accurately identify errors when you run the code analysis tools, be sure to add the Use_decl_annotations annotation to your function definition. The Use_decl_annotations annotation ensures that the annotations that are applied to the PROTOCOL_RECEIVE_NET_BUFFER_LISTS function type in the header file are used. For more information about the requirements for function declarations, see Declaring Functions by Using Function Role Types for NDIS Drivers.

For information about Use_decl_annotations, see Annotating Function Behavior.

Requirements

Requirement	Value
Minimum supported client	Supported in NDIS 6.0 and later.
Target Platform	Windows
Header	ndis.h (include Ndis.h)
IRQL	<= DISPATCH_LEVEL