Fonction NdisAllocatePacketPoolEx (ndis.h)

  • Article

Note NDIS 5. x a été déconseillé et est remplacé par NDIS 6. x. Pour le développement de nouveaux pilotes NDIS, consultez Pilotes réseau à partir de Windows Vista. Pour plus d’informations sur le portage de NDIS 5. x pilotes dans NDIS 6. x, consultez Portage des pilotes NDIS 5.x vers NDIS 6.0.

Cette fonction alloue et initialise un bloc de stockage pour un pool de descripteurs de paquets.

Syntaxe

void NdisAllocatePacketPoolEx(
  [out] PNDIS_STATUS Status,
  [out] PNDIS_HANDLE PoolHandle,
  [in]  UINT         NumberOfDescriptors,
  [in]  UINT         NumberOfOverflowDescriptors,
  [in]  UINT         ProtocolReservedLength
);

Paramètres

[out] Status

Pointe vers une variable fournie par l’appelant dans laquelle cette fonction retourne le status de l’allocation du pool de paquets.

[out] PoolHandle

Pointe vers une variable fournie par l’appelant dans laquelle cette fonction retourne un handle au pool de paquets. Ce handle est un paramètre obligatoire pour les fonctions de paquet NdisXXX que le pilote appelle par la suite.

[in] NumberOfDescriptors

Spécifie le nombre de descripteurs de paquets que le pool doit contenir pour une utilisation normale prévue. Le nombre maximal de NumberOfDescriptors qui peuvent être alloués est 0xFFFF. Si une tentative d’allocation est supérieure à celle-ci, NdisAllocatePacketPoolEx retourne un état de NDIS_STATUS_RESOURCES.

[in] NumberOfOverflowDescriptors

Spécifie le nombre de descripteurs de paquets réservés à une situation de dépassement de capacité, c’est-à-dire lorsque tous les descripteurs spécifiés par NumberOfDescriptors sont en cours d’utilisation . Si la somme de ce paramètre et de NumberOfDescriptors dépasse 0xFFFF, NdisAllocatePacketPoolEx réduit la valeur fournie en tant que paramètre afin que le nombre total de NumberOfDescriptors et numberOfOverflowDescriptors soit égal à 0xFFFF.

[in] ProtocolReservedLength

Spécifie le nombre d’octets à allouer pour le tableau ProtocolReserved de chaque descripteur de paquets. Pour les descripteurs de paquets à utiliser dans les indications de réception, ce paramètre est de 4* taille de (PVOID).

Valeur de retour

None

Remarques

Le tableau suivant montre les valeurs de retour possibles pour cette fonction.

Statut Description
NDIS_STATUS_SUCCESS Le pilote peut effectuer des appels à NdisAllocatePacket lorsqu’il a besoin de descripteurs de paquets pour faire des indications jusqu’à des pilotes de niveau supérieur ou pour envoyer des paquets vers des pilotes de niveau inférieur.
NDIS_STATUS_RESOURCES La tentative d’allocation du pool de paquets a échoué, peut-être en raison d’un manque de mémoire. Ce retour ne signifie pas nécessairement qu’un appel suivant échouera. Toutefois, l’appelant peut tenter de réduire les numberOfDescriptors et d’appeler à nouveau immédiatement.

Un appel réussi à NdisAllocatePacketPoolEx retourne un handle au pool de paquets, que l’appelant doit enregistrer. En règle générale, le pilote appelle ensuite NdisAllocatePacket une ou plusieurs fois avec ce handle pour allouer un ensemble de descripteurs de paquets.

NdisAllocatePacketPoolEx alloue statiquement uniquement suffisamment de mémoire pour prendre en charge le nombre de descripteurs de paquets spécifié par NumberOfDescriptors. Le nombre total de descripteurs de paquets qui peuvent être alloués à partir du pool avec des appels à NdisAllocatePacket est le moins élevé de 0xFFFF ou la somme des nombres NumberOfDescriptors et NumberOfOverflowDescriptors initialement passés à NdisAllocatePacketPoolEx. Les descripteurs de dépassement de capacité sont alloués dynamiquement uniquement lors d’une situation de dépassement de capacité, c’est-à-dire lorsque les numberOfDescriptors donnés ont déjà été alloués et sont toujours en cours d’utilisation.

La somme de NumberOfDescriptors et numberOfOverflowDescriptors est la limite effective du nombre de fois où le pilote peut appeler NdisAllocatePacket avant d’appeler NdisFreePacket pour renvoyer un descripteur de paquets à la liste libre du pool de paquets. Lorsqu’aucun descripteur de dépassement de capacité n’a encore été alloué, NdisFreePacket retourne le descripteur de paquets au pool alloué statiquement. Si un ou plusieurs descripteurs de dépassement de capacité ont déjà été alloués, NdisFreePacket retourne le descripteur de paquets à la mémoire système, et non au pool.

L’appelant de NdisAllocatePacketPoolEx doit définir NumberOfDescriptors sur le nombre de descripteurs de paquets nécessaires pour les charges normales anticipées. Le pilote doit définir NumberOfOverflowDescriptors sur le nombre de descripteurs supplémentaires nécessaires pour prendre en charge les pics de charge prévus. Si le nombre total possible de descripteurs de paquets (NumberOfDescriptors plus NumberOfOverflowDescriptors) a été alloué à partir du pool, un appel à NdisAllocatePacket retourne NDIS_STATUS_RESOURCES.

Lorsque les paquets envoyés ou indiqués sont retournés au pilote d’allocation, il peut réutiliser chaque descripteur de paquet après avoir appelé NdisReinitializePacket et l’avoir configuré à nouveau avec une chaîne de descripteurs de mémoire tampon, ou le pilote peut appeler NdisFreePacket pour renvoyer ce paquet à la liste gratuite. La réinitialisation et la réutilisation des paquets alloués à partir d’un pool de paquets sont beaucoup plus rapides que la libération et, ensuite, la nécessité de les réallouer. Avant qu’un pilote appelle NdisReinitializePacket avec un descripteur de paquets, il doit enregistrer les pointeurs vers les descripteurs de mémoire tampon qui sont chaînés au descripteur de paquets, car NdisReinitializePacket définit le chef de la chaîne de mémoire tampon sur NULL.

Lorsqu’un pilote n’a plus besoin de descripteurs de paquets, il appelle [(nf-ndis-ndisfreepacketpool.md) pour libérer le stockage qu’il a alloué avec NdisAllocatePacketPoolEx.

Versions du système d’exploitation : Windows CE .NET 4.0 et versions ultérieures.

Configuration requise

Condition requise Valeur
En-tête ndis.h
Bibliothèque Ndis.lib
IRQL IRQL <= DISPATCH_LEVEL

Voir aussi