FwpsStreamInjectAsync0 function (fwpsk.h)
The FwpsStreamInjectAsync0 function injects TCP data segments into a TCP data stream.
Syntax
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
);
Parameters
[in] injectionHandle
An injection handle that was previously created by a call to the FwpsInjectionHandleCreate0 function.
[in, optional] injectionContext
An optional handle to the injection context.
[in] flags
Reserved. Callout drivers should set this parameter to zero.
[in] flowId
A run-time identifier that specifies the data flow into which to inject 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 filter engine provided to the callout driver's classifyFn callout function.
[in] calloutId
The run-time identifier for the callout in the filter engine. This identifier was returned when the callout driver called either the FwpsCalloutRegister0 or FwpsCalloutRegister1 functions to register the callout with the filter engine.
[in] 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 driver's classifyFn callout function.
[in] streamFlags
Flags that specify characteristics of the data stream into which the data is to be injected.
When injecting data into an inbound 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 inbound data stream. This flag is required when injecting data into an inbound 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 inbound data stream.
FWPS_STREAM_FLAG_RECEIVE_EXPEDITED
Specifies that the data being injected into the inbound data stream is high-priority, out-of-band data.
FWPS_STREAM_FLAG_RECEIVE_PUSH
Specifies that the inbound 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. This flag is available starting with Windows Vista with SP1.
When injecting data into an outbound 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 outbound data stream. This flag is required when injecting data into an outbound data stream.
FWPS_STREAM_FLAG_SEND_EXPEDITED
Specifies that the data being injected into the outbound 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 outbound data stream.
FWPS_STREAM_FLAG_SEND_DISCONNECT
Specifies that the stream is to be disconnected after the data being injected into the outbound 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.
[in, out] netBufferList
A pointer to a NET_BUFFER_LIST structure that describes the data that is being injected into the data stream. A callout driver allocates a NET_BUFFER_LIST structure to use for injecting data into a data stream by calling the FwpsAllocateCloneNetBufferList0, FwpsAllocateNetBufferAndNetBufferList0, or FwpsCloneStreamData0 functions. The NET_BUFFER_LIST structure can describe a chain of network buffer lists. If the streamFlags parameter is FWPS_STREAM_FLAG_RECEIVE_DISCONNECT or FWPS_STREAM_FLAG_SEND_DISCONNECT, netBufferList can be NULL.
[in] dataLength
The number of bytes of data being injected into the data stream.
[in] completionFn
A pointer to a completionFn callout function provided by the callout driver. The filter engine calls this function after the packet data, described by the netBufferList parameter, has been injected into the network stack.
If the netBufferList parameter describes a NET_BUFFER_LIST chain, completionFn will be called once for each NET_BUFFER_LIST in the chain.
If the netBufferList parameter is NULL and the streamFlags parameter has either FWPS_STREAM_FLAG_RECEIVE_DISCONNECT or FWPS_STREAM_FLAG_SEND_DISCONNECT set, the completionFn function will not be called.
This parameter is required and cannot be NULL. If it is NULL, STATUS_FWP_NULL_POINTER will be returned.
[in, optional] 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 an NTSTATUS code such as one of the following.
| Return code | Description |
|---|---|
|
The injection into the data stream was initiated successfully. The filter engine will call the completion function that was specified when the NET_BUFFER_LIST structure was allocated after the filter engine has completed injecting the data into the data stream. |
|
The TCP/IP network stack is not ready to accept injection of stream data. |
|
The injection handle is being closed. |
|
An error occurred. |
Remarks
A callout driver calls the FwpsStreamInjectAsync0 function from within a callout's classifyFn callout function to inject new or cloned data into the data stream that is currently being processed. A callout driver can call the FwpsStreamInjectAsync0 function only if it is processing a data flow at the stream layer.
A callout driver can also call the FwpsStreamInjectAsync0 function from outside of a callout's classifyFn callout function to inject 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.
In addition, a callout driver can call the FwpsStreamInjectAsync0 function from outside of a callout's classifyFn callout function to inject data into a data stream after a FIN indication has been pended.
Alternately, a callout driver can 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 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 way.
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 will not be reindicated to the callout, but it will be made available to stream callouts from lower-weight sublayers.
If the return value is not STATUS_SUCCESS, the completion function will not be called. In this case, the network buffer list pointed to by netBufferList must be freed by a call to FwpsFreeNetBufferList0 or FwpsFreeCloneNetBufferList0.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Available starting with Windows Vista. |
| Target Platform | Universal |
| Header | fwpsk.h (include Fwpsk.h) |
| Library | Fwpkclnt.lib |
| IRQL | <= DISPATCH_LEVEL |