FILTER_RECEIVE_NET_BUFFER_LISTS fonction de rappel (ndis.h)

Article
08/07/2023

NDIS appelle la fonction FilterReceiveNetBufferLists pour demander un pilote de filtre pour traiter une indication de réception.

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

Syntaxe

FILTER_RECEIVE_NET_BUFFER_LISTS FilterReceiveNetBufferLists;

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

Paramètres

[in] FilterModuleContext

Handle de la zone de contexte du module de filtre. Le pilote de filtre a créé et initialisé cette zone de contexte dans la fonction FilterAttach .

[in] NetBufferLists

Liste liée des structures NET_BUFFER_LIST allouées par les pilotes sous-jacents. Chaque structure NET_BUFFER_LIST contient une structure NET_BUFFER .

[in] PortNumber

Numéro de port qui identifie un port d’adaptateur miniport. Les numéros de port de l’adaptateur miniport sont attribués en appelant la fonction NdisMAllocatePort . Une valeur zéro identifie le port par défaut d’un adaptateur miniport.

[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’indication de réception. 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 des structures NET_BUFFER attachées immédiatement après l’appel à FilterReceiveNetBufferLists .

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 dans la liste dans NetBufferLists incluent uniquement les données qui correspondent au filtre de paquets et à la liste d’adresses 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 d’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é.

NDIS_RECEIVE_FLAGS_SWITCH_SINGLE_SOURCE

Si cet indicateur est défini, tous les paquets d’une liste liée de structures NET_BUFFER_LIST proviennent du même port source de commutateur extensible Hyper-V.

Pour plus d’informations, consultez Indicateurs d’envoi et de réception du commutateur extensible Hyper-V.

Note Si chaque paquet de la liste liée des structures NET_BUFFER_LIST utilise le même port source, l’extension doit définir l’indicateur NDIS_RETURN_FLAGS_SWITCH_SINGLE_SOURCE dans le paramètre ReturnFlags de FilterReturnNetBufferLists une fois la demande de réception terminée. L’extension doit définir cet indicateur dans le paramètre ReturnFlags si elle appelle NdisFReturnNetBufferLists pour retourner des paquets qu’elle n’a pas créés ou clonés.

NDIS_RECEIVE_FLAGS_SWITCH_DESTINATION_GROUP

Si cet indicateur est défini, tous les paquets d’une liste liée de structures NET_BUFFER_LIST doivent être transférés vers le même port de destination de commutateur extensible.

Pour plus d’informations, consultez Indicateurs d’envoi et de réception du commutateur extensible Hyper-V.

Note Si chaque paquet de la liste liée des structures NET_BUFFER_LIST utilise les mêmes ports de destination, l’extension doit définir l’indicateur NDIS_RECEIVE_FLAGS_SWITCH_DESTINATION_GROUP dans le paramètre ReturnFlags de FilterReturnNetBufferLists une fois la demande de réception terminée. L’extension doit définir cet indicateur dans le paramètre ReturnFlags si elle appelle NdisFReturnNetBufferLists pour retourner des paquets qu’elle n’a pas créés ou clonés.

Valeur de retour

None

Remarques

FilterReceiveNetBufferLists est une fonction facultative. Si un pilote de filtre ne filtre pas les indications de réception, il peut définir le point d’entrée de cette fonction sur NULL lorsqu’il appelle le Fonction NdisFRegisterFilterDriver .

Note Un pilote de filtre qui fournit une fonction FilterReceiveNetBufferLists doit fournir une fonction FilterStatus .

Le pilote de filtre peut appeler la fonction NdisSetOptionalHandlers , à partir de la fonction FilterSetModuleOptions , pour spécifier une fonction FilterReceiveNetBufferLists pour un module de filtre.

NDIS appelle FilterReceiveNetBufferLists pour traiter les indications de réception initiées par les pilotes sous-jacents. NDIS peut également appeler cette fonction à la suite d’un bouclage.

Si le pilote de filtre n’a pas spécifié de fonction FilterReceiveNetBufferLists , NDIS appelle le pilote de filtre supérieur suivant dans la pile qui a spécifié une fonction FilterReceiveNetBufferLists . S’il n’existe aucun pilote de filtre de ce type, NDIS appelle un pilote qui se trouve trop Fonction ProtocolReceiveNetBufferLists .

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

Si l’indicateur NDIS_RECEIVE_FLAGS_RESOURCES dans le paramètre ReceiveFlags est défini, le pilote de filtre ne peut pas conserver la structure NET_BUFFER_LIST et les ressources allouées au pilote sous-jacent associées. Cet indicateur peut indiquer que le pilote sous-jacent est faible sur les ressources de réception. La fonction FilterReceiveNetBufferLists doit retourner aussi rapidement que possible. Avant de retourner, la fonction FilterReceiveNetBufferLists peut copier les données reçues dans le stockage alloué par un pilote de filtre ou transmettre la mémoire tampon en appelant le Fonction NdisFIndicateReceiveNetBufferLists .

Note Si l’indicateur NDIS_RECEIVE_FLAGS_RESOURCES est défini, le pilote de filtre 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.

Les pilotes de filtre peuvent filtrer les données reçues avant d’indiquer les données aux pilotes qui se superposent. Pour chaque mémoire tampon soumise à sa fonction FilterReceiveNetBufferLists , un pilote de filtre peut effectuer les opérations suivantes :

Passez la mémoire tampon au pilote supérieur en appelant le Fonction NdisFIndicateReceiveNetBufferLists .
Le pilote peut modifier le contenu de la mémoire tampon avant d’appeler NdisFIndicateReceiveNetBufferLists.

Le pilote peut modifier le paramètre d’indicateur de NDIS_RECEIVE_FLAGS_RESOURCES que NDIS a passé à FilterReceiveNetBufferLists ou le transmettre simplement à NdisFIndicateReceiveNetBufferLists.
Ignorez la mémoire tampon. Si NDIS a effacé l’indicateur NDIS_RECEIVE_FLAGS_RESOURCES , appelez la fonction NdisFReturnNetBufferLists pour ignorer la mémoire tampon. Si NDIS définit l’indicateur NDIS_RECEIVE_FLAGS_RESOURCES , n’effectuez aucune action et retournez à partir de FilterReceiveNetBufferLists pour ignorer la mémoire tampon.
Mettre en file d’attente la mémoire tampon dans une structure de données locale pour un traitement ultérieur. Si NDIS définit l’indicateur de NDIS_RECEIVE_FLAGS_RESOURCESde FilterReceiveNetBufferLists, le pilote de filtre doit créer une copie avant de retourner à partir de FilterReceiveNetBufferLists.
Copiez la mémoire tampon et proviennent d’une indication de réception avec la copie. L’indication de réception est similaire à une indication de réception initiée par le filtre. Dans ce cas, le pilote doit retourner la mémoire tampon d’origine au pilote sous-jacent.

Si le pilote de filtre a appelé NdisFIndicateReceiveNetBufferLists et n’a pas défini l’indicateur NDIS_RECEIVE_FLAGS_RESOURCES , NDIS appelle le Fonction FilterReturnNetBufferLists pour le module de filtre. Dans sa fonction FilterReturnNetBufferLists , le pilote de filtre annule les opérations qu’il a effectuées sur la mémoire tampon sur le chemin d’indication de réception.

Si un module de filtre est à l’état Suspendu , le pilote de filtre ne doit pas être à l’origine des indications de réception pour ce module de filtre. Le pilote de filtre ne doit pas transmettre les mémoires tampons qu’il a créées à NdisFIndicateReceiveNetBufferLists. Toutefois, le pilote peut transmettre une indication de réception d’un pilote sous-jacent.

NDIS appelle FilterReceiveNetBufferLists à IRQL <= DISPATCH_LEVEL.

Exemples

Pour définir une fonction FilterReceiveNetBufferLists , 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 FilterReceiveNetBufferLists nommée « MyReceiveNetBufferLists », utilisez le type FILTER_RECEIVE_NET_BUFFER_LISTS comme indiqué dans cet exemple de code :

FILTER_RECEIVE_NET_BUFFER_LISTS MyReceiveNetBufferLists;

Ensuite, implémentez votre fonction comme suit :

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

Le type de fonction FILTER_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 FILTER_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