IPMonitor Class

Properties   Methods   Events   Config Settings   Errors  

The IPMonitor class is used to listen to network traffic.

Syntax

IPMonitor

Remarks

The IPMonitor class will bind to a specific local host address and listen for network traffic received by the interface. The interface must support promiscuous mode (which may not work in many wireless cards because of security considerations) and must be installed on Windows 2000 or greater.

Note: If your computer connects to a switch, the switch will forward only those packets addressed to your computer. If your computer is on a hub, then you will receive everything.

The use of this component requires administrative permissions.

The first step in using the IPMonitor class is to set LocalHost to the IP address whose traffic you wish to monitor, and then set Active to True. For each packet that crosses the interface, the class will parse the header and fire an IPPacket event.

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.

AcceptData Property (IPMonitor Class)

This property indicates whether data reception is currently enabled.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetAcceptData();

Unicode (Windows)
BOOL GetAcceptData();

int ipworks_ipmonitor_getacceptdata(void* lpObj);

bool GetAcceptData();

Default Value

TRUE

Remarks

This property indicates whether data reception is currently enabled. When false, data reception is disabled and the IPPacket event will not fire. Use the PauseData and ProcessData methods to pause and resume data reception.

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

Data Type

Boolean

Active Property (IPMonitor Class)

This property indicates whether the class is active.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetActive();

Unicode (Windows)
BOOL GetActive();

int ipworks_ipmonitor_getactive(void* lpObj);

bool GetActive();

Default Value

FALSE

Remarks

This property indicates whether the class is currently active and is monitoring network traffic. Use the Activate and Deactivate methods to control whether the class is active.

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

Data Type

Boolean

IPPacket Property (IPMonitor Class)

This property includes the contents of the current packet.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetIPPacket(char* &lpIPPacket, int &lenIPPacket);

Unicode (Windows)
INT GetIPPacket(LPSTR &lpIPPacket, INT &lenIPPacket);

int ipworks_ipmonitor_getippacket(void* lpObj, char** lpIPPacket, int* lenIPPacket);

QByteArray GetIPPacket();

Default Value

""

Remarks

This property contains the contents of the current packet. This property is available only while the IPPacket event is being processed. An empty string is returned at all other times.

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

Data Type

Binary String

LocalHost Property (IPMonitor Class)

The name of the local host or user-assigned IP interface through which connections are initiated or accepted.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetLocalHost();
int SetLocalHost(const char* lpszLocalHost);

Unicode (Windows)
LPWSTR GetLocalHost();
INT SetLocalHost(LPCWSTR lpszLocalHost);

char* ipworks_ipmonitor_getlocalhost(void* lpObj);
int ipworks_ipmonitor_setlocalhost(void* lpObj, const char* lpszLocalHost);

QString GetLocalHost();
int SetLocalHost(QString qsLocalHost);

Default Value

""

Remarks

This property contains the name of the local host as obtained by the gethostname() system call, or if the user has assigned an IP address, the value of that address.

In multihomed hosts (machines with more than one IP interface) setting LocalHost to the IP address of an interface will make the class initiate connections (or accept in the case of server classs) only through that interface. It is recommended to provide an IP address rather than a hostname when setting this property to ensure the desired interface is used.

If the class is connected, the LocalHost property shows the IP address of the interface through which the connection is made in internet dotted format (aaa.bbb.ccc.ddd). In most cases, this is the address of the local host, except for multihomed hosts (machines with more than one IP interface).

Note: LocalHost is not persistent. You must always set it in code, and never in the property window.

Data Type

String

Activate Method (IPMonitor Class)

This method enables network monitoring.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int Activate();

Unicode (Windows)
INT Activate();

int ipworks_ipmonitor_activate(void* lpObj);

int Activate();

Remarks

This methods enables network monitoring. When called, the class will create a communication endpoint (socket) that can be used to monitor network traffic.

To stop monitoring traffic, call Deactivate.

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* ipworks_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)

This method disables network monitoring.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int Deactivate();

Unicode (Windows)
INT Deactivate();

int ipworks_ipmonitor_deactivate(void* lpObj);

int Deactivate();

Remarks

This methods disables network monitoring. When called, the class will stop monitoring network traffic.

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)

This method processes events from the internal message queue.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int DoEvents();

Unicode (Windows)
INT DoEvents();

int ipworks_ipmonitor_doevents(void* lpObj);

int DoEvents();

Remarks

When DoEvents is called, the class processes any available events. If no events are available, it waits for a preset period of time, and then returns.

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

ListIPAddresses Method (IPMonitor Class)

This method lists the valid IP addresses for this host.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int ListIPAddresses();

Unicode (Windows)
INT ListIPAddresses();

int ipworks_ipmonitor_listipaddresses(void* lpObj);

int ListIPAddresses();

Remarks

Use this method to list all valid addresses that can be monitored. Before monitoring the network, LocalHost must be set to a valid address on the host. After a call to this method, an IPAddress event will fire for each address.

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

ParsePcapFile Method (IPMonitor Class)

This method parses the specified pcap file.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int ParsePcapFile(const char* lpszfileName);

Unicode (Windows)
INT ParsePcapFile(LPCWSTR lpszfileName);

int ipworks_ipmonitor_parsepcapfile(void* lpObj, const char* lpszfileName);

int ParsePcapFile(const QString& qsfileName);

Remarks

This method parses the specified pcap (packet capture) file and fires events as if the traffic were received directly.

The class supports both the standard pcap and the newer pcap-ng file formats used by a variety of popular network capture tools. When calling this method, the file will be parsed and the IPPacket event will fire for each parsed packet.

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

PauseData Method (IPMonitor Class)

This method pauses data reception.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int PauseData();

Unicode (Windows)
INT PauseData();

int ipworks_ipmonitor_pausedata(void* lpObj);

int PauseData();

Remarks

This method pauses data reception when called. While data reception is paused, the IPPacket event will not fire. Call ProcessData to reenable data reception.

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

ProcessData Method (IPMonitor Class)

This method reenables data reception after a call to PauseData .

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int ProcessData();

Unicode (Windows)
INT ProcessData();

int ipworks_ipmonitor_processdata(void* lpObj);

int ProcessData();

Remarks

This method reenables data reception after a previous call to PauseData. When PauseData is called, the IPPacket event will not fire. To reenable data reception and allow IPPacket to fire, call this method.

Note: This method is used only after previously calling PauseData. It does not need to be called to process data by default.

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

Reset Method (IPMonitor Class)

This method will reset the class.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int Reset();

Unicode (Windows)
INT Reset();

int ipworks_ipmonitor_reset(void* lpObj);

int Reset();

Remarks

This method will reset the class's properties to their default values.

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)

Fired when information is available about errors during data delivery.

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

The Error event is fired in case of exceptional conditions during message processing. Normally the class fails with an error.

The ErrorCode parameter contains an error code, and the Description parameter contains a textual description of the error. For a list of valid error codes and their descriptions, please refer to the Error Codes section.

IPAddress Event (IPMonitor Class)

This event is fired for each valid IP address on this host.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireIPAddress(IPMonitorIPAddressEventParams *e);

typedef struct {
  const char *IpAddress;
  int reserved;
} IPMonitorIPAddressEventParams;


Unicode (Windows)
virtual INT FireIPAddress(IPMonitorIPAddressEventParams *e);

typedef struct {
  LPCWSTR IpAddress;
  INT reserved;
} IPMonitorIPAddressEventParams;

#define EID_IPMONITOR_IPADDRESS 2

virtual INT IPWORKS_CALL FireIPAddress(LPSTR &lpszIpAddress);

class IPMonitorIPAddressEventParams {
public:
  const QString &IpAddress();

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

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

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

Remarks

Before monitoring the network, LocalHost must be set to a valid address on the host. Use the ListIPAddresses method to list all valid addresses that can be monitored. After a call to the method, an IPAddress event will fire for each address.

IPPacket Event (IPMonitor Class)

This event is fired whenever a packet is received.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireIPPacket(IPMonitorIPPacketEventParams *e);

typedef struct {
  const char *SourceAddress;
  int SourcePort;
  const char *DestinationAddress;
  int DestinationPort;
  int IPVersion;
  int TOS;
  int Id;
  int Flags;
  int Offset;
  int TTL;
  int Checksum;
  int IPProtocol;
  const char *Payload;
  int lenPayload;
  int64 Timestamp;
  int reserved;
} IPMonitorIPPacketEventParams;


Unicode (Windows)
virtual INT FireIPPacket(IPMonitorIPPacketEventParams *e);

typedef struct {
  LPCWSTR SourceAddress;
  INT SourcePort;
  LPCWSTR DestinationAddress;
  INT DestinationPort;
  INT IPVersion;
  INT TOS;
  INT Id;
  INT Flags;
  INT Offset;
  INT TTL;
  INT Checksum;
  INT IPProtocol;
  LPCSTR Payload;
  INT lenPayload;
  LONG64 Timestamp;
  INT reserved;
} IPMonitorIPPacketEventParams;

#define EID_IPMONITOR_IPPACKET 3

virtual INT IPWORKS_CALL FireIPPacket(LPSTR &lpszSourceAddress, INT &iSourcePort, LPSTR &lpszDestinationAddress, INT &iDestinationPort, INT &iIPVersion, INT &iTOS, INT &iId, INT &iFlags, INT &iOffset, INT &iTTL, INT &iChecksum, INT &iIPProtocol, LPSTR &lpPayload, INT &lenPayload, LONG64 &lTimestamp);

class IPMonitorIPPacketEventParams {
public:
  const QString &SourceAddress();

  int SourcePort();

  const QString &DestinationAddress();

  int DestinationPort();

  int IPVersion();

  int TOS();

  int Id();

  int Flags();

  int Offset();

  int TTL();

  int Checksum();

  int IPProtocol();

  const QByteArray &Payload();

  qint64 Timestamp();

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

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

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

Remarks

When Active is True or ParsePcapFile is called, the class will listen for network traffic or parse the provided file, respectively. For each packet sent across the interface in LocalHost, the class will parse the packet and fire an IPPacket event with the header fields and payload. The parameters are defined as follows:

TOS

Precedence

Flags

IPProtocol (For a full list, visit www.iana.org.)

Config Settings (IPMonitor Class)

IPMonitor Config Settings

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

IPMonitor Errors

SSL Errors

TCP/IP Errors