NetFilter Class

Properties   Methods   Events   Config Settings   Errors  

The NetFilter class allows applications to intercept and control network traffic.

Syntax

class pcapfilter.NetFilter

Remarks

The NetFilter class gives applications the ability to intercept network packets, allowing them to be altered or blocked. Applications use filter rules to specify which requests they are interested in intercepting or blocking.

To learn more about the class's capabilities, please refer to the product's General Information topics.

Getting Started

1. If the class's system driver has not been installed yet, call the install method to do so. This needs to be done only once.
   • In production, the driver can be installed (or updated) ahead of time with the application's installation script using the Installer DLL. Please refer to the Driver Installation topic for more information.
2. Call the initialize method to initialize the NetFilter class. This must be done each time the application starts.
3. Call the list_adapters method to populate the list of network adapters that NetFilter can control. Your application will likely use adapter names to add rules.
4. Add one or more filter rules using methods like add_filter_rule. (Rules can also be added or removed after the filter is started.)
5. Call the start_filter method to start filtering network packets.
6. When finished, call the stop_filter method to stop filtering network packets.
7. To uninstall the class's system driver, call the uninstall method. This should not be done as part of the driver upgrade process.
   • In production, the driver can be uninstalled by the application's uninstallation script using the Installer DLL. Please refer to the Driver Installation topic for more information.

Property List

---

The following is the full list of the properties of the class with short descriptions. Click on the links for further details.

Method List

---

The following is the full list of the methods of the class with short descriptions. Click on the links for further details.

Event List

---

The following is the full list of the events fired by the class with short descriptions. Click on the links for further details.

Config Settings

---

The following is a list of config settings for the class with short descriptions. Click on the links for further details.

active property

This property notes whether the class is active and processing requests.

Syntax

def get_active() -> bool: ...

active = property(get_active, None)

Default Value

FALSE

Remarks

This property reflects whether the class is active and currently processing requests. It will be True after the filter has been attached successfully via a call to start_filter.

This property is read-only.

adapter_count property

The number of records in the Adapter arrays.

Syntax

def get_adapter_count() -> int: ...

adapter_count = property(get_adapter_count, None)

Default Value

0

Remarks

This property controls the size of the following arrays:

• adapter_buffer_size
• adapter_collect_statistics
• adapter_description
• adapter_friendly_name
• adapter_id
• adapter_interface_type
• adapter_mac_address
• adapter_max_packet_bytes
• adapter_name
• adapter_packet_timeout
• adapter_promiscuous_mode
• adapter_wi_fi_monitor_mode
• adapter_wi_fi_monitor_mode_supported

The array indices start at 0 and end at adapter_count - 1.

This property is read-only.

adapter_buffer_size property

Specifies the size of the kernel-level buffer associated with a capture, expressed in KB (kilobytes).

Syntax

def get_adapter_buffer_size(adapter_index: int) -> int: ...
def set_adapter_buffer_size(adapter_index: int, value: int) -> None: ...

Default Value

1024

Remarks

Specifies the size of the kernel-level buffer associated with a capture, expressed in KB (kilobytes).

This field is used only by the IPMonitor class when it is using a third-party capture driver and is ignored by NetFilter driver, which manages memory dynamically.

The default value of 0 tells libpcap to use the default value hard-coded in it. In Windows, this is 1 000 000 bytes (approx.1 megabyte); in Linux, this is 2MB.

The field corresponds to the pcap_set_buffer_size() function.

This value can be changed only when the class is not activated (the Active property is False).

The adapter_index parameter specifies the index of the item in the array. The size of the array is controlled by the adapter_count property.

adapter_collect_statistics property

Specifies whether the class should report statistics for this adapter when the class is operating in the omStat OperationMode .

Syntax

def get_adapter_collect_statistics(adapter_index: int) -> bool: ...
def set_adapter_collect_statistics(adapter_index: int, value: bool) -> None: ...

Default Value

TRUE

Remarks

Specifies whether the class should report statistics for this adapter when the class is operating in the omStat operation_mode.

The adapter_index parameter specifies the index of the item in the array. The size of the array is controlled by the adapter_count property.

adapter_description property

The description of the network adapter.

Syntax

def get_adapter_description(adapter_index: int) -> str: ...

Default Value

""

Remarks

The description of the network adapter.

The adapter_index parameter specifies the index of the item in the array. The size of the array is controlled by the adapter_count property.

This property is read-only.

adapter_friendly_name property

The human-readable name of the adapter, which may be modified by a user using Windows functionality.

Syntax

def get_adapter_friendly_name(adapter_index: int) -> str: ...

Default Value

""

Remarks

The human-readable name of the adapter, which may be modified by a user using Windows functionality.

The adapter_index parameter specifies the index of the item in the array. The size of the array is controlled by the adapter_count property.

This property is read-only.

adapter_id property

Contains the Id of the adapter.

Syntax

def get_adapter_id(adapter_index: int) -> int: ...

Default Value

0

Remarks

Contains the Id of the adapter.

Each network adapter in the system has an Id that is used in all operations of NetFilter where an adapter is referenced by the class or must be specified by an application.

The adapter_index parameter specifies the index of the item in the array. The size of the array is controlled by the adapter_count property.

This property is read-only.

adapter_interface_type property

Contains the type of the adapter interface.

Syntax

def get_adapter_interface_type(adapter_index: int) -> int: ...

Default Value

0

Remarks

Contains the type of the adapter interface.

This field specifies the type of the network with which the adapter works. The available values are defined by IANA.

The adapter_index parameter specifies the index of the item in the array. The size of the array is controlled by the adapter_count property.

This property is read-only.

adapter_mac_address property

The MAC address of the adapter.

Syntax

def get_adapter_mac_address(adapter_index: int) -> str: ...

Default Value

""

Remarks

The MAC address of the adapter.

This field contains the MAC address of the adapter, if such an address exists (only some adapter types have MAC addresses).

The value may be absent or contains a MAC address in HEX-encoded form where bytes are ordered in the transmission order with each byte's HEX characters separated by a hyphen ("-").

The adapter_index parameter specifies the index of the item in the array. The size of the array is controlled by the adapter_count property.

This property is read-only.

adapter_max_packet_bytes property

Defines the maximum number of bytes of a packet to pass in events.

Syntax

def get_adapter_max_packet_bytes(adapter_index: int) -> int: ...
def set_adapter_max_packet_bytes(adapter_index: int, value: int) -> None: ...

Default Value

262144

Remarks

Defines the maximum number of bytes of a packet to pass in events.

The default value of 0 tells libpcap to set the maximum length to 262 144 bytes.

The field corresponds to the pcap_set_snaplen() function.

This value can be changed only when the class is not activated (the Active property is False).

The adapter_index parameter specifies the index of the item in the array. The size of the array is controlled by the adapter_count property.

adapter_name property

The name of the adapter.

Syntax

def get_adapter_name(adapter_index: int) -> str: ...

Default Value

""

Remarks

The name of the adapter. This value can be passed into the activate method to start monitoring the adapter in IPMonitor or as a parameter to the add_filter_rule method when adding filtration rules in NetFilter.

The adapter_index parameter specifies the index of the item in the array. The size of the array is controlled by the adapter_count property.

This property is read-only.

adapter_packet_timeout property

Specifies the packet buffer timeout, expressed in milliseconds, which tell the driver how long it may wait before replying with no packets, when packets are not available.

Syntax

def get_adapter_packet_timeout(adapter_index: int) -> int: ...
def set_adapter_packet_timeout(adapter_index: int, value: int) -> None: ...

Default Value

1000

Remarks

Specifies the packet buffer timeout, expressed in milliseconds, which tell the driver how long it may wait before replying with no packets, when packets are not available.

This field is used only by the IPMonitor class when it is using a third-party capture driver and is ignored by NetFilter driver, which works in the so-called "immediate mode" in libpcap terms.

The value must be specified in milliseconds. The behavior if a zero or a negative value is set is not defined by libpcap, thus, it is recommended to always set the value to a positive number. The default value is 1000 ms (one second).

For the detailed description of a packet buffer timeout, please refer to libpcap documentation.

This value can be changed only when the class is not activated (the Active property is False).

The adapter_index parameter specifies the index of the item in the array. The size of the array is controlled by the adapter_count property.

adapter_promiscuous_mode property

Enables or disables the promiscuous mode on the adapter, telling the adapter to capture or skippackets that pass by, i.

Syntax

def get_adapter_promiscuous_mode(adapter_index: int) -> bool: ...
def set_adapter_promiscuous_mode(adapter_index: int, value: bool) -> None: ...

Default Value

FALSE

Remarks

Enables or disables the promiscuous mode on the adapter, telling the adapter to capture or skippackets that pass by, i.e., which do not originate in the given adapter and do not have it as a destination.

For the detailed description of the promiscuous mode, please refer to libpcap documentation.

In the IPMonitor class, the field corresponds to the pcap_set_promisc() function.

This value can be changed only when the class is not activated (the Active property is False).

The adapter_index parameter specifies the index of the item in the array. The size of the array is controlled by the adapter_count property.

adapter_wi_fi_monitor_mode property

Enables or disables the WiFi monitoring mode on the adapter.

Syntax

def get_adapter_wi_fi_monitor_mode(adapter_index: int) -> bool: ...
def set_adapter_wi_fi_monitor_mode(adapter_index: int, value: bool) -> None: ...

Default Value

FALSE

Remarks

Enables or disables the WiFi monitoring mode on the adapter.

This functionality is provided by adapters, not by the driver itself, and not all WiFi adapters support this mode. Check the adapter_wi_fi_monitor_mode_supported field before enabling the WiFi monitoring mode.

For the detailed description of the WiFi monitoring mode, please refer to libpcap documentation, where it is described under the "monitor mode" title.

In the IPMonitor class, the field corresponds to the pcap_set_rfmon() function.

This value can be changed only when the class is not activated (the Active property is False).

The adapter_index parameter specifies the index of the item in the array. The size of the array is controlled by the adapter_count property.

adapter_wi_fi_monitor_mode_supported property

Indicates whether the WiFi monitoring mode is supported by the adapter.

Syntax

def get_adapter_wi_fi_monitor_mode_supported(adapter_index: int) -> bool: ...

Default Value

FALSE

Remarks

Indicates whether the WiFi monitoring mode is supported by the adapter. Check this value before trying to enable the WiFi monitor mode.

This functionality is provided by adapters, not by the driver itself, and not all WiFi adapters support this mode.

For the detailed description of the WiFi monitoring mode, please refer to libpcap documentation, where it is described under the "monitor mode" title.

The adapter_index parameter specifies the index of the item in the array. The size of the array is controlled by the adapter_count property.

This property is read-only.

altitude property

This property specifies the altitude the class's system driver should use.

Syntax

def get_altitude() -> int: ...
def set_altitude(value: int) -> None: ...

altitude = property(get_altitude, set_altitude)

Default Value

0

Remarks

This property specifies the altitude that the class's system driver should use. The altitude defines the order of calling the instances - the higher the altitude, the earlier the instance's events are fired.

If this property is queried before an altitude has been set (via this property or the install method), it will return 0.

NOTE: This property cannot be changed when active is True. Additionally, the initialize method must be called before attempting to get or set this property's value, which is stored in the registry.

filter_rule_count property

The number of records in the FilterRule arrays.

Syntax

def get_filter_rule_count() -> int: ...

filter_rule_count = property(get_filter_rule_count, None)

Default Value

0

Remarks

This property controls the size of the following arrays:

• filter_rule_action
• filter_rule_adapter_id
• filter_rule_bpf_rule
• filter_rule_direction
• filter_rule_max_packet_size
• filter_rule_min_packet_size
• filter_rule_rule_id

The array indices start at 0 and end at filter_rule_count - 1.

This property is read-only.

filter_rule_action property

This property specifies the action that the driver should take in regard to the packet that matches the rule.

Syntax

def get_filter_rule_action(filter_rule_index: int) -> int: ...

Default Value

0

Remarks

This property specifies the action that the driver should take in regard to the packet that matches the rule.

This property specifies the action that the driver should take in regard to the packet that matches the rule. The value passed for this parameter may be one of the following:

The filter_rule_index parameter specifies the index of the item in the array. The size of the array is controlled by the filter_rule_count property.

This property is read-only.

filter_rule_adapter_id property

This property specifies the adapter, on which the driver should track and process packets.

Syntax

def get_filter_rule_adapter_id(filter_rule_index: int) -> int: ...

Default Value

0

Remarks

This property specifies the adapter, on which the driver should track and process packets.

This property specifies the adapter, on which the driver should track and process packets. If the value is -1, all adapters are tracked.

The filter_rule_index parameter specifies the index of the item in the array. The size of the array is controlled by the filter_rule_count property.

This property is read-only.

filter_rule_bpf_rule property

This property specifies a BPF-compatible rule for matching for packet properties.

Syntax

def get_filter_rule_bpf_rule(filter_rule_index: int) -> str: ...

Default Value

""

Remarks

This property specifies a BPF-compatible rule for matching for packet properties.

This property specifies a BPF-compatible rule for matching for packet properties. The format of this rule is compatible with libpcap filters, please refer to the libpcap documentation for the detailed guide. A BPF rule is optional, and may be omitted when a rule is added.

The filter_rule_index parameter specifies the index of the item in the array. The size of the array is controlled by the filter_rule_count property.

This property is read-only.

filter_rule_direction property

This property specifies the direction of the packets that will match the rule.

Syntax

def get_filter_rule_direction(filter_rule_index: int) -> int: ...

Default Value

0

Remarks

This property specifies the direction of the packets that will match the rule.

This property specifies the direction of the packets that will match the rule. The value passed for this parameter may be one of the following:

The filter_rule_index parameter specifies the index of the item in the array. The size of the array is controlled by the filter_rule_count property.

This property is read-only.

filter_rule_max_packet_size property

This property specifies the maximum size of the packets that match the rule.

Syntax

def get_filter_rule_max_packet_size(filter_rule_index: int) -> int: ...

Default Value

0

Remarks

This property specifies the maximum size of the packets that match the rule.

This property specifies the maximum size of the packets that match the rule. If the packet is larger than the value of this parameter, the rule is not applicable to this packet. The value of -1 indicates that the size condition was not specified.

The filter_rule_index parameter specifies the index of the item in the array. The size of the array is controlled by the filter_rule_count property.

This property is read-only.

filter_rule_min_packet_size property

This property specifies the minimum size of the packets that match the rule.

Syntax

def get_filter_rule_min_packet_size(filter_rule_index: int) -> int: ...

Default Value

0

Remarks

This property specifies the minimum size of the packets that match the rule.

This property specifies the minimum size of the packets that match the rule. If the packet is smaller than the value of this parameter, the rule is not applicable to this packet. The value of -1 indicates that the size condition was not specified.

The filter_rule_index parameter specifies the index of the item in the array. The size of the array is controlled by the filter_rule_count property.

This property is read-only.

filter_rule_rule_id property

This property specifies the application-provided Id of the rule.

Syntax

def get_filter_rule_rule_id(filter_rule_index: int) -> int: ...

Default Value

0

Remarks

This property specifies the application-provided Id of the rule.

This property specifies the application-provided Id of the rule. This Id is set in the add_filter_rule method and is used to identify the rule in the delete_filter_rule method.

The filter_rule_index parameter specifies the index of the item in the array. The size of the array is controlled by the filter_rule_count property.

This property is read-only.

operation_mode property

Specifies the mode of operation.

Syntax

def get_operation_mode() -> int: ...
def set_operation_mode(value: int) -> None: ...

operation_mode = property(get_operation_mode, set_operation_mode)

Possible Values

0   # Capture
1   # Stat

Default Value

0

Remarks

This property determines the type of packet information to report. The property value can be one of the following:

passthrough_rule_count property

The number of records in the PassthroughRule arrays.

Syntax

def get_passthrough_rule_count() -> int: ...

passthrough_rule_count = property(get_passthrough_rule_count, None)

Default Value

0

Remarks

This property controls the size of the following arrays:

• passthrough_rule_adapter_id
• passthrough_rule_bpf_rule
• passthrough_rule_direction
• passthrough_rule_max_packet_size
• passthrough_rule_min_packet_size
• passthrough_rule_rule_id

The array indices start at 0 and end at passthrough_rule_count - 1.

This property is read-only.

passthrough_rule_adapter_id property

This property specifies the adapter, on which the driver should track and process packets.

Syntax

def get_passthrough_rule_adapter_id(passthrough_rule_index: int) -> int: ...

Default Value

0

Remarks

This property specifies the adapter, on which the driver should track and process packets.

This property specifies the adapter, on which the driver should track and process packets. If the value is -1, all adapters are tracked.

The passthrough_rule_index parameter specifies the index of the item in the array. The size of the array is controlled by the passthrough_rule_count property.

This property is read-only.

passthrough_rule_bpf_rule property

This property specifies a BPF-compatible rule for matching for packet properties.

Syntax

def get_passthrough_rule_bpf_rule(passthrough_rule_index: int) -> str: ...

Default Value

""

Remarks

This property specifies a BPF-compatible rule for matching for packet properties.

This property specifies a BPF-compatible rule for matching for packet properties. The format of this rule is compatible with libpcap filters, please refer to the libpcap documentation for the detailed guide. A BPF rule is optional, and may be omitted when a rule is added.

The passthrough_rule_index parameter specifies the index of the item in the array. The size of the array is controlled by the passthrough_rule_count property.

This property is read-only.

passthrough_rule_direction property

This property specifies the direction of the packets that will match the rule.

Syntax

def get_passthrough_rule_direction(passthrough_rule_index: int) -> int: ...

Default Value

0

Remarks

This property specifies the direction of the packets that will match the rule.

This property specifies the direction of the packets that will match the rule. The value passed for this parameter may be one of the following:

The passthrough_rule_index parameter specifies the index of the item in the array. The size of the array is controlled by the passthrough_rule_count property.

This property is read-only.

passthrough_rule_max_packet_size property

This property specifies the maximum size of the packets that match the rule.

Syntax

def get_passthrough_rule_max_packet_size(passthrough_rule_index: int) -> int: ...

Default Value

0

Remarks

This property specifies the maximum size of the packets that match the rule.

This property specifies the maximum size of the packets that match the rule. If the packet is larger than the value of this parameter, the rule is not applicable to this packet. The value of -1 indicates that the size condition was not specified.

The passthrough_rule_index parameter specifies the index of the item in the array. The size of the array is controlled by the passthrough_rule_count property.

This property is read-only.

passthrough_rule_min_packet_size property

This property specifies the minimum size of the packets that match the rule.

Syntax

def get_passthrough_rule_min_packet_size(passthrough_rule_index: int) -> int: ...

Default Value

0

Remarks

This property specifies the minimum size of the packets that match the rule.

This property specifies the minimum size of the packets that match the rule. If the packet is smaller than the value of this parameter, the rule is not applicable to this packet. The value of -1 indicates that the size condition was not specified.

The passthrough_rule_index parameter specifies the index of the item in the array. The size of the array is controlled by the passthrough_rule_count property.

This property is read-only.

passthrough_rule_rule_id property

This property specifies the application-provided Id of the rule.

Syntax

def get_passthrough_rule_rule_id(passthrough_rule_index: int) -> int: ...

Default Value

0

Remarks

This property specifies the application-provided Id of the rule.

This property specifies the application-provided Id of the rule. This Id is set in the add_passthrough_rule method and is used to identify the rule in the delete_passthrough_rule method.

The passthrough_rule_index parameter specifies the index of the item in the array. The size of the array is controlled by the passthrough_rule_count property.

This property is read-only.

serialize_events property

Whether events should be fired on a single worker thread, or many.

Syntax

def get_serialize_events() -> int: ...
def set_serialize_events(value: int) -> None: ...

serialize_events = property(get_serialize_events, set_serialize_events)

Possible Values

0   # OnMultipleThreads
1   # OnOneWorkerThread

Default Value

0

Remarks

This property specifies whether the class should fire all events serially on a single worker thread, or concurrently on multiple worker threads. The possible values are:

Please refer to the Threading and Concurrency topic for more information.

NOTE: This property cannot be changed when active is True, and it cannot be changed within events.

tag property

This property stores application-defined data specific to a particular instance of the class.

Syntax

def get_tag() -> int: ...
def set_tag(value: int) -> None: ...

tag = property(get_tag, set_tag)

Default Value

0

Remarks

This property can be used to store data specific to a particular instance of the class.

add_filter_rule method

This method adds a filter rule.

Syntax

def add_filter_rule(rule_id: int, adapter_id: int, direction: int, min_packet_size: int, max_packet_size: int, bpf_rule: str, action: int) -> bool: ...

Remarks

This method adds a filter rule.

If the rule is added successfully, this method returns True; otherwise, it returns False.

Filter rules determine which packets, of those passing by an adapter, the class should act on or fire its events for.

The RuleId parameter specifies the application-provided Id of the rule. This Id is set in add_filter_rule or add_passthrough_rule and is used to identify the rule in delete_filter_rule and delete_passthrough_rule methods.

The AdapterId parameter, if set, specifies the adapter, on which the driver should track and process packets. If the value is -1, all adapters are tracked.

The Direction parameter specifies the direction of the packets that should be captured. The value passed for this parameter may be one of the following:

The MinPacketSize parameter specifies the minimum size of the packets that match the rule. If the packet is smaller than the value of this parameter, the rule is not applicable to this packet. Use the value of -1 to specify that no lower limit is set.

The MaxPacketSize parameter specifies the maximum size of the packets that match the rule. If the packet is larger than the value of this parameter, the rule is not applicable to this packet. Use the value of -1 to specify that no upper limit is set.

The BPFRule parameter specifies a BPF-compatible rule for matching for packet properties. The format of this rule is compatible with libpcap filters, please refer to the libpcap documentation for the detailed guide. A BPF rule is optional, and an empty value may be passed when it is not needed.

The Action parameter specifies the action that the driver should take in regard to the packet that matches the rule. The value passed for this parameter may be one of the following:

NOTE: The methods and properties related to rule management are not intended to be used from multiple threads at once. Applications that wish to use said methods and properties from multiple threads are responsible for employing proper thread synchronization techniques to ensure that manipulation and enumeration of the rule lists both occur in a thread-safe manner.

add_passthrough_rule method

This method adds a passthrough rule.

Syntax

def add_passthrough_rule(rule_id: int, adapter_id: int, direction: int, min_packet_size: int, max_packet_size: int, bpf_rule: str) -> bool: ...

Remarks

This method adds a passthrough rule .

If the rule is added successfully, this method returns True; otherwise, it returns False.

Filter rules determine which packets, of those passing by an adapter, the class should act on or fire its events for.

The RuleId parameter specifies the application-provided Id of the rule. This Id is set in add_filter_rule or add_passthrough_rule and is used to identify the rule in delete_filter_rule and delete_passthrough_rule methods.

The AdapterId parameter, if set, specifies the adapter, on which the driver should track and process packets. If the value is -1, all adapters are tracked.

The Direction parameter specifies the direction of the packets that should be captured. The value passed for this parameter may be one of the following:

The MinPacketSize parameter specifies the minimum size of the packets that match the rule. If the packet is smaller than the value of this parameter, the rule is not applicable to this packet. Use the value of -1 to specify that no lower limit is set.

The MaxPacketSize parameter specifies the maximum size of the packets that match the rule. If the packet is larger than the value of this parameter, the rule is not applicable to this packet. Use the value of -1 to specify that no upper limit is set.

The BPFRule parameter specifies a BPF-compatible rule for matching for packet properties. The format of this rule is compatible with libpcap filters, please refer to the libpcap documentation for the detailed guide. A BPF rule is optional, and an empty value may be passed when it is not needed.

NOTE: The methods and properties related to rule management are not intended to be used from multiple threads at once. Applications that wish to use said methods and properties from multiple threads are responsible for employing proper thread synchronization techniques to ensure that manipulation and enumeration of the rule lists both occur in a thread-safe manner.

config method

Sets or retrieves a configuration setting.

Syntax

def config(configuration_string: str) -> str: ...

Remarks

config is a generic method available in every class. It is used to set and retrieve configuration settings for the class.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, access to these internal properties is provided through the config method.

To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.

delete_all_filter_rules method

This method deletes all filter rules.

Syntax

def delete_all_filter_rules() -> bool: ...

Remarks

This method deletes all filter rules that are currently present.

If the rules are deleted successfully, this method returns True; otherwise, it returns False.

To delete standard filter rules individually, use the delete_filter_rule method instead.

NOTE: The methods and properties related to rule management are not intended to be used from multiple threads at once. Applications that wish to use said methods and properties from multiple threads are responsible for employing proper thread synchronization techniques to ensure that manipulation and enumeration of the rule lists both occur in a thread-safe manner.

delete_all_passthrough_rules method

This method deletes all passthrough rules.

Syntax

def delete_all_passthrough_rules() -> bool: ...

Remarks

This method deletes all passthrough rules that are currently present.

If the rules are deleted successfully, this method returns True; otherwise, it returns False.

To delete passthrough rules individually, use the delete_passthrough_rule method instead.

NOTE: The methods and properties related to rule management are not intended to be used from multiple threads at once. Applications that wish to use said methods and properties from multiple threads are responsible for employing proper thread synchronization techniques to ensure that manipulation and enumeration of the rule lists both occur in a thread-safe manner.

delete_filter_rule method

This method deletes a particular filter rule.

Syntax

def delete_filter_rule(rule_id: int) -> bool: ...

Remarks

This method deletes the specified filter rule identified by RuleId.

If the rule is deleted successfully, this method returns True; otherwise, it returns False.

To delete all filter rules, use the delete_all_filter_rules method instead.

NOTE: The methods and properties related to rule management are not intended to be used from multiple threads at once. Applications that wish to use said methods and properties from multiple threads are responsible for employing proper thread synchronization techniques to ensure that manipulation and enumeration of the rule lists both occur in a thread-safe manner.

delete_passthrough_rule method

This method deletes a particular passthrough rule.

Syntax

def delete_passthrough_rule(rule_id: int) -> bool: ...

Remarks

This method deletes the specified passthrough rule identified by RuleId.

If the rule is deleted successfully, this method returns True; otherwise, it returns False.

To delete all passthrough rules, use the delete_all_passthrough_rules method instead.

NOTE: The methods and properties related to rule management are not intended to be used from multiple threads at once. Applications that wish to use said methods and properties from multiple threads are responsible for employing proper thread synchronization techniques to ensure that manipulation and enumeration of the rule lists both occur in a thread-safe manner.

flush_send_buffer method

Sends packets enqueued in the send buffer to the network.

Syntax

def flush_send_buffer(adapter_id: int) -> None: ...

Remarks

This method sends the packets previously placed by the send_packet method into the send buffer of the adapter identified by AdapterId to the network. If AdapterId is set to -1, send buffers of all adapters are flushed.

get_driver_status method

This method retrieves the status of the class's system driver.

Syntax

def get_driver_status(product_guid: str) -> int: ...

Remarks

This method retrieves the status of the class's system driver. This status can then be used to verify whether it has been properly installed and is ready for use.

The value returned by the method corresponds to the dwCurrentState field of the SERVICE_STATUS structure from the Windows API. It will be one of the following:

ProductGUID is used to distinguish among driver installations performed by different applications as well as separate filter instances. Such information is necessary to guard against unexpected situations, such as the driver being uninstalled by one application despite other applications still needing it.

Therefore, to ensure proper operation, it is critical that each individual application have its own unique ProductGUID value, and that applications (and their installation scripts) use that value when calling any of the following methods:

• install
• uninstall
• get_driver_status
• get_driver_version
• initialize

Additionally, some per-instance settings are stored in the GUID-specific registry keys. If multiple instances of the class are used, each instance must have own ProductGUID, and the driver must be installed several times.

This method is available in both the class API and the Installer DLL included with the product; please refer to the Driver Installation topic for more information about the latter.

NOTE: This method cannot be called within events.

get_driver_version method

This method retrieves the version of the class's system driver.

Syntax

def get_driver_version(product_guid: str) -> int: ...

Remarks

This method retrieves the version of the class's system driver. The value is returned as a 64-bit integer composed of four 16-bit words that each correspond to a piece of the overall module version. For example, a version of 2.32.6.28 would cause the value 0x000200200006001C to be returned.

If the class's system driver is not installed, this method returns 0.

ProductGUID is used to distinguish among driver installations performed by different applications as well as separate filter instances. Such information is necessary to guard against unexpected situations, such as the driver being uninstalled by one application despite other applications still needing it.

Therefore, to ensure proper operation, it is critical that each individual application have its own unique ProductGUID value, and that applications (and their installation scripts) use that value when calling any of the following methods:

• install
• uninstall
• get_driver_status
• get_driver_version
• initialize

Additionally, some per-instance settings are stored in the GUID-specific registry keys. If multiple instances of the class are used, each instance must have own ProductGUID, and the driver must be installed several times.

This method is available in both the class API and the Installer DLL included with the product; please refer to the Driver Installation topic for more information about the latter.

NOTE: This method cannot be called within events.

get_statistics method

Requests the statistics to be passed via the Statistics event.

Syntax

def get_statistics(adapter_id: int) -> None: ...

Remarks

This method asks the driver to send the available statistics to the application via the on_statistics event regardless of the current operation mode.

The AdapterId parameters identifies the adapter, whose statistics are requested.

initialize method

This method initializes the class.

Syntax

def initialize(product_guid: str) -> None: ...

Remarks

This method initializes the class and must be called each time the application starts before attempting to call any of the class's other methods with the exception of installation-related methods.

ProductGUID is used to distinguish between driver installations performed by different applications. Such information is necessary to guard against unexpected situations such as, e.g., the driver being uninstalled by one application despite other applications still needing it.

The GUID must be specified in so-called "Registry Format" (e.g., "{1FAD0EF2-9A03-4B87-B4BC-645B7035ED90}") with curly braces included.

To ensure proper operation, it is critical that each individual application have its own unique ProductGUID value, and that applications (and their installation scripts) use that value when calling any of the following methods:

• install
• uninstall
• get_driver_status
• get_module_version
• register_icon
• unregister_icon
• initialize

If the required driver was not installed using the install method with the same value of ProductGUID, initialize will return a ERROR_FILE_NOT_FOUND error (Win32 error code 2).

If the loaded kernel-mode driver is older than the user-mode API, initialize will return a ERROR_INVALID_KERNEL_INFO_VERSION error (Win32 error code 340). In this situation, an update of the driver using the install method is required before the class can be used.

insert_incoming_packet method

Inserts an "incoming" packet in the incoming packets flow of the adapter.

Syntax

def insert_incoming_packet(adapter_id: int, data: bytes) -> None: ...

Remarks

This method inserts the packet contained in Data to the stream of incoming packets of the adapter identified by its Id in the AdapterId parameter. For sending packets to other systems, use the send_packet method.

Use the list_adapters method to populate the adapters property; then, use the name from the populated property in a call to this method.

Important: The caller is responsible for building complete packets suitable for inserting to the specified adapter; this includes calculating packet checksums where it is required (IP, TCP, UDP, etc.) and storing them in the packets being inserted.

install method

This method installs (or upgrades) the class's system driver.

Syntax

def install(cab_file_name: str, product_guid: str, altitude: int, flags: int, allowed_controllers: str) -> bool: ...

Remarks

This method is used to install or upgrade the class's system driver. If the system must be rebooted to complete the installation process, this method returns True; otherwise, it returns False.

Important: To upgrade the product's modules, use only the install method. Previously installed versions of the modules should not be uninstalled first. Calling the install method will upgrade the previously installed version.

Please refer to the Driver Installation topic for more information.

CabFileName must be the path of the netfilter.cab file containing the class's system driver.

NOTE: This .cab file must remain on the target system (or be available in some other way) after installation, as it is required to uninstall the driver from the system.

ProductGUID is used to distinguish among driver installations performed by different applications as well as separate filter instances. Such information is necessary to guard against unexpected situations, such as the driver being uninstalled by one application despite other applications still needing it.

Therefore, to ensure proper operation, it is critical that each individual application have its own unique ProductGUID value, and that applications (and their installation scripts) use that value when calling any of the following methods:

• install
• uninstall
• get_driver_status
• get_driver_version
• initialize

Additionally, some per-instance settings are stored in the GUID-specific registry keys. If multiple instances of the class are used, each instance must have own ProductGUID, and the driver must be installed several times.

The Altitude parameter specifies the altitude of this filter relative to other filters implmented using the NetFilter driver. The altitude defines the order of calling the instances - the higher the altitude, the earlier the instance's events are fired.

Flags specifies various installation options. It should be created by OR'ing together (e.g., "CONST_A | CONST_B") zero or more of the following flags:

AllowedControllers is the optional parameter that makes it possible to limit communication with the driver to just the predefined set of processes. When the caller specifies one or more names of the executable files, filtering can be started with the specified ProductGUID only when filtering is initiated by the process created from one of the listed executable files. If the name of the caller process does not match any of the allowed names, the call to start_filter will fail with an error.

The parameter may be either empty or contain one or more EXE file names with complete paths. Separate names/paths should be separated by the LF character (numeric code 10).

This method is available in both the class API and the Installer DLL included with the product; please refer to the Driver Installation topic for more information about the latter.

This method requires administrative rights to execute successfully. If the user account of the process that calls this method doesn't have such rights, the call will fail with an ERROR_PRIVILEGE_NOT_HELD (0x0522) error.

NOTE: This method cannot be called within events.

list_adapters method

Fills the Adapters property with the list of network adapters.

Syntax

def list_adapters() -> None: ...

Remarks

This method fills the Adapters property / collection with the list of items that represent the adapters available for monitoring. The list includes adapter IDs, names, descriptions, and supplementary information.

Use this method to obtain the Ids and various information about the adapters; then, use one of the provided Ids in calls to the add_filter_rule or add_passthrough_rule methods.

nt_status_to_win32_error method

This method converts a native status code to a Win32 error code.

Syntax

def nt_status_to_win32_error(status: int) -> int: ...

Remarks

This method converts the native status code specified by Status to a Win32 error code. If the specified native status code does not map directly to a Win32 error code, this method returns ERROR_MR_MID_NOT_FOUND (317).

send_packet method

Sends a packet to the network or adds it to the send buffer.

Syntax

def send_packet(adapter_id: int, data: bytes, num_times: int, buffer_only: bool) -> None: ...

Remarks

This method sends the packet contained in Data to the adapter identified by its Id in the AdapterId parameter for delivery to other systems. To insert the "incoming" packet to the adapter's queue of incoming packets, use the insert_incoming_packet method.

If the BufferOnly parameter is True, the packet is only added to the send buffer and is not sent immediately. To send the packets from the buffer later, use the flush_send_buffer method. An application can use the BufferOnly parameter and the send buffer to prepare a set of packets and send them all together, which is more efficient than sending packets one by one.

The NumTimes parameter specifies, how many times the packet will be sent or added to the buffer.

Use the list_adapters method to populate the adapters property; then, use the name from the populated property in a call to this method.

Important: The caller is responsible for building complete packets suitable for sending via the specified adapter; this includes calculating packet checksums where it is required (IP, TCP, UDP, etc.) and inserting them into the packets being sent.

shutdown_system method

Shuts down or reboots the operating system.

Syntax

def shutdown_system(shutdown_prompt: str, timeout: int, force_close_apps: bool, reboot: bool) -> bool: ...

Remarks

This method shuts down or (if Reboot is True) reboots the operating system. If the appropriate privileges cannot be obtained, or if the InitiateSystemShutdown system call returns False, then this method will return False; otherwise, it returns True. This method can be used if the installation or uninstallation function requires the system to be rebooted in order to complete.

ShutdownPrompt, if non-empty, specifies a message that the OS should display to the user for Timeout seconds. If empty string is passed for ShutdownPrompt, no message is displayed and the Timeout parameter's value is ignored.

ForceCloseApps specifies whether the OS should forcefully close all applications. Please keep in mind that forceful closing of applications with unsaved data can lead to data loss.

Reboot specifies whether the OS should reboot (True) or just shut down (False).

This method is available in both the class API and the Installer DLL included with the product; please refer to the Driver Installation topic for more information about the latter.

NOTE: This method cannot be called within events.

start_filter method

This method start filtering network operations.

Syntax

def start_filter(timeout: int) -> None: ...

Remarks

This method attaches the filter, causing the class's system driver to start filtering network operations according to the filter rules currently present. Rules can be added and removed both before and after this method is called, so long as the initialize method is called before doing anything else.

This method can fail for a number of reasons, including (but not limited to) the following:

• If the class's system driver has not been properly installed, or is awaiting a system reboot (as indicated by the return value of install), this method fails with an ERROR_FILE_NOT_FOUND (2) error code.
• If the initialize method has not been called yet, this method fails with an ERROR_NOT_READY (21) error code.
• If the filter is already active, this method fails with an ERROR_CONNECTION_ACTIVE (1230) error code.
• If an invalid value is passed for Timeout, this method fails with an ERROR_IMPLEMENTATION_LIMIT (1292) error code.

Timeout

Timeout specifies how many milliseconds the driver should wait for events to execute before releasing or cancelling the underlying OS requests; please refer to the Timeouts topic for more information. Valid values are 0, which disables event timeouts, and values greater than or equal to 3000. When event timeouts are in effect, event handlers can call reset_timeout to reset the timer if they require additional time to complete.

stop_filter method

This method stops filtering network operations.

Syntax

def stop_filter() -> None: ...

Remarks

This method detaches the filter, causing the class's system driver to stop filtering network operations. This method will block until all pending requests have been completed and the filter has been detached.

toggle_process_protection method

This method enables or disables termination protection for the application.

Syntax

def toggle_process_protection(enabled: bool) -> bool: ...

Remarks

This method controls the termination protection mechanism, which applications can enable to prevent their process and threads from being terminated. If successful, this method returns True; otherwise, it returns False.

The Enabled parameter specifies whether termination protection should be enabled (True) or disabled (False); it is disabled by default. If termination protection is enabled, an application must disable it before attempting to exit.

NOTE: When developing a GUI-based application, please keep in mind that the termination protection mechanism does not intercept Windows' notifications like WM_CLOSE or WM_QUIT; applications must intercept and handle such messages themselves if they wish to protect their UI. Please refer to Microsoft's Window Notifications articles for more information.

uninstall method

This method uninstalls the class's system driver.

Syntax

def uninstall(cab_file_name: str, product_guid: str, flags: int) -> bool: ...

Remarks

This method is used to uninstall the class's system driver. If the system must be rebooted to complete the uninstallation process, this method returns True; otherwise, it returns False.

Important: To upgrade the product's modules, use only the install method. Previously installed versions of the modules should not be uninstalled first. Calling the install method will upgrade the previously installed version.

Please refer to the Driver Installation topic for more information.

The same values must be passed for the CabFileName and ProductGUID parameters as were passed when install was called; please refer to its documentation for more information.

Flags specifies which versions of the class's system driver should be uninstalled and which should be set by OR'ing together (e.g., "CONST_A | CONST_B") one or more of the following values:

This method is available in both the class API and the Installer DLL included with the product; please refer to the Driver Installation topic for more information about the latter.

This method requires administrative rights to execute successfully. If the user account of the process that calls this method doesn't have such rights, the call will fail with an ERROR_PRIVILEGE_NOT_HELD (0x0522) error.

NOTE: This method cannot be called within events.

on_adapter_added event

Fires to inform about a new adapter being added to the system.

Syntax

class NetFilterAdapterAddedEventParams(object):
  @property
  def adapter_id() -> int: ...

# In class NetFilter:
@property
def on_adapter_added() -> Callable[[NetFilterAdapterAddedEventParams], None]: ...
@on_adapter_added.setter
def on_adapter_added(event_hook: Callable[[NetFilterAdapterAddedEventParams], None]) -> None: ...

Remarks

This event fires when a new adapter is added to the system. If an application uses adapter-specific rules, it can add or update rules in the corresponding event handler.

NOTE: The methods and properties related to rule management are not intended to be used from multiple threads at once. Applications that wish to use said methods and properties from multiple threads are responsible for employing proper thread synchronization techniques to ensure that manipulation and enumeration of the rule lists both occur in a thread-safe manner.

on_adapter_removed event

Fires to inform about an adapter being removed from the system.

Syntax

class NetFilterAdapterRemovedEventParams(object):
  @property
  def adapter_id() -> int: ...

# In class NetFilter:
@property
def on_adapter_removed() -> Callable[[NetFilterAdapterRemovedEventParams], None]: ...
@on_adapter_removed.setter
def on_adapter_removed(event_hook: Callable[[NetFilterAdapterRemovedEventParams], None]) -> None: ...

Remarks

This event fires when an adapter is removed from the system. If an application uses adapter-specific rules, it can remove or update rules in the corresponding event handler.

NOTE: The methods and properties related to rule management are not intended to be used from multiple threads at once. Applications that wish to use said methods and properties from multiple threads are responsible for employing proper thread synchronization techniques to ensure that manipulation and enumeration of the rule lists both occur in a thread-safe manner.

on_error event

This event fires if an unhandled error occurs during an event.

Syntax

class NetFilterErrorEventParams(object):
  @property
  def error_code() -> int: ...

  @property
  def description() -> str: ...

# In class NetFilter:
@property
def on_error() -> Callable[[NetFilterErrorEventParams], None]: ...
@on_error.setter
def on_error(event_hook: Callable[[NetFilterErrorEventParams], None]) -> None: ...

Remarks

This event fires if an unhandled error occurs during another event. Developers can use this information to track down unhandled errors in an application's event handlers.

on_notify_packet event

This event fires when a packet is captured for notification.

Syntax

class NetFilterNotifyPacketEventParams(object):
  @property
  def adapter_id() -> int: ...

  @property
  def timestamp() -> datetime.datetime: ...

  @property
  def timestamp_ns() -> int: ...

  @property
  def packet_type() -> int: ...

  @property
  def direction() -> int: ...

  @property
  def packet_size() -> int: ...

  @property
  def data() -> c_void_p: ...

  @property
  def data_size() -> int: ...

  @property
  def ip_offset() -> int: ...

  @property
  def ip_size() -> int: ...

# In class NetFilter:
@property
def on_notify_packet() -> Callable[[NetFilterNotifyPacketEventParams], None]: ...
@on_notify_packet.setter
def on_notify_packet(event_hook: Callable[[NetFilterNotifyPacketEventParams], None]) -> None: ...

Remarks

This event fires asynchronously after a network packet is captured on the adapter identified by the AdapterId parameter.

The Timestamp parameter contains the time when the packet was received by the network adapter. TimestampNS contains the number of nanoseconds since the millisecond specified in Timestamp.

The PacketType parameter specifies the type of the network and the format of the received packet. The value passed for this parameter may be one of the following:

The Direction parameter specifies the direction of the packet. The value passed for this parameter may be one of the following:

The PacketSize parameter contains the total size of the packet as received by the network adapter. This represents the full byte size of the packet, which may be larger than the amount of data captured in the Data parameter.

The Data parameter contains the packet data that was captured. The amount of data captured is controlled by the field of the Adapter and may be smaller than the full packet size.

The DataSize parameter provides the size of the data contained in the Data parameter. This value represents how much of the packet data was actually captured and made available.

The IPOffset parameter specifies the starting position of the IP packet within the Data, and the IPSize parameter contains the size of the data of the IP packet contained in Data (this size may be smaller than the full packet depending on the value of the field of the Adapter).

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason, set it to a non-zero value to report an appropriate error.

NOTE: This event fires after the operation has already completed, so reporting an error will not actually affect the operation itself. Please refer to the Error Handling topic for more information.

This event is fired asynchronously; please refer to the Event Types topic for more information.

on_packet event

This event fires when a network packet is captured.

Syntax

class NetFilterPacketEventParams(object):
  @property
  def adapter_id() -> int: ...

  @property
  def timestamp() -> datetime.datetime: ...

  @property
  def timestamp_ns() -> int: ...

  @property
  def packet_type() -> int: ...

  @property
  def direction() -> int: ...

  @property
  def packet_size() -> int: ...

  @property
  def buffer() -> c_void_p: ...

  @property
  def buffer_size() -> int: ...

  @property
  def data_size() -> int: ...
  @data_size.setter
  def data_size(value) -> None: ...

  @property
  def ip_offset() -> int: ...

  @property
  def ip_size() -> int: ...

  @property
  def action() -> int: ...
  @action.setter
  def action(value) -> None: ...

  @property
  def result_code() -> int: ...
  @result_code.setter
  def result_code(value) -> None: ...

# In class NetFilter:
@property
def on_packet() -> Callable[[NetFilterPacketEventParams], None]: ...
@on_packet.setter
def on_packet(event_hook: Callable[[NetFilterPacketEventParams], None]) -> None: ...

Remarks

This event fires when a network packet is captured on the adapter identified by the AdapterId parameter with an option to drop or alter the packet.

The Timestamp parameter contains the time when the packet was received by the network adapter. TimestampNS contains the number of nanoseconds since the millisecond specified in Timestamp.

The PacketType parameter specifies the type of the network and the format of the received packet. The value passed for this parameter may be one of the following:

The Direction parameter specifies the direction of the packet. The value passed for this parameter may be one of the following:

The PacketSize parameter contains the total size of the packet as received by the network adapter. This represents the full byte size of the packet, which may be larger than the amount of data contained in the Buffer parameter.

The Buffer parameter contains the packet data that was captured. The amount of data captured is controlled by the field of the Adapter and may be smaller than the full packet size.

The BufferSize parameter indicates the size of the buffer in the Buffer parameter.

The DataSize parameter indicates the size of the data contained in the Buffer parameter.

The IPOffset parameter specifies the starting position of the IP packet within the Buffer, and the IPSize parameter contains the size of the data of the IP packet contained in Buffer (this size may be smaller than the full packet depending on the value of the field of the Adapter).

The Action parameter specifies the action that the driver should take in regard to this specific packet. The value passed for this parameter may be one of the following:

If the event handler needs to alter the packet, it should setAction to PACKET_ACTION_SEND_MODIFIED, write the completely formed packet suitable for sending via the adapter to Buffer, and set DataSize to the size of the data stored in the buffer. If the buffer size as indicated by BufferSize is too small, the event handler should set DataSize to the required size and then set ResultCode to ERROR_INSUFFICIENT_BUFFER (122). The class will allocate the buffer of the needed size and will fire the event again.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

This event is fired synchronously; please refer to the Event Types topic for more information.

on_statistics event

Fires to provide aggregated packet statistics.

Syntax

class NetFilterStatisticsEventParams(object):
  @property
  def adapter_id() -> int: ...

  @property
  def filter_specific() -> bool: ...

  @property
  def time_stamp() -> datetime.datetime: ...

  @property
  def packets_received() -> int: ...

  @property
  def bytes_received() -> int: ...

  @property
  def packets_sent() -> int: ...

  @property
  def bytes_sent() -> int: ...

  @property
  def packets_dropped_inbound() -> int: ...

  @property
  def bytes_dropped_inbound() -> int: ...

  @property
  def packets_dropped_outbound() -> int: ...

  @property
  def bytes_dropped_outbound() -> int: ...

# In class NetFilter:
@property
def on_statistics() -> Callable[[NetFilterStatisticsEventParams], None]: ...
@on_statistics.setter
def on_statistics(event_hook: Callable[[NetFilterStatisticsEventParams], None]) -> None: ...

Remarks

This event fires to provide aggregated packet statistics collected from the network adapter. The event will fire if operation_mode is set to omStat (1) or after get_statistics is called.

The values grow over time and are not reset automatically (until the counter overflows).

The AdapterId parameter contains the Id of the adapter, to which the statistics are related.

The FilterSpecific parameter indicates if the statistics in the event parameters is total for the adapter or specific to the filter (if start_filter was called and filtration is active). The driver sends only total statistics if filtration is not started (e.g., when get_statistics is called) or both sets of data separately when filtration is active and operation_mode is set to omStat (1).

The TimeStamp parameter contains the time when the packet statistics were collected.

The PacketsReceived parameter contains the number of packets received on the interface since the driver start.

The BytesReceived parameter contains the number of bytes received on the interface since the driver start.

The PacketsSent parameter contains the number of packets sent on the interface since the driver start.

The BytesSent parameter contains the number of bytes sent on the interface since the driver start.

The PacketsDroppedInbound parameter contains the number of inbound packets that have been dropped.

The BytesDroppedInbound parameter contains the number of bytes in inbound packets that have been dropped.

The PacketsDroppedOutbound parameter contains the number of outbound packets that have been dropped.

The BytesDroppedOutbound parameter contains the number of bytes in outbound packets that have been dropped.

The dropped packets are counted when they are dropped regardless of the reason - either according to the rules or because the on_packet event handler instructed NetFilter to drop the packet.

on_worker_thread_creation event

Fires just after a new worker thread is created.

Syntax

class NetFilterWorkerThreadCreationEventParams(object):
  @property
  def result_code() -> int: ...
  @result_code.setter
  def result_code(value) -> None: ...

# In class NetFilter:
@property
def on_worker_thread_creation() -> Callable[[NetFilterWorkerThreadCreationEventParams], None]: ...
@on_worker_thread_creation.setter
def on_worker_thread_creation(event_hook: Callable[[NetFilterWorkerThreadCreationEventParams], None]) -> None: ...

Remarks

This event fires just after a worker thread is created, in the context of that worker thread.

This event is optional; it is provided to give applications a chance to perform additional processing when a new worker thread is created, such as allocating per-thread objects.

The class maintains a pool of worker threads and uses them to fire events; please refer to the Threading and Concurrency topic for more information.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

on_worker_thread_termination event

Fires just before a worker thread is terminated.

Syntax

class NetFilterWorkerThreadTerminationEventParams(object):
# In class NetFilter:
@property
def on_worker_thread_termination() -> Callable[[NetFilterWorkerThreadTerminationEventParams], None]: ...
@on_worker_thread_termination.setter
def on_worker_thread_termination(event_hook: Callable[[NetFilterWorkerThreadTerminationEventParams], None]) -> None: ...

Remarks

This event fires just before a worker thread is terminated, in the context of that worker thread.

This event is optional; it is provided to give applications a chance to perform additional processing before a worker thread is terminated, such as deallocating per-thread objects.

The class maintains a pool of worker threads and uses them to fire events; please refer to the Threading and Concurrency topic for more information.

Any errors that occur during this event are ignored.

NetFilter Config Settings

The class accepts one or more of the following configuration settings. Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, access to these internal properties is provided through the config method.

NetFilter Config Settings

Base Config Settings

NetFilter Errors