notifyFn (Compact 2013)

3/26/2014

The WFP Filter Engine calls a callout's notifyFn callout function to notify the callout driver about associated events.

Syntax

NTSTATUS NTAPI
  notifyFn(
    IN FWPS_CALLOUT_NOTIFY_TYPE  notifyType,
    IN const GUID  *filterKey,
    IN const FWPS_FILTER0  *filter
    );

Parameters

• notifyType
  A value that indicates the type of notification that the filter engine is sending to the callout. Valid values for this parameter are as follows:

  • FWPS_CALLOUT_NOTIFY_ADD_FILTER: a filter is being added to the filter engine that specifies the callout for the filter's action
  • FWPS_CALLOUT_NOTIFY_DELETE_FILTER: a filter is being deleted from the filter engine that specifies the callout for the filter's action
  • FWPS_CALLOUT_NOTIFY_TYPE_MAX: a maximum value for testing

• filterKey
  A pointer to the management identifier for the filter, as specified by the application or driver that is adding or deleting the filter. Must be NULL if the notifyType parameter is set to FWPS_CALLOUT_NOTIFY_DELETE_FILTER.

• filter
  A pointer to an FWPS_FILTER0 structure. This structure describes the filter that is being added to or deleted from the filter engine.

  A callout's notifyFn callout function can point the context member of this structure to a callout driver-supplied context structure when the filter is added to the filter engine. This context structure is opaque to the filter engine, and can be used by the callout's classifyFn callout function to preserve any driver-specific data or state information between calls by the filter engine to the callout's classifyFn callout function.

  A callout's notifyFn callout function can clean up any context associated with a filter when the filter is deleted from the filter engine.

Return Value

The notifyFn function returns one of the following NTSTATUS codes:

Value	Description
STATUS_SUCCESS	The callout driver accepts the notification from the filter engine
Other status codes	An error occurred

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 notifyFn callout function to notify the callout driver about associated events. If the callout's notifyFn callout function does not recognize the type of notification that is passed in the notifyType parameter, it should ignore the notification and return STATUS_SUCCESS.

If a callout driver registers a callout with the filter engine after filters that specify the callout for the filter's action have already been added to the filter engine, the filter engine does not call the callout's notifyFn callout function to notify the callout about any of the existing filters. The filter engine calls the callout's notifyFn callout function to notify the callout when new filters that specify the callout for the filter's action are added to the filter engine. In this situation, a callout's notifyFn callout function might not be called for every filter in the filter engine that specifies the callout for the filter's action. If a callout driver registers a callout after the filter engine is started and the callout must know about every filter in the filter engine that specifies the callout for the filter's action, the callout driver must call the appropriate management functions to enumerate all the filters in the filter engine and sort through the resulting list of filters to find those that specify the callout for the filter's action.

When a filter that specifies a callout for the filter's action is deleted from the filter engine, the filter engine calls the callout's notifyFn callout function and passes FWP_CALLOUT_NOTIFY_DELETE_FILTER in the notifyType parameter and NULL in the filterKey parameter.

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

typedef NTSTATUS (NTAPI *FWPS_CALLOUT_NOTIFY_FN0)  notifyFn

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

Requirements

Header

fwpsk.h

See Also

Reference

Callout Driver Callout Functions
FWPS_CALLOUT0
FWPS_FILTER0
FwpsCalloutRegister0
classifyFn
completionFn
flowDeleteFn
WFP Callout Driver Functions