A Discrete-Event Network Simulator
API
ns3::Ping Class Reference

This application behaves similarly to the Unix ping application, although with fewer options supported. More...

#include "ping.h"

+ Inheritance diagram for ns3::Ping:
+ Collaboration diagram for ns3::Ping:

Classes

class  EchoRequestData
 Sent echo request data. More...
 
struct  PingReport
 A ping report provides all of the data that is typically output to the terminal when the application stops, including number sent and received and the RTT statistics. More...
 

Public Types

enum  DropReason { DROP_TIMEOUT = 0 , DROP_HOST_UNREACHABLE , DROP_NET_UNREACHABLE }
 Reason why a ping was dropped. More...
 
typedef void(* DropTrace) (uint16_t seq, DropReason reason)
 TracedCallback signature for Drop trace. More...
 
typedef void(* ReportTrace) (const PingReport &report)
 TracedCallback signature for Report trace. More...
 
typedef void(* RttTrace) (uint16_t seq, Time rtt)
 TracedCallback signature for Rtt trace. More...
 
typedef void(* TxTrace) (uint16_t seq, Ptr< const Packet > p)
 TracedCallback signature for Rtt trace. More...
 
enum  VerboseMode { VERBOSE = 0 , QUIET = 1 , SILENT = 2 }
 Encode three possible levels of verbose output. More...
 
- Public Types inherited from ns3::Application
typedef void(* DelayAddressCallback) (const Time &delay, const Address &from)
 Common callback signature for packet delay and address. More...
 
typedef void(* StateTransitionCallback) (const std::string &oldState, const std::string &newState)
 Common signature used by callbacks to application's state transition trace source. More...
 

Public Member Functions

 Ping ()
 Constructor. More...
 
 ~Ping () override
 Destructor. More...
 
void SetRouters (const std::vector< Ipv6Address > &routers)
 Set routers for IPv6 routing type 0 (loose routing). More...
 
- Public Member Functions inherited from ns3::Application
 Application ()
 
 ~Application () override
 
Ptr< NodeGetNode () const
 
void SetNode (Ptr< Node > node)
 
void SetStartTime (Time start)
 Specify application start time. More...
 
void SetStopTime (Time stop)
 Specify application stop time. More...
 
- Public Member Functions inherited from ns3::Object
 Object ()
 Constructor. More...
 
 ~Object () override
 Destructor. More...
 
void AggregateObject (Ptr< Object > other)
 Aggregate two Objects together. More...
 
void Dispose ()
 Dispose of this Object. More...
 
AggregateIterator GetAggregateIterator () const
 Get an iterator to the Objects aggregated to this one. More...
 
TypeId GetInstanceTypeId () const override
 Get the most derived TypeId for this Object. More...
 
template<typename T >
Ptr< T > GetObject () const
 Get a pointer to the requested aggregated Object. More...
 
template<>
Ptr< ObjectGetObject () const
 Specialization of () for objects of type ns3::Object. More...
 
template<typename T >
Ptr< T > GetObject (TypeId tid) const
 Get a pointer to the requested aggregated Object by TypeId. More...
 
template<>
Ptr< ObjectGetObject (TypeId tid) const
 Specialization of (TypeId tid) for objects of type ns3::Object. More...
 
void Initialize ()
 Invoke DoInitialize on all Objects aggregated to this one. More...
 
bool IsInitialized () const
 Check if the object has been initialized. More...
 
- Public Member Functions inherited from ns3::SimpleRefCount< Object, ObjectBase, ObjectDeleter >
 SimpleRefCount ()
 Default constructor. More...
 
 SimpleRefCount (const SimpleRefCount &o[[maybe_unused]])
 Copy constructor. More...
 
uint32_t GetReferenceCount () const
 Get the reference count of the object. More...
 
SimpleRefCountoperator= (const SimpleRefCount &o[[maybe_unused]])
 Assignment operator. More...
 
void Ref () const
 Increment the reference count. More...
 
void Unref () const
 Decrement the reference count. More...
 
- Public Member Functions inherited from ns3::ObjectBase
virtual ~ObjectBase ()
 Virtual destructor. More...
 
void GetAttribute (std::string name, AttributeValue &value) const
 Get the value of an attribute, raising fatal errors if unsuccessful. More...
 
bool GetAttributeFailSafe (std::string name, AttributeValue &value) const
 Get the value of an attribute without raising errors. More...
 
void SetAttribute (std::string name, const AttributeValue &value)
 Set a single attribute, raising fatal errors if unsuccessful. More...
 
bool SetAttributeFailSafe (std::string name, const AttributeValue &value)
 Set a single attribute without raising errors. More...
 
bool TraceConnect (std::string name, std::string context, const CallbackBase &cb)
 Connect a TraceSource to a Callback with a context. More...
 
bool TraceConnectWithoutContext (std::string name, const CallbackBase &cb)
 Connect a TraceSource to a Callback without a context. More...
 
bool TraceDisconnect (std::string name, std::string context, const CallbackBase &cb)
 Disconnect from a TraceSource a Callback previously connected with a context. More...
 
bool TraceDisconnectWithoutContext (std::string name, const CallbackBase &cb)
 Disconnect from a TraceSource a Callback previously connected without a context. More...
 

Static Public Member Functions

static TypeId GetTypeId ()
 Get the type ID. More...
 
- Static Public Member Functions inherited from ns3::Application
static TypeId GetTypeId ()
 Get the type ID. More...
 
- Static Public Member Functions inherited from ns3::Object
static TypeId GetTypeId ()
 Register this type. More...
 
- Static Public Member Functions inherited from ns3::ObjectBase
static TypeId GetTypeId ()
 Get the type ID. More...
 

Private Member Functions

void DoDispose () override
 Destructor implementation. More...
 
uint64_t GetApplicationSignature () const
 Return the application signatiure. More...
 
void PrintReport ()
 Print the report. More...
 
uint64_t Read64 (const uint8_t *buffer)
 Writes data from a little-endian formatted buffer to data. More...
 
void Receive (Ptr< Socket > socket)
 Receive an ICMPv4 or an ICMPv6 Echo reply. More...
 
void Send ()
 Send one Ping (ICMPv4 ECHO or ICMPv6 ECHO) to the destination. More...
 
void StartApplication () override
 Application specific startup code. More...
 
void StopApplication () override
 Application specific shutdown code. More...
 
void Write64 (uint8_t *buffer, const uint64_t data)
 Writes data to buffer in little-endian format. More...
 

Private Attributes

uint64_t m_appSignature {0}
 App signature: ID of the node where the app is installed || ID of the Application. More...
 
Average< double > m_avgRtt
 Average rtt is ms. More...
 
uint32_t m_count {0}
 Number of packets to be sent. More...
 
Address m_destination
 Remote address. More...
 
TracedCallback< uint16_t, DropReasonm_dropTrace
 TracedCallback for drop events. More...
 
uint32_t m_duplicate {0}
 Duplicate packets counter. More...
 
Address m_interfaceAddress
 Sender Local Address. More...
 
Time m_interval {Seconds(1)}
 Wait interval between ECHO requests. More...
 
bool m_multipleDestinations {false}
 Destination is Broadcast or Multicast. More...
 
EventId m_next
 Next packet will be sent. More...
 
uint32_t m_recv {0}
 Received packets counter. More...
 
bool m_reportPrinted {false}
 True if the report has been printed already. More...
 
TracedCallback< const PingReport & > m_reportTrace
 TracedCallback for final ping report. More...
 
std::vector< Ipv6Addressm_routers
 Routers addresses for IPv6 routing type 0. More...
 
TracedCallback< uint16_t, Timem_rttTrace
 TracedCallback for RTT samples. More...
 
std::vector< EchoRequestDatam_sent
 All sent but not answered packets. Map icmp seqno -> when sent, acked at least once. More...
 
uint16_t m_seq {0}
 ICMP ECHO sequence number. More...
 
uint32_t m_size {56}
 Specifies the number of data bytes to be sent. More...
 
Ptr< Socketm_socket
 The socket we send packets from. More...
 
Time m_started
 Start time to report total ping time. More...
 
Time m_timeout {Seconds(1)}
 Time to wait for a response, in seconds. More...
 
uint8_t m_tos
 The Type of Service carried by ICMP ECHOs. More...
 
TracedCallback< uint16_t, Ptr< Packet > > m_txTrace
 Callbacks for tracing the packet Tx events. More...
 
bool m_useIpv6 {false}
 Use IPv4 (false) or IPv6 (true) More...
 
VerboseMode m_verbose {VerboseMode::VERBOSE}
 Variable to stor verbose mode. More...
 

Additional Inherited Members

- Protected Member Functions inherited from ns3::Application
void DoDispose () override
 Destructor implementation. More...
 
void DoInitialize () override
 Initialize() implementation. More...
 
- Protected Member Functions inherited from ns3::Object
 Object (const Object &o)
 Copy an Object. More...
 
virtual void NotifyNewAggregate ()
 Notify all Objects aggregated to this one of a new Object being aggregated. More...
 
- Protected Member Functions inherited from ns3::ObjectBase
void ConstructSelf (const AttributeConstructionList &attributes)
 Complete construction of ObjectBase; invoked by derived classes. More...
 
virtual void NotifyConstructionCompleted ()
 Notifier called once the ObjectBase is fully constructed. More...
 
- Protected Attributes inherited from ns3::Application
Ptr< Nodem_node
 The node that this application is installed on. More...
 
EventId m_startEvent
 The event that will fire at m_startTime to start the application. More...
 
Time m_startTime
 The simulation time that the application will start. More...
 
EventId m_stopEvent
 The event that will fire at m_stopTime to end the application. More...
 
Time m_stopTime
 The simulation time that the application will end. More...
 

Detailed Description

This application behaves similarly to the Unix ping application, although with fewer options supported.

The application can be used to send ICMP echo requests to unicast IPv4 and IPv6 addresses. The application can produce a verbose output similar to the real application, and can also export statistics via a trace source. The ping packet count, packet size, and interval between pings can be controlled via attributes of this class.

Definition at line 55 of file ping.h.

Member Typedef Documentation

◆ DropTrace

typedef void(* ns3::Ping::DropTrace) (uint16_t seq, DropReason reason)

TracedCallback signature for Drop trace.

Parameters
[in]seqThe ICMP sequence number
[in]reasonThe reason for the reported drop

Definition at line 141 of file ping.h.

◆ ReportTrace

typedef void(* ns3::Ping::ReportTrace) (const PingReport &report)

TracedCallback signature for Report trace.

Parameters
[in]reportThe report information

Definition at line 148 of file ping.h.

◆ RttTrace

typedef void(* ns3::Ping::RttTrace) (uint16_t seq, Time rtt)

TracedCallback signature for Rtt trace.

Parameters
[in]seqThe ICMP sequence number
[in]rttThe reported RTT

Definition at line 133 of file ping.h.

◆ TxTrace

typedef void(* ns3::Ping::TxTrace) (uint16_t seq, Ptr< const Packet > p)

TracedCallback signature for Rtt trace.

Parameters
[in]seqThe ICMP sequence number
[in]pThe ICMP echo request packet (including ICMP header)

Definition at line 125 of file ping.h.

Member Enumeration Documentation

◆ DropReason

Reason why a ping was dropped.

Enumerator
DROP_TIMEOUT 

Response timed out.

DROP_HOST_UNREACHABLE 

Received ICMP Destination Host Unreachable.

DROP_NET_UNREACHABLE 

Received ICMP Destination Network Unreachable.

Definition at line 79 of file ping.h.

◆ VerboseMode

Encode three possible levels of verbose output.

Enumerator
VERBOSE 

Verbose output (similar to real ping output)

QUIET 

Quiet output (similar to real 'ping -q' output)

SILENT 

Silent output (no terminal output at all)

Definition at line 68 of file ping.h.

Constructor & Destructor Documentation

◆ Ping()

ns3::Ping::Ping ( )

Constructor.

Definition at line 131 of file ping.cc.

References NS_LOG_FUNCTION.

◆ ~Ping()

ns3::Ping::~Ping ( )
override

Destructor.

Definition at line 136 of file ping.cc.

References NS_LOG_FUNCTION.

Member Function Documentation

◆ DoDispose()

void ns3::Ping::DoDispose ( void  )
overrideprivatevirtual

Destructor implementation.

This method is called by Dispose() or by the Object's destructor, whichever comes first.

Subclasses are expected to implement their real destruction code in an overridden version of this method and chain up to their parent's implementation once they are done. i.e, for simplicity, the destructor of every subclass should be empty and its content should be moved to the associated DoDispose() method.

It is safe to call GetObject() from within this method.

Reimplemented from ns3::Object.

Definition at line 142 of file ping.cc.

References ns3::Application::DoDispose(), m_socket, NS_LOG_FUNCTION, and StopApplication().

+ Here is the call graph for this function:

◆ GetApplicationSignature()

uint64_t ns3::Ping::GetApplicationSignature ( ) const
private

Return the application signatiure.

Returns
the application signature.

The application signature is the NodeId concatenated with the application index in the node.

Definition at line 151 of file ping.cc.

References ns3::Node::GetApplication(), ns3::Node::GetId(), ns3::Node::GetNApplications(), ns3::Application::GetNode(), NS_ASSERT_MSG, and NS_LOG_FUNCTION.

Referenced by StartApplication().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ GetTypeId()

TypeId ns3::Ping::GetTypeId ( void  )
static

◆ PrintReport()

◆ Read64()

uint64_t ns3::Ping::Read64 ( const uint8_t *  buffer)
private

Writes data from a little-endian formatted buffer to data.

Parameters
bufferthe buffer to read from
Returns
the read data

Definition at line 400 of file ping.cc.

References data, and NS_LOG_FUNCTION.

Referenced by Receive().

+ Here is the caller graph for this function:

◆ Receive()

void ns3::Ping::Receive ( Ptr< Socket socket)
private

Receive an ICMPv4 or an ICMPv6 Echo reply.

Parameters
socketthe receiving socket

This function is called by lower layers through a callback.

Definition at line 172 of file ping.cc.

References ns3::Inet6SocketAddress::ConvertFrom(), ns3::InetSocketAddress::ConvertFrom(), ns3::Packet::CopyData(), two-ray-to-three-gpp-ch-calibration::delta, ns3::Ipv6PacketInfoTag::GetAddress(), ns3::Icmpv4Echo::GetData(), ns3::Icmpv4Echo::GetDataSize(), ns3::Ipv6Header::GetHopLimit(), ns3::Icmpv6Echo::GetId(), ns3::Icmpv4Echo::GetIdentifier(), ns3::InetSocketAddress::GetIpv4(), ns3::Inet6SocketAddress::GetIpv6(), ns3::Object::GetObject(), ns3::Socket::GetRxAvailable(), ns3::Icmpv6Echo::GetSeq(), ns3::Icmpv4Echo::GetSequenceNumber(), ns3::Ipv4Header::GetSerializedSize(), ns3::Ipv6Header::GetSerializedSize(), ns3::Packet::GetSize(), ns3::Ipv4Header::GetTtl(), ns3::Icmpv4Header::GetType(), ns3::Icmpv4Header::ICMPV4_DEST_UNREACH, ns3::Icmpv4Header::ICMPV4_ECHO_REPLY, ns3::Icmpv4Header::ICMPV4_TIME_EXCEEDED, ns3::Icmpv6Header::ICMPV6_ECHO_REPLY, ns3::Icmpv6Header::ICMPV6_ERROR_DESTINATION_UNREACHABLE, ns3::Icmpv6Header::ICMPV6_ERROR_TIME_EXCEEDED, ns3::Inet6SocketAddress::IsMatchingType(), ns3::InetSocketAddress::IsMatchingType(), m_appSignature, m_avgRtt, m_count, m_duplicate, m_multipleDestinations, ns3::Application::m_node, m_recv, m_rttTrace, m_sent, m_socket, m_verbose, ns3::Simulator::Now(), NS_ASSERT, NS_LOG_DEBUG, NS_LOG_FUNCTION, NS_LOG_INFO, ns3::PING_ID, Read64(), ns3::Socket::RecvFrom(), ns3::Packet::RemoveHeader(), ns3::Packet::RemovePacketTag(), ns3::Simulator::ScheduleNow(), StopApplication(), check-style-clang-format::type, and ns3::Average< T >::Update().

Referenced by StartApplication().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ Send()

◆ SetRouters()

void ns3::Ping::SetRouters ( const std::vector< Ipv6Address > &  routers)

Set routers for IPv6 routing type 0 (loose routing).

Parameters
routersrouters addresses

Definition at line 698 of file ping.cc.

References m_routers.

◆ StartApplication()

◆ StopApplication()

void ns3::Ping::StopApplication ( void  )
overrideprivatevirtual

Application specific shutdown code.

The StopApplication method is called at the stop time specified by Stop This method should be overridden by all or most application subclasses.

Reimplemented from ns3::Application.

Definition at line 626 of file ping.cc.

References ns3::EventId::Cancel(), ns3::Socket::Close(), ns3::EventId::IsRunning(), m_next, m_socket, ns3::Application::m_stopEvent, NS_LOG_FUNCTION, and PrintReport().

Referenced by DoDispose(), Receive(), and Send().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ Write64()

void ns3::Ping::Write64 ( uint8_t *  buffer,
const uint64_t  data 
)
private

Writes data to buffer in little-endian format.

Least significant byte of data is at lowest buffer address

Parameters
[out]bufferthe buffer to write to
[in]datathe data to write

Definition at line 385 of file ping.cc.

References data, and NS_LOG_FUNCTION.

Referenced by Send().

+ Here is the caller graph for this function:

Member Data Documentation

◆ m_appSignature

uint64_t ns3::Ping::m_appSignature {0}
private

App signature: ID of the node where the app is installed || ID of the Application.

Definition at line 280 of file ping.h.

Referenced by Receive(), Send(), and StartApplication().

◆ m_avgRtt

Average<double> ns3::Ping::m_avgRtt
private

Average rtt is ms.

Definition at line 237 of file ping.h.

Referenced by PrintReport(), Receive(), and Send().

◆ m_count

uint32_t ns3::Ping::m_count {0}
private

Number of packets to be sent.

Definition at line 265 of file ping.h.

Referenced by GetTypeId(), Receive(), Send(), and StartApplication().

◆ m_destination

Address ns3::Ping::m_destination
private

Remote address.

Definition at line 204 of file ping.h.

Referenced by GetTypeId(), PrintReport(), Send(), and StartApplication().

◆ m_dropTrace

TracedCallback<uint16_t, DropReason> ns3::Ping::m_dropTrace
private

TracedCallback for drop events.

Definition at line 225 of file ping.h.

Referenced by GetTypeId().

◆ m_duplicate

uint32_t ns3::Ping::m_duplicate {0}
private

Duplicate packets counter.

Definition at line 233 of file ping.h.

Referenced by PrintReport(), and Receive().

◆ m_interfaceAddress

Address ns3::Ping::m_interfaceAddress
private

Sender Local Address.

Definition at line 202 of file ping.h.

Referenced by GetTypeId(), and StartApplication().

◆ m_interval

Time ns3::Ping::m_interval {Seconds(1)}
private

Wait interval between ECHO requests.

Definition at line 206 of file ping.h.

Referenced by GetTypeId(), Send(), and StartApplication().

◆ m_multipleDestinations

bool ns3::Ping::m_multipleDestinations {false}
private

Destination is Broadcast or Multicast.

Definition at line 274 of file ping.h.

Referenced by Receive(), and StartApplication().

◆ m_next

EventId ns3::Ping::m_next
private

Next packet will be sent.

Definition at line 239 of file ping.h.

Referenced by Send(), and StopApplication().

◆ m_recv

uint32_t ns3::Ping::m_recv {0}
private

Received packets counter.

Definition at line 231 of file ping.h.

Referenced by PrintReport(), and Receive().

◆ m_reportPrinted

bool ns3::Ping::m_reportPrinted {false}
private

True if the report has been printed already.

Definition at line 270 of file ping.h.

Referenced by PrintReport(), and StartApplication().

◆ m_reportTrace

TracedCallback<const PingReport&> ns3::Ping::m_reportTrace
private

TracedCallback for final ping report.

Definition at line 227 of file ping.h.

Referenced by GetTypeId(), and PrintReport().

◆ m_routers

std::vector<Ipv6Address> ns3::Ping::m_routers
private

Routers addresses for IPv6 routing type 0.

Definition at line 277 of file ping.h.

Referenced by Send(), and SetRouters().

◆ m_rttTrace

TracedCallback<uint16_t, Time> ns3::Ping::m_rttTrace
private

TracedCallback for RTT samples.

Definition at line 223 of file ping.h.

Referenced by GetTypeId(), and Receive().

◆ m_sent

std::vector<EchoRequestData> ns3::Ping::m_sent
private

All sent but not answered packets. Map icmp seqno -> when sent, acked at least once.

Definition at line 263 of file ping.h.

Referenced by Receive(), Send(), and StartApplication().

◆ m_seq

uint16_t ns3::Ping::m_seq {0}
private

ICMP ECHO sequence number.

Definition at line 219 of file ping.h.

Referenced by PrintReport(), and Send().

◆ m_size

uint32_t ns3::Ping::m_size {56}
private

Specifies the number of data bytes to be sent.

The default is 56, which translates into 64 ICMP data bytes when combined with the 8 bytes of ICMP header data.

Definition at line 213 of file ping.h.

Referenced by GetTypeId(), Send(), and StartApplication().

◆ m_socket

Ptr<Socket> ns3::Ping::m_socket
private

The socket we send packets from.

Definition at line 215 of file ping.h.

Referenced by DoDispose(), Receive(), Send(), StartApplication(), and StopApplication().

◆ m_started

Time ns3::Ping::m_started
private

Start time to report total ping time.

Definition at line 235 of file ping.h.

Referenced by PrintReport(), and StartApplication().

◆ m_timeout

Time ns3::Ping::m_timeout {Seconds(1)}
private

Time to wait for a response, in seconds.

The option affects only timeout in absence of any responses, otherwise ping waits for two RTTs

Definition at line 268 of file ping.h.

Referenced by GetTypeId(), and Send().

◆ m_tos

uint8_t ns3::Ping::m_tos
private

The Type of Service carried by ICMP ECHOs.

Definition at line 217 of file ping.h.

Referenced by GetTypeId(), and Send().

◆ m_txTrace

TracedCallback<uint16_t, Ptr<Packet> > ns3::Ping::m_txTrace
private

Callbacks for tracing the packet Tx events.

Definition at line 221 of file ping.h.

Referenced by GetTypeId(), and Send().

◆ m_useIpv6

bool ns3::Ping::m_useIpv6 {false}
private

Use IPv4 (false) or IPv6 (true)

Definition at line 272 of file ping.h.

Referenced by Send(), and StartApplication().

◆ m_verbose

VerboseMode ns3::Ping::m_verbose {VerboseMode::VERBOSE}
private

Variable to stor verbose mode.

Definition at line 229 of file ping.h.

Referenced by GetTypeId(), PrintReport(), Receive(), and StartApplication().


The documentation for this class was generated from the following files: