NetFilter Class

Properties   Methods   Events   Config Settings   Errors  

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

Syntax

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

• C++
• C
• Qt

ANSI (Cross Platform)
int GetActive();

Unicode (Windows)
BOOL GetActive();

int pcapfilter_netfilter_getactive(void* lpObj);

bool getActive();

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.

Data Type

Boolean

Adapters Property (NetFilter Class)

A collection of network adapters available for monitoring.

Syntax

• C++
• C
• Qt

PCAPFilterList<PCAPFilterAdapter>* GetAdapters();

int pcapfilter_netfilter_getadaptercount(void* lpObj);

int pcapfilter_netfilter_getadapterbuffersize(void* lpObj, int adapterindex);
int pcapfilter_netfilter_setadapterbuffersize(void* lpObj, int adapterindex, int iAdapterBufferSize);

int pcapfilter_netfilter_getadaptercollectstatistics(void* lpObj, int adapterindex);
int pcapfilter_netfilter_setadaptercollectstatistics(void* lpObj, int adapterindex, int bAdapterCollectStatistics);

char* pcapfilter_netfilter_getadapterdescription(void* lpObj, int adapterindex);

char* pcapfilter_netfilter_getadapterfriendlyname(void* lpObj, int adapterindex);

int pcapfilter_netfilter_getadapterid(void* lpObj, int adapterindex);

int pcapfilter_netfilter_getadapterinterfacetype(void* lpObj, int adapterindex);

char* pcapfilter_netfilter_getadaptermacaddress(void* lpObj, int adapterindex);

int pcapfilter_netfilter_getadaptermaxpacketbytes(void* lpObj, int adapterindex);
int pcapfilter_netfilter_setadaptermaxpacketbytes(void* lpObj, int adapterindex, int iAdapterMaxPacketBytes);

char* pcapfilter_netfilter_getadaptername(void* lpObj, int adapterindex);

int pcapfilter_netfilter_getadapterpackettimeout(void* lpObj, int adapterindex);
int pcapfilter_netfilter_setadapterpackettimeout(void* lpObj, int adapterindex, int iAdapterPacketTimeout);

int pcapfilter_netfilter_getadapterpromiscuousmode(void* lpObj, int adapterindex);
int pcapfilter_netfilter_setadapterpromiscuousmode(void* lpObj, int adapterindex, int bAdapterPromiscuousMode);

int pcapfilter_netfilter_getadapterwifimonitormode(void* lpObj, int adapterindex);
int pcapfilter_netfilter_setadapterwifimonitormode(void* lpObj, int adapterindex, int bAdapterWiFiMonitorMode);

int pcapfilter_netfilter_getadapterwifimonitormodesupported(void* lpObj, int adapterindex);

int getAdapterCount();

int getAdapterBufferSize(int iAdapterIndex);
int setAdapterBufferSize(int iAdapterIndex, int iAdapterBufferSize);

bool getAdapterCollectStatistics(int iAdapterIndex);
int setAdapterCollectStatistics(int iAdapterIndex, bool bAdapterCollectStatistics);

QString getAdapterDescription(int iAdapterIndex);

QString getAdapterFriendlyName(int iAdapterIndex);

int getAdapterId(int iAdapterIndex);

int getAdapterInterfaceType(int iAdapterIndex);

QString getAdapterMACAddress(int iAdapterIndex);

int getAdapterMaxPacketBytes(int iAdapterIndex);
int setAdapterMaxPacketBytes(int iAdapterIndex, int iAdapterMaxPacketBytes);

QString getAdapterName(int iAdapterIndex);

int getAdapterPacketTimeout(int iAdapterIndex);
int setAdapterPacketTimeout(int iAdapterIndex, int iAdapterPacketTimeout);

bool getAdapterPromiscuousMode(int iAdapterIndex);
int setAdapterPromiscuousMode(int iAdapterIndex, bool bAdapterPromiscuousMode);

bool getAdapterWiFiMonitorMode(int iAdapterIndex);
int setAdapterWiFiMonitorMode(int iAdapterIndex, bool bAdapterWiFiMonitorMode);

bool getAdapterWiFiMonitorModeSupported(int iAdapterIndex);

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.

Data Type

PCAPFilterAdapter

Altitude Property (NetFilter Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetAltitude();
int SetAltitude(int iAltitude);

Unicode (Windows)
INT GetAltitude();
INT SetAltitude(INT iAltitude);

int pcapfilter_netfilter_getaltitude(void* lpObj);
int pcapfilter_netfilter_setaltitude(void* lpObj, int iAltitude);

int getAltitude();
int setAltitude(int iAltitude);

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.

Data Type

Integer

FilterRules Property (NetFilter Class)

This property includes a collection of filter rules.

Syntax

• C++
• C
• Qt

PCAPFilterList<PCAPFilterFilterRule>* GetFilterRules();

int pcapfilter_netfilter_getfilterrulecount(void* lpObj);

int pcapfilter_netfilter_getfilterruleaction(void* lpObj, int filterruleindex);

int64 pcapfilter_netfilter_getfilterruleadapterid(void* lpObj, int filterruleindex);

char* pcapfilter_netfilter_getfilterrulebpfrule(void* lpObj, int filterruleindex);

int pcapfilter_netfilter_getfilterruledirection(void* lpObj, int filterruleindex);

int pcapfilter_netfilter_getfilterrulemaxpacketsize(void* lpObj, int filterruleindex);

int pcapfilter_netfilter_getfilterruleminpacketsize(void* lpObj, int filterruleindex);

int64 pcapfilter_netfilter_getfilterruleruleid(void* lpObj, int filterruleindex);

int getFilterRuleCount();

int getFilterRuleAction(int iFilterRuleIndex);

qint64 getFilterRuleAdapterId(int iFilterRuleIndex);

QString getFilterRuleBPFRule(int iFilterRuleIndex);

int getFilterRuleDirection(int iFilterRuleIndex);

int getFilterRuleMaxPacketSize(int iFilterRuleIndex);

int getFilterRuleMinPacketSize(int iFilterRuleIndex);

qint64 getFilterRuleRuleId(int iFilterRuleIndex);

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.

Data Type

PCAPFilterFilterRule

OperationMode Property (NetFilter Class)

Specifies the mode of operation.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetOperationMode();
int SetOperationMode(int iOperationMode);

Unicode (Windows)
INT GetOperationMode();
INT SetOperationMode(INT iOperationMode);

OM_CAPTURE(0), 
OM_STAT(1)

int pcapfilter_netfilter_getoperationmode(void* lpObj);
int pcapfilter_netfilter_setoperationmode(void* lpObj, int iOperationMode);

int getOperationMode();
int setOperationMode(int iOperationMode);

Default Value

0

Remarks

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

Data Type

Integer

PassthroughRules Property (NetFilter Class)

This property includes a collection of passthrough rules.

Syntax

• C++
• C
• Qt

PCAPFilterList<PCAPFilterPassthroughRule>* GetPassthroughRules();

int pcapfilter_netfilter_getpassthroughrulecount(void* lpObj);

int64 pcapfilter_netfilter_getpassthroughruleadapterid(void* lpObj, int passthroughruleindex);

char* pcapfilter_netfilter_getpassthroughrulebpfrule(void* lpObj, int passthroughruleindex);

int pcapfilter_netfilter_getpassthroughruledirection(void* lpObj, int passthroughruleindex);

int pcapfilter_netfilter_getpassthroughrulemaxpacketsize(void* lpObj, int passthroughruleindex);

int pcapfilter_netfilter_getpassthroughruleminpacketsize(void* lpObj, int passthroughruleindex);

int64 pcapfilter_netfilter_getpassthroughruleruleid(void* lpObj, int passthroughruleindex);

int getPassthroughRuleCount();

qint64 getPassthroughRuleAdapterId(int iPassthroughRuleIndex);

QString getPassthroughRuleBPFRule(int iPassthroughRuleIndex);

int getPassthroughRuleDirection(int iPassthroughRuleIndex);

int getPassthroughRuleMaxPacketSize(int iPassthroughRuleIndex);

int getPassthroughRuleMinPacketSize(int iPassthroughRuleIndex);

qint64 getPassthroughRuleRuleId(int iPassthroughRuleIndex);

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.

Data Type

PCAPFilterPassthroughRule

SerializeEvents Property (NetFilter Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetSerializeEvents();
int SetSerializeEvents(int iSerializeEvents);

Unicode (Windows)
INT GetSerializeEvents();
INT SetSerializeEvents(INT iSerializeEvents);

SE_ON_MULTIPLE_THREADS(0), 
SE_ON_ONE_WORKER_THREAD(1)

int pcapfilter_netfilter_getserializeevents(void* lpObj);
int pcapfilter_netfilter_setserializeevents(void* lpObj, int iSerializeEvents);

int getSerializeEvents();
int setSerializeEvents(int iSerializeEvents);

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.

Data Type

Integer

Tag Property (NetFilter Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int64 GetTag();
int SetTag(int64 lTag);

Unicode (Windows)
LONG64 GetTag();
INT SetTag(LONG64 lTag);

int64 pcapfilter_netfilter_gettag(void* lpObj);
int pcapfilter_netfilter_settag(void* lpObj, int64 lTag);

qint64 getTag();
int setTag(qint64 lTag);

Default Value

0

Remarks

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

Data Type

Long64

AddFilterRule Method (NetFilter Class)

This method adds a filter rule.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
bool AddFilterRule(int64 lRuleId, int iAdapterId, int iDirection, int iMinPacketSize, int iMaxPacketSize, const char* lpszBPFRule, int iAction);

Unicode (Windows)
bool AddFilterRule(LONG64 lRuleId, INT iAdapterId, INT iDirection, INT iMinPacketSize, INT iMaxPacketSize, LPCWSTR lpszBPFRule, INT iAction);

bool pcapfilter_netfilter_addfilterrule(void* lpObj, int64 lRuleId, int iAdapterId, int iDirection, int iMinPacketSize, int iMaxPacketSize, const char* lpszBPFRule, int iAction);

bool addFilterRule(qint64 lRuleId, int iAdapterId, int iDirection, int iMinPacketSize, int iMaxPacketSize, const QString& qsBPFRule, int iAction);

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.

Error Handling (C++)

This method returns a Boolean value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

AddPassthroughRule Method (NetFilter Class)

This method adds a passthrough rule.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
bool AddPassthroughRule(int64 lRuleId, int iAdapterId, int iDirection, int iMinPacketSize, int iMaxPacketSize, const char* lpszBPFRule);

Unicode (Windows)
bool AddPassthroughRule(LONG64 lRuleId, INT iAdapterId, INT iDirection, INT iMinPacketSize, INT iMaxPacketSize, LPCWSTR lpszBPFRule);

bool pcapfilter_netfilter_addpassthroughrule(void* lpObj, int64 lRuleId, int iAdapterId, int iDirection, int iMinPacketSize, int iMaxPacketSize, const char* lpszBPFRule);

bool addPassthroughRule(qint64 lRuleId, int iAdapterId, int iDirection, int iMinPacketSize, int iMaxPacketSize, const QString& qsBPFRule);

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.

Error Handling (C++)

This method returns a Boolean value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

Config Method (NetFilter Class)

Sets or retrieves a configuration setting.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* Config(const char* lpszConfigurationString);

Unicode (Windows)
LPWSTR Config(LPCWSTR lpszConfigurationString);

char* pcapfilter_netfilter_config(void* lpObj, const char* lpszConfigurationString);

QString config(const QString& qsConfigurationString);

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.

Error Handling (C++)

This method returns a String value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

DeleteAllFilterRules Method (NetFilter Class)

This method deletes all filter rules.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
bool DeleteAllFilterRules();

Unicode (Windows)
bool DeleteAllFilterRules();

bool pcapfilter_netfilter_deleteallfilterrules(void* lpObj);

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

Error Handling (C++)

This method returns a Boolean value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

DeleteAllPassthroughRules Method (NetFilter Class)

This method deletes all passthrough rules.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
bool DeleteAllPassthroughRules();

Unicode (Windows)
bool DeleteAllPassthroughRules();

bool pcapfilter_netfilter_deleteallpassthroughrules(void* lpObj);

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

Error Handling (C++)

This method returns a Boolean value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

DeleteFilterRule Method (NetFilter Class)

This method deletes a particular filter rule.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
bool DeleteFilterRule(int64 lRuleId);

Unicode (Windows)
bool DeleteFilterRule(LONG64 lRuleId);

bool pcapfilter_netfilter_deletefilterrule(void* lpObj, int64 lRuleId);

bool deleteFilterRule(qint64 lRuleId);

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.

Error Handling (C++)

This method returns a Boolean value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

DeletePassthroughRule Method (NetFilter Class)

This method deletes a particular passthrough rule.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
bool DeletePassthroughRule(int64 lRuleId);

Unicode (Windows)
bool DeletePassthroughRule(LONG64 lRuleId);

bool pcapfilter_netfilter_deletepassthroughrule(void* lpObj, int64 lRuleId);

bool deletePassthroughRule(qint64 lRuleId);

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.

Error Handling (C++)

This method returns a Boolean value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

FlushSendBuffer Method (NetFilter Class)

Sends packets enqueued in the send buffer to the network.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int FlushSendBuffer(int iAdapterId);

Unicode (Windows)
INT FlushSendBuffer(INT iAdapterId);

int pcapfilter_netfilter_flushsendbuffer(void* lpObj, int iAdapterId);

int flushSendBuffer(int iAdapterId);

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.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

GetDriverStatus Method (NetFilter Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetDriverStatus(const char* lpszProductGUID);

Unicode (Windows)
INT GetDriverStatus(LPCWSTR lpszProductGUID);

int pcapfilter_netfilter_getdriverstatus(void* lpObj, const char* lpszProductGUID);

int getDriverStatus(const QString& qsProductGUID);

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.

Error Handling (C++)

This method returns an Integer value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

GetDriverVersion Method (NetFilter Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int64 GetDriverVersion(const char* lpszProductGUID);

Unicode (Windows)
LONG64 GetDriverVersion(LPCWSTR lpszProductGUID);

int64 pcapfilter_netfilter_getdriverversion(void* lpObj, const char* lpszProductGUID);

qint64 getDriverVersion(const QString& qsProductGUID);

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.

Error Handling (C++)

This method returns a Long64 value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

GetStatistics Method (NetFilter Class)

Requests the statistics to be passed via the Statistics event.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetStatistics(int iAdapterId);

Unicode (Windows)
INT GetStatistics(INT iAdapterId);

int pcapfilter_netfilter_getstatistics(void* lpObj, int iAdapterId);

int getStatistics(int iAdapterId);

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.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

Initialize Method (NetFilter Class)

This method initializes the class.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int Initialize(const char* lpszProductGUID);

Unicode (Windows)
INT Initialize(LPCWSTR lpszProductGUID);

int pcapfilter_netfilter_initialize(void* lpObj, const char* lpszProductGUID);

int initialize(const QString& qsProductGUID);

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.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

InsertIncomingPacket Method (NetFilter Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int InsertIncomingPacket(int iAdapterId, const char* lpData, int lenData);

Unicode (Windows)
INT InsertIncomingPacket(INT iAdapterId, LPCSTR lpData, INT lenData);

int pcapfilter_netfilter_insertincomingpacket(void* lpObj, int iAdapterId, const char* lpData, int lenData);

int insertIncomingPacket(int iAdapterId, QByteArray& qbaData);

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.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

Install Method (NetFilter Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
bool Install(const char* lpszCabFileName, const char* lpszProductGUID, int iAltitude, int iFlags, const char* lpszAllowedControllers);

Unicode (Windows)
bool Install(LPCWSTR lpszCabFileName, LPCWSTR lpszProductGUID, INT iAltitude, INT iFlags, LPCWSTR lpszAllowedControllers);

bool pcapfilter_netfilter_install(void* lpObj, const char* lpszCabFileName, const char* lpszProductGUID, int iAltitude, int iFlags, const char* lpszAllowedControllers);

bool install(const QString& qsCabFileName, const QString& qsProductGUID, int iAltitude, int iFlags, const QString& qsAllowedControllers);

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

Error Handling (C++)

This method returns a Boolean value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

ListAdapters Method (NetFilter Class)

Fills the Adapters property with the list of network adapters.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int ListAdapters();

Unicode (Windows)
INT ListAdapters();

int pcapfilter_netfilter_listadapters(void* lpObj);

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

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

NtStatusToWin32Error Method (NetFilter Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int NtStatusToWin32Error(int iStatus);

Unicode (Windows)
INT NtStatusToWin32Error(INT iStatus);

int pcapfilter_netfilter_ntstatustowin32error(void* lpObj, int iStatus);

int ntStatusToWin32Error(int iStatus);

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

Error Handling (C++)

This method returns an Integer value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

SendPacket Method (NetFilter Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int SendPacket(int iAdapterId, const char* lpData, int lenData, int iNumTimes, int bBufferOnly);

Unicode (Windows)
INT SendPacket(INT iAdapterId, LPCSTR lpData, INT lenData, INT iNumTimes, BOOL bBufferOnly);

int pcapfilter_netfilter_sendpacket(void* lpObj, int iAdapterId, const char* lpData, int lenData, int iNumTimes, int bBufferOnly);

int sendPacket(int iAdapterId, QByteArray& qbaData, int iNumTimes, bool bBufferOnly);

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.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

ShutdownSystem Method (NetFilter Class)

Shuts down or reboots the operating system.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
bool ShutdownSystem(const char* lpszShutdownPrompt, int iTimeout, int bForceCloseApps, int bReboot);

Unicode (Windows)
bool ShutdownSystem(LPCWSTR lpszShutdownPrompt, INT iTimeout, BOOL bForceCloseApps, BOOL bReboot);

bool pcapfilter_netfilter_shutdownsystem(void* lpObj, const char* lpszShutdownPrompt, int iTimeout, int bForceCloseApps, int bReboot);

bool shutdownSystem(const QString& qsShutdownPrompt, int iTimeout, bool bForceCloseApps, bool bReboot);

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.

Error Handling (C++)

This method returns a Boolean value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

StartFilter Method (NetFilter Class)

This method start filtering network operations.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int StartFilter(int iTimeout);

Unicode (Windows)
INT StartFilter(INT iTimeout);

int pcapfilter_netfilter_startfilter(void* lpObj, int iTimeout);

int startFilter(int iTimeout);

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.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

StopFilter Method (NetFilter Class)

This method stops filtering network operations.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int StopFilter();

Unicode (Windows)
INT StopFilter();

int pcapfilter_netfilter_stopfilter(void* lpObj);

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

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

ToggleProcessProtection Method (NetFilter Class)

This method enables or disables termination protection for the application.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
bool ToggleProcessProtection(int bEnabled);

Unicode (Windows)
bool ToggleProcessProtection(BOOL bEnabled);

bool pcapfilter_netfilter_toggleprocessprotection(void* lpObj, int bEnabled);

bool toggleProcessProtection(bool bEnabled);

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.

Error Handling (C++)

This method returns a Boolean value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

Uninstall Method (NetFilter Class)

This method uninstalls the class's system driver.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
bool Uninstall(const char* lpszCabFileName, const char* lpszProductGUID, int iFlags);

Unicode (Windows)
bool Uninstall(LPCWSTR lpszCabFileName, LPCWSTR lpszProductGUID, INT iFlags);

bool pcapfilter_netfilter_uninstall(void* lpObj, const char* lpszCabFileName, const char* lpszProductGUID, int iFlags);

bool uninstall(const QString& qsCabFileName, const QString& qsProductGUID, int iFlags);

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

Error Handling (C++)

This method returns a Boolean value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

AdapterAdded Event (NetFilter Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireAdapterAdded(NetFilterAdapterAddedEventParams *e);

typedef struct {
  int AdapterId;
  int reserved;
} NetFilterAdapterAddedEventParams;


Unicode (Windows)
virtual INT FireAdapterAdded(NetFilterAdapterAddedEventParams *e);

typedef struct {
  INT AdapterId;
  INT reserved;
} NetFilterAdapterAddedEventParams;

#define EID_NETFILTER_ADAPTERADDED 1

virtual INT PCAPFILTER_CALL FireAdapterAdded(INT &iAdapterId);

class NetFilterAdapterAddedEventParams {
public:
  int adapterId();

  int eventRetVal();
  void setEventRetVal(int iRetVal);
};

// To handle, subclass NetFilter and override this emitter function.
virtual int fireAdapterAdded(NetFilterAdapterAddedEventParams *e) {...}

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

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireAdapterRemoved(NetFilterAdapterRemovedEventParams *e);

typedef struct {
  int AdapterId;
  int reserved;
} NetFilterAdapterRemovedEventParams;


Unicode (Windows)
virtual INT FireAdapterRemoved(NetFilterAdapterRemovedEventParams *e);

typedef struct {
  INT AdapterId;
  INT reserved;
} NetFilterAdapterRemovedEventParams;

#define EID_NETFILTER_ADAPTERREMOVED 2

virtual INT PCAPFILTER_CALL FireAdapterRemoved(INT &iAdapterId);

class NetFilterAdapterRemovedEventParams {
public:
  int adapterId();

  int eventRetVal();
  void setEventRetVal(int iRetVal);
};

// To handle, subclass NetFilter and override this emitter function.
virtual int fireAdapterRemoved(NetFilterAdapterRemovedEventParams *e) {...}

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

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireError(NetFilterErrorEventParams *e);

typedef struct {
  int ErrorCode;
  const char *Description;
  int reserved;
} NetFilterErrorEventParams;


Unicode (Windows)
virtual INT FireError(NetFilterErrorEventParams *e);

typedef struct {
  INT ErrorCode;
  LPCWSTR Description;
  INT reserved;
} NetFilterErrorEventParams;

#define EID_NETFILTER_ERROR 3

virtual INT PCAPFILTER_CALL FireError(INT &iErrorCode, LPSTR &lpszDescription);

class NetFilterErrorEventParams {
public:
  int errorCode();

  const QString &description();

  int eventRetVal();
  void setEventRetVal(int iRetVal);
};

// To handle, subclass NetFilter and override this emitter function.
virtual int fireError(NetFilterErrorEventParams *e) {...}

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

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireNotifyPacket(NetFilterNotifyPacketEventParams *e);

typedef struct {
  int AdapterId;
  int64 Timestamp;
  int TimestampNS;
  int PacketType;
  int Direction;
  int PacketSize;
  const void *Data;
  int DataSize;
  int IPOffset;
  int IPSize;
  int reserved;
} NetFilterNotifyPacketEventParams;


Unicode (Windows)
virtual INT FireNotifyPacket(NetFilterNotifyPacketEventParams *e);

typedef struct {
  INT AdapterId;
  LONG64 Timestamp;
  INT TimestampNS;
  INT PacketType;
  INT Direction;
  INT PacketSize;
  LPCVOID Data;
  INT DataSize;
  INT IPOffset;
  INT IPSize;
  INT reserved;
} NetFilterNotifyPacketEventParams;

#define EID_NETFILTER_NOTIFYPACKET 4

virtual INT PCAPFILTER_CALL FireNotifyPacket(INT &iAdapterId, LONG64 &lTimestamp, INT &iTimestampNS, INT &iPacketType, INT &iDirection, INT &iPacketSize, LPVOID &lpData, INT &iDataSize, INT &iIPOffset, INT &iIPSize);

class NetFilterNotifyPacketEventParams {
public:
  int adapterId();

  const QDateTime &timestamp();

  int timestampNS();

  int packetType();

  int direction();

  int packetSize();

  const void *data();

  int dataSize();

  int IPOffset();

  int IPSize();

  int eventRetVal();
  void setEventRetVal(int iRetVal);
};

// To handle, subclass NetFilter and override this emitter function.
virtual int fireNotifyPacket(NetFilterNotifyPacketEventParams *e) {...}

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

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FirePacket(NetFilterPacketEventParams *e);

typedef struct {
  int AdapterId;
  int64 Timestamp;
  int TimestampNS;
  int PacketType;
  int Direction;
  int PacketSize;
  const void *Buffer;
  int BufferSize;
  int DataSize;
  int IPOffset;
  int IPSize;
  int Action;
  int ResultCode;
  int reserved;
} NetFilterPacketEventParams;


Unicode (Windows)
virtual INT FirePacket(NetFilterPacketEventParams *e);

typedef struct {
  INT AdapterId;
  LONG64 Timestamp;
  INT TimestampNS;
  INT PacketType;
  INT Direction;
  INT PacketSize;
  LPCVOID Buffer;
  INT BufferSize;
  INT DataSize;
  INT IPOffset;
  INT IPSize;
  INT Action;
  INT ResultCode;
  INT reserved;
} NetFilterPacketEventParams;

#define EID_NETFILTER_PACKET 5

virtual INT PCAPFILTER_CALL FirePacket(INT &iAdapterId, LONG64 &lTimestamp, INT &iTimestampNS, INT &iPacketType, INT &iDirection, INT &iPacketSize, LPVOID &lpBuffer, INT &iBufferSize, INT &iDataSize, INT &iIPOffset, INT &iIPSize, INT &iAction, INT &iResultCode);

class NetFilterPacketEventParams {
public:
  int adapterId();

  const QDateTime &timestamp();

  int timestampNS();

  int packetType();

  int direction();

  int packetSize();

  const void *buffer();

  int bufferSize();

  int dataSize();
  void setDataSize(int iDataSize);

  int IPOffset();

  int IPSize();

  int action();
  void setAction(int iAction);

  int resultCode();
  void setResultCode(int iResultCode);

  int eventRetVal();
  void setEventRetVal(int iRetVal);
};

// To handle, subclass NetFilter and override this emitter function.
virtual int firePacket(NetFilterPacketEventParams *e) {...}

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

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireStatistics(NetFilterStatisticsEventParams *e);

typedef struct {
  int AdapterId;
  int FilterSpecific;
  int64 TimeStamp;
  int64 PacketsReceived;
  int64 BytesReceived;
  int64 PacketsSent;
  int64 BytesSent;
  int64 PacketsDroppedInbound;
  int64 BytesDroppedInbound;
  int64 PacketsDroppedOutbound;
  int64 BytesDroppedOutbound;
  int reserved;
} NetFilterStatisticsEventParams;


Unicode (Windows)
virtual INT FireStatistics(NetFilterStatisticsEventParams *e);

typedef struct {
  INT AdapterId;
  BOOL FilterSpecific;
  LONG64 TimeStamp;
  LONG64 PacketsReceived;
  LONG64 BytesReceived;
  LONG64 PacketsSent;
  LONG64 BytesSent;
  LONG64 PacketsDroppedInbound;
  LONG64 BytesDroppedInbound;
  LONG64 PacketsDroppedOutbound;
  LONG64 BytesDroppedOutbound;
  INT reserved;
} NetFilterStatisticsEventParams;

#define EID_NETFILTER_STATISTICS 6

virtual INT PCAPFILTER_CALL FireStatistics(INT &iAdapterId, BOOL &bFilterSpecific, LONG64 &lTimeStamp, LONG64 &lPacketsReceived, LONG64 &lBytesReceived, LONG64 &lPacketsSent, LONG64 &lBytesSent, LONG64 &lPacketsDroppedInbound, LONG64 &lBytesDroppedInbound, LONG64 &lPacketsDroppedOutbound, LONG64 &lBytesDroppedOutbound);

class NetFilterStatisticsEventParams {
public:
  int adapterId();

  bool filterSpecific();

  const QDateTime &timeStamp();

  qint64 packetsReceived();

  qint64 bytesReceived();

  qint64 packetsSent();

  qint64 bytesSent();

  qint64 packetsDroppedInbound();

  qint64 bytesDroppedInbound();

  qint64 packetsDroppedOutbound();

  qint64 bytesDroppedOutbound();

  int eventRetVal();
  void setEventRetVal(int iRetVal);
};

// To handle, subclass NetFilter and override this emitter function.
virtual int fireStatistics(NetFilterStatisticsEventParams *e) {...}

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

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireWorkerThreadCreation(NetFilterWorkerThreadCreationEventParams *e);

typedef struct {
  int ResultCode;
  int reserved;
} NetFilterWorkerThreadCreationEventParams;


Unicode (Windows)
virtual INT FireWorkerThreadCreation(NetFilterWorkerThreadCreationEventParams *e);

typedef struct {
  INT ResultCode;
  INT reserved;
} NetFilterWorkerThreadCreationEventParams;

#define EID_NETFILTER_WORKERTHREADCREATION 7

virtual INT PCAPFILTER_CALL FireWorkerThreadCreation(INT &iResultCode);

class NetFilterWorkerThreadCreationEventParams {
public:
  int resultCode();
  void setResultCode(int iResultCode);

  int eventRetVal();
  void setEventRetVal(int iRetVal);
};

// To handle, subclass NetFilter and override this emitter function.
virtual int fireWorkerThreadCreation(NetFilterWorkerThreadCreationEventParams *e) {...}

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

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireWorkerThreadTermination(NetFilterWorkerThreadTerminationEventParams *e);

typedef struct {
  int reserved;
} NetFilterWorkerThreadTerminationEventParams;


Unicode (Windows)
virtual INT FireWorkerThreadTermination(NetFilterWorkerThreadTerminationEventParams *e);

typedef struct {
  INT reserved;
} NetFilterWorkerThreadTerminationEventParams;

#define EID_NETFILTER_WORKERTHREADTERMINATION 8

virtual INT PCAPFILTER_CALL FireWorkerThreadTermination();

class NetFilterWorkerThreadTerminationEventParams {
public:
  int eventRetVal();
  void setEventRetVal(int iRetVal);
};

// To handle, subclass NetFilter and override this emitter function.
virtual int fireWorkerThreadTermination(NetFilterWorkerThreadTerminationEventParams *e) {...}

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.

Syntax

PCAPFilterAdapter (declared in pcapfilter.h)

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.

Syntax

PCAPFilterFilterRule (declared in pcapfilter.h)

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.

Syntax

PCAPFilterPassthroughRule (declared in pcapfilter.h)

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

PCAPFilterList Type

Syntax

PCAPFilterList<T> (declared in pcapfilter.h)

Remarks

PCAPFilterList is a generic class that is used to hold a collection of objects of type T, where T is one of the custom types supported by the NetFilter class.

int GetCount() {}

int SetCount(int count) {}

T* Get(int index) {}

T* Set(int index, T* value) {}

Config Settings (NetFilter Class)

NetFilter Config Settings

Base Config Settings

Trappable Errors (NetFilter Class)

Error Handling (C++)

Call the GetLastErrorCode() method to obtain the last called method's result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. Known error codes are listed below. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.