NdisAllocateNetBufferAndNetBufferList, fonction (ndis/nblapi.h)

Article
08/07/2023

Appelez la fonction NdisAllocateNetBufferAndNetBufferList pour allouer et initialiser une structure de NET_BUFFER_LIST initialisée avec une structure de NET_BUFFER préalloué.

Syntaxe

NDIS_EXPORTED_ROUTINE NET_BUFFER_LIST * NdisAllocateNetBufferAndNetBufferList(
  [in]           NDIS_HANDLE          PoolHandle,
  [in]           USHORT               ContextSize,
  [in]           USHORT               ContextBackFill,
  [in, optional] __drv_aliasesMem MDL *MdlChain,
  [in]           ULONG                DataOffset,
  [in]           SIZE_T               DataLength
);

Paramètres

[in] PoolHandle

Un handle de pool de structure NET_BUFFER_LIST qui a été précédemment retourné à partir du Fonction NdisAllocateNetBufferListPool . Le membre fAllocateNetBuffer de la structure NET_BUFFER_LIST_POOL_PARAMETERS que l’appelant a passé à NdisAllocateNetBufferListPool doit avoir été défini sur TRUE et le membre DataSize défini sur zéro.

[in] ContextSize

Quantité d’espace de données utilisé dans la structure NET_BUFFER_LIST_CONTEXT à réserver à l’appelant. ContextSize doit être un multiple de la valeur définie par MEMORY_ALLOCATION_ALIGNMENT.

[in] ContextBackFill

Quantité d’espace de données inutilisé (espace de remplissage) dont l’appelant a besoin. NDIS ajoute cette valeur à ContextSize et alloue de l’espace supplémentaire. Le ContextBackFill doit être un multiple de la valeur définie par MEMORY_ALLOCATION_ALIGNMENT.

[in, optional] MdlChain

Pointeur vers une chaîne MDL que NDIS utilise pour initialiser la structure de NET_BUFFER préallouée. MdlChain peut avoir la valeur NULL.

[in] DataOffset

Décalage initial, en octets, du début de la mémoire tampon au début de l’espace de données utilisé dans la chaîne MDL. L’espace de données avant ce décalage est un espace de données inutilisé. Par conséquent, cette valeur représente également la quantité initiale d’espace de remplissage disponible dans la chaîne MDL. Si MdlChain a la valeur NULL, DataOffset doit avoir la valeur 0.

[in] DataLength

Longueur, en octets, de l’espace de données utilisé dans la chaîne MDL. Si MdlChain a la valeur NULL, DataLength doit avoir la valeur 0.

Valeur retournée

NdisAllocateNetBufferAndNetBufferList retourne un pointeur vers la structure NET_BUFFER_LIST allouée. La structure NET_BUFFER_LIST inclut une structure NET_BUFFER. Si l’allocation a échoué, ce pointeur a la valeur NULL.

Remarques

Les structures allouées par la fonction NdisAllocateNetBufferAndNetBufferList doivent provenir d’un pool qui inclut des structures NET_BUFFER_LIST associées à des structures de NET_BUFFER préalloués. Pour créer un tel pool, vous devez appeler le Fonction NdisAllocateNetBufferListPool avec le membre fAllocateNetBuffer de la structure NET_BUFFER_LIST_POOL_PARAMETERS défini sur TRUE et le membre DataSize défini sur zéro.

NotezNET_BUFFER et NET_BUFFER_LIST structures doivent être allouées à partir d’un pool de mémoires tampons NDIS. Un pilote ne doit pas allouer et initialiser une structure NET_BUFFER_LIST ou NET_BUFFER à partir de son pool de mémoire privée ou de la pile.

Appelez la fonction NdisFreeNetBufferList pour libérer une structure NET_BUFFER_LIST .

Le NET_BUFFER préalloué peut être réutilisé en le réinitialisant avec une autre chaîne MDL lorsqu’il possède NET_BUFFER, mais les champs DataOffset, DataLength, CurrentMdl et CurrentMdlOffset dans le NET_BUFFER doivent être cohérents avec la nouvelle chaîne MDL.

Par exemple, si la chaîne MDL d’origine contient XDataLength et YDataOffset, et que CurrentMdl commence par la deuxième MDL (M) dans la chaîne MDL d’origine, CurrentMdlOffset a la valeur Z. Le champ MdlChain dans NET_BUFFER_DATA doit ensuite pointer vers une nouvelle chaîne MDL qui contient X’DataLength et Y’DataOffset. Si CurrentMdl commence par la troisième MDL (M') dans la nouvelle chaîne MDL, CurrentMdlOffset a la valeur Z', et les macros suivantes doivent être utilisées pour définir des champs dans NET_BUFFER :

NET_BUFFER_FIRST_MDL(_NB) = New MDL chain;
NET_BUFFER_DATA_LENGTH(_NB) = X';
NET_BUFFER_DATA_OFFSET(_NB) = Y';
NET_BUFFER_CURRENT_MDL(_NB) = M';
NET_BUFFER_CURRENT_MDL_OFFSET(_NB) = Z';

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Pris en charge dans NDIS 6.0 et versions ultérieures.
Plateforme cible	Universal
En-tête	ndis/nblapi.h (include ndis.h)
Bibliothèque	Ndis.lib
IRQL	<= DISPATCH_LEVEL
Règles de conformité DDI	Irql_NetBuffer_Function(ndis), NdisAllocateNetBufferList(ndis), NdisAllocateNetBufferList_InitFail(ndis)