FwpmEngineSetOption0 function (fwpmk.h)

  • Article

The FwpmEngineSetOption0 function changes the filter engine settings.

Syntax

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

Parameters

[in] engineHandle

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

[in] option

The option to be set.

[in] newValue

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

Return code/value Description
ERROR_SUCCESS
0		 Success
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.
Other NTSTATUS codes An error occurred.

Remarks

This function cannot be called from within a transaction, it fails 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 fails 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,

  1. Call FwpmEngineSetOption0 with option set to FWPM_ENGINE_COLLECT_NET_EVENTS and newValue set to 1.
  2. 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 Available starting with Windows Vista.
Target Platform Universal
Header fwpmk.h
Library fwpkclnt.lib
IRQL <= PASSIVE_LEVEL

See also