Share via

classifyFn (Compact 7)

  • Article

3/12/2014

The WFP Filter Engine calls a callout's classifyFn callout function whenever there is data to be processed by the callout.

Syntax

VOID NTAPI
  classifyFn(
    IN const FWPS_INCOMING_VALUES0  *inFixedValues,
    IN const FWPS_INCOMING_METADATA_VALUES0  *inMetaValues,
    IN OUT VOID  *layerData,
    IN const FWPS_FILTER0  *filter,
    IN UINT64  flowContext,
    OUT FWPS_CLASSIFY_OUT0  *classifyOut
    );

Parameters

  • inFixedValues
    A pointer to an FWPS_INCOMING_VALUES0 structure. that contains the values for each data field at the layer being filtered
  • inMetaValues
    A pointer to an FWPS_INCOMING_METADATA_VALUES0 structure. This structure contains the values for each metadata field at the layer being filtered
  • layerData
    A pointer to a structure that describes the raw data at the layer being filtered. This parameter might be NULL, depending on the layer being filtered and the conditions under which the classifyFn callout function is called. For the stream layer, this parameter points to the FWPS_STREAM_CALLOUT_IO_PACKET0 structure. For all other layers, this parameter points to a NET_BUFFER_LIST structure (if it is not NULL).
  • filter
    A pointer to a FWPS_FILTER0 structure, that describes the filter that specifies the callout for the filter's action
  • flowContext
    A UINT64-typed variable that contains the context associated with the data flow. If no context is associated with the data flow, this parameter is zero. If the callout is added to the filter engine at a filtering layer that does not support data flows, the classifyFn callout function should ignore this parameter
  • classifyOut
    A pointer to a FWPS_CLASSIFY_OUT0 structure that receives any data returned to the caller by the classifyFn callout function

Return Value

None

Remarks

A callout driver registers a callout's callout functions with the filter engine by calling the FwpsCalloutRegister0 function.

The filter engine calls a callout's classifyFn callout function together with data to be processed whenever all the test conditions are true for a filter in the filter engine that specifies the callout for the filter's action.

A callout's classifyFn callout function should clear the FWPS_RIGHT_ACTION_WRITE flag in the rights member of the FWPS_CLASSIFY_OUT0 structure in any of the following situations:

  • When the classifyFn callout function sets the actionType member of the FWPS_CLASSIFY_OUT0 structure to FWP_ACTION_BLOCK
  • When the classifyFn callout function sets the actionType member of the FWPS_CLASSIFY_OUT0 structure to FWP_ACTION_PERMIT, and the FWPS_FILTER_FLAG_CLEAR_ACTION_RIGHT flag is set in the flags member of the FWPS_FILTER0 structure

The following examples show how a classifyFn callout function can access data associated with the inFixedValues input parameter. The sample defines a FLOW_DATA structure that stores the extracted address and port information:

typedef struct _FLOW_DATA
{
  UINT64      flowHandle;
  UINT64      flowContext;
  UINT64      calloutId;
  ULONG       localAddressV4;
  USHORT      localPort;
  USHORT      ipProto;
  ULONG       remoteAddressV4;
  USHORT      remotePort;
  WCHAR*      processPath;
  LIST_ENTRY  listEntry;
  BOOLEAN     deleting;
} FLOW_DATA;

This code extracts the local IPv4 address from the inFixedValues input parameter to classifyFn:

UINT64
MonitorCoCreateFlowContext(
  IN const FWPS_INCOMING_VALUES0*          inFixedValues,
  IN const FWPS_INCOMING_METADATA_VALUES0* inMetaValues,
  OUT UINT64*                     flowHandle)
{
  FLOW_DATA* flowContext = NULL;
  UINT32 index; 
…
index = FWPS_FIELD_ALE_FLOW_ESTABLISHED_V4_IP_LOCAL_ADDRESS;
flowContext->localAddressV4 = inFixedValues->incomingValue[index].value.uint32;
…
}

This code extracts the local transport protocol port number:

index = FWPS_FIELD_ALE_FLOW_ESTABLISHED_V4_IP_LOCAL_PORT;
flowContext->localPort = inFixedValues->incomingValue[index].value.uint16;

This code extracts the remote IPv4 address:

index = FWPS_FIELD_ALE_FLOW_ESTABLISHED_V4_IP_REMOTE_ADDRESS;
flowContext->remoteAddressV4 = inFixedValues->incomingValue[index].value.uint32;

The FWPS_CALLOUT_NOTIFY_FN0 type is defined as a pointer to the classifyFn function as follows:

typedef NTSTATUS (NTAPI *FWPS_CALLOUT_NOTIFY_FN0)  classifyFn

The filter engine calls a callout's classifyFn callout function at IRQL <= DISPATCH_LEVEL.

Requirements

Header

fwpsk.h

See Also

Reference

Callout Driver Callout Functions
FwpsCalloutRegister0
NET_BUFFER_LIST
FwpsReferenceNetBufferList0
FWPS_CALLOUT0
FWPS_CLASSIFY_OUT0
FWPS_FILTER0
FWPS_INCOMING_METADATA_VALUES0
FWPS_INCOMING_VALUES0
completionFn
flowDeleteFn
notifyFn
WFP Callout Driver Functions