IPMonitor Component

Properties   Methods   Events   Config Settings   Errors  

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

Syntax

TcbpIPMonitor

Remarks

IPMonitor is a lightweight component 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 component provides the ability to capture individual network packets for detailed analysis, or collect aggregated packet statistics for monitoring network performance.

Setup

Before using the component, a libpcap-compatible network library must be installed on the system. For detailed installation instructions, please refer to the Network Filter Library section. This setup only needs to be done once.

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

The first step in using the component is to identify the name of the network adapter that will be monitored. To retrieve the list of network adapters available on the system, call the ListAdapters method. Once the method is called, the adapters will be accessible via the Adapters property.

// 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

Before starting to monitor a network adapter, filters can be applied to capture only the packets that match certain criteria.

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

In addition to packet filters, the component supports multiple operation modes that determine what kind of packet information will be reported.

Capture Mode

Setting the OperationMode property to PCAP_MODE_CAPT will cause the component 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 component 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

After configuring the filters and operation mode, start monitoring the network adapter by calling the Activate method and specifying the adapter name.

// 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

Depending on the current OperationMode, packet information is retrieved differently. In both modes, the DoEvents method must be called to prompt the component to fire events and report packet information.

Capture Mode:

In capture mode, calling DoEvents will cause the component to process any packets captured by the component 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 component 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

Regardless of the current OperationMode, cumulative statistics about the packets captured since monitoring began can be retrieved by calling the GetStatistics method. long receivedPackets = 0; // The number of packets received since monitoring began long droppedPackets = 0; // The number of packets dropped by the component since monitoring began long adapterDroppedPackets = 0; // The number of packets dropped by the adapter since monitoring began ipmonitor.GetStatistics(ref receivedPackets, ref droppedPackets, ref adapterDroppedPackets); Console.WriteLine($"Packets Received: {receivedPackets}"); Console.WriteLine($"Packets Dropped: {droppedPackets}"); Console.WriteLine($"Packets Dropped by Adapter: {adapterDroppedPackets}");

Deactivating Monitoring

To stop monitoring the adapter and cease reporting packets, call the Deactivate method. ipmonitor.Deactivate();

Property List


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

ActiveIndicates whether the component is active and monitoring network traffic.
AdaptersA collection of network adapters available for monitoring.
DirectionSpecifies the direction of packets to capture.
FilterSpecifies filter criteria used to determine which network packets are captured.
OperationModeSpecifies the mode of operation.
TagThis property stores application-defined data specific to a particular instance of the component.

Method List


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

ActivateStarts monitoring network traffic.
ConfigSets or retrieves a configuration setting.
DeactivateStops monitoring network traffic.
DoEventsProcesses events from the internal message queue.
GetStatisticsRetrieves the total number of packets received and dropped since monitoring began.
ListAdaptersRetrieves the network adapters available for monitoring.

Event List


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

ErrorThis event fires if an unhandled error occurs during an event.
PacketFires when a network packet is captured.
StatisticsFires to provide aggregated packet statistics.

Config Settings


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

BufferSizeThe size of the buffer that the driver should use to store packets.
MaxPacketSizeThe number of bytes of a packet to report.
PacketTimeoutThe time to wait for a packet.
PromiscuousModeWhether the driver should capture packets where a local system is neither a source or the destination of a packet.
WiFiMonitorModeWhether the adapter should work in monitor mode (available in Wi-Fi adapters).
BuildInfoInformation about the product's build.
LicenseInfoInformation about the current license.

Active Property (IPMonitor Component)

Indicates whether the component is active and monitoring network traffic.

Syntax

property Active: Boolean read get_Active;

Default Value

false

Remarks

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

Adapters Property (IPMonitor Component)

A collection of network adapters available for monitoring.

Syntax

property Adapters: TcbpAdapterList read get_Adapters;

Remarks

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

This property 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.

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

Direction Property (IPMonitor Component)

Specifies the direction of packets to capture.

Syntax

property Direction: Integer read get_Direction write set_Direction;

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:

PACKET_DIRECTION_ANY0x00All packets are processed.

PACKET_DIRECTION_INCOMING0x01Incoming packets are processed.

PACKET_DIRECTION_OUTGOING0x02Outgoing packets are processed.

Filter Property (IPMonitor Component)

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

Syntax

property Filter: String read get_Filter write set_Filter;

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

The filter expression follows the syntax used by libpcap. A filter takes the form of a series of conditions that specify the criteria packets must meet to be captured. Expressions can be combined using conjunctions and, or, and optionally preceded by not.

[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:

src|dst host <host>Captures packets to or from the specified IP address or name.
src host <host>Captures packets where the source is the specified host.
dst host <host>Captures packets where the destination is the specified host.
net <network>Captures packets to or from the specified network.
src net <network>Captures packets where the source is in the specified network.
dst net <network>Captures packets where the destination is in the specified network.
port <port>Captures packets to or from the specified port.
src port <port>Captures packets where the source port is the specified port.
dst port <port>Captures packets where the destination port is the specified port.
ether broadcastCaptures all Ethernet broadcast packets.
ether multicastCaptures all Ethernet multicast packets.
greater <length>Captures packets with a length greater than or equal to the specified length (in bytes).
less <length>Captures packets with a length lesser than or equal to the specified length (in bytes).
broadcastCaptures all broadcast packets (Ethernet and IP).
broadcastCaptures all multicast packets (Ethernet and IP).
<protocol>Captures all packets using the specified protocol.

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";

OperationMode Property (IPMonitor Component)

Specifies the mode of operation.

Syntax

property OperationMode: Integer read get_OperationMode write set_OperationMode;

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:

PCAP_MODE_CAPT0x00Capture mode.

Individual packets are reported through the Packet event as they are received from the network driver. Only packets that match the filter criteria specified in Filter and Direction will trigger the event.

PCAP_MODE_STAT0x01Statistical mode.

The component does not report individual packets. Instead, it will collect packet statistics and provide aggregated packet data via the Statistics event.

Tag Property (IPMonitor Component)

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

Syntax

property Tag: Int64 read get_Tag write set_Tag;

Default Value

0

Remarks

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

Activate Method (IPMonitor Component)

Starts monitoring network traffic.

Syntax

procedure Activate(Adapter: String);

Remarks

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

When this method is called, the component 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

When Active is set to True, the component will report packet information based on the value of the OperationMode property. The following operation modes determine how packets are processed and reported:

PCAP_MODE_CAPT0x00Capture mode.

Individual packets are reported through the Packet event as they are received from the network driver. Only packets that match the filter criteria specified in Filter and Direction will trigger the event.

PCAP_MODE_STAT0x01Statistical mode.

The component does not report individual packets. Instead, it will collect packet statistics and provide aggregated packet data via the Statistics event.

Config Method (IPMonitor Component)

Sets or retrieves a configuration setting.

Syntax

function Config(ConfigurationString: String): String;

Remarks

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

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

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

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

Deactivate Method (IPMonitor Component)

Stops monitoring network traffic.

Syntax

procedure Deactivate();

Remarks

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

DoEvents Method (IPMonitor Component)

Processes events from the internal message queue.

Syntax

procedure 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 component to fire events and report packet information.

Capture Modes

This method behaves differently depending on the value of the OperationMode property.

When OperationMode is set to PCAP_MODE_CAPT, calling this method while monitoring is active will prompt the component 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 component to collect packet statistics since the last call and fire the Statistics event with the aggregated data.

GetStatistics Method (IPMonitor Component)

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

Syntax

procedure GetStatistics(var Received: Int64; var Dropped: Int64; var AdapterDropped: Int64);

Remarks

This method provides capture statistics about the packets monitored by the component 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.

ListAdapters Method (IPMonitor Component)

Retrieves the network adapters available for monitoring.

Syntax

procedure 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 Event (IPMonitor Component)

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

Syntax

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

property OnError: TErrorEvent read FOnError write FOnError;

Remarks

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

Packet Event (IPMonitor Component)

Fires when a network packet is captured.

Syntax

type TPacketEvent = procedure (
  Sender: TObject;
  TimeStamp: TDateTime;
  PacketSize: Integer;
  Data: Pointer;
  DataSize: Integer
) of Object;

property OnPacket: TPacketEvent read FOnPacket write FOnPacket;

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

When Active is set to True, the component will report packet information based on the value of the OperationMode property. The following operation modes determine how packets are processed and reported:

PCAP_MODE_CAPT0x00Capture mode.

Individual packets are reported through the Packet event as they are received from the network driver. Only packets that match the filter criteria specified in Filter and Direction will trigger the event.

PCAP_MODE_STAT0x01Statistical mode.

The component does not report individual packets. Instead, it will collect packet statistics and provide aggregated packet data via the Statistics event.

Statistics Event (IPMonitor Component)

Fires to provide aggregated packet statistics.

Syntax

type TStatisticsEvent = procedure (
  Sender: TObject;
  TimeStamp: TDateTime;
  CapturedPackets: Int64;
  CapturedBytes: Int64
) of Object;

property OnStatistics: TStatisticsEvent read FOnStatistics write FOnStatistics;

Remarks

This event fires to provide aggregated packet statistics collected from the network adapter. The event will only fire if OperationMode is set to PCAP_MODE_STAT. Calling DoEvents while monitoring is active will prompt the component 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

When Active is set to True, the component will report packet information based on the value of the OperationMode property. The following operation modes determine how packets are processed and reported:

PCAP_MODE_CAPT0x00Capture mode.

Individual packets are reported through the Packet event as they are received from the network driver. Only packets that match the filter criteria specified in Filter and Direction will trigger the event.

PCAP_MODE_STAT0x01Statistical mode.

The component does not report individual packets. Instead, it will collect packet statistics and provide aggregated packet data via the Statistics event.

Adapter Type

Represents a network adapter in the system.

Remarks

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

The following fields are available:

Fields

Description
String (read-only)

Default Value: ""

Description of the adapter.

Name
String (read-only)

Default Value: ""

The name of the adapter. This value can be passed into the Activate method to start monitoring the adapter.

Config Settings (IPMonitor Component)

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

IPMonitor Config Settings

BufferSize:   The size of the buffer that the driver should use to store packets.

This configuration setting specifies the size of the buffer used by the driver.

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

The setting corresponds to the pcap_set_buffer_size() function.

In Linux and macOS, this configuration setting can be changed only when the component is not activated (Active is False).

MaxPacketSize:   The number of bytes of a packet to report.

This setting tells the driver how many bytes of a packet it should keep and pass to the component.

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

The setting corresponds to the pcap_set_snaplen() function.

This configuration setting can be changed only when the component is not activated (Active is False).

PacketTimeout:   The time to wait for a packet.

This setting tells the driver how long it may wait before replying with no packets, when packets are not available.

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

The setting corresponds to the pcap_set_timeout() function.

This configuration setting can be changed only when the component is not activated (Active is False).

PromiscuousMode:   Whether the driver should capture packets where a local system is neither a source or the destination of a packet.

This setting, when enabled, tells the adapter to capture packets that pass by, i.e., which don't originate in the given adapter and don't have it as a destination.

By default, the setting is disabled.

The setting corresponds to the pcap_set_promisc() function.

This configuration setting can be changed only when the component is not activated (Active is False).

WiFiMonitorMode:   Whether the adapter should work in monitor mode (available in Wi-Fi adapters).

By default, the setting is disabled.

The setting corresponds to the pcap_set_rfmon() function.

This configuration setting can be changed only when the component is not activated (Active is False).

Base Config Settings

BuildInfo:   Information about the product's build.

When queried, this setting will return a string containing information about the product's build.

LicenseInfo:   Information about the current license.

When queried, this setting will return a string containing information about the license this instance of a component is using. It will return the following information:

  • Product: The product the license is for.
  • Product Key: The key the license was generated from.
  • License Source: Where the license was found (e.g., RuntimeLicense, License File).
  • License Type: The type of license installed (e.g., Royalty Free, Single Server).

Trappable Errors (IPMonitor Component)