FwpsInjectTransportSendAsync1 function (fwpsk.h)

The FwpsInjectTransportSendAsync1 function injects packet data from the transport, datagram data, or ICMP error layers into the send data path. This function differs from the previous version (FwpsInjectTransportSendAsync0) in that it takes an updated parameters structure as an argument.

Note  FwpsInjectTransportSendAsync1 is the specific version of FwpsInjectTransportSendAsync used in Windows 7 and later. See WFP Version-Independent Names and Targeting Specific Versions of Windows for more information. For Windows Vista, FwpsInjectTransportSendAsync0 is available.
 

Syntax

NTSTATUS FwpsInjectTransportSendAsync1(
  [in]           HANDLE                      injectionHandle,
  [in, optional] HANDLE                      injectionContext,
  [in]           UINT64                      endpointHandle,
  [in]           UINT32                      flags,
  [in, optional] FWPS_TRANSPORT_SEND_PARAMS1 *sendArgs,
  [in]           ADDRESS_FAMILY              addressFamily,
  [in]           COMPARTMENT_ID              compartmentId,
  [in, out]      NET_BUFFER_LIST             *netBufferList,
  [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. If specified, it can be obtained by calling the FwpsQueryPacketInjectionState0 function when the packet injection state FWPS_PACKET_INJECTION_STATE is FWPS_PACKET_INJECTED_BY_SELF or FWPS_PACKET_PREVIOUSLY_INJECTED_BY_SELF.

[in] endpointHandle

A handle that indicates the stack transport endpoint in the send data path into which the packet is to be injected. This endpoint handle is provided to a callout through the transportEndpointHandle member of the FWPS_INCOMING_METADATA_VALUES0 structure that is passed to the callout driver's classifyFn callout function. Callout drivers should use the provided handle to inject cloned packets back into the data path as soon as possible, before the socket associated with the stack endpoint is closed and the handle becomes no longer valid.

[in] flags

This parameter is reserved. Callout drivers must set this parameter to zero.

[in, optional] sendArgs

A pointer to a FWPS_TRANSPORT_SEND_PARAMS1 structure that specifies the properties of the current outbound packet. This parameter can be NULL only if the net buffer list to be injected contains an IP header (for example, if the packet is sent through a raw socket).

[in] addressFamily

One of the following address families:

AF_INET

The IPv4 address family.

AF_INET6

The IPv6 address family.

[in] compartmentId

The identifier of the routing compartment into which the packet data is injected, specified as a COMPARTMENT_ID type. This identifier is provided to a callout through the compartmentId member of the FWPS_INCOMING_METADATA_VALUES0 structure that is passed to the callout driver's classifyFn callout function. If the compartmentId member is available to callouts, FWPS_METADATA_FIELD_COMPARTMENT_ID will be set in the currentMetadataValues member. Otherwise, set this parameter to UNSPECIFIED_COMPARTMENT_ID.

[in, 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 inject packet data by calling either the FwpsAllocateCloneNetBufferList0 function or the FwpsAllocateNetBufferAndNetBufferList0 function.

[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.

[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 FwpsInjectTransportSendAsync1 function returns one of the following NTSTATUS codes:

Return code Description
STATUS_SUCCESS
The packet data injection was initiated successfully. The filter engine will call the completion function after the filter engine has completed injecting the packet data into the network stack, or when an error occurred subsequently. In case of an error, the Status member of the completed NET_BUFFER_LIST structure will indicate the reason for failure.
STATUS_FWP_TCPIP_NOT_READY
The TCP/IP network stack is not ready to accept injection of packet data.
STATUS_FWP_INJECT_HANDLE_CLOSING
The injection handle is being closed.
Other status codes
An error occurred.

Remarks

A callout driver calls the FwpsInjectTransportSendAsync1 function to inject packet data from the transport, datagram data, or ICMP error layers into the send data path. At these layers, the IP header might not yet be formed, and when IPsec policy is active, the packet data is not encrypted or signed. Therefore, this function is ideal to use for packet inspection in an IPsec-enabled environment.

This function can execute asynchronously.

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

Callout drivers normally inject data into the network stack when they modify packet data. For more information about how a callout driver can modify packet data, see Callout Driver Operations.

The injected packet can be indicated to the callout driver again. To prevent infinite looping, the driver should first call the FwpsQueryPacketInjectionState0 function before calling the classifyFn callout function, and permit packets that have the injection state FWPS_PACKET_INJECTION_STATE set to FWPS_PACKET_INJECTED_BY_SELF or FWPS_PACKET_PREVIOUSLY_INJECTED_BY_SELF.

The endpointHandle parameter and members declared in the
FWPS_TRANSPORT_SEND_PARAMS1 structure pointed to by the sendArgs parameter are provided to callouts from the following network layers:

FWPS_LAYER_OUTBOUND_TRANSPORT_V4
FWPS_LAYER_OUTBOUND_TRANSPORT_V6
FWPS_LAYER_DATAGRAM_DATA_V4 (when outbound direction is specified with FWP_DIRECTION_OUTBOUND)
FWPS_LAYER_DATAGRAM_DATA_V6 (when outbound direction is specified with FWP_DIRECTION_OUTBOUND)
FWPS_LAYER_OUTBOUND_ICMP_ERROR_V4
FWPS_LAYER_OUTBOUND_ICMP_ERROR_V6

The datagram belongs to a raw socket if both of the following are true:

At the following network layers, if the datagram belongs to a raw socket, you'll need to copy the headerIncludeHeader and headerIncludeHeaderLength members of the FWPS_INCOMING_METADATA_VALUES0 structure into the corresponding member of the FWPS_TRANSPORT_SEND_PARAMS1 structure that the sendArgs parameter points to:

  • FWPS_LAYER_DATAGRAM_DATA_V4 (when outbound direction is specified with FWP_DIRECTION_OUTBOUND)
  • FWPS_LAYER_DATAGRAM_DATA_V6 (when outbound direction is specified with FWP_DIRECTION_OUTBOUND)

Requirements

Requirement Value
Minimum supported client Available starting with Windows 7.
Target Platform Universal
Header fwpsk.h (include Fwpsk.h)
Library Fwpkclnt.lib
IRQL <= DISPATCH_LEVEL

See also

FWPS_INCOMING_METADATA_VALUES0

FWPS_PACKET_INJECTION_STATE

FWPS_TRANSPORT_SEND_PARAMS1

FwpsAllocateCloneNetBufferList0 FwpsAllocateNetBufferAndNetBufferList0

FwpsFreeCloneNetBufferList0

FwpsFreeNetBufferList0

FwpsInjectTransportSendAsync0

FwpsInjectionHandleCreate0

FwpsInjectionHandleDestroy0

FwpsQueryPacketInjectionState0

NET_BUFFER_LIST

classifyFn

completionFn