2 =======================================
12 =======================================
13 This application provides means to check the availability of remote hosts
14 through pings to them.
18 ---------------------------------------
19 The application uses ICMP echo requests messages to verify if a given host
22 The host's address can be an IP or a DNS.
26 ---------------------------------------
27 There are many ways to invoke the application, the simplest is just type:
29 which uses the configuration values from the configuration file (describled in
30 the Configuration File section).
34 ---------------------------------------
35 Further information about the problem domain can be found in the References
40 ---------------------------------------
41 All rights reserved to Intra2net AG.
46 =======================================
47 This section describes the code conventions that must be followed when maintain
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.
57 - Use the std::string to represent array of characters.
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.
65 - Use only int for regular integer numbers that do not require any specific
66 size. And document that a variable is non-negative using assertions. Do not
67 use unsigned types to say a number will never be negative.
69 - Use std::size_t for integers that represent sizes of vectors, objects or
70 buffers. Thus leaving the size difinition to the platform.
74 ---------------------------------------
75 The coding style used in this program is in accordance with the Intra2net,
76 which can be found in the following source:
78 - http://intranet/support_wiki/doku.php?id=entwicklung:codingstyle
82 ---------------------------------------
83 Version is built as follows:
84 major.minor[-[a|b|rc]]
86 - major represents big changes in application functionality.
87 - minor means small changes of bug fixes.
88 - a, b and rc stand for Alpha, Beta and Release Candidate respectivelly. Though
89 they are optional and not required in public release.
93 ---------------------------------------
94 There are two basic kinds of errors that shall happen in the program, errors
95 that the program can recover (expected) and errors that the progam can not or
96 should not recover from (exceptional errors). Bellow the description and the
97 method adopted to deal with each one:
98 - Expected: these errors can occur and must be handled by boolean return values.
99 (i.e. if a host is down, if the address was not resolved). This errors can
100 happen, but THE PROGRAM MUST CONTINUE TO OPERATE EVEN IF THEY HAPPEN.
101 - Exceptional: these are the kinds of errors that should not occur. They must be
102 handled by exceptions and THE PROGRAM MUST HALT IF THEY HAPPEN.
103 Thus, to keep things as simple as possible, this program adopts just two kinds
104 of error detection and handling:
105 - Return Boolean Value for expected errors and
106 - Handle Exceptions for exceptional errors.
111 =======================================
112 In this section is presented an overview of the source code and key design
116 3.1. Main directories
117 ---------------------------------------
118 The sources are spread over these distincts directories:
119 - src: contains the main application.
120 - test: where is located the unit tests.
121 - conf: keeps default and example configuration files.
124 3.2. Main concept of application operation
125 ---------------------------------------
126 This application makes extensive use of asynchronous timers-handlers from
127 Boost ASIO. So this section describes briefly how ASIO works. More information
128 can be found in the References section.
130 The basic idea is to have a handler which will be called when a timer expires.
131 After the timer expires, you have to schedule the timer again to call your
132 handler once more. Given the declaration of the timer:
134 boost::asio::deadline_timer my_timer( my_io_service );
136 you must specify when it will expire:
138 my_timer.expires_at( some_time_in_seconds + seconds( interval_in_seconds ) );
140 and which method will handle when the timer expires.
142 my_timer.async_wait( boost::bind( &MyClass::my_handle_method, this ) );
144 Then, the my_io_service service can be called to perform a loop:
150 4. Configuration file
151 =======================================
152 In this section are describled the configuration items, along with they
153 possible values and meanings. This section is organized in each major
158 ---------------------------------------
159 This configurations are shared among and affect all the hosts.
160 - limit-hosts-down: ranges from 0 to the number of hosts available. This value
161 represents the minimum number of hosts that have to fail (i.e. do not reply
162 the ping) in order to alert any external system.
166 ---------------------------------------
167 - address: the DNS or IP of the host to ping. Take in consideration that, if a
168 DNS is given, the application pings all IPs in the look up table, however, if
169 IP is provide, it is the only which will be pinged.
174 =======================================
175 [1] http://tools.ietf.org/html/rfc792
176 [2] http://en.wikipedia.org/wiki/Ping
177 [3] http://en.wikipedia.org/wiki/Internet_Control_Message_Protocol
178 [4] http://www.boost.org/doc/libs/1_45_0/doc/html/boost_asio.html
179 [5] http://www.boost.org/doc/libs/1_45_0/doc/html/program_options.html