A Discrete-Event Network Simulator
API
Loading...
Searching...
No Matches
ping.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2022 Chandrakant Jena
3 * Copyright (c) 2007-2009 Strasbourg University (original Ping6 code)
4 * Copyright (c) 2008 INRIA (original v4Ping code)
5 *
6 * SPDX-License-Identifier: GPL-2.0-only
7 *
8 * Author: Chandrakant Jena <chandrakant.barcelona@gmail.com>
9 *
10 * Derived from original v4Ping application (author: Mathieu Lacage)
11 * Derived from original ping6 application (author: Sebastien Vincent)
12 */
13
14#ifndef PING_H
15#define PING_H
16
17#include "ns3/application.h"
18#include "ns3/average.h"
19#include "ns3/traced-callback.h"
20
21#include <map>
22
23namespace ns3
24{
25
26class Socket;
27
28/**
29 * @ingroup internet-apps
30 * @defgroup ping Ping
31 */
32
33/**
34 * @ingroup ping
35 *
36 * This application behaves similarly to the Unix ping application, although
37 * with fewer options supported. The application can be used to send
38 * ICMP echo requests to unicast IPv4 and IPv6 addresses.
39 * The application can produce a verbose output similar to the real
40 * application, and can also export statistics via a trace source.
41 * The ping packet count, packet size, and interval between pings can
42 * be controlled via attributes of this class.
43 */
44class Ping : public Application
45{
46 public:
47 /**
48 * @brief Get the type ID.
49 * @return the object TypeId
50 */
51 static TypeId GetTypeId();
52
53 /**
54 * @enum VerboseMode
55 * @brief Encode three possible levels of verbose output
56 */
58 {
59 VERBOSE = 0, //!< Verbose output (similar to real ping output)
60 QUIET = 1, //!< Quiet output (similar to real 'ping -q' output)
61 SILENT = 2, //!< Silent output (no terminal output at all)
62 };
63
64 /**
65 * @enum DropReason
66 * @brief Reason why a ping was dropped
67 */
69 {
70 DROP_TIMEOUT = 0, //!< Response timed out
71 DROP_HOST_UNREACHABLE, //!< Received ICMP Destination Host Unreachable
72 DROP_NET_UNREACHABLE, //!< Received ICMP Destination Network Unreachable
73 };
74
75 /**
76 * A ping report provides all of the data that is typically output to the
77 * terminal when the application stops, including number sent and received
78 * and the RTT statistics.
79 */
81 {
82 uint32_t m_transmitted{0}; //!< Number of echo requests sent
83 uint32_t m_received{0}; //!< Number of echo replies received
84 uint16_t m_loss{0}; //!< Percentage of lost packets (decimal value 0-100)
85 Time m_duration{0}; //!< Duration of the application
86 double m_rttMin{0}; //!< rtt min value
87 double m_rttAvg{0}; //!< rtt avg value
88 double m_rttMax{0}; //!< rtt max value
89 double m_rttMdev{0}; //!< rtt mdev value
90 };
91
92 /**
93 * Constructor
94 */
95 Ping();
96
97 /**
98 * Destructor
99 */
100 ~Ping() override;
101
102 /**
103 * @brief Set routers for IPv6 routing type 0 (loose routing).
104 * @param routers routers addresses
105 */
106 void SetRouters(const std::vector<Ipv6Address>& routers);
107
108 /**
109 * TracedCallback signature for Rtt trace
110 *
111 * @param [in] seq The ICMP sequence number
112 * @param [in] p The ICMP echo request packet (including ICMP header)
113 */
114 typedef void (*TxTrace)(uint16_t seq, Ptr<const Packet> p);
115
116 /**
117 * TracedCallback signature for Rtt trace
118 *
119 * @param [in] seq The ICMP sequence number
120 * @param [in] rtt The reported RTT
121 */
122 typedef void (*RttTrace)(uint16_t seq, Time rtt);
123
124 /**
125 * TracedCallback signature for Drop trace
126 *
127 * @param [in] seq The ICMP sequence number
128 * @param [in] reason The reason for the reported drop
129 */
130 typedef void (*DropTrace)(uint16_t seq, DropReason reason);
131
132 /**
133 * TracedCallback signature for Report trace
134 *
135 * @param [in] report The report information
136 */
137 typedef void (*ReportTrace)(const PingReport& report);
138
139 protected:
140 void DoDispose() override;
141
142 private:
143 void StartApplication() override;
144 void StopApplication() override;
145
146 /**
147 * @brief Writes data to buffer in little-endian format.
148 *
149 * Least significant byte of data is at lowest buffer address
150 *
151 * \param[out] buffer the buffer to write to
152 * \param[in] data the data to write
153 */
154 void Write64(uint8_t* buffer, const uint64_t data);
155
156 /**
157 * @brief Writes data from a little-endian formatted buffer to data.
158 *
159 * @param buffer the buffer to read from
160 * @return the read data
161 */
162 uint64_t Read64(const uint8_t* buffer);
163
164 /**
165 * @brief Return the application signatiure.
166 * @returns the application signature.
167 *
168 * The application signature is the NodeId concatenated with the
169 * application index in the node.
170 */
171 uint64_t GetApplicationSignature() const;
172
173 /**
174 * @brief Receive an ICMPv4 or an ICMPv6 Echo reply
175 * @param socket the receiving socket
176 *
177 * This function is called by lower layers through a callback.
178 */
179 void Receive(Ptr<Socket> socket);
180
181 /**
182 * @brief Send one Ping (ICMPv4 ECHO or ICMPv6 ECHO) to the destination
183 */
184 void Send();
185
186 /**
187 * Print the report
188 */
189 void PrintReport();
190
191 /// Sender Local Address
193 /// Remote address
195 /// Wait interval between ECHO requests
197
198 /**
199 * Specifies the number of data bytes to be sent.
200 * The default is 56, which translates into 64 ICMP data bytes when combined with the 8 bytes of
201 * ICMP header data.
202 */
204 /// The socket we send packets from
206 /// The Type of Service carried by ICMP ECHOs
207 uint8_t m_tos;
208 /// ICMP ECHO sequence number
209 uint16_t m_seq{0};
210 /// Callbacks for tracing the packet Tx events
212 /// TracedCallback for RTT samples
214 /// TracedCallback for drop events
216 /// TracedCallback for final ping report
218 /// Variable to stor verbose mode
220 /// Received packets counter
222 /// Duplicate packets counter
224 /// Start time to report total ping time
226 /// Average rtt is ms
228 /// Next packet will be sent
230
231 /**
232 * @brief Sent echo request data.
233 */
235 {
236 public:
237 /**
238 * Constructor.
239 * @param txTimePar Echo request Tx time.
240 * @param ackedPar True if the Echo request has been acknowledged at least once.
241 */
242 EchoRequestData(Time txTimePar, bool ackedPar)
243 : txTime(txTimePar),
244 acked(ackedPar)
245 {
246 }
247
248 Time txTime; //!< Tx time
249 bool acked{false}; //!< True if packet has been acknowledged
250 };
251
252 /// All sent but not answered packets. Map icmp seqno -> when sent, acked at least once.
253 std::vector<EchoRequestData> m_sent;
254 /// Number of packets to be sent.
256 /// Time to wait for a response, in seconds. The option affects only timeout in absence of any
257 /// responses, otherwise ping waits for two RTTs
259 /// True if the report has been printed already.
260 bool m_reportPrinted{false};
261 /// Use IPv4 (false) or IPv6 (true)
262 bool m_useIpv6{false};
263 /// Destination is Broadcast or Multicast
265
266 /// Routers addresses for IPv6 routing type 0.
267 std::vector<Ipv6Address> m_routers;
268
269 /// App signature: ID of the node where the app is installed || ID of the Application.
270 uint64_t m_appSignature{0};
271};
272
273} // namespace ns3
274
275#endif /* PING_H */
a polymophic address class
Definition address.h:90
The base class for all ns3 applications.
Definition application.h:51
Simple average, min, max and std.
Definition average.h:32
An identifier for simulation events.
Definition event-id.h:45
Sent echo request data.
Definition ping.h:235
EchoRequestData(Time txTimePar, bool ackedPar)
Constructor.
Definition ping.h:242
bool acked
True if packet has been acknowledged.
Definition ping.h:249
Time txTime
Tx time.
Definition ping.h:248
This application behaves similarly to the Unix ping application, although with fewer options supporte...
Definition ping.h:45
uint32_t m_size
Specifies the number of data bytes to be sent.
Definition ping.h:203
uint32_t m_recv
Received packets counter.
Definition ping.h:221
Time m_started
Start time to report total ping time.
Definition ping.h:225
bool m_reportPrinted
True if the report has been printed already.
Definition ping.h:260
std::vector< EchoRequestData > m_sent
All sent but not answered packets. Map icmp seqno -> when sent, acked at least once.
Definition ping.h:253
uint64_t Read64(const uint8_t *buffer)
Writes data from a little-endian formatted buffer to data.
Definition ping.cc:389
void(* RttTrace)(uint16_t seq, Time rtt)
TracedCallback signature for Rtt trace.
Definition ping.h:122
void(* TxTrace)(uint16_t seq, Ptr< const Packet > p)
TracedCallback signature for Rtt trace.
Definition ping.h:114
bool m_useIpv6
Use IPv4 (false) or IPv6 (true)
Definition ping.h:262
VerboseMode
Encode three possible levels of verbose output.
Definition ping.h:58
@ SILENT
Silent output (no terminal output at all)
Definition ping.h:61
@ VERBOSE
Verbose output (similar to real ping output)
Definition ping.h:59
@ QUIET
Quiet output (similar to real 'ping -q' output)
Definition ping.h:60
void SetRouters(const std::vector< Ipv6Address > &routers)
Set routers for IPv6 routing type 0 (loose routing).
Definition ping.cc:687
std::vector< Ipv6Address > m_routers
Routers addresses for IPv6 routing type 0.
Definition ping.h:267
~Ping() override
Destructor.
Definition ping.cc:125
TracedCallback< uint16_t, Ptr< Packet > > m_txTrace
Callbacks for tracing the packet Tx events.
Definition ping.h:211
uint64_t m_appSignature
App signature: ID of the node where the app is installed || ID of the Application.
Definition ping.h:270
uint32_t m_count
Number of packets to be sent.
Definition ping.h:255
uint64_t GetApplicationSignature() const
Return the application signatiure.
Definition ping.cc:140
void Send()
Send one Ping (ICMPv4 ECHO or ICMPv6 ECHO) to the destination.
Definition ping.cc:412
void DoDispose() override
Destructor implementation.
Definition ping.cc:131
void(* DropTrace)(uint16_t seq, DropReason reason)
TracedCallback signature for Drop trace.
Definition ping.h:130
void StartApplication() override
Application specific startup code.
Definition ping.cc:514
TracedCallback< const PingReport & > m_reportTrace
TracedCallback for final ping report.
Definition ping.h:217
void StopApplication() override
Application specific shutdown code.
Definition ping.cc:615
DropReason
Reason why a ping was dropped.
Definition ping.h:69
@ DROP_TIMEOUT
Response timed out.
Definition ping.h:70
@ DROP_NET_UNREACHABLE
Received ICMP Destination Network Unreachable.
Definition ping.h:72
@ DROP_HOST_UNREACHABLE
Received ICMP Destination Host Unreachable.
Definition ping.h:71
Average< double > m_avgRtt
Average rtt is ms.
Definition ping.h:227
void PrintReport()
Print the report.
Definition ping.cc:634
Ping()
Constructor.
Definition ping.cc:120
Time m_interval
Wait interval between ECHO requests.
Definition ping.h:196
static TypeId GetTypeId()
Get the type ID.
Definition ping.cc:46
bool m_multipleDestinations
Destination is Broadcast or Multicast.
Definition ping.h:264
uint16_t m_seq
ICMP ECHO sequence number.
Definition ping.h:209
uint32_t m_duplicate
Duplicate packets counter.
Definition ping.h:223
Address m_interfaceAddress
Sender Local Address.
Definition ping.h:192
void Receive(Ptr< Socket > socket)
Receive an ICMPv4 or an ICMPv6 Echo reply.
Definition ping.cc:161
uint8_t m_tos
The Type of Service carried by ICMP ECHOs.
Definition ping.h:207
void Write64(uint8_t *buffer, const uint64_t data)
Writes data to buffer in little-endian format.
Definition ping.cc:374
Address m_destination
Remote address.
Definition ping.h:194
EventId m_next
Next packet will be sent.
Definition ping.h:229
Ptr< Socket > m_socket
The socket we send packets from.
Definition ping.h:205
VerboseMode m_verbose
Variable to stor verbose mode.
Definition ping.h:219
TracedCallback< uint16_t, DropReason > m_dropTrace
TracedCallback for drop events.
Definition ping.h:215
Time m_timeout
Time to wait for a response, in seconds.
Definition ping.h:258
void(* ReportTrace)(const PingReport &report)
TracedCallback signature for Report trace.
Definition ping.h:137
TracedCallback< uint16_t, Time > m_rttTrace
TracedCallback for RTT samples.
Definition ping.h:213
Smart pointer class similar to boost::intrusive_ptr.
Simulation virtual time values and global simulation resolution.
Definition nstime.h:94
Forward calls to a chain of Callback.
a unique identifier for an interface.
Definition type-id.h:48
Time Seconds(double value)
Construct a Time in the indicated unit.
Definition nstime.h:1344
Every class exported by the ns3 library is enclosed in the ns3 namespace.
uint8_t data[writeSize]
A ping report provides all of the data that is typically output to the terminal when the application ...
Definition ping.h:81
Time m_duration
Duration of the application.
Definition ping.h:85
uint16_t m_loss
Percentage of lost packets (decimal value 0-100)
Definition ping.h:84
double m_rttAvg
rtt avg value
Definition ping.h:87
double m_rttMdev
rtt mdev value
Definition ping.h:89
uint32_t m_received
Number of echo replies received.
Definition ping.h:83
double m_rttMin
rtt min value
Definition ping.h:86
uint32_t m_transmitted
Number of echo requests sent.
Definition ping.h:82
double m_rttMax
rtt max value
Definition ping.h:88