FwpmEngineSetOption0 function (fwpmu.h)

Article
10/13/2021

The FwpmEngineSetOption0 function changes the filter engine settings.

Syntax

DWORD FwpmEngineSetOption0(
  [in] HANDLE             engineHandle,
  [in] FWPM_ENGINE_OPTION option,
  [in] const FWP_VALUE0   *newValue
);

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] option

Type: FWPM_ENGINE_OPTION

The option to be set.

[in] newValue

Type: FWP_VALUE0*

The new option value. The data type contained in the newValue parameter should be FWP_UINT32.

When option is FWPM_ENGINE_COLLECT_NET_EVENTS, newValue should be one of the following.

Value	Meaning
0	Do not collect network events.
1	Collect network events. This is the default setting.

When option is FWPM_ENGINE_NET_EVENT_MATCH_ANY_KEYWORDS, newValue should be either 0 (zero) or a bitwise combination of the following values.

Note If newValue is 0 the collection of inbound multicast and broadcast events is disabled. This is the default setting.

Value	Meaning
FWPM_NET_EVENT_KEYWORD_INBOUND_MCAST 1	Collect inbound multicast network events.
FWPM_NET_EVENT_KEYWORD_INBOUND_BCAST 2	Collect inbound broadcast network events.

When option is FWPM_ENGINE_PACKET_QUEUING (available only in Windows 8 and Windows Server 2012), newValue should be one of the following.

Value	Meaning
FWPM_ENGINE_OPTION_PACKET_QUEUE_NONE 0	Do not enable packet queuing.
FWPM_ENGINE_OPTION_PACKET_QUEUE_INBOUND 1	Enable inbound packet queuing.
FWPM_ENGINE_OPTION_PACKET_QUEUE_OUTBOUND 2	Enable outbound packet queuing.

When option is FWPM_ENGINE_MONITOR_IPSEC_CONNECTIONS (available only in Windows 8 and Windows Server 2012), newValue should be the following. (FwpmEngineSetOption0 may be used to enable connections, but will fail with FWP_E_STILL_ON ERROR when attempting to disable it.)

Value	Meaning
1	The IPsec Connection Monitoring feature will be enabled. New IPsec connection events will be logged as well as notifications sent.

When option is FWPM_ENGINE_TXN_WATCHDOG_TIMEOUT_IN_MSEC (available only in Windows 8 and Windows Server 2012), newValue should be the time in milliseconds that specifies the maximum duration for a single WFP transaction. Transactions taking longer than this duration will trigger a watchdog event.

The FWPM_ENGINE_NAME_CACHE option is reserved for internal use.

Return value

Type: DWORD

Return code/value	Description
ERROR_SUCCESS 0	The option was set successfully.
*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

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

This function cannot be called from within a dynamic session. It will fail with FWP_E_DYNAMIC_SESSION_IN_PROGRESS. See Object Management for more information about sessions.

The caller needs FWPM_ACTRL_WRITE access to the filter engine. See Access Control for more information.

The default settings for network event collection are as follows:

Outbound, all (unicast, multicast, and broadcast) events are collected.
Inbound, only unicast events are collected.

Network event collection settings persist across reboots.

To collect inbound broadcast and/or multicast network events,

Call FwpmEngineSetOption0 with option set to FWPM_ENGINE_COLLECT_NET_EVENTS and newValue set to 1.
Call FwpmEngineSetOption0 with option set to FWPM_ENGINE_NET_EVENT_MATCH_ANY_KEYWORDS and newValue parameter set to FWPM_NET_EVENT_KEYWORD_INBOUND_MCAST and/or FWPM_NET_EVENT_KEYWORD_INBOUND_BCAST.

To stop collecting inbound broadcast and/or multicast network events,

Call FwpmEngineSetOption0 with option set to FWPM_ENGINE_NET_EVENT_MATCH_ANY_KEYWORDS and newValue parameter set to 0 (zero).

Disabling and re-enabling of network event collection (FWPM_ENGINE_COLLECT_NET_EVENTS) does not reset the collection of inbound broadcast and multicast events.

FwpmEngineSetOption0 is a specific implementation of FwpmEngineSetOption. 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