NDIS_SWITCH_UPDATE_NET_BUFFER_LIST_DESTINATIONS callback function (ndis.h)

Article
10/21/2021

The Hyper-V extensible switch extension calls the UpdateNetBufferListDestinations function to commit modifications that the extension made to a packet that contains multiple extensible switch destination ports. The function saves these modifications to the out-of-band (OOB) extensible switch forwarding context of the packet's NET_BUFFER_LIST structure.

Syntax

NDIS_SWITCH_UPDATE_NET_BUFFER_LIST_DESTINATIONS NdisSwitchUpdateNetBufferListDestinations;

NDIS_STATUS NdisSwitchUpdateNetBufferListDestinations(
  [in]      NDIS_SWITCH_CONTEXT NdisSwitchContext,
  [in, out] PNET_BUFFER_LIST NetBufferList,
  [in]      UINT32 NumberOfNewDestinations,
  [in]      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 NET_BUFFER_LIST structure for a single packet.

Note This structure must contain an extensible switch forwarding context. If the extension created or cloned the packet, it must have previously allocated this structure by calling the AllocateNetBufferListForwardingContext function.

[in] NumberOfNewDestinations

A UINT32 value that specifies the number of new destination ports that were added to the packet.

[in] Destinations

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

Note The extension received this structure through a previous call to the GetNetBufferListDestinations function.

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 a 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.

After the extension obtains the NDIS_SWITCH_FORWARDING_DESTINATION_ARRAY structure, the extension can do the following:

Add additional NDIS_SWITCH_PORT_DESTINATION elements in the array.
For more information, see Adding Extensible Switch Destination Port Data to a Packet.
Modify existing NDIS_SWITCH_PORT_DESTINATION elements of the array to exclude a packet from being forwarded to a specified port.
For more information, see Excluding Packet Delivery to Extensible Switch Destination Ports.

If the extension adds or modifies destination ports in the NDIS_SWITCH_FORWARDING_DESTINATION_ARRAY structure, the extension must call the UpdateNetBufferListDestinations function to commit those changes to the packet's NET_BUFFER_LIST structure.

Note Only forwarding extensions can call UpdateNetBufferListDestinations to commit destination ports that were added or changed for packets with multiple destination ports. For more information on this type of extension, see Forwarding Extensions.

If the call to UpdateNetBufferListDestinations returns NDIS_STATUS_SUCCESS, the extensible switch interface guarantees that the extensible switch port and network adapter connection that are referenced in the destination ports will not be deleted until the packet's send or receive operation is completed.

Also, after the changes for destination ports have been committed, destination ports cannot be removed, and only the IsExcluded member of a destination port's NDIS_SWITCH_PORT_DESTINATION structure can be changed. For more information, see Excluding Packet Delivery to Extensible Switch Destination Ports.

Note For performance reasons, the extension should not call the UpdateNetBufferListDestinations function to commit the changes to a packet with only one destination port. Instead, the extension calls AddNetBufferListDestination to commit the changes to the packet's destination port.

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

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