FwpmCalloutAdd0 function (fwpmu.h)

Article
10/13/2021

The FwpmCalloutAdd0 function adds a new callout object to the system.

Syntax

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

Parameters

[in] engineHandle

Type: HANDLE

Handle for an open session to the filter engine. Call FwpmEngineOpen0 to open a session to the filter engine.

[in] callout

Type: FWPM_CALLOUT0*

The callout object to be added.

[in, optional] sd

Type: PSECURITY_DESCRIPTOR

The security information associated with the callout.

[out, optional] id

Type: UINT32*

Runtime identifier for this callout.

Return value

Type: DWORD

Return code/value	Description
ERROR_SUCCESS 0	The callout was successfully added.
FWP_E_INVALID_PARAMETER 0x80320035	FWPM_TUNNEL_FLAG_POINT_TO_POINT was not set and conditions other than local/remote address were specified.
*FWP_E_ error code** 0x80320001—0x80320039	A Windows Filtering Platform (WFP) specific error. See WFP Error Codes for details.
*RPC_ error code** 0x80010001—0x80010122	Failure to communicate with the remote or local firewall engine.

Remarks

Some fields in the FWPM_CALLOUT0 structure are assigned by the system, not the caller, and are ignored in the call to FwpmCalloutAdd0. If the caller supplies a null security descriptor, the system will assign a default security descriptor.

This function cannot be called from within a read-only transaction. It will fail with FWP_E_INCOMPATIBLE_TXN. See Object Management for more information about transactions.

The caller needs FWPM_ACTRL_ADD access to the callout's container, FWPM_ACTRL_ADD_LINK access to the provider (if any), and FWPM_ACTRL_ADD_LINK access to the applicable layer. See Access Control for more information.

To add a filter that references a callout, invoke the functions in the following order.

Call FwpsCalloutRegister (documented in the Windows Driver Kit (WDK)), to register the callout with the filter engine.
Call FwpmCalloutAdd0 to add the callout to the system.
Call FwpmFilterAdd0 to add the filter that references the callout to the system.

By default filters that reference callouts that have been added but have not yet registered with the filter engine are treated as Block filters.

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

Requirements

Requirement	Value
Minimum supported client	Windows Vista [desktop apps only]
Minimum supported server	Windows Server 2008 [desktop apps only]
Target Platform	Windows
Header	fwpmu.h
Library	Fwpuclnt.lib
DLL	Fwpuclnt.dll