developer.intra2net.com Git - pingcheck/blob - Readme

   1      Table of Contents
   2 =======================================
   3 1. Introduction
   4 2. Code Conventions
   5 3. Source Code
   6 4. Configuration File
   7 5. References
   8
   9
  10
  11 1.   Introduction
  12 =======================================
  13 This application provides means to check the availability of remote hosts
  14 through pings to them.
  15
  16
  17 1.1. Rationale
  18 ---------------------------------------
  19 The application uses ICMP echo requests messages to verify if a given host
  20 is available or not.
  21
  22 The host's address can be an IP or a DNS.
  23
  24
  25 1.2. How to use
  26 ---------------------------------------
  27 There are many ways to invoke the application, the simplest is just type:
  28   ./libpingcheck
  29 which uses the configuration values from the configuration file (describled in
  30 the Configuration File section).
  31
  32
  33 1.3. Resources
  34 ---------------------------------------
  35 Further information about the problem domain can be found in the References
  36 section.
  37
  38
  39 1.4. Legal Issues
  40 ---------------------------------------
  41 All rights reserved to Intra2net AG.
  42
  43
  44
  45 2.   Code Conventions
  46 =======================================
  47 This section describes the code conventions that must be followed when maintain
  48 this code.
  49
  50
  51 2.1. Data Types
  52 ---------------------------------------
  53 This section is a guideline about the type you MUST use when declaring
  54 variables and constants. These types were chose to provide portability and
  55 improve code reradability.
  56
  57 - Use the std::string to represent array of characters.
  58
  59 - Use int32_t, int16_t and int8_t (or their unsigned couter parts) - instead of
  60   int, short and char, respectively - when the variable or constant MUST have a
  61   specific size (e.g. like in the protocol headers). This documents that the
  62   variable has the given number of bits. This states clear the intent of the
  63   original programmer and avoids improper modifications.
  64
  65 - Use int or uint for regular integer numbers that do not require any specific
  66   size.
  67
  68 - Use std::size_t for integers that represent sizes of vectors, objects or
  69   buffers. Thus leaving the size difinition to the platform.
  70
  71
  72 2.2. Coding Style
  73 ---------------------------------------
  74 The coding style used in this program is in accordance with the Intra2net,
  75 which can be found in the following source:
  76
  77 - http://intranet/support_wiki/doku.php?id=entwicklung:codingstyle
  78
  79
  80 2.3. Versioning
  81 ---------------------------------------
  82 Version is built as follows:
  83   major.minor[-[a|b|rc]]
  84 where:
  85 - major represents big changes in application functionality.
  86 - minor means small changes of bug fixes.
  87 - a, b and rc stand for Alpha, Beta and Release Candidate respectivelly. Though
  88   they are optional and not required in public release.
  89
  90
  91
  92 3.   Source Code
  93 =======================================
  94 In this section is presented an overview of the source code and key design
  95 decisions.
  96
  97
  98 3.1. Main directories
  99 ---------------------------------------
 100 The sources are spread over these distincts directories:
 101 - src: contains the main application.
 102 - test: where is located the unit tests.
 103 - conf: keeps default and example configuration files.
 104
 105
 106 3.2. Main concept of application operation
 107 ---------------------------------------
 108 This application makes extensive use of asynchronous timers-handlers from
 109 Boost ASIO. So this section describes briefly how ASIO works. More information
 110 can be found in the References section.
 111
 112 The basic idea is to have a handler which will be called when a timer expires.
 113 After the timer expires, you have to schedule the timer again to call your
 114 handler once more. Given the declaration of the timer:
 115
 116     boost::asio::deadline_timer my_timer( my_io_service );
 117
 118 you must specify when it will expire:
 119
 120     my_timer.expires_at( some_time_in_seconds + seconds( interval_in_seconds ) );
 121
 122 and which method will handle when the timer expires.
 123
 124     my_timer.async_wait( boost::bind( &MyClass::my_handle_method, this ) );
 125
 126 Then, the my_io_service service can be called to perform a loop:
 127
 128     my_io_service.run();
 129
 130
 131
 132 4.   Configuration file
 133 =======================================
 134 In this section are describled the configuration items, along with they
 135 possible values and meanings. This section is organized in each major
 136 configuration block.
 137
 138
 139 4.1. General
 140 ---------------------------------------
 141 This configurations are shared among and affect all the hosts.
 142 - limit-to-notify: range from 0 to the number of hosts available. This value
 143   represents minimum number of hosts that have to fail (i.e. do not reply the
 144   ping) in order to alert any external system.
 145
 146
 147 4.2. Host
 148 ---------------------------------------
 149 - address: the DNS or IP of the host to ping. Take in consideration that, if a
 150   DNS is given, the application pings all IPs in the look up table, however, if
 151   IP is provide, it is the only which will be pinged.
 152
 153
 154
 155 5.   References
 156 =======================================
 157 [1]  http://tools.ietf.org/html/rfc792
 158 [2]  http://en.wikipedia.org/wiki/Ping
 159 [3]  http://en.wikipedia.org/wiki/Internet_Control_Message_Protocol
 160 [4]  http://www.boost.org/doc/libs/1_45_0/doc/html/boost_asio.html
 161 [5]  http://www.boost.org/doc/libs/1_45_0/doc/html/program_options.html