PROTOCOL_RECEIVE_NET_BUFFER_LISTS fonction de rappel (ndis.h)

Article
08/07/2023

La fonction ProtocolReceiveNetBufferLists traite les indications des pilotes sous-jacents.

Note Vous devez déclarer la fonction à l’aide du type PROTOCOL_RECEIVE_NET_BUFFER_LISTS . Pour plus d’informations, consultez la section Exemples suivante.

Syntaxe

PROTOCOL_RECEIVE_NET_BUFFER_LISTS ProtocolReceiveNetBufferLists;

void ProtocolReceiveNetBufferLists(
  [in] NDIS_HANDLE ProtocolBindingContext,
  [in] PNET_BUFFER_LIST NetBufferLists,
  [in] NDIS_PORT_NUMBER PortNumber,
  [in] ULONG NumberOfNetBufferLists,
  [in] ULONG ReceiveFlags
)
{...}

Paramètres

[in] ProtocolBindingContext

Handle dans une zone de contexte que le pilote de protocole a allouée pour conserver les informations d’état d’une liaison. Ce handle a été passé à NDIS lors d’un appel précédent à la fonction NdisOpenAdapterEx .

[in] NetBufferLists

Liste liée des structures NET_BUFFER_LIST allouées par le pilote sous-jacent. Chaque structure NET_BUFFER_LIST est généralement associée à une structure NET_BUFFER .

[in] PortNumber

Numéro de port qui identifie un port d’adaptateur miniport. Le numéro de port par défaut d’un adaptateur miniport est zéro. Les pilotes de protocole qui n’utilisent pas de ports d’adaptateur miniport doivent ignorer ce paramètre.

[in] NumberOfNetBufferLists

Nombre de structures NET_BUFFER_LIST qui figurent dans la liste liée des structures dans NetBufferLists .

[in] ReceiveFlags

Indicateurs qui définissent des attributs pour l’opération d’envoi. Les indicateurs peuvent être combinés à une opération OR. Pour effacer tous les indicateurs, définissez ce membre sur zéro. Cette fonction prend en charge les indicateurs suivants :

NDIS_RECEIVE_FLAGS_DISPATCH_LEVEL

Spécifie que l’IRQL actuel est DISPATCH_LEVEL. Pour plus d’informations sur cet indicateur, consultez Dispatch IRQL Tracking.

NDIS_RECEIVE_FLAGS_RESOURCES

Spécifie que NDIS récupère la propriété des structures NET_BUFFER_LIST et de toutes les structures NET_BUFFER attachées immédiatement après l’appel à ProtocolReceiveNetBufferLists .

NDIS_RECEIVE_FLAGS_SINGLE_ETHER_TYPE

Spécifie que toutes les structures NET_BUFFER_LIST de la liste sur NetBufferLists ont le même type de protocole (EtherType).

NDIS_RECEIVE_FLAGS_SINGLE_VLAN

Spécifie que toutes les structures NET_BUFFER_LIST de la liste dans NetBufferLists appartiennent au même VLAN.

NDIS_RECEIVE_FLAGS_PERFECT_FILTERED

Spécifie que toutes les structures NET_BUFFER_LIST de la liste dans NetBufferLists incluent uniquement les données qui correspondent au filtre de paquets et à la liste de multidiffusion qui sont attribuées à l’adaptateur miniport.

NDIS_RECEIVE_FLAGS_SINGLE_QUEUE

Spécifie que toutes les structures NET_BUFFER_LIST de la liste dans NetBufferLists appartiennent à la même file d’attente de machines virtuelles. Un pilote miniport doit définir cet indicateur pour toutes les indications de réception sur une file d’attente si l’indicateur NDIS_RECEIVE_QUEUE_PARAMETERS_PER_QUEUE_RECEIVE_INDICATION a été défini dans le membre Flags du NDIS_RECEIVE_QUEUE_PARAMETERS structure lorsque cette file d’attente a été allouée.

NDIS_RECEIVE_FLAGS_SHARED_MEMORY_INFO_VALID

Spécifie que toutes les structures NET_BUFFER_LIST de la liste dans NetBufferLists contiennent des informations de mémoire partagées valides. Lorsque cet indicateur est défini sur un NET_BUFFER_LIST reçu, NDIS traite les informations de mémoire partagée comme valides. Lorsque cet indicateur n’est pas défini, NDIS et les pilotes ignorent les informations de mémoire partagée. Par exemple, les pilotes intermédiaires qui modifient les données de paquets peuvent utiliser cet indicateur pour déterminer si les données doivent être copiées. Les pilotes miniport peuvent utiliser l’indicateur pour déterminer comment libérer la mémoire associée à une file d’attente de machine virtuelle lors de la suppression d’une file d’attente.

NDIS_RECEIVE_FLAGS_MORE_NBLS

Réservé.

Valeur de retour

None

Remarques

ProtocolReceiveNetBufferLists est une fonction obligatoire pour les pilotes de protocole. NDIS appelle ProtocolReceiveNetBufferLists après qu’un pilote miniport lié appelle le Fonction NdisMIndicateReceiveNetBufferLists . Un appel à ProtocolReceiveNetBufferLists peut également se produire à la suite d’un bouclage.

Si l’indicateur NDIS_RECEIVE_FLAGS_RESOURCES dans le paramètre ReceiveFlags n’est pas défini, le pilote de protocole conserve la propriété des structures NET_BUFFER_LIST jusqu’à ce qu’il appelle le Fonction NdisReturnNetBufferLists .

Si NDIS définit le NDIS_RECEIVE_FLAGS_RESOURCES indicateur, le pilote de protocole ne peut pas conserver la structure NET_BUFFER_LIST et les ressources associées. L’indicateur défini NDIS_RECEIVE_FLAGS_RESOURCES indique qu’un pilote sous-jacent est faible sur les ressources de réception. Dans ce cas, la fonction ProtocolReceiveNetBufferLists doit copier les données reçues dans le stockage alloué au protocole et retourner aussi rapidement que possible.

Note Si l’indicateur NDIS_RECEIVE_FLAGS_RESOURCES est défini, le pilote de protocole doit conserver l’ensemble d’origine de structures NET_BUFFER_LIST dans la liste liée. Par exemple, lorsque cet indicateur est défini, le pilote peut traiter les structures et les indiquer une par une dans la pile, mais avant que la fonction ne retourne, il doit restaurer la liste liée d’origine.

Sur un système multiprocesseur, cette fonction peut s’exécuter simultanément sur plusieurs processeurs. Appliquer la protection (par exemple, utiliser des verrous de rotation) aux structures de données critiques accessibles par ProtocolReceiveNetBufferLists.

NDIS appelle ProtocolReceiveNetBufferLists à IRQL<= DISPATCH_LEVEL.

Exemples

Pour définir une fonction ProtocolReceiveNetBufferLists , vous devez d’abord fournir une déclaration de fonction qui identifie le type de fonction que vous définissez. Windows fournit un ensemble de types de fonctions pour les pilotes. La déclaration d’une fonction à l’aide des types de fonction permet à l’analyse du code pour les pilotes, le vérificateur de pilotes statique (SDV) et d’autres outils de vérification de trouver les erreurs, et il s’agit d’une exigence pour l’écriture de pilotes pour le système d’exploitation Windows.

Par exemple, pour définir une fonction ProtocolReceiveNetBufferLists nommée « MyReceiveNetBufferLists », utilisez le type PROTOCOL_RECEIVE_NET_BUFFER_LISTS comme indiqué dans cet exemple de code :

PROTOCOL_RECEIVE_NET_BUFFER_LISTS MyReceiveNetBufferLists;

Ensuite, implémentez votre fonction comme suit :

_Use_decl_annotations_
VOID
 MyReceiveNetBufferLists(
    NDIS_HANDLE  ProtocolBindingContext,
    PNET_BUFFER_LIST  NetBufferLists,
    NDIS_PORT_NUMBER  PortNumber,
    ULONG  NumberOfNetBufferLists,
    ULONG ReceiveFlags
    )
  {...}

Le type de fonction PROTOCOL_RECEIVE_NET_BUFFER_LISTS est défini dans le fichier d’en-tête Ndis.h. Pour identifier plus précisément les erreurs lors de l’exécution des outils d’analyse du code, veillez à ajouter l’annotation Use_decl_annotations à votre définition de fonction. L’annotation Use_decl_annotations garantit que les annotations appliquées au type de fonction PROTOCOL_RECEIVE_NET_BUFFER_LISTS dans le fichier d’en-tête sont utilisées. Pour plus d’informations sur la configuration requise pour les déclarations de fonction, consultez Déclaration de fonctions à l’aide de types de rôles de fonction pour les pilotes NDIS.

Pour plus d’informations sur Use_decl_annotations, consultez Annotating Function Behavior.

Configuration requise

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