NDIS_SWITCH_SET_NET_BUFFER_LIST_SWITCH_CONTEXT fonction de rappel (ndis.h)

Article
02/29/2024

L’extension de commutateur extensible Hyper-V appelle la fonction SetNetBufferListSwitchContext pour attacher une mémoire tampon de contexte allouée à l’extension au NET_BUFFER_LIST. Le contexte est ensuite accessible pendant toute la durée de vie de cette NET_BUFFER_LIST, y compris si le contexte est défini à l’entrée et que le NBL est à nouveau visible à la sortie, que d’autres extensions définissent ou non leur propre contexte. Ce type d’accès n’est pas possible à l’aide des API de contexte NET_BUFFER_LIST NDIS existantes (NdisAllocateNetBufferListContext/ NET_BUFFER_LIST_CONTEXT_DATA_START), car une autre extension peut allouer le contexte NDIS lorsqu’elle obtient la propriété du NET_BUFFER_LIST, auquel cas le pointeur vers le contexte NDIS d’origine est perdu.

Syntaxe

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
)
{...}

Paramètres

[in] NdisSwitchContext

Valeur NDIS_SWITCH_CONTEXT qui contient le handle du module de commutateur extensible auquel l’extension de commutateur extensible Hyper-V est attachée. Lorsque l’extension appelle NdisFGetOptionalSwitchHandlers, ce handle est retourné par le biais du paramètre NdisSwitchContext .

[in, out] NetBufferList

Pointeur vers une structure NET_BUFFER_LIST pour un paquet unique qui reçoit l’association de contexte.

Note Cette structure doit contenir un contexte de transfert de commutateur extensible. Si l’extension a créé ou cloné le paquet, elle doit avoir précédemment alloué cette structure en appelant la fonction AllocateNetBufferListForwardingContext .

[in] ContextType

Type de contexte déclaré à l’aide de NDIS_DECLARE_SWITCH_NET_BUFFER_LIST_CONTEXT_TYPE qui sera utilisé comme clé lors de la récupération du contexte.

[in] Context

Pointeur vers le contexte qui sera récupérable à l’aide du ContextType spécifié.

Valeur retournée

Si l’appel réussit, la fonction retourne NDIS_STATUS_SUCCESS. Sinon, elle retourne un code d’erreur NDIS_STATUS_Xxx défini dans Ndis.h.

Remarques

Les API SetNetBufferListSwitchContext permettent aux extensions d’attacher un contexte à un NET_BUFFER_LIST à l’entrée et de le récupérer à la sortie. Malgré cela, les extensions doivent être résilientes au contexte d’entrée qui n’est pas présent à la sortie. Le contexte de commutateur n’est pas conservé lorsqu’un NET_BUFFER_LIST est cloné. Par conséquent, dans les scénarios où le NET_BUFFER_LIST est cloné entre l’entrée et la sortie, le NET_BUFFER_LIST n’aura pas le contexte de commutateur de l’original.

L’extension doit gérer la durée de vie du contexte. Une approche consiste à allouer NDIS NET_BUFFER_LIST contexte (à l’aide de NdisAllocateNetBufferListContext, ou préconfiguré si l’extension possède le pool de NET_BUFFER_LIST) et d’utiliser setNetBufferListSwitchContext pour associer un identificateur de type de contexte au contexte de NET_BUFFER_LIST NDIS. Une fois le NBL terminé, l’extension peut libérer le contexte de NET_BUFFER_LIST NDIS (à l’aide de NdisFreeNetBufferListContext, ou de libérer le NET_BUFFER_LIST lui-même s’il provient de l’extension).

Pour plus d’informations sur le contexte de transfert de commutateur extensible, consultez Contexte de transfert de commutateur extensible Hyper-V.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Pris en charge dans NDIS 6.30 et versions ultérieures.
Plateforme cible	Desktop (Expérience utilisateur)
En-tête	ndis.h (inclure Ndis.h)
IRQL	<= DISPATCH_LEVEL