UpdateNetBufferListDestinations routine

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_STATUS UpdateNetBufferListDestinations(
  _In_     NDIS_SWITCH_CONTEXT NdisSwitchContext,
  _Inout_  PNET_BUFFER_LIST NetBufferList,
  _In_     UINT32 NumberOfNewDestinations,
  _In_     PNDIS_SWITCH_FORWARDING_DESTINATION_ARRAY Destinations
);

Parameters

NdisSwitchContext [in]

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.

NetBufferList [in, out]

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.

NumberOfNewDestinations [in]

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

Destinations [in]

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:

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

Version

Supported in NDIS 6.30 and later.

Header

Ndis.h (include Ndis.h)

IRQL

<= DISPATCH_LEVEL

See also

AllocateNetBufferListForwardingContext
GetNetBufferListDestinations
NDIS_SWITCH_PORT_DESTINATION
NdisFGetOptionalSwitchHandlers
NdisFOidRequest
NET_BUFFER
NET_BUFFER_LIST
OID_SWITCH_NIC_DELETE

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft