MINIPORT_RETURN_NET_BUFFER_LISTS callback function (ndis.h)

Article
10/21/2021

NDIS calls the MiniportReturnNetBufferLists function to return ownership of NET_BUFFER_LIST structures, associated NET_BUFFER structures, and any attached MDLs to a miniport driver.

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

Syntax

MINIPORT_RETURN_NET_BUFFER_LISTS MiniportReturnNetBufferLists;

void MiniportReturnNetBufferLists(
  [in] NDIS_HANDLE MiniportAdapterContext,
  [in] PNET_BUFFER_LIST NetBufferLists,
  [in] ULONG ReturnFlags
)
{...}

Parameters

[in] MiniportAdapterContext

A handle to a context area that the miniport driver allocated in its MiniportInitializeEx function. The miniport driver uses this context area to maintain state information about an adapter.

[in] NetBufferLists

A pointer to a linked list of NET_BUFFER_LIST structures that NDIS is returning to the miniport driver. The linked list can contain NET_BUFFER_LIST structures from multiple previous calls to the NdisMIndicateReceiveNetBufferLists function.

[in] ReturnFlags

NDIS flags that can be combined with an OR operation. This function supports the NDIS_RETURN_FLAGS_DISPATCH_LEVEL flag which, if set, indicates that the current IRQL is DISPATCH_LEVEL. For more information about this flag, see Dispatch IRQL Tracking.

Return value

None

Remarks

MiniportReturnNetBufferLists is a required function for miniport drivers that indicate received network data with the NdisMIndicateReceiveNetBufferLists function. When an overlying driver calls the NdisReturnNetBufferLists function, NDIS calls the MiniportReturnNetBufferLists function of the miniport driver that indicated the specified NET_BUFFER_LIST structures.

MiniportReturnNetBufferLists can prepare a returned NET_BUFFER_LIST structure for use in a subsequent receive indication. Although MiniportReturnNetBufferLists can return the NET_BUFFER_LIST structures to a pool (for example, it could call the NdisFreeNetBufferList function), it can be more efficient to reuse the structures without returning them to the pool.

NDIS calls MiniportReturnNetBufferLists at IRQL<= DISPATCH_LEVEL.

Examples

To define a MiniportReturnNetBufferLists 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 MiniportReturnNetBufferLists function that is named "MyReturnNetBufferLists", use the MINIPORT_RETURN_NET_BUFFER_LISTS type as shown in this code example:

MINIPORT_RETURN_NET_BUFFER_LISTS MyReturnNetBufferLists;

Then, implement your function as follows:

_Use_decl_annotations_
VOID
 MyReturnNetBufferLists(
    NDIS_HANDLE  MiniportAdapterContext,
    PNET_BUFFER_LIST  NetBufferLists,
    ULONG  ReturnFlags
    )
  {...}

The MINIPORT_RETURN_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 MINIPORT_RETURN_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