FwpsStreamInjectAsync0 (Compact 2013)

3/26/2014

This function injects TCP data segments into a TCP data stream.

Syntax

NTSTATUS NTAPI
  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 OPTIONAL NET_BUFFER_LIST  *netBufferList,
    IN SIZE_T  dataLength
    IN FWPS_INJECT_COMPLETE0  completionFn,
    IN OPTIONAL HANDLE  completionContext
    );

Parameters

• injectionHandle
  An injection handle that was previously created by a call to the FwpsInjectionHandleCreate0 function, with the flags parameter set to FWPS_INJECTION_TYPE_NETWORK

• injectionContext
  An optional handle to the injection context

• flags
  Reserved. Callout drivers must set this parameter to zero.

• flowId
  A run-time identifier that specifies the data flow into which to insert the data. The run-time identifier for a data flow is provided to a callout driver through the FWPS_METADATA_FIELD_FLOW_HANDLE metadata value that the WFP Filter Engine provided to the callout's classifyFn callout function.

• calloutId
  The run-time identifier for the callout in the filter engine. This is the same identifier that was returned when the callout driver called the FwpsCalloutRegister0 function to register the callout with the filter engine.

• layerId
  The run-time identifier for the filtering layer at which the data stream is being processed. This value must be either FWPS_LAYER_STREAM_V4 or FWPS_LAYER_STREAM_V6. The run-time identifier for the layer at which the data stream is being processed is provided to a callout in the layerId member of the FWPS_INCOMING_VALUES0 structure that the filter engine passed to the callout's classifyFn callout function.

• streamFlags
  Flags that specify characteristics of the data stream into which the data is to be injected.

  When injecting data into an incoming data stream, a callout driver specifies one or more of the following flags:

  • FWPS_STREAM_FLAG_RECEIVE: Specifies that the data is to be injected into the incoming data stream. This flag is required when injecting data into an incoming data stream.
  • FWPS_STREAM_FLAG_RECEIVE_DISCONNECT: Specifies that the FIN flag is to be set in the TCP header for the data being injected into the incoming data stream.
  • FWPS_STREAM_FLAG_RECEIVE_EXPEDITED: Specifies that the data being injected into the incoming data stream is high-priority, out-of-band data.
  • FWPS_STREAM_FLAG_RECEIVE_PUSH: Specifies that the incoming data has arrived with the PUSH flag set in the TCP header, which indicates that the sender requests immediate data transfer. Unwanted delays in data transfer can occur if this flag is not set.

  When injecting data into an outgoing data stream, a callout driver specifies one or more of the following flags:

  • FWPS_STREAM_FLAG_SEND: Specifies that the data is to be injected into the outgoing data stream. This flag is required when injecting data into an outgoing data stream.
  • FWPS_STREAM_FLAG_SEND_EXPEDITED: Specifies that the data being injected into the outgoing data stream is high-priority, out-of-band data.
  • FWPS_STREAM_FLAG_SEND_NODELAY: Specifies that the callout driver requests that there is no buffering of the data being injected into the outgoing data stream.
  • FWPS_STREAM_FLAG_SEND_DISCONNECT: Specifies that the stream is to be disconnected after the data being injected into the outgoing data stream has been sent. The network stack will set the FIN flag in the TCP header of the last packet that is sent out.

• netBufferList
  A pointer to a NET_BUFFER_LIST structure that describes the packet data that is being injected. A callout driver allocates a NET_BUFFER_LIST structure to use to insert packet data by calling either the FwpsAllocateCloneNetBufferList0 function or the FwpsAllocateNetBufferAndNetBufferList0 function. The NET_BUFFER_LIST structure can describe a chain of net buffer lists. If the streamFlags parameter is FWPS_STREAM_FLAG_RECEIVE_DISCONNECT or FWPS_STREAM_FLAG_SEND_DISCONNECT, netBufferList can be NULL.

• dataLength
  The number of bytes of data being injected into the data stream

• completionFn
  A pointer to a completionFn callout function that is provided by the callout driver. The filter engine calls this function after the packet data described by the netBufferList parameter is injected into the network stack. If the netBufferList parameter describes a NET_BUFFER_LIST chain, completionFn is called one time for each NET_BUFFER_LIST in the chain.

• completionContext
  A pointer to a callout driver-provided context that is passed to the callout function pointed to by the completionFn parameter. This parameter is optional and can be NULL

Return Value

The FwpsStreamInjectAsync0 function returns one of the following NTSTATUS codes:

Remarks

A callout driver calls the FwpsStreamInjectAsync0 function from inside a callout's classifyFn callout function to insert new or cloned data into the data stream that is currently being processed. A callout driver can call the FwpsStreamInjectAsync0 function if it is processing a data flow at the stream layer only.

A callout driver can also call the FwpsStreamInjectAsync0 function from outside a callout's classifyFn callout function to insert data into a data stream that is currently deferred. A data stream is deferred when a callout's classifyFn callout function sets the streamAction member of the FWPS_STREAM_CALLOUT_IO_PACKET0 structure to FWPS_STREAM_ACTION_DEFER.

A callout driver can call the FwpsStreamInjectAsync0 function from outside a callout's classifyFn callout function to insert data into a data stream after a FIN indication has been pended.

A callout driver can also call the FwpsStreamInjectAsync0 function from an arbitrary thread context outside a callout's classifyFn callout function if the callout driver clones and blocks all data that has been indicated for out-of-band processing. A callout driver that redirects all indicated data to user mode for processing can call the FwpsStreamInjectAsync0 function in this manner.

A callout can pend a data segment by first cloning it with a call to the FwpsCloneStreamData0 function, followed by blocking the data segment by setting FWP_ACTION_BLOCK in the actionType member of the FWPS_CLASSIFY_OUT0 structure.

Injected stream data is not re-indicated to the callout, but is made available to stream callouts from lower-weight sublayers.

If the return value is not STATUS_SUCCESS, the completion function is not called. In this case, the NET_BUFFER_LIST pointed to by netBufferList must be freed by a call to FwpsFreeNetBufferList0 or FwpsFreeCloneNetBufferList0.

Requirements

See Also

Reference

Functions Called by Callout Drivers
classifyFn
completionFn
FwpsAllocateCloneNetBufferList0
FwpsAllocateNetBufferAndNetBufferList0
FwpsCalloutRegister0
FwpsCloneStreamData0
FwpsInjectionHandleCreate0
FwpsInjectionHandleDestroy0
FWPS_INCOMING_VALUES0
NET_BUFFER_LIST
FWPS_STREAM_CALLOUT_IO_PACKET0
WFP Callout Driver Functions