NetFilter Component

Properties   Methods   Events   Config Settings   Errors  

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

Syntax

TcbpNetFilter

Remarks

The NetFilter component 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 component's capabilities, please refer to the product's General Information topics.

Getting Started

1. If the component'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 component. 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 component'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 component with short descriptions. Click on the links for further details.

Method List

---

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

Event List

---

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

Config Settings

---

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

Active Property (NetFilter Component)

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

Syntax

property Active: Boolean read get_Active;

Default Value

false

Remarks

This property reflects whether the component 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 Component)

A collection of network adapters available for monitoring.

Syntax

property Adapters: TcbpAdapterList read get_Adapters;

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

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

Syntax

property Altitude: Integer read get_Altitude write set_Altitude;

Default Value

0

Remarks

This property specifies the altitude that the component'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 Component)

This property includes a collection of filter rules.

Syntax

property FilterRules: TcbpFilterRuleList read get_FilterRules;

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

Specifies the mode of operation.

Syntax

property OperationMode: TcbpFilterOperationModes read get_OperationMode write set_OperationMode;

TcbpFilterOperationModes = (
  omCapture,
  omStat
);

Default Value

omCapture

Remarks

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

PassthroughRules Property (NetFilter Component)

This property includes a collection of passthrough rules.

Syntax

property PassthroughRules: TcbpPassthroughRuleList read get_PassthroughRules;

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

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

Syntax

property SerializeEvents: TcbpTSerializeEvents read get_SerializeEvents write set_SerializeEvents;

TcbpTSerializeEvents = (
  seOnMultipleThreads,
  seOnOneWorkerThread
);

Default Value

seOnMultipleThreads

Remarks

This property specifies whether the component 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 Component)

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

Syntax

property Tag: Int64 read get_Tag write set_Tag;

Default Value

0

Remarks

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

AddFilterRule Method (NetFilter Component)

This method adds a filter rule.

Syntax

function AddFilterRule(RuleId: Int64; AdapterId: Integer; Direction: Integer; MinPacketSize: Integer; MaxPacketSize: Integer; BPFRule: String; Action: Integer): Boolean;

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 component 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 Component)

This method adds a passthrough rule.

Syntax

function AddPassthroughRule(RuleId: Int64; AdapterId: Integer; Direction: Integer; MinPacketSize: Integer; MaxPacketSize: Integer; BPFRule: String): Boolean;

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 component 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 Component)

Sets or retrieves a configuration setting.

Syntax

function Config(ConfigurationString: String): String;

Remarks

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

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the component, 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 Component)

This method deletes all filter rules.

Syntax

function DeleteAllFilterRules(): Boolean;

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

This method deletes all passthrough rules.

Syntax

function DeleteAllPassthroughRules(): Boolean;

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

This method deletes a particular filter rule.

Syntax

function DeleteFilterRule(RuleId: Int64): Boolean;

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

This method deletes a particular passthrough rule.

Syntax

function DeletePassthroughRule(RuleId: Int64): Boolean;

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

Sends packets enqueued in the send buffer to the network.

Syntax

procedure FlushSendBuffer(AdapterId: Integer);

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

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

Syntax

function GetDriverStatus(ProductGUID: String): Integer;

Remarks

This method retrieves the status of the component'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 component are used, each instance must have own ProductGUID, and the driver must be installed several times.

This method is available in both the component 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 Component)

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

Syntax

function GetDriverVersion(ProductGUID: String): Int64;

Remarks

This method retrieves the version of the component'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 component'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 component are used, each instance must have own ProductGUID, and the driver must be installed several times.

This method is available in both the component 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 Component)

Requests the statistics to be passed via the Statistics event.

Syntax

procedure GetStatistics(AdapterId: Integer);

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

This method initializes the component.

Syntax

procedure Initialize(ProductGUID: String);

Remarks

This method initializes the component and must be called each time the application starts before attempting to call any of the component'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 component can be used.

InsertIncomingPacket Method (NetFilter Component)

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

Syntax

procedure InsertIncomingPacket(AdapterId: Integer; Data: TBytes);

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

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

Syntax

function Install(CabFileName: String; ProductGUID: String; Altitude: Integer; Flags: Integer; AllowedControllers: String): Boolean;

Remarks

This method is used to install or upgrade the component'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 component'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 component 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., "cbpconstants.CONST_A or cbpconstants.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 component 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 ($0522) error.

NOTE: This method cannot be called within events.

ListAdapters Method (NetFilter Component)

Fills the Adapters property with the list of network adapters.

Syntax

procedure 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 Component)

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

Syntax

function NtStatusToWin32Error(Status: Integer): Integer;

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

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

Syntax

procedure SendPacket(AdapterId: Integer; Data: TBytes; NumTimes: Integer; BufferOnly: Boolean);

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

Shuts down or reboots the operating system.

Syntax

function ShutdownSystem(ShutdownPrompt: String; Timeout: Integer; ForceCloseApps: Boolean; Reboot: Boolean): Boolean;

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 component 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 Component)

This method start filtering network operations.

Syntax

procedure StartFilter(Timeout: Integer);

Remarks

This method attaches the filter, causing the component'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 component'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 Component)

This method stops filtering network operations.

Syntax

procedure StopFilter();

Remarks

This method detaches the filter, causing the component'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 Component)

This method enables or disables termination protection for the application.

Syntax

function ToggleProcessProtection(Enabled: Boolean): Boolean;

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

This method uninstalls the component's system driver.

Syntax

function Uninstall(CabFileName: String; ProductGUID: String; Flags: Integer): Boolean;

Remarks

This method is used to uninstall the component'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 component's system driver should be uninstalled and which should be set by OR'ing together (e.g., "cbpconstants.CONST_A or cbpconstants.CONST_B") one or more of the following values:

This method is available in both the component 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 ($0522) error.

NOTE: This method cannot be called within events.

AdapterAdded Event (NetFilter Component)

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

Syntax

type TAdapterAddedEvent = procedure (
  Sender: TObject;
  AdapterId: Integer
) of Object;

property OnAdapterAdded: TAdapterAddedEvent read FOnAdapterAdded write FOnAdapterAdded;

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

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

Syntax

type TAdapterRemovedEvent = procedure (
  Sender: TObject;
  AdapterId: Integer
) of Object;

property OnAdapterRemoved: TAdapterRemovedEvent read FOnAdapterRemoved write FOnAdapterRemoved;

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

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

Syntax

type TErrorEvent = procedure (
  Sender: TObject;
  ErrorCode: Integer;
  const Description: String
) of Object;

property OnError: TErrorEvent read FOnError write FOnError;

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

This event fires when a packet is captured for notification.

Syntax

type TNotifyPacketEvent = procedure (
  Sender: TObject;
  AdapterId: Integer;
  Timestamp: TDateTime;
  TimestampNS: Integer;
  PacketType: Integer;
  Direction: Integer;
  PacketSize: Integer;
  Data: Pointer;
  DataSize: Integer;
  IPOffset: Integer;
  IPSize: Integer
) of Object;

property OnNotifyPacket: TNotifyPacketEvent read FOnNotifyPacket write FOnNotifyPacket;

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

This event fires when a network packet is captured.

Syntax

type TPacketEvent = procedure (
  Sender: TObject;
  AdapterId: Integer;
  Timestamp: TDateTime;
  TimestampNS: Integer;
  PacketType: Integer;
  Direction: Integer;
  PacketSize: Integer;
  Buffer: Pointer;
  BufferSize: Integer;
  var DataSize: Integer;
  IPOffset: Integer;
  IPSize: Integer;
  var Action: Integer;
  var ResultCode: Integer
) of Object;

property OnPacket: TPacketEvent read FOnPacket write FOnPacket;

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 component 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 Component)

Fires to provide aggregated packet statistics.

Syntax

type TStatisticsEvent = procedure (
  Sender: TObject;
  AdapterId: Integer;
  FilterSpecific: Boolean;
  TimeStamp: TDateTime;
  PacketsReceived: Int64;
  BytesReceived: Int64;
  PacketsSent: Int64;
  BytesSent: Int64;
  PacketsDroppedInbound: Int64;
  BytesDroppedInbound: Int64;
  PacketsDroppedOutbound: Int64;
  BytesDroppedOutbound: Int64
) of Object;

property OnStatistics: TStatisticsEvent read FOnStatistics write FOnStatistics;

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

Fires just after a new worker thread is created.

Syntax

type TWorkerThreadCreationEvent = procedure (
  Sender: TObject;
  var ResultCode: Integer
) of Object;

property OnWorkerThreadCreation: TWorkerThreadCreationEvent read FOnWorkerThreadCreation write FOnWorkerThreadCreation;

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 component 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 Component)

Fires just before a worker thread is terminated.

Syntax

type TWorkerThreadTerminationEvent = procedure (
  Sender: TObject
) of Object;

property OnWorkerThreadTermination: TWorkerThreadTerminationEvent read FOnWorkerThreadTermination write FOnWorkerThreadTermination;

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 component 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 Component)

The component 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 component, access to these internal properties is provided through the Config method.

NetFilter Config Settings

Base Config Settings

Trappable Errors (NetFilter Component)