Fonction FwpsStreamInjectAsync0 (fwpsk.h)

Article
08/07/2023

La fonction FwpsStreamInjectAsync0 injecte des segments de données TCP dans un flux de données TCP.

RemarqueFwpsStreamInjectAsync0 est une version spécifique de FwpsStreamInjectAsync. Pour plus d’informations , consultez WFP Version-Independent Names and Targeting Specific Versions of Windows .

Syntaxe

NTSTATUS FwpsStreamInjectAsync0(
  [in]           HANDLE                injectionHandle,
  [in, optional] HANDLE                injectionContext,
  [in]           UINT32                flags,
  [in]           UINT64                flowId,
  [in]           UINT32                calloutId,
  [in]           UINT16                layerId,
  [in]           UINT32                streamFlags,
  [in, out]      NET_BUFFER_LIST       *netBufferList,
  [in]           SIZE_T                dataLength,
  [in]           FWPS_INJECT_COMPLETE0 completionFn,
  [in, optional] HANDLE                completionContext
);

Paramètres

[in] injectionHandle

Handle d’injection précédemment créé par un appel à Fonction FwpsInjectionHandleCreate0 .

[in, optional] injectionContext

Handle facultatif pour le contexte d’injection.

[in] flags

Réservé. Les pilotes de légende doivent définir ce paramètre sur zéro.

[in] flowId

Identificateur d’exécution qui spécifie le flux de données dans lequel injecter les données. L’identificateur d’exécution d’un flux de données est fourni à un pilote de légende via la valeur de métadonnées FWPS_METADATA_FIELD_FLOW_HANDLE que le moteur de filtre a fournie à la fonction de légende classifyFn du pilote de légende.

[in] calloutId

Identificateur d’exécution de la légende dans le moteur de filtre. Cet identificateur a été retourné lorsque le pilote de légende a appelé les fonctions FwpsCalloutRegister0 ou FwpsCalloutRegister1 pour inscrire la légende auprès du moteur de filtre.

[in] layerId

Identificateur d’exécution de la couche de filtrage au niveau de laquelle le flux de données est traité. Cette valeur doit être FWPS_LAYER_STREAM_V4 ou FWPS_LAYER_STREAM_V6. L’identificateur d’exécution de la couche au niveau de laquelle le flux de données est traité est fourni à une légende dans le membre layerId de la structure FWPS_INCOMING_VALUES0 que le moteur de filtre a transmise à la fonction de légende classifyFn du pilote de légende.

[in] streamFlags

Indicateurs qui spécifient les caractéristiques du flux de données dans lequel les données doivent être injectées.

Lors de l’injection de données dans un flux de données entrantes, un pilote de légende spécifie un ou plusieurs des indicateurs suivants :

FWPS_STREAM_FLAG_RECEIVE

Spécifie que les données doivent être injectées dans le flux de données entrantes. Cet indicateur est requis lors de l’injection de données dans un flux de données entrant.

FWPS_STREAM_FLAG_RECEIVE_DISCONNECT

Spécifie que l’indicateur FIN doit être défini dans l’en-tête TCP pour les données injectées dans le flux de données entrantes.

Note Si cet indicateur est défini, l’indicateur FWPS_STREAM_FLAG_RECEIVE doit également être défini, sinon STATUS_FWP_INVALID_PARAMETER sera retourné.

FWPS_STREAM_FLAG_RECEIVE_EXPEDITED

Spécifie que les données injectées dans le flux de données entrantes sont des données hors bande de priorité élevée.

FWPS_STREAM_FLAG_RECEIVE_PUSH

Spécifie que les données entrantes sont arrivées avec l’indicateur PUSH défini dans l’en-tête TCP, ce qui indique que l’expéditeur demande un transfert de données immédiat. Des retards indésirables dans le transfert de données peuvent se produire si cet indicateur n’est pas défini. Cet indicateur est disponible à partir de Windows Vista avec SP1.

Lors de l’injection de données dans un flux de données sortant, un pilote de légende spécifie un ou plusieurs des indicateurs suivants :

FWPS_STREAM_FLAG_SEND

Spécifie que les données doivent être injectées dans le flux de données sortant. Cet indicateur est requis lors de l’injection de données dans un flux de données sortant.

FWPS_STREAM_FLAG_SEND_EXPEDITED

Spécifie que les données injectées dans le flux de données sortantes sont des données hors bande de priorité élevée.

FWPS_STREAM_FLAG_SEND_NODELAY

Spécifie que le pilote de légende demande qu’il n’y ait pas de mise en mémoire tampon des données injectées dans le flux de données sortant.

FWPS_STREAM_FLAG_SEND_DISCONNECT

Spécifie que le flux doit être déconnecté une fois que les données injectées dans le flux de données sortantes ont été envoyées. La pile réseau définit l’indicateur FIN dans l’en-tête TCP du dernier paquet envoyé.

Note Si cet indicateur est défini, l’indicateur FWPS_STREAM_FLAG_SEND doit également être défini, sinon STATUS_FWP_INVALID_PARAMETER est retourné.

[in, out] netBufferList

Pointeur vers une structure de NET_BUFFER_LIST qui décrit les données injectées dans le flux de données. Un pilote de légende alloue une structure NET_BUFFER_LIST à utiliser pour injecter des données dans un flux de données en appelant le Fonctions FwpsAllocateCloneNetBufferList0, FwpsAllocateNetBufferAndNetBufferList0 ou FwpsCloneStreamData0 . La structure NET_BUFFER_LIST peut décrire une chaîne de listes de mémoires tampons réseau. Si le paramètre streamFlags est FWPS_STREAM_FLAG_RECEIVE_DISCONNECT ou FWPS_STREAM_FLAG_SEND_DISCONNECT, netBufferList peut avoir la valeur NULL.

[in] dataLength

Nombre d’octets de données injectées dans le flux de données.

[in] completionFn

Pointeur vers une fonction de légende completionFn fournie par le pilote de légende. Le moteur de filtre appelle cette fonction après que les données de paquet, décrites par le paramètre netBufferList , ont été injectées dans la pile réseau.

Si le paramètre netBufferList décrit une chaîne NET_BUFFER_LIST , completionFn est appelé une fois pour chaque NET_BUFFER_LIST de la chaîne.

Si le paramètre netBufferList a la valeur NULL et que le paramètre streamFlags a FWPS_STREAM_FLAG_RECEIVE_DISCONNECT ou FWPS_STREAM_FLAG_SEND_DISCONNECT défini, la fonction completionFn n’est pas appelée.

Ce paramètre est obligatoire et ne peut pas être NULL. S’il a la valeur NULL, STATUS_FWP_NULL_POINTER sera retourné.

[in, optional] completionContext

Pointeur vers un contexte fourni par le pilote de légende qui est passé à la fonction de légende pointée par le paramètre completionFn . Ce paramètre est facultatif et peut être NULL.

Valeur retournée

La fonction FwpsStreamInjectAsync0 est un code NTSTATUS comme l’un des suivants.

Code de retour	Description
STATUS_SUCCESS	L’injection dans le flux de données a été lancée avec succès. Le moteur de filtre appelle la fonction d’achèvement qui a été spécifiée lorsque la structure NET_BUFFER_LIST a été allouée une fois que le moteur de filtre a terminé d’injecter les données dans le flux de données.
STATUS_FWP_TCPIP_NOT_READY	La pile réseau TCP/IP n’est pas prête à accepter l’injection de données de flux.
STATUS_FWP_INJECT_HANDLE_CLOSING	La poignée d’injection est en cours de fermeture.
Autres codes status	Une erreur est survenue.

Remarques

Un pilote de légende appelle la fonction FwpsStreamInjectAsync0 à partir de la fonction de légende classifyFn d’une légende pour injecter des données nouvelles ou clonées dans le flux de données en cours de traitement. Un pilote de légende peut appeler la fonction FwpsStreamInjectAsync0 uniquement s’il traite un flux de données au niveau de la couche de flux.

Un pilote de légende peut également appeler la fonction FwpsStreamInjectAsync0 en dehors de la fonction de légende classifyFn d’une légende pour injecter des données dans un flux de données actuellement différé. Un flux de données est différé lorsque la fonction de légende classifyFn d’une légende définit le membre streamAction du FWPS_STREAM_CALLOUT_IO_PACKET0 structure à FWPS_STREAM_ACTION_DEFER.

En outre, un pilote de légende peut appeler la fonction FwpsStreamInjectAsync0 à partir de l’extérieur de la fonction de légende classifyFn d’une légende pour injecter des données dans un flux de données après qu’une indication FIN a été suspendu.

Un pilote de légende peut également appeler la fonction FwpsStreamInjectAsync0 à partir d’un contexte de thread arbitraire en dehors de la fonction de légende classifyFn d’une légende si le pilote de légende clone et bloque toutes les données indiquées pour le traitement hors bande. Un pilote de légende qui redirige toutes les données indiquées vers le mode utilisateur pour traitement peut appeler la fonction FwpsStreamInjectAsync0 de cette façon.

Une légende peut pendre un segment de données en le clonant d’abord avec un appel à la fonction FwpsCloneStreamData0 , puis en bloquant le segment de données en définissant FWP_ACTION_BLOCK dans le membre actionType de la structure FWPS_CLASSIFY_OUT0 .

Les données de flux injectées ne seront pas réindicées à la légende, mais elles seront mises à disposition pour diffuser en continu des légendes à partir de sous-couches de poids inférieur.

Si la valeur de retour n’est pas STATUS_SUCCESS, la fonction d’achèvement n’est pas appelée. Dans ce cas, la liste de mémoires tampons réseau pointée par netBufferList doit être libérée par un appel à FwpsFreeNetBufferList0 ou FwpsFreeCloneNetBufferList0.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Disponible à partir de Windows Vista.
Plateforme cible	Universal
En-tête	fwpsk.h (include Fwpsk.h)
Bibliothèque	Fwpkclnt.lib
IRQL	<= DISPATCH_LEVEL