FwpsInjectMacReceiveAsync0 function

The FwpsInjectMacReceiveAsync0 function can reinject a previously absorbed media access control (MAC) frame (or a clone of the frame) back to the layer 2 inbound data path from which it was intercepted, or inject an invented MAC frame.

Note  FwpsInjectMacReceiveAsync0 is a specific version of FwpsInjectMacReceiveAsync. See WFP Version-Independent Names and Targeting Specific Versions of Windows for more information.

 

Syntax

NTSTATUS FwpsInjectMacReceiveAsync0(
  HANDLE               injectionHandle,
  HANDLE               injectionContext,
  UINT32               flags,
  UINT16               layerId,
  IF_INDEX             interfaceIndex,
  NDIS_PORT_NUMBER     NdisPortNumber,
  NET_BUFFER_LIST      *netBufferLists,
  FWPS_INJECT_COMPLETE completionFn,
  HANDLE               completionContext
);

Parameters

injectionHandle

An injection handle that was previously obtained by a call to the FwpsInjectionHandleCreate0 function with the flags parameter set to FWPS_INJECTION_TYPE_L2.

Note  Set the addressFamily parameter of the FwpsInjectionHandleCreate0 function to AF_UNSPEC.
 

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.

flags

Reserved. Must be set to zero.

layerId

The run-time identifier for the filtering layer at which the data stream is being processed.

interfaceIndex

The interface index that is passed to the callout driver's classifyFn incoming value FWPS_FIELD_XxxMAC_FRAMEXxx_INTERFACE_INDEX.

NdisPortNumber

The NDIS port number that is passed to the callout driver's classifyFn incoming value FWPS_FIELD_XxxMAC_FRAMEXxx_NDIS_PORT.

netBufferLists

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.

The NET_BUFFER_LIST structure must begin with an IP header if calling this function at the Ethernet layer where (layerId == FWPS_LAYER_INBOUND_MAC_FRAME_ETHERNET).

For receive injection in the native case, where (layerId == FWPS_LAYER_INBOUND_MAC_FRAME_NATIVE), the NET_BUFFER_LIST must begin with a MAC header.

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 netBufferLists parameter, has been injected into the network stack. This pointer must be specified when injecting cloned or created NET_BUFFER_LIST structures. When injecting original NET_BUFFER_LIST structures, this parameter can be NULL if the original structures are not altered.

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 FwpsInjectMacReceiveAsync0 function returns one of the following NTSTATUS codes.

Return code Description
STATUS_SUCCESS
The MAC frame data injection was initiated successfully. The filter engine calls the completion function after the filter engine has completed injecting the MAC frame data, 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 MAC layer is not ready to accept injection of packet data.
STATUS_FWP_INJECT_HANDLE_CLOSING
The injection handle is being closed.
STATUS_FWP_INJECT_HANDLE_STALE
The injection handle was not created with the flags parameter of the FwpsInjectionHandleCreate0 function set to FWPS_INJECTION_TYPE_L2.
Other status codes
An error occurred.

Remarks

A callback driver calls the FwpsInjectMacReceiveAsync0 function to reinject a previously absorbed MAC frame (or a clone of the frame) back to the layer 2 inbound data path from which it was intercepted, or to inject an invented MAC frame.

The netBufferLists parameter can be a NET_BUFFER_LIST chain. However the completion function could be invoked multiple times each, completing a segment (or single NET_BUFFER_LIST) of the chain.

Injected frames could get classified again if the packets match the same filter as originally classified. Therefore, as with callouts at IP layers, layer 2 callouts must also protect against infinite packet inspection by calling FwpsQueryPacketInjectionState0.

Requirements

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

See Also

FwpsAllocateCloneNetBufferList0 FwpsAllocateNetBufferAndNetBufferList0 FwpsInjectionHandleCreate0

FwpsQueryPacketInjectionState0

NET_BUFFER_LIST

classifyFn

completionFn