IPMonitor Class

Properties   Methods   Events   Config Settings   Errors  

The IPMonitor class allows applications to monitor network packets on multiple platforms.

Syntax

IPMonitor

Remarks

IPMonitor is a lightweight class that allows applications to monitor network activity across multiple platforms, including Windows, Linux, and macOS. It utilizes the "libpcap" library and underlying network drivers to capture and report network packets in real-time. The class provides the ability to capture individual network packets for detailed analysis, or collect aggregated packet statistics for monitoring network performance.

Setup

Linux and macOS

For Linux and macOS systems, permissions may need to be adjusted as described in the System Configuration in Linux and macOS instructions page to allow the application to capture packets.

Retrieving Network Adapters

// Retrieve the list of network adapters available on the system ipmonitor.ListAdapters(); // Display the available adapters foreach (Adapter adapter in ipmonitor.Adapters) { Console.WriteLine($"Adapter Name: {adapter.Name}"); Console.WriteLine($"Description: {adapter.Description}"); }

Packet Filters

The Direction property can be used to specify whether to capture incoming packets, outgoing packets, or both. In addition to directionality, the Filter property can be set to a pcap filter expression string that allows for filtering based on IP addresses, protocol types, ports, and more. For more information on supported filter expressions, please see the pcap-filter(7) man page. // Only capture incoming packets ipmonitor.Direction = callback.PCAPFilter.Constants.PACKET_DIRECTION_INCOMING; // Only capture TCP packets from IP 192.168.1.1 on port 80 ipmonitor.Filter = "src host 192.168.1.1 and tcp port 80";

Operation Modes

Capture Mode

Setting the OperationMode property to PCAP_MODE_CAPT will cause the class to capture individual network packets and report them through the Packet event. // Capture individual packet information ipmonitor.OperationMode = (int)OperationModes.PCAP_MODE_CAPT;

Statistical Mode

Setting the OperationMode property to PCAP_MODE_STAT will instead cause the class to collect aggregated packet statistics and report them through the Statistics event. // Report aggregated packet statistics ipmonitor.OperationMode = (int)OperationModes.PCAP_MODE_STAT;

Monitoring an Adapter

// Get the name of the first adapter returned by ListAdapters() ipmonitor.ListAdapters(); string adapterToMonitor = ipmonitor.Adapters[0].Name; // Start monitoring the adapter ipmonitor.Activate(adapterToMonitor);

Retrieving Packet Information

Capture Mode:

In capture mode, calling DoEvents will cause the class to process any packets captured by the class and fire the Packet for each one. ipmonitor.OnPacket += (s, e) => { // Print out information about each individual packet Console.WriteLine($"Packet captured at {e.TimeStamp}"); Console.WriteLine($"Packet Size: {e.PacketSize} bytes"); };

Statistical Mode:

In statistical mode, calling DoEvents will prompt the class to collect packet statistics and report them through the Statistics event. ipmonitor.OnStatistics += (s, e) => { // Print out packet statistics Console.WriteLine($"Statistics collected at {e.TimeStamp}"); Console.WriteLine($"Packets Captured: {e.CapturedPackets}"); Console.WriteLine($"Bytes Captured: {e.CapturedBytes}"); };

Capture Statistics

Deactivating Monitoring

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

Indicates whether the class is active and monitoring network traffic.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetActive();

Unicode (Windows)
BOOL GetActive();

int pcapfilter_ipmonitor_getactive(void* lpObj);

bool GetActive();

Default Value

FALSE

Remarks

This property reflects whether the class is actively monitoring network traffic. It is automatically set to true after a successful call to Activate, and to false when monitoring is stopped with the Deactivate method.

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

Data Type

Boolean

Adapters Property (IPMonitor Class)

A collection of network adapters available for monitoring.

Syntax

• C++
• C
• Qt

PCAPFilterList<PCAPFilterAdapter>* GetAdapters();

int pcapfilter_ipmonitor_getadaptercount(void* lpObj);

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

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

int GetAdapterCount();

QString GetAdapterDescription(int iAdapterIndex);

QString GetAdapterName(int iAdapterIndex);

Remarks

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

This property can be used to access the name of a network adapter before calling Activate to start monitoring it.

Example: // Populate the 'Adapters' collection with the list of available network adapters ipmonitor.ListAdapters(); // Start monitoring the first adapter in the collection ipmonitor.Activate(ipmonitor.Adapters[0].Name);

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

Data Type

PCAPFilterAdapter

Direction Property (IPMonitor Class)

Specifies the direction of packets to capture.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetDirection();
int SetDirection(int iDirection);

Unicode (Windows)
INT GetDirection();
INT SetDirection(INT iDirection);

int pcapfilter_ipmonitor_getdirection(void* lpObj);
int pcapfilter_ipmonitor_setdirection(void* lpObj, int iDirection);

int GetDirection();
int SetDirection(int iDirection);

Default Value

0

Remarks

The property makes it possible to capture just outgoing or just incoming packets, working as a simple filter for the network packets. The property value can be one of the following:

Data Type

Integer

Filter Property (IPMonitor Class)

Specifies filter criteria used to determine which network packets are captured.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetFilter();
int SetFilter(const char* lpszFilter);

Unicode (Windows)
LPWSTR GetFilter();
INT SetFilter(LPCWSTR lpszFilter);

char* pcapfilter_ipmonitor_getfilter(void* lpObj);
int pcapfilter_ipmonitor_setfilter(void* lpObj, const char* lpszFilter);

QString GetFilter();
int SetFilter(QString qsFilter);

Default Value

""

Remarks

This property specifies a filter expression string that determines which network packets are captured and reported. For additional filtering, the Direction property can be used to limit packet capture to incoming or outgoing traffic.

This property can be set before or after calling Activate to start monitoring. In some platforms, changing the value of this property while monitoring is active may result in some packets being dropped or reported even if they do not match the new filter rules. For more details on platform-specific behavior, please see the pcap-filter(7) man page.

Filter Expression Syntax

[not] condition [and|or [not] condition ... ]

For more comprehensive information on filter expressions, please refer to the pcap-filter(7) documentation. Below is a simplified overview of common filter expressions:

Example (Simple): // Only capture packets to and from IP 192.168.1.1 ipmonitor.Filter = "host 192.168.1.1";

Example (Advanced): // Only capture TCP packets from IP 192.168.1.1 on port 80 ipmonitor.Filter = "src host 192.168.1.1 and tcp port 80";

Data Type

String

OperationMode Property (IPMonitor 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);

int pcapfilter_ipmonitor_getoperationmode(void* lpObj);
int pcapfilter_ipmonitor_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 when DoEvents is called. The property value can be one of the following:

Data Type

Integer

Tag Property (IPMonitor 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_ipmonitor_gettag(void* lpObj);
int pcapfilter_ipmonitor_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

Activate Method (IPMonitor Class)

Starts monitoring network traffic.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int Activate(const char* lpszAdapter);

Unicode (Windows)
INT Activate(LPCWSTR lpszAdapter);

int pcapfilter_ipmonitor_activate(void* lpObj, const char* lpszAdapter);

int Activate(const QString& qsAdapter);

Remarks

This method enables monitoring network packets on a specified network adapter. To disable monitoring, call Deactivate instead.

When this method is called, the class will begin monitoring the specified adapter for network activity. Packets will be captured and reported differently depending on the value of the OperationMode property. Once monitoring is active, the Active property will be automatically set to true.

Adapter specifies the name of the network adapter to monitor. The list of available adapters can be obtained via the ListAdapters method.

Packet Reporting

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

Config Method (IPMonitor 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_ipmonitor_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.

Deactivate Method (IPMonitor Class)

Stops monitoring network traffic.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int Deactivate();

Unicode (Windows)
INT Deactivate();

int pcapfilter_ipmonitor_deactivate(void* lpObj);

int Deactivate();

Remarks

This method stops monitoring network traffic. Once called, the class will cease capturing packets and the Active property will be automatically set to false.

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

DoEvents Method (IPMonitor Class)

Processes events from the internal message queue.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int DoEvents();

Unicode (Windows)
INT DoEvents();

int pcapfilter_ipmonitor_doevents(void* lpObj);

int DoEvents();

Remarks

This method processes events from the internal message queue and fires the corresponding events based on the current OperationMode. It should be called periodically to prompt the class to fire events and report packet information.

Capture Modes

When OperationMode is set to PCAP_MODE_CAPT, calling this method while monitoring is active will prompt the class to process any packets captured since the last call and fire the Packet event for each one. If there are no new packets to report, the method will wait for a duration specified by the PacketTimeout configuration setting before returning.

If OperationMode is set to PCAP_MODE_STAT, calling this method will instead tell the class to collect packet statistics since the last call and fire the Statistics event with the aggregated data.

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

GetStatistics Method (IPMonitor Class)

Retrieves the total number of packets received and dropped since monitoring began.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetStatistics(int64* lReceived, int64* lDropped, int64* lAdapterDropped);

Unicode (Windows)
INT GetStatistics(LONG64*  lReceived, LONG64*  lDropped, LONG64*  lAdapterDropped);

int pcapfilter_ipmonitor_getstatistics(void* lpObj, int64* lReceived, int64* lDropped, int64* lAdapterDropped);

int GetStatistics(qint64* lReceived, qint64* lDropped, qint64* lAdapterDropped);

Remarks

This method provides capture statistics about the packets monitored by the class and the underlying driver since Activate was called to start monitoring.

The Received parameter provides the number of packets received since monitoring began.

The Dropped parameter provides the number of packets that were dropped since monitoring began. Packets may be dropped if BufferSize is too small to keep all of the data, or because DoEvents was called too infrequently.

The AdapterDropped parameter provides the full number of packets that were dropped by the network adapter since monitoring began.

Platform Differences

This method is platform-dependent. It uses the underlying pcap_stats() function from the libpcap library to retrieve packet statistics, which may cause the values provided in the Received, Dropped, and AdapterDropped parameters to differ depending on the platform.

• Received: On some platforms, this count may include all packets, regardless of whether they matched the filter criteria set using Filter.
• Dropped: This value may not be available on all platforms.
• AdapterDropped: This count might not be implemented on some platforms. If its value is 0, it could indicate either no drops or that the statistic is unavailable.

For more information regarding platform differences, please see the pcap_stats() documentation.

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

ListAdapters Method (IPMonitor Class)

Retrieves the network adapters available for monitoring.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int ListAdapters();

Unicode (Windows)
INT ListAdapters();

int pcapfilter_ipmonitor_listadapters(void* lpObj);

int ListAdapters();

Remarks

This method populates the Adapters collection with a list of network adapters available for monitoring. Each adapter in the collection includes a name and description provided by the network driver.

This method can be used to obtain the name of a network adapter before calling Activate to start monitoring it.

Example: // Populate the 'Adapters' collection with the list of available network adapters ipmonitor.ListAdapters(); // Start monitoring the first adapter in the collection ipmonitor.Activate(ipmonitor.Adapters[0].Name);

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

Error Event (IPMonitor Class)

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

Syntax

• C++
• C
• Qt

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

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


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

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

#define EID_IPMONITOR_ERROR 1

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

class IPMonitorErrorEventParams {
public:
  int ErrorCode();

  const QString &Description();

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void Error(IPMonitorErrorEventParams *e);

// Or, subclass IPMonitor and override this emitter function.
virtual int FireError(IPMonitorErrorEventParams *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.

Packet Event (IPMonitor Class)

Fires when a network packet is captured.

Syntax

• C++
• C
• Qt

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

typedef struct {
  int64 TimeStamp;
  int PacketSize;
  const void *Data;
  int DataSize;
  int reserved;
} IPMonitorPacketEventParams;


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

typedef struct {
  LONG64 TimeStamp;
  INT PacketSize;
  LPCVOID Data;
  INT DataSize;
  INT reserved;
} IPMonitorPacketEventParams;

#define EID_IPMONITOR_PACKET 2

virtual INT PCAPFILTER_CALL FirePacket(LONG64 &lTimeStamp, INT &iPacketSize, LPVOID &lpData, INT &iDataSize);

class IPMonitorPacketEventParams {
public:
  const QDateTime &TimeStamp();

  int PacketSize();

  const void *Data();

  int DataSize();

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void Packet(IPMonitorPacketEventParams *e);

// Or, subclass IPMonitor and override this emitter function.
virtual int FirePacket(IPMonitorPacketEventParams *e) {...}

Remarks

This event fires for each packet received from the monitored network adapter. The event will only fire if OperationMode is set to PCAP_MODE_CAPT and the captured packet matches the filter criteria specified in Filter and Direction. Packets are reported in the order they are received from the network adapter.

The Timestamp parameter contains the time when the packet was received by the network adapter.

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 MaxPacketSize configuration setting, and it 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.

Packet Reporting

Statistics Event (IPMonitor Class)

Fires to provide aggregated packet statistics.

Syntax

• C++
• C
• Qt

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

typedef struct {
  int64 TimeStamp;
  int64 CapturedPackets;
  int64 CapturedBytes;
  int reserved;
} IPMonitorStatisticsEventParams;


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

typedef struct {
  LONG64 TimeStamp;
  LONG64 CapturedPackets;
  LONG64 CapturedBytes;
  INT reserved;
} IPMonitorStatisticsEventParams;

#define EID_IPMONITOR_STATISTICS 3

virtual INT PCAPFILTER_CALL FireStatistics(LONG64 &lTimeStamp, LONG64 &lCapturedPackets, LONG64 &lCapturedBytes);

class IPMonitorStatisticsEventParams {
public:
  const QDateTime &TimeStamp();

  qint64 CapturedPackets();

  qint64 CapturedBytes();

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void Statistics(IPMonitorStatisticsEventParams *e);

// Or, subclass IPMonitor and override this emitter function.
virtual int FireStatistics(IPMonitorStatisticsEventParams *e) {...}

Remarks

This event fires to provide aggregated packet statistics collected from the network adapter. The event will only fire if OperationMode is set to PCAP_MODE_STAT. Calling DoEvents while monitoring is active will prompt the class to report packet statistics and fire this event.

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

The CapturedPackets parameter contains the number of packets captured since the last time the event was fired.

The CapturedBytes parameter contains the total byte size of the packets captured since the last time the event was fired.

Packet Reporting

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.

• Description
• Name

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 IPMonitor class.

int GetCount() {}

int SetCount(int count) {}

T* Get(int index) {}

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

Config Settings (IPMonitor Class)

IPMonitor Config Settings

Base Config Settings

Trappable Errors (IPMonitor 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.