Funzione FwpsStreamInjectAsync0 (fwpsk.h)

Articolo
02/26/2024

La funzione FwpsStreamInjectAsync0 inserisce segmenti di dati TCP in un flusso di dati TCP.

NotaFwpsStreamInjectAsync0 è una versione specifica di FwpsStreamInjectAsync. Per altre informazioni, vedere Wfp Version-Independent Names and Targeting Specific Versions of Windows .See WFP Version-Independent Names and Targeting Specific Versions of Windows.See WFP Version-Independent Names and Targeting Specific Versions of Windows for more information.

Sintassi

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
);

Parametri

[in] injectionHandle

Handle injection creato in precedenza da una chiamata all'oggetto Funzione FwpsChangectionHandleCreate0 .

[in, optional] injectionContext

Handle facoltativo per il contesto di inserimento.

[in] flags

Riservato. I driver di callout devono impostare questo parametro su zero.

[in] flowId

Identificatore di runtime che specifica il flusso di dati in cui inserire i dati. L'identificatore di runtime per un flusso di dati viene fornito a un driver di callout tramite il valore dei metadati FWPS_METADATA_FIELD_FLOW_HANDLE fornito dal motore di filtro fornito alla funzione di callout del driver di callout del callout del callout del driver.

[in] calloutId

Identificatore di runtime per il callout nel motore di filtro. Questo identificatore è stato restituito quando il driver callout ha chiamato le funzioni FwpsCalloutRegister0 o FwpsCalloutRegister1 per registrare il callout con il motore di filtro.

[in] layerId

Identificatore di runtime per il livello di filtro in cui viene elaborato il flusso di dati. Questo valore deve essere FWPS_LAYER_STREAM_V4 o FWPS_LAYER_STREAM_V6. L'identificatore di runtime per il livello in cui viene elaborato il flusso di dati viene fornito a un callout nel membro layerId della struttura FWPS_INCOMING_VALUES0 che il motore di filtro passato alla funzione di callout del driver classifyFn del callout.

[in] streamFlags

Flag che specificano le caratteristiche del flusso di dati in cui inserire i dati.

Quando si inseriscono dati in un flusso di dati in ingresso, un driver di callout specifica uno o più dei flag seguenti:

FWPS_STREAM_FLAG_RECEIVE

Specifica che i dati devono essere inseriti nel flusso di dati in ingresso. Questo flag è obbligatorio quando si inseriscono dati in un flusso di dati in ingresso.

FWPS_STREAM_FLAG_RECEIVE_DISCONNECT

Specifica che il flag FIN deve essere impostato nell'intestazione TCP per i dati inseriti nel flusso di dati in ingresso.

Nota Se questo flag è impostato, è necessario impostare anche il flag di FWPS_STREAM_FLAG_RECEIVE oppure STATUS_FWP_INVALID_PARAMETER verrà restituito.

FWPS_STREAM_FLAG_RECEIVE_EXPEDITED

Specifica che i dati inseriti nel flusso di dati in ingresso sono dati out-of-band con priorità elevata.

FWPS_STREAM_FLAG_RECEIVE_PUSH

Specifica che i dati in ingresso sono arrivati con il flag PUSH impostato nell'intestazione TCP, che indica che il mittente richiede il trasferimento immediato dei dati. I ritardi indesiderati nel trasferimento dei dati possono verificarsi se questo flag non è impostato. Questo flag è disponibile a partire da Windows Vista con SP1.

Quando si inseriscono dati in un flusso di dati in uscita, un driver di callout specifica uno o più dei flag seguenti:

FWPS_STREAM_FLAG_SEND

Specifica che i dati devono essere inseriti nel flusso di dati in uscita. Questo flag è obbligatorio quando si inseriscono dati in un flusso di dati in uscita.

FWPS_STREAM_FLAG_SEND_EXPEDITED

Specifica che i dati inseriti nel flusso di dati in uscita sono dati out-of-band con priorità elevata.

FWPS_STREAM_FLAG_SEND_NODELAY

Specifica che il driver del callout richiede che non vi sia alcun buffering dei dati inseriti nel flusso di dati in uscita.

FWPS_STREAM_FLAG_SEND_DISCONNECT

Specifica che il flusso deve essere disconnesso dopo l'invio dei dati nel flusso di dati in uscita. Lo stack di rete imposterà il flag FIN nell'intestazione TCP dell'ultimo pacchetto inviato.

Nota Se questo flag è impostato, è necessario impostare anche il flag di FWPS_STREAM_FLAG_SEND oppure STATUS_FWP_INVALID_PARAMETER verrà restituito.

[in, out] netBufferList

Puntatore a una struttura NET_BUFFER_LIST che descrive i dati inseriti nel flusso di dati. Un driver di callout alloca una struttura di NET_BUFFER_LIST da usare per inserire dati in un flusso di dati chiamando Funzioni FwpsAllocateCloneNetBufferList0, FwpsAllocateNetBufferAndNetBufferList0 o FwpsCloneStreamData0 . La struttura NET_BUFFER_LIST può descrivere una catena di elenchi di buffer di rete. Se il parametro streamFlags è FWPS_STREAM_FLAG_RECEIVE_DISCONNECT o FWPS_STREAM_FLAG_SEND_DISCONNECT, netBufferList può essere NULL.

[in] dataLength

Numero di byte di dati inseriti nel flusso di dati.

[in] completionFn

Puntatore a una funzione callout completionFn fornita dal driver del callout. Il motore di filtro chiama questa funzione dopo che i dati del pacchetto, descritti dal parametro netBufferList , sono stati inseriti nello stack di rete.

Se il parametro netBufferList descrive una catena di NET_BUFFER_LIST , completionFn verrà chiamato una volta per ogni NET_BUFFER_LIST nella catena.

Se il parametro netBufferList è NULL e il parametro streamFlags ha FWPS_STREAM_FLAG_RECEIVE_DISCONNECT o FWPS_STREAM_FLAG_SEND_DISCONNECT impostato, la funzione completionFn non verrà chiamata.

Questo parametro è obbligatorio e non può essere NULL. Se è NULL, verrà restituito STATUS_FWP_NULL_POINTER .

[in, optional] completionContext

Puntatore a un contesto fornito dal driver di callout passato alla funzione callout a cui punta il parametro completionFn . Questo parametro è facoltativo e può essere NULL.

Valore restituito

La funzione FwpsStreamInjectAsync0 è un codice NTSTATUS, ad esempio uno dei seguenti.

Codice restituito	Descrizione
STATUS_SUCCESS	L'inserimento nel flusso di dati è stato avviato correttamente. Il motore di filtro chiamerà la funzione di completamento specificata quando la struttura NET_BUFFER_LIST è stata allocata dopo che il motore di filtro ha completato l'inserimento dei dati nel flusso di dati.
STATUS_FWP_TCPIP_NOT_READY	Lo stack di rete TCP/IP non è pronto per accettare l'inserimento di dati di flusso.
STATUS_FWP_INJECT_HANDLE_CLOSING	L'handle di inserimento viene chiuso.
Altri codici di stato	Si è verificato un errore.

Commenti

Un driver callout chiama la funzione FwpsStreamInjectAsync0 dall'interno della funzione di callout classifyFn di un callout per inserire dati nuovi o clonati nel flusso di dati attualmente in fase di elaborazione. Un driver callout può chiamare la funzione FwpsStreamInjectAsync0 solo se elabora un flusso di dati a livello di flusso.

Un driver di callout può anche chiamare la funzione FwpsStreamInjectAsync0 dall'esterno della funzione di callout classifyFn di un callout del callout per inserire dati in un flusso di dati attualmente posticipato. Un flusso di dati viene posticipato quando la funzione di callout classifyFn di un callout imposta il membro streamAction dell'oggetto FWPS_STREAM_CALLOUT_IO_PACKET0 struttura da FWPS_STREAM_ACTION_DEFER.

Inoltre, un driver callout può chiamare la funzione FwpsStreamInjectAsync0 dall'esterno della funzione di callout classifyFn di un callout del callout per inserire dati in un flusso di dati dopo che è stata inserita un'indicazione FIN.

In alternativa, un driver callout può chiamare la funzione FwpsStreamInjectAsync0 da un contesto di thread arbitrario all'esterno di una funzione callout classifyFn di callout se il driver callout clona e blocca tutti i dati indicati per l'elaborazione fuori banda. Un driver callout che reindirizza tutti i dati indicati alla modalità utente per l'elaborazione può chiamare la funzione FwpsStreamInjectAsync0 in questo modo.

Un callout può creare un segmento di dati clonandolo prima con una chiamata alla funzione FwpsCloneStreamData0 , seguita dal blocco del segmento di dati impostando FWP_ACTION_BLOCK nel membro actionType della struttura FWPS_CLASSIFY_OUT0 .

I dati del flusso inseriti non verranno reindicati al callout, ma saranno resi disponibili per trasmettere i callout dai sottostrati di peso inferiore.

Se il valore restituito non è STATUS_SUCCESS, la funzione di completamento non verrà chiamata. In questo caso, l'elenco di buffer di rete a cui punta netBufferList deve essere liberato da una chiamata a FwpsFreeNetBufferList0 o FwpsFreeCloneNetBufferList0.

Requisiti

Requisito	Valore
Client minimo supportato	Disponibile a partire da Windows Vista.
Piattaforma di destinazione	Universale
Intestazione	fwpsk.h (include Fwpsk.h)
Libreria	Fwpkclnt.lib
IRQL	<= DISPATCH_LEVEL