NDIS_SWITCH_GET_NET_BUFFER_LIST_DESTINATIONS callback function (ndis.h)

Article
02/22/2024

The GetNetBufferListDestinations function returns the Hyper-V extensible switch destination ports of a packet that is specified by a NET_BUFFER_LIST structure.

Syntax

NDIS_SWITCH_GET_NET_BUFFER_LIST_DESTINATIONS NdisSwitchGetNetBufferListDestinations;

void NdisSwitchGetNetBufferListDestinations(
  [in]      NDIS_SWITCH_CONTEXT NdisSwitchContext,
  [in, out] PNET_BUFFER_LIST NetBufferList,
  [out]     PNDIS_SWITCH_FORWARDING_DESTINATION_ARRAY *Destinations
)
{...}

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.

Note If the NetBufferList parameter contains a pointer to a linked-list of multiple NET_BUFFER_LIST structures, the destination ports are only returned from the first NET_BUFFER_LIST structure in the list.

[out] Destinations

A pointer to an NDIS_SWITCH_FORWARDING_DESTINATION_ARRAY structure. This structure specifies the extensible switch destination ports of the packet.

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 calls the GetNetBufferListDestinations function to obtain an array of the extensible switch destination ports for a packet. If the function returns successfully, the array is obtained through the Destinations parameter, which contains a pointer to an NDIS_SWITCH_FORWARDING_DESTINATION_ARRAY structure. Each element in this array is formatted as an NDIS_SWITCH_PORT_DESTINATION structure that specifies a destination port for the packet.

If the extension is allocating a packet, the extension must first call the AllocateNetBufferListForwardingContext function before it calls GetNetBufferListDestinations. The AllocateNetBufferListForwardingContext function allocates the extensible switch forwarding context for the packet. This context contains the out-of-band (OOB) extensible switch data that includes the NDIS_SWITCH_FORWARDING_DESTINATION_ARRAY structure.

For more information about the extensible switch forwarding context, see Hyper-V Extensible Switch Forwarding Context.

After the extension has obtained the array, it can do the following:

Allocate space for additional NDIS_SWITCH_PORT_DESTINATION elements in the array.
For more information, see Adding Extensible Switch Destination Port Data to a Packet.
Modify the destination port information in the NDIS_SWITCH_PORT_DESTINATION elements of the array. For example, the extension can specify which port the packet is to be forwarded to or can exclude a packet from being forwarded to a specified port.
For more information, see Modifying a Packet's Extensible Switch Source Port Data.

Note The NDIS_SWITCH_FORWARDING_DESTINATION_ARRAY structure is guaranteed to be valid while the extension retains ownership of the packet's NET_BUFFER_LIST structure.

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