NDIS_SWITCH_GET_NET_BUFFER_LIST_SWITCH_CONTEXT callback function (ndis.h)

Article
10/21/2021

The Hyper-V extensible switch extension calls the GetNetBufferListSwitchContext function to retrieve the switch context previously set on the NET_BUFFER_LIST.

Syntax

NDIS_SWITCH_GET_NET_BUFFER_LIST_SWITCH_CONTEXT NdisSwitchGetNetBufferListSwitchContext;

PVOID NdisSwitchGetNetBufferListSwitchContext(
  [in] NDIS_SWITCH_CONTEXT NdisSwitchContext,
  [in] PNET_BUFFER_LIST NetBufferList,
  [in] PNDIS_SWITCH_NET_BUFFER_LIST_CONTEXT_TYPE ContextType
)
{...}

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

A pointer to a NET_BUFFER_LIST structure for a single packet that contains the context to be retrieved.

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

Context

Context type declared using the NDIS_DECLARE_SWITCH_NET_BUFFER_LIST_CONTEXT_TYPE that was used when setting the context.

Return value

NULL if no context was found in the NET_BUFFER_LIST that matches the specified context type. Otherwise, a non-NULL pointer to the buffer is returned.

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