FwpsInjectMacReceiveAsync0 function (fwpsk.h)

Article
09/14/2022

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(
  [in]           HANDLE               injectionHandle,
  [in, optional] HANDLE               injectionContext,
  [in]           UINT32               flags,
  [in]           UINT16               layerId,
  [in]           IF_INDEX             interfaceIndex,
  [in]           NDIS_PORT_NUMBER     NdisPortNumber,
  [in, out]      NET_BUFFER_LIST      *netBufferLists,
  [in]           FWPS_INJECT_COMPLETE completionFn,
  [in, optional] HANDLE               completionContext
);

Parameters

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

[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] flags

Reserved. Must be set to zero.

[in] layerId

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

[in] interfaceIndex

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

[in] NdisPortNumber

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

[in, out] 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.

When (layerId == FWPS_LAYER_INBOUND_MAC_FRAME_ETHERNET), the NET_BUFFER_LIST must begin with an Ethernet header.

When (layerId == FWPS_LAYER_INBOUND_MAC_FRAME_NATIVE), the NET_BUFFER_LIST must begin with a MAC header.

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

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

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