NDIS_SWITCH_SET_NET_BUFFER_LIST_SWITCH_CONTEXT callback function (ndis.h)

Article
06/29/2022

The Hyper-V extensible switch extension calls the SetNetBufferListSwitchContext function to attach an extension-allocated context buffer to the NET_BUFFER_LIST. The context is then accessible for the lifetime of that NET_BUFFER_LIST, including if the context is set on ingress and the NBL is seen again on egress, regardless of whether other extensions set their own context. This type of access is not possible using the existing NDIS NET_BUFFER_LIST context APIs (NdisAllocateNetBufferListContext/ NET_BUFFER_LIST_CONTEXT_DATA_START) because another extension can allocate NDIS context when it gets ownership of the NET_BUFFER_LIST, at which point the pointer to the original NDIS context is lost.

Syntax

NDIS_SWITCH_SET_NET_BUFFER_LIST_SWITCH_CONTEXT NdisSwitchSetNetBufferListSwitchContext;

NDIS_STATUS NdisSwitchSetNetBufferListSwitchContext(
  [in]      NDIS_SWITCH_CONTEXT NdisSwitchContext,
  [in, out] PNET_BUFFER_LIST NetBufferList,
  [in]      PNDIS_SWITCH_NET_BUFFER_LIST_CONTEXT_TYPE ContextType,
  [in]      PVOID Context
)
{...}

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 that receives the context association.

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] ContextType

The context type declared using NDIS_DECLARE_SWITCH_NET_BUFFER_LIST_CONTEXT_TYPE that will be used as the key when retrieving the context.

[in] Context

The pointer to the context that will be retrievable using the specified ContextType.

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 SetNetBufferListSwitchContext APIs allow extensions to attach context to a NET_BUFFER_LIST on ingress and retrieve it on egress. Even so, extensions should be resilient to the ingress context not being present on egress. The switch context is not preserved when an NET_BUFFER_LIST is cloned, so in scenarios where the NET_BUFFER_LIST is cloned between ingress and egress, the NET_BUFFER_LIST will not have the original's switch context.

The extension must manage the lifetime of the context. One approach is to allocate NDIS NET_BUFFER_LIST context (using NdisAllocateNetBufferListContext, or preconfigured if the extension owns the NET_BUFFER_LIST pool), and use the SetNetBufferListSwitchContext to associate a context type identifier with the NDIS NET_BUFFER_LIST context. When the NBL is completed, the extension can free the NDIS NET_BUFFER_LIST context (using NdisFreeNetBufferListContext, or freeing the NET_BUFFER_LIST itself if it was originated by the extension).

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