NDIS_SWITCH_ALLOCATE_NET_BUFFER_LIST_FORWARDING_CONTEXT callback function (ndis.h)

Article
02/22/2024

The AllocateNetBufferListForwardingContext function prepares a NET_BUFFER_LIST structure for send or receive operations within the extensible switch.

Syntax

NDIS_SWITCH_ALLOCATE_NET_BUFFER_LIST_FORWARDING_CONTEXT NdisSwitchAllocateNetBufferListForwardingContext;

NDIS_STATUS NdisSwitchAllocateNetBufferListForwardingContext(
  [in]      NDIS_SWITCH_CONTEXT NdisSwitchContext,
  [in, out] PNET_BUFFER_LIST NetBufferList
)
{...}

Parameters

[in] NdisSwitchContext

An NDIS_SWITCH_CONTEXT value that contains the handle of the extensible switch module to which the Hyper-V extensible switch extension is attached. When the extension calls NdisFGetOptionalSwitchHandlers, this handle is returned through the NdisSwitchContext parameter.

[in, out] NetBufferList

A pointer to a linked list of NET_BUFFER_LIST structures.

Return value

If the call succeeds, the function returns NDIS_STATUS_SUCCESS. Otherwise, it returns an NDIS_STATUS_Xxx error code that is defined in Ndis.h.

Remarks

The extensible switch extension can originate packet send operations within the extensible switch data path. For example, the extension can send packets to any port on the extensible switch. For more information about this data path, see Hyper-V Extensible Switch Data Path.

After the extension calls NdisAllocateNetBufferList or NdisAllocateCloneNetBufferList to create or clone a packet from its NET_BUFFER_LIST pool, the extension must call the AllocateNetBufferListForwardingContext function. This function allocates and initializes the out-of-band (OOB) extensible switch forwarding context for the specified NET_BUFFER_LIST structure. For more information about this context, see Hyper-V Extensible Switch Forwarding Context.

The extension must follow these guidelines for allocating the forwarding context through the AllocateNetBufferListForwardingContext function:

The extension calls NdisAllocateNetBufferList to allocate a packet from the extension's NET_BUFFER_LIST pool for a send or receive operation over the extensible switch. Before the extension initializes source and destination ports for the packet, it must call AllocateNetBufferListForwardingContext.
For more information on how to specify source and destination extensible switch ports, see Managing Hyper-V Extensible Switch Source and Destination Port Data.
Before the extension calls AllocateNetBufferListForwardingContext, it must set the SourceHandle member of each allocated NET_BUFFER_LIST structure to the handle value that identifies the extension. The extension receives this handle through the NdisFilterHandle parameter when NDIS calls the extension's FilterAttach function.
When the send operation is complete, the extension must call the FreeNetBufferListForwardingContext function to deallocate the resources for the forwarding context. The extension must call this function before it calls NdisFreeNetBufferList to return the packet to its NET_BUFFER_LIST pool.
If the extension is cloning a packet, it must call CopyNetBufferListInfo to copy the forwarding context from the original packet to the cloned packet. The extension must do this after it calls AllocateNetBufferListForwardingContext.

For more information on how to originate send operations, see Filter Module Send and Receive Operations.

Note If the NetBufferList parameter contains a pointer to a linked-list of multiple NET_BUFFER_LIST structures, only the first NET_BUFFER_LIST structure in the list has a forwarding context allocated for it.

Requirements

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