The FwpsStreamInjectAsync0 function injects TCP data segments into a TCP data stream.
NTSTATUS NTAPI FwpsStreamInjectAsync0( _In_ HANDLE injectionHandle, _In_opt_ HANDLE injectionContext, _In_ UINT32 flags, _In_ UINT64 flowId, _In_ UINT32 calloutId, _In_ UINT16 layerId, _In_ UINT32 streamFlags, _Inout_ NET_BUFFER_LIST *netBufferList, _In_ SIZE_T dataLength, _In_ FWPS_INJECT_COMPLETE0 completionFn, _In_opt_ HANDLE completionContext );
- injectionHandle [in]
An injection handle that was previously created by a call to the FwpsInjectionHandleCreate0 function.
- injectionContext [in, optional]
An optional handle to the injection context.
- flags [in]
Reserved. Callout drivers should set this parameter to zero.
- flowId [in]
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.
- calloutId [in]
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.
- layerId [in]
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.
- streamFlags [in]
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:
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.
Specifies that the FIN flag is to be set in the TCP header for the data being injected into the inbound data stream.
Specifies that the data being injected into the inbound data stream is high-priority, out-of-band data.
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:
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.
Specifies that the data being injected into the outbound data stream is high-priority, out-of-band data.
Specifies that the callout driver requests that there is no buffering of the data being injected into the outbound data stream.
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.
- netBufferList [in, out]
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.
- dataLength [in]
The number of bytes of data being injected into the data stream.
- completionFn [in]
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 is FWPS_STREAM_FLAG_RECEIVE_DISCONNECT or FWPS_STREAM_FLAG_SEND_DISCONNECT, completionFn will not be called.
This parameter is required and cannot be NULL.
- completionContext [in, optional]
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.
The FwpsStreamInjectAsync0 function returns one of the following NTSTATUS codes.
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.
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 metBufferList must be freed by a call to FwpsFreeNetBufferList0 or FwpsFreeCloneNetBufferList0.
|Available starting with Windows Vista.|
Build date: 5/7/2013