
                                 M-Ping README 
                       <http://m-ping.sourceforge.net/>

                             Tomasz Stelmach, 2008
                      <http://www.stelmach-online.net/>

                  Icons by: http://miloszwl.deviantart.com/

===============================================================================
Basic concept
===============================================================================

M-Ping application provides three types of operations:
- Ping
- Traceroute
- Whois

All of these operations can be executed at the same time and in multiple 
instances. The results are visualized either using graphical methods or with 
text output (or both) inside an MDI window. The processing itself is based on
standard external tools (e.g. for ping and traceroute) or on internal 
implementation inside the application.

The application is developed and tested mainly on Linux but it should compile
and work properly additionally at least on Windows and Sun Solaris.

-------------------------------------------------------------------------------
PING
-------------------------------------------------------------------------------

Ping functionality is based on the standard tools available in most of the
operating systems. M-Ping starts a ping tool and parses its output to produce
a graphical picture of the results.

The application assumes that the ping tool that is used is able to provide
the following output on stdout:

1) For reporting success:

  a) One line that indicates start of the pinging process (optionally this 
     line may also contain information about IP address of the host being 
     pinged)

  b) One line for each successful ping indicating the success and containing
     information about the elapsed time.

2) For reporting failures:
  
  either...

  a) one line per failure (available on Windows)
  
  or...

  b) information about current icmp_seq in the "success" and "failure" lines
     (available on Linux and Solaris)

In other words: on Windows the statistics and "error" bars are based on the
presence of failure (timeout) lines, and on Linux / Solaris they are based
on "icmp seq" information which is present in the success and failure lines.

Ping functionality is configurable and should work with all popular ping
implementations. Settings for supported operating systems are provided within
standard configuration of the application.

-------------------------------------------------------------------------------
TRACEROUTE
-------------------------------------------------------------------------------

Traceroute functionality is based on standard tools available in most operating
systems. M-Ping starts the traceroute process and parses its output to read the
results. The application assumes that certain format of the output is used
(this assumption is currently correct for Linux, Solaris and Windows) by the
standard tool: 

* One line containing IP of the address being traced.

* One more lines with results in the form of:

  [ ID ] [ Result 1 ] [ Result 2 ] ... [ Result n ]
  
  where result consists of host, IP and time information in any order.
  
  Each result may also contain error information instead of other fields.
  
* One more lines containing error messages. 

The recognition of the information is configurable within the Preferences
window. Regular expressions are used for that purpose.

-------------------------------------------------------------------------------
WHOIS
-------------------------------------------------------------------------------

Whois functionality is implemented internally using Qt Network package. It
should work properly under any operating system. The implementation is based
on RFC 3912 specification and it attempts to connect to the destination server
using port 43.

Whois requires the "whois" server to be defined. By default M-Ping contains
a pre-defined server list, but it can be modified at any time in the 
preferences dialog. Usually entering a proper "whois" server is the key factor
in getting useful results for a query.

===============================================================================
COMPILATION & INSTALLATION
===============================================================================

Simply run "./configure" and a valid Makefile should be created. Then type
"make all" and the binary should be produced inside the "bin" directory.

Dependencies:
- Qt 4.3.x or higher

The application can be installed at any place in the system. It requires only
access to a Qt library and the ping and traceroute tools.

===============================================================================
HISTORY OF THE CHANGES
===============================================================================

v0.4
----
- nicer handling of text output for "ping" 
- "ping" (and "trace" too) now detects "command not found" errors
- selected tab is now saved within the project data
- "traceroute" functionality added (reg exp rules are still "experimental" and
  require a lot of testing)

v0.3
----
- different icons for different child windows
- switched to QMdiArea class for better future compatibility
- load & save project in the file system
- scrollbars are enabled in the MDI area to allow bigger projects
- save & restore last visible project in m-ping configuration
- command line support for loading project
- saving graphics now works under Linux
- main menu implemented to provide the expected functionality

v0.2
----
- history of hosts available via a combo box
- application icon
- new toolbar icons
- "whois" functionality added
- "ping" chart drawing performance fix
- save to text file added to "ping" and "whois"
- reset data added to "ping"
- save to graphics file added to "ping"
- "configure" fixed in the repository to be executable

v0.1
----
- basic implementation of the MDI GUI is ready (although icons are not)
- pinging "works" (both graphical and text modes)
- preferences window allows configuration of the ping functionality
- settings (from preferences and window posistion) are stored withing standard
  QT storage.
- window menu is implemented and provides the expected functionality (it is not
  a standard component of the Qt library)
- this is the first version to be released on the sourceforge.net page
