Edit

Share via

FwpmCalloutAdd0 function (fwpmk.h)

  • Article

The FwpmCalloutAdd0 function adds a callout to the filter engine.

Syntax

NTSTATUS FwpmCalloutAdd0(
  [in]            HANDLE               engineHandle,
  [in]            const FWPM_CALLOUT0  *callout,
  [in, optional]  PSECURITY_DESCRIPTOR sd,
  [out, optional] UINT32               *id
);

Parameters

[in] engineHandle

A handle for an open session to the filter engine. A callout driver calls the FwpmEngineOpen0 function to open a session to the filter engine.

[in] callout

A pointer to a constant FWPM_CALLOUT0 structure that contains the data that is required to add the callout to the filter engine.

[in, optional] sd

A pointer to a constant SECURITY_DESCRIPTOR structure that describes the security descriptor for the callout that is being added to the filter engine. This parameter is optional and can be NULL.

[out, optional] id

A pointer to a UINT32-typed variable that receives a run-time identifier that identifies the callout in the filter engine. This is the same identifier that is returned when a callout driver registers the callout driver's callout functions with the filter engine. The callout driver passes this identifier to the FwpmCalloutDeleteById0 function when removing the callout from the filter engine. This parameter is optional and can be NULL.

Return value

The FwpmCalloutAdd0 function returns one of the following NTSTATUS codes:

Return code Description
STATUS_SUCCESS The callout was successfully added to the filter engine.
STATUS_FWP_ALREADY_EXISTS The callout could not be added to the filter engine. A callout already exists in the filter engine with an identifier identical to the GUID specified in the calloutKey member of the FWPM_CALLOUT0 structure pointed to by the callout parameter.
Other NTSTATUS codes An error occurred.

Remarks

A callout driver calls the FwpmCalloutAdd0 function to add a callout to the filter engine.

Callout drivers do not typically add their callouts to the filter engine. In most situations this is handled by a user-mode Windows Filtering Platform management application.

A callout and filters that specify the callout for the filter's action can be added to the filter engine before a callout driver registers the callout with the filter engine. In this situation, filters with an action type of FWP_ACTION_CALLOUT_TERMINATING or FWP_ACTION_CALLOUT_UNKNOWN are treated as FWP_ACTION_BLOCK and filters with an action type of FWP_ACTION_CALLOUT_INSPECTION are ignored until the callout is registered with the filter engine.

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

Requirements

Requirement Value
Minimum supported client Available starting with Windows Vista.
Target Platform Universal
Header fwpmk.h (include Fwpmk.h)
Library Fwpkclnt.lib
IRQL PASSIVE_LEVEL

See also