FwpmCalloutAdd0 function (fwpmu.h)

  • Article

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

See also

FWPM_CALLOUT0

Kernel-Mode FwpmCalloutAdd0