NDIS_TCP_OFFLOAD_RECEIVE_INDICATE fonction de rappel (ndischimney.h)

Article
08/07/2023

[La fonctionnalité de déchargement de cheminée TCP est déconseillée et ne doit pas être utilisée.]

Une cible de déchargement appelle la fonction NdisTcpOffloadReceiveHandler pour indiquer que les données réseau reçues sont disponibles pour la consommation par une application cliente.

Syntaxe

NDIS_TCP_OFFLOAD_RECEIVE_INDICATE NdisTcpOffloadReceiveIndicate;

NDIS_STATUS NdisTcpOffloadReceiveIndicate(
  [in]  IN NDIS_HANDLE NdisOffloadHandle,
  [in]  IN PNET_BUFFER_LIST NetBufferList,
  [in]  IN NDIS_STATUS Status,
  [out] OUT PULONG BytesConsumed
)
{...}

Paramètres

[in] NdisOffloadHandle

Handle qui identifie la connexion TCP déchargée sur laquelle l’indication est effectuée. Lorsque la connexion a été déchargée, ce handle a été fourni dans le membre NdisOffloadHandle du NDIS_MINIPORT_OFFLOAD_BLOCK_LIST structure associée à l’état de connexion.

[in] NetBufferList

Pointeur vers une structure NET_BUFFER_LIST . Chaque structure NET_BUFFER_LIST décrit une liste de structures NET_BUFFER . Chaque structure NET_BUFFER dans la liste est mappée à une chaîne de listes de descripteurs mémoire (MDL). Les dll MDL contiennent les données reçues. Les dll MDL sont verrouillées afin qu’elles restent résidentes, mais elles ne sont pas mappées dans la mémoire système.

La structure NET_BUFFER_LIST spécifiée par NetBufferList doit être une structure autonome et ne peut pas être la première structure d’une liste liée de structures NET_BUFFER_LIST . Les cibles de déchargement peuvent contourner cette limitation en chaînant autant de DLL que nécessaire à la même NET_BUFFER dans une indication de réception de déchargement.

[in] Status

La cible de déchargement doit fournir la valeur status suivante :

NDIS_STATUS_SUCCESS

Cela indique que la pile hôte peut conserver la propriété des structures NET_BUFFER_LIST et des structures associées jusqu’à ce qu’elle retourne ces structures à la Fonction MiniportTcpOffloadReceiveReturn de la cible de déchargement.

[out] BytesConsumed

Pointeur vers une variable de type ULONG qui reçoit le nombre d’octets consommés par l’application cliente.

Valeur retournée

La fonction NdisTcpOffloadReceiveHandler peut retourner l’une des valeurs suivantes :

Code de retour	Description
NDIS_STATUS_SUCCESS	L’application cliente a consommé toutes les données de réception indiquées.
NDIS_STATUS_OFFLOAD_DATA_NOT_ACCEPTED	L’application cliente a rejeté toutes les données de réception indiquées.
NDIS_STATUS_OFFLOAD_DATA_PARTIALLY_ACCEPTED	L’application cliente a consommé un sous-ensemble des données de réception indiquées. La quantité de données, en octets, qui ont été consommées par l’application cliente est retournée dans la variable spécifiée par le paramètre BytesConsumed .

Remarques

Les mémoires tampons de réception sont publiées dans le Fonction MiniportTcpOffloadReceive de la cible de déchargement. Si les demandes de réception prépostées (mémoires tampons fournies par l’application cliente) sont disponibles pour la connexion, la cible de déchargement doit transférer les données de réception en appelant le Fonction NdisTcpOffloadReceiveComplete . Pour plus d’informations, consultez Algorithme de remise.

Toutes les demandes de réception doivent être effectuées par la cible de déchargement (même s’il s’agit de demandes de réception de zéro octet).

Une fois qu’une cible de déchargement a indiqué recevoir des données et que les données ont été refusées, la cible de déchargement ne peut plus indiquer ces données tant que la pile hôte n’a pas affiché une demande de réception :

Demandes de réception normales
Si la pile hôte publie des demandes de réception normales, la cible de déchargement doit effectuer ces demandes avant d’effectuer des indications de réception. Pour plus d’informations, consultez Algorithme de remise.
Demandes de réception de zéro octet
La pile hôte peut publier une demande de réception de zéro octet pour activer les indications de réception par la cible de déchargement. Une demande de réception de zéro octet est une requête dans laquelle la valeur du membre DataLength (pour plus d’informations, consultez NET_BUFFER structure) est égale à zéro. Une demande de réception de zéro octet ne consomme aucune donnée mise en mémoire tampon.

Pendant l’initialisation, la cible de déchargement doit allouer deux pools de mémoires tampons, chacun contenant NET_BUFFER_LIST structures et NET_BUFFER structures. La cible de déchargement utilise un pool pour effectuer des indications de réception via la cheminée TCP lors de l’appel du Fonction NdisTcpOffloadReceiveHandler . La cible de déchargement utilise l’autre pool pour effectuer des indications de réception via l’interface NDIS de non-chargement lors de l’appel du Fonction NdisMIndicateReceiveNetBufferLists .

Chaque structure de NET_BUFFER_LIST allouée ne doit avoir qu’une seule structure NET_BUFFER associée. Le nombre de ces structures à allouer est à la hauteur de l’enregistreur de pilotes. Pour plus d’informations sur l’allocation de ces structures, consultez Gestion de la mémoire tampon du pilote Miniport.

À condition qu’elle n’effectue pas d’accusé de réception différé, la cible de déchargement doit accuser réception des données reçues dès que la cible de déchargement dispose de mémoires tampons internes dans lesquelles elle peut déposer les données. La cible de déchargement peut accuser réception des données reçues avant, pendant ou après l’appel de la fonction NdisTcpOffloadReceiveHandler .

La cible de déchargement fournit toujours une valeur Status de NDIS_STATUS_SUCCESS lors de l’appel de la fonction NdisTcpOffloadReceiveHandler . Cela indique que la pile hôte peut conserver la propriété des structures NET_BUFFER_LIST et des structures associées jusqu’à ce qu’elle retourne ces structures à la cible de déchargement.

Si la pile hôte retourne NDIS_STATUS_SUCCESS, indiquant que l’application cliente a accepté et consommé les données de réception, la pile hôte retourne les structures NET_BUFFER_LIST à la Fonction MiniportTcpOffloadReceiveReturn de la cible de déchargement. La pile hôte définit la variable spécifiée par le paramètre BytesConsumed sur le nombre d’octets qui ont été indiqués par la cible de déchargement.
Si la pile hôte retourne NDIS_STATUS_NOT_ACCEPTED, indiquant que l’application cliente a rejeté les données de réception, la cible de déchargement reprend la propriété des structures NET_BUFFER_LIST indiquées au retour de la fonction NdisTcpOffloadReceiveHandler . La cible de déchargement doit mettre en mémoire tampon les données de réception en prévision du fait que l’application cliente publiera des mémoires tampons de réception sur la connexion. Une fois que l’application cliente publie des mémoires tampons, la cible de déchargement copie les données de réception mises en mémoire tampon dans les mémoires tampons publiées et termine les mémoires tampons publiées en appelant le Fonction NdisTcpOffloadReceiveComplete . Pour plus d’informations, consultez Algorithme de remise. La pile hôte définit la variable spécifiée par le paramètre BytesConsumed sur zéro.
Si la pile hôte retourne NDIS_STATUS_OFFLOAD_DATA_PARTIALLY_ACCEPTED, indiquant que l’application cliente a consommé un sous-ensemble des données de réception, la cible de déchargement reprend la propriété des structures NET_BUFFER_LIST indiquées lorsque la fonction NdisTcpOffloadReceiveHandler retourne. La pile hôte définit la variable spécifiée par le paramètre BytesConsumed sur une valeur différente de zéro qui spécifie la quantité de données, en octets, qui a été consommée par l’application cliente. La cible de déchargement doit mettre en mémoire tampon les données de réception restantes en prévision du fait que l’application cliente publiera les mémoires tampons de réception sur la connexion.

Notez que la cible de déchargement ne fournit jamais une valeur Status de NDIS_STATUS_RESOURCES lors de l’appel de la fonction NdisTcpOffloadReceiveHandler .

Dans le membre RcvIndicationSize de la structure TCP_OFFLOAD_STATE_CACHED, la pile hôte peut spécifier le nombre optimal d’octets de données que la cible de déchargement doit fournir en un seul appel à la fonction NdisTcpOffloadReceiveHandler . Pour plus d’informations, consultez Utilisation de la taille d’indication de réception spécifiée.