FwpsInjectMacReceiveAsync0 function (fwpsk.h)
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.
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.
[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 |
|---|---|
|
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. |
|
The MAC layer is not ready to accept injection of packet data. |
|
The injection handle is being closed. |
|
The injection handle was not created with the flags parameter of the FwpsInjectionHandleCreate0 function set to FWPS_INJECTION_TYPE_L2. |
|
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 |