NetFilter Class

Properties   Methods   Events   Config Settings   Errors  

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

Syntax

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 ListAdapters 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 AddFilterRule. (Rules can also be added or removed after the filter is started.)
5. Call the StartFilter method to start filtering network packets.
6. When finished, call the StopFilter 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 (NetFilter Class)

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

Syntax

public boolean isActive();

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 StartFilter.

This property is read-only and not available at design time.

Adapters Property (NetFilter Class)

A collection of network adapters available for monitoring.

Syntax

public AdapterList getAdapters();

Remarks

This collection contains the list of network adapters available for monitoring. Calling ListAdapters will populate this collection.

This property is read-only and not available at design time.

Please refer to the Adapter type for a complete list of fields.

Altitude Property (NetFilter Class)

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

Syntax

public int getAltitude();
public void setAltitude(int 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.

FilterRules Property (NetFilter Class)

This property includes a collection of filter rules.

Syntax

public FilterRuleList getFilterRules();

Remarks

This property holds a collection of FilterRule objects, each of which represents a filter rule. Please refer to the Filter Rules topic for more information.

Use the following methods to manage the rules in this collection:

• AddFilterRule
• DeleteFilterRule
• DeleteAllFilterRules

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.

This property is read-only and not available at design time.

Please refer to the FilterRule type for a complete list of fields.

OperationMode Property (NetFilter Class)

Specifies the mode of operation.

Syntax

public int getOperationMode();
public void setOperationMode(int operationMode);

Enumerated values:
  public final static int omCapture = 0;
  public final static int omStat = 1;

Default Value

0

Remarks

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

PassthroughRules Property (NetFilter Class)

This property includes a collection of passthrough rules.

Syntax

public PassthroughRuleList getPassthroughRules();

Remarks

This property holds a collection of PassthroughRule objects, each of which represents a passthrough rule. Please refer to the Passthrough Rules topic for more information.

Use the following methods to manage the rules in this collection:

• AddPassthroughRule
• DeletePassthroughRule
• DeleteAllPassthroughRules

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.

This property is read-only and not available at design time.

Please refer to the PassthroughRule type for a complete list of fields.

SerializeEvents Property (NetFilter Class)

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

Syntax

public int getSerializeEvents();
public void setSerializeEvents(int serializeEvents);

Enumerated values:
  public final static int seOnMultipleThreads = 0;
  public final static int seOnOneWorkerThread = 1;

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 (NetFilter Class)

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

Syntax

public long getTag();
public void setTag(long tag);

Default Value

0

Remarks

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

AddFilterRule Method (NetFilter Class)

This method adds a filter rule.

Syntax

public boolean addFilterRule(long ruleId, int adapterId, int direction, int minPacketSize, int maxPacketSize, String BPFRule, int action);

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 AddFilterRule or AddPassthroughRule and is used to identify the rule in DeleteFilterRule and DeletePassthroughRule 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.

AddPassthroughRule Method (NetFilter Class)

This method adds a passthrough rule.

Syntax

public boolean addPassthroughRule(long ruleId, int adapterId, int direction, int minPacketSize, int maxPacketSize, String BPFRule);

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 AddFilterRule or AddPassthroughRule and is used to identify the rule in DeleteFilterRule and DeletePassthroughRule 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 (NetFilter Class)

Sets or retrieves a configuration setting.

Syntax

public String config(String configurationString);

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.

DeleteAllFilterRules Method (NetFilter Class)

This method deletes all filter rules.

Syntax

public boolean deleteAllFilterRules();

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 DeleteFilterRule 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.

DeleteAllPassthroughRules Method (NetFilter Class)

This method deletes all passthrough rules.

Syntax

public boolean deleteAllPassthroughRules();

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 DeletePassthroughRule 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.

DeleteFilterRule Method (NetFilter Class)

This method deletes a particular filter rule.

Syntax

public boolean deleteFilterRule(long ruleId);

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 DeleteAllFilterRules 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.

DeletePassthroughRule Method (NetFilter Class)

This method deletes a particular passthrough rule.

Syntax

public boolean deletePassthroughRule(long ruleId);

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 DeleteAllPassthroughRules 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.

FlushSendBuffer Method (NetFilter Class)

Sends packets enqueued in the send buffer to the network.

Syntax

public void flushSendBuffer(int adapterId);

Remarks

This method sends the packets previously placed by the SendPacket 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.

GetDriverStatus Method (NetFilter Class)

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

Syntax

public int getDriverStatus(String productGUID);

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
• GetDriverStatus
• GetDriverVersion
• 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.

GetDriverVersion Method (NetFilter Class)

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

Syntax

public long getDriverVersion(String productGUID);

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
• GetDriverStatus
• GetDriverVersion
• 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.

GetStatistics Method (NetFilter Class)

Requests the statistics to be passed via the Statistics event.

Syntax

public void getStatistics(int adapterId);

Remarks

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

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

Initialize Method (NetFilter Class)

This method initializes the class.

Syntax

public void initialize(String productGUID);

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
• GetDriverStatus
• GetModuleVersion
• RegisterIcon
• UnregisterIcon
• 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.

InsertIncomingPacket Method (NetFilter Class)

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

Syntax

public void insertIncomingPacket(int adapterId, byte[] data);

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 SendPacket method.

Use the ListAdapters 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 (NetFilter Class)

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

Syntax

public boolean install(String cabFileName, String productGUID, int altitude, int flags, String allowedControllers);

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
• GetDriverStatus
• GetDriverVersion
• 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., "Constants.CONST_A | Constants.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 StartFilter 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.

ListAdapters Method (NetFilter Class)

Fills the Adapters property with the list of network adapters.

Syntax

public void listAdapters();

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 AddFilterRule or AddPassthroughRule methods.

NtStatusToWin32Error Method (NetFilter Class)

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

Syntax

public int ntStatusToWin32Error(int status);

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).

SendPacket Method (NetFilter Class)

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

Syntax

public void sendPacket(int adapterId, byte[] data, int numTimes, boolean bufferOnly);

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 InsertIncomingPacket 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 FlushSendBuffer 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 ListAdapters 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.

ShutdownSystem Method (NetFilter Class)

Shuts down or reboots the operating system.

Syntax

public boolean shutdownSystem(String shutdownPrompt, int timeout, boolean forceCloseApps, boolean reboot);

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.

StartFilter Method (NetFilter Class)

This method start filtering network operations.

Syntax

public void startFilter(int timeout);

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 ResetTimeout to reset the timer if they require additional time to complete.

StopFilter Method (NetFilter Class)

This method stops filtering network operations.

Syntax

public void stopFilter();

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.

ToggleProcessProtection Method (NetFilter Class)

This method enables or disables termination protection for the application.

Syntax

public boolean toggleProcessProtection(boolean enabled);

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 (NetFilter Class)

This method uninstalls the class's system driver.

Syntax

public boolean uninstall(String cabFileName, String productGUID, int flags);

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., "Constants.CONST_A | Constants.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.

AdapterAdded Event (NetFilter Class)

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

Syntax

public class DefaultNetFilterEventListener implements NetFilterEventListener {
  ...
  public void adapterAdded(NetFilterAdapterAddedEvent e) {}
  ...
}

public class NetFilterAdapterAddedEvent {
  public int adapterId;
}

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.

AdapterRemoved Event (NetFilter Class)

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

Syntax

public class DefaultNetFilterEventListener implements NetFilterEventListener {
  ...
  public void adapterRemoved(NetFilterAdapterRemovedEvent e) {}
  ...
}

public class NetFilterAdapterRemovedEvent {
  public int adapterId;
}

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.

Error Event (NetFilter Class)

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

Syntax

public class DefaultNetFilterEventListener implements NetFilterEventListener {
  ...
  public void error(NetFilterErrorEvent e) {}
  ...
}

public class NetFilterErrorEvent {
  public int errorCode;
  public String description;
}

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.

NotifyPacket Event (NetFilter Class)

This event fires when a packet is captured for notification.

Syntax

public class DefaultNetFilterEventListener implements NetFilterEventListener {
  ...
  public void notifyPacket(NetFilterNotifyPacketEvent e) {}
  ...
}

public class NetFilterNotifyPacketEvent {
  public int adapterId;
  public java.util.Date timestamp;
  public int timestampNS;
  public int packetType;
  public int direction;
  public int packetSize;
  public ByteBuffer data;
  public int dataSize;
  public int IPOffset;
  public int IPSize;
}

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 MaxPacketBytes 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 MaxPacketBytes 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.

Packet Event (NetFilter Class)

This event fires when a network packet is captured.

Syntax

public class DefaultNetFilterEventListener implements NetFilterEventListener {
  ...
  public void packet(NetFilterPacketEvent e) {}
  ...
}

public class NetFilterPacketEvent {
  public int adapterId;
  public java.util.Date timestamp;
  public int timestampNS;
  public int packetType;
  public int direction;
  public int packetSize;
  public ByteBuffer buffer;
  public int bufferSize;
  public int dataSize; //read-write
  public int IPOffset;
  public int IPSize;
  public int action; //read-write
  public int resultCode; //read-write
}

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 MaxPacketBytes 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 MaxPacketBytes 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.

Statistics Event (NetFilter Class)

Fires to provide aggregated packet statistics.

Syntax

public class DefaultNetFilterEventListener implements NetFilterEventListener {
  ...
  public void statistics(NetFilterStatisticsEvent e) {}
  ...
}

public class NetFilterStatisticsEvent {
  public int adapterId;
  public boolean filterSpecific;
  public java.util.Date timeStamp;
  public long packetsReceived;
  public long bytesReceived;
  public long packetsSent;
  public long bytesSent;
  public long packetsDroppedInbound;
  public long bytesDroppedInbound;
  public long packetsDroppedOutbound;
  public long bytesDroppedOutbound;
}

Remarks

This event fires to provide aggregated packet statistics collected from the network adapter. The event will fire if OperationMode is set to omStat (1) or after GetStatistics 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 StartFilter was called and filtration is active). The driver sends only total statistics if filtration is not started (e.g., when GetStatistics is called) or both sets of data separately when filtration is active and OperationMode 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 Packet event handler instructed NetFilter to drop the packet.

WorkerThreadCreation Event (NetFilter Class)

Fires just after a new worker thread is created.

Syntax

public class DefaultNetFilterEventListener implements NetFilterEventListener {
  ...
  public void workerThreadCreation(NetFilterWorkerThreadCreationEvent e) {}
  ...
}

public class NetFilterWorkerThreadCreationEvent {
  public int resultCode; //read-write
}

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.

WorkerThreadTermination Event (NetFilter Class)

Fires just before a worker thread is terminated.

Syntax

public class DefaultNetFilterEventListener implements NetFilterEventListener {
  ...
  public void workerThreadTermination(NetFilterWorkerThreadTerminationEvent e) {}
  ...
}

public class NetFilterWorkerThreadTerminationEvent {
}

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.

Adapter Type

Represents a network adapter in the system.

Remarks

Each item of this type represents a network adapter available in the system that can be used for monitoring.

• BufferSize
• CollectStatistics
• Description
• FriendlyName
• Id
• InterfaceType
• MACAddress
• MaxPacketBytes
• Name
• PacketTimeout
• PromiscuousMode
• WiFiMonitorMode
• WiFiMonitorModeSupported

Fields

FilterRule Type

This type represents a network filter rule.

Remarks

This type represents a network filter rule. Please refer to the Filter Rules topic for more information.

• Action
• AdapterId
• BPFRule
• Direction
• MaxPacketSize
• MinPacketSize
• RuleId

Fields

PassthroughRule Type

This type represents a netork passthrough rule.

Remarks

This type represents a network passthrough rule. Please refer to the Passthrough Rules topic for more information.

• AdapterId
• BPFRule
• Direction
• MaxPacketSize
• MinPacketSize
• RuleId

Fields

Config Settings (NetFilter Class)

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

Trappable Errors (NetFilter Class)