join::Ping Class Reference

ICMP echo client. More...

#include <ping.hpp>

Inheritance diagram for join::Ping:

Collaboration diagram for join::Ping:

Classes
struct	PendingRequest
	pending echo request. More...

Public Types
using	PingNotify = std::function<void (const PingStats&)>
	notification callback definition.

Public Member Functions
	Ping (int ttl=_defaultTtl, Reactor &reactor=ReactorThread::reactor())
	create the Ping instance.
	Ping (const std::string &device, int ttl=_defaultTtl, Reactor &reactor=ReactorThread::reactor())
	create the Ping instance bound to the given device.
	Ping (const Ping &other)=delete
	create instance by copy.
Ping &	operator= (const Ping &other)=delete
	assign instance by copy.
	Ping (Ping &&other)=delete
	create instance by move.
Ping &	operator= (Ping &&other)=delete
	assign instance by move.
	~Ping ()=default
	destroy the Ping instance.
int	ping (const IpAddress &source, const std::string &destination, int size=_defaultSize, int count=1, std::chrono::milliseconds interval=std::chrono::milliseconds(500), int df=IP_PMTUDISC_DONT, std::chrono::milliseconds timeout=std::chrono::seconds(5))
	send echo requests to the given destination.
int	pathMtu (const IpAddress &source, const std::string &destination, std::chrono::milliseconds timeout=std::chrono::seconds(5))
	discover the path MTU towards the given destination.
int	trace (const IpAddress &source, const std::string &destination, int maxHops=_defaultMaxHops, int probes=_defaultProbes, int size=_defaultSize, int df=IP_PMTUDISC_DONT, std::chrono::milliseconds timeout=std::chrono::seconds(5))
	discover the route towards the given destination.
Public Member Functions inherited from join::EventHandler
	EventHandler ()=default
	create instance.
	EventHandler (const EventHandler &other)=default
	copy constructor.
EventHandler &	operator= (const EventHandler &other)=default
	copy assignment operator.
	EventHandler (EventHandler &&other)=default
	move constructor.
EventHandler &	operator= (EventHandler &&other)=default
	move assignment operator.
virtual	~EventHandler ()=default
	destroy instance.

Static Public Member Functions
static int	ping4 (const std::string &destination, int size=_defaultSize, int count=1, std::chrono::milliseconds interval=std::chrono::milliseconds(500), int ttl=_defaultTtl, int df=IP_PMTUDISC_DONT, std::chrono::milliseconds timeout=std::chrono::seconds(5))
	send echo requests to the given destination using the AF_INET address family.
static int	ping6 (const std::string &destination, int size=_defaultSize, int count=1, std::chrono::milliseconds interval=std::chrono::milliseconds(500), int ttl=_defaultTtl, int df=IP_PMTUDISC_DONT, std::chrono::milliseconds timeout=std::chrono::seconds(5))
	send echo requests to the given destination using the AF_INET6 address family.
static const char *	message (int family, uint8_t type, uint8_t code) noexcept
	get the human readable form of an ICMP type and code pair.

Public Attributes
PingNotify	onStart
	callback called when a sequence is going to start.
PingNotify	onSuccess
	callback called when an echo request is answered.
PingNotify	onFailure
	callback called when an echo request failed.
PingNotify	onHop
	callback called when all the probes of a hop have been sent.
PingNotify	onStop
	callback called when a sequence is going to stop.

Protected Member Functions
int	open (Icmp::Socket &socket, PingStats &stats)
	resolve the destination then open and register the socket used by a sequence.
void	close (Icmp::Socket &socket)
	unregister and close the socket used by a sequence.
int	echo (Icmp::Socket &socket, PingStats &stats, std::chrono::milliseconds timeout)
	send an echo request through the given socket and wait for its answer.
void	onReadable (int fd) override final
	method called when data are ready to be read.
void	onError (int fd) override final
	method called when an error occurred.
Protected Member Functions inherited from join::EventHandler
virtual void	onEvent (int fd, uint32_t revents)
	method called when events are reported on handle.
virtual void	onWriteable (int fd)
	method called when data are ready to be written on handle.
virtual void	onClose (int fd)
	method called when handle was closed by the peer.

Static Protected Member Functions
static bool	isFatal (const PingStats &stats, uint32_t transmitted)
	check if the last failure occurred before the request could be transmitted.
static int	headerSize (const PingStats &stats)
	get the number of header bytes added to the data of an echo request.
static int	setFilter (Icmp::Socket &socket, PingStats &stats)
	restrict the ICMP messages delivered to the given socket.
static void	notify (const PingNotify &function, const PingStats &stats)
	safe way to notify sequence events.
static int	fail (PingStats &stats, const std::error_code &code, const std::string &error)
	set the outcome of the last request in the statistics.

Protected Attributes
std::unordered_map< uint16_t, std::unique_ptr< PendingRequest > >	_pending
	pending echo requests indexed by sequence number.
Mutex	_syncMutex
	mutex for synchronous operations.
std::unique_ptr< char[]>	_buffer
	receive buffer.
const std::string	_device
	device name to bind to.
const uint16_t	_identity
	echo request identifier.
uint16_t	_sequence = 0
	sequence number of the last echo request sent.
const int	_ttl
	default time to live.
Reactor &	_reactor
	event loop reactor.

Static Protected Attributes
static constexpr int	_defaultTtl = 60
	default time to live.
static constexpr int	_defaultSize = 56
	default number of data bytes sent in each echo request.
static constexpr int	_defaultMaxHops = 30
	default maximum number of hops probed by trace.
static constexpr int	_defaultProbes = 3
	default number of echo requests sent per hop by trace.
static constexpr int	_icmpHeaderSize = 8
	ICMP header size.
static constexpr size_t	_bufferSize = 65535
	receive buffer size.
static constexpr int	_maxMtuProbes = 30
	maximum number of probes sent by pathMtu.
static constexpr int	_retryDelay = 200
	delay in milliseconds applied before retrying a request that could not be queued.
static constexpr int	_dumpSize = 64
	maximum number of bytes dumped in debug builds.

Detailed Description

ICMP echo client.

Member Typedef Documentation

PingNotify

using join::Ping::PingNotify = std::function<void (const PingStats&)>

notification callback definition.

Constructor & Destructor Documentation

Ping() [1/4]

Ping::Ping ( int ttl = _defaultTtl, Reactor & reactor = ReactorThread::reactor () )

explicit

create the Ping instance.

Parameters

ttl	maximum number of IP routers the echo requests can go through.
reactor	reactor instance.

Ping() [2/4]

Ping::Ping ( const std::string & device, int ttl = _defaultTtl, Reactor & reactor = ReactorThread::reactor () )

explicit

create the Ping instance bound to the given device.

Parameters

device	device name to bind to.
ttl	maximum number of IP routers the echo requests can go through.
reactor	reactor instance.

Ping() [3/4]

join::Ping::Ping ( const Ping & other )

delete

create instance by copy.

Parameters

other

other object to copy.

Ping() [4/4]

join::Ping::Ping ( Ping && other )

delete

create instance by move.

Parameters

other

other object to move.

~Ping()

join::Ping::~Ping ( )

default

destroy the Ping instance.

Member Function Documentation

close()

void Ping::close ( Icmp::Socket & socket )

protected

unregister and close the socket used by a sequence.

Parameters

socket

socket to close.

echo()

int Ping::echo ( Icmp::Socket & socket, PingStats & stats, std::chrono::milliseconds timeout )

protected

send an echo request through the given socket and wait for its answer.

Parameters

socket	socket the echo request is sent through.
stats	sequence statistics, holds the request settings and receives the outcome.
timeout	answer timeout.

Returns

0 if the destination answered, -1 otherwise.

fail()

int Ping::fail ( PingStats & stats, const std::error_code & code, const std::string & error )

staticprotected

set the outcome of the last request in the statistics.

Parameters

stats	sequence statistics.
code	error code.
error	human readable error message.

Returns

-1.

headerSize()

int Ping::headerSize ( const PingStats & stats )

staticprotected

get the number of header bytes added to the data of an echo request.

Parameters

stats

sequence statistics, holds the resolved destination.

Returns

IP and ICMP header size.

isFatal()

bool Ping::isFatal ( const PingStats & stats, uint32_t transmitted )

staticprotected

check if the last failure occurred before the request could be transmitted.

Parameters

stats	sequence statistics.
transmitted	number of requests sent before the last attempt.

Returns

true if nothing left the host and retrying cannot succeed.

message()

const char * Ping::message ( int family, uint8_t type, uint8_t code )

staticnoexcept

get the human readable form of an ICMP type and code pair.

Parameters

family	address family.
type	ICMP message type.
code	ICMP message code.

Returns

human readable message.

notify()

void Ping::notify ( const PingNotify & function, const PingStats & stats )

staticprotected

safe way to notify sequence events.

Parameters

function	callback to call.
stats	sequence statistics.

onError()

void Ping::onError ( int fd )

finaloverrideprotectedvirtual

method called when an error occurred.

Parameters

fd	file descriptor.

Reimplemented from join::EventHandler.

onReadable()

void Ping::onReadable ( int fd )

finaloverrideprotectedvirtual

method called when data are ready to be read.

Parameters

fd	file descriptor.

Reimplemented from join::EventHandler.

open()

int Ping::open ( Icmp::Socket & socket, PingStats & stats )

protected

resolve the destination then open and register the socket used by a sequence.

Parameters

socket	socket to open.
stats	sequence statistics.

Returns

0 on success, -1 on failure.

operator=() [1/2]

Ping & join::Ping::operator= ( const Ping & other )

delete

assign instance by copy.

Parameters

other

other object to copy.

Returns

a reference of the current object.

operator=() [2/2]

Ping & join::Ping::operator= ( Ping && other )

delete

assign instance by move.

Parameters

other

other object to move.

Returns

a reference of the current object.

pathMtu()

int Ping::pathMtu	(	const IpAddress &	source,
		const std::string &	destination,
		std::chrono::milliseconds	timeout = std::chrono::seconds (5) )

discover the path MTU towards the given destination.

Parameters

source	source address to bind to, wildcard to let the stack choose.
destination	destination address or host name.
timeout	answer timeout.

Returns

the path MTU on success, -1 on failure.

ping()

int Ping::ping	(	const IpAddress &	source,
		const std::string &	destination,
		int	size = _defaultSize,
		int	count = 1,
		std::chrono::milliseconds	interval = std::chrono::milliseconds (500),
		int	df = IP_PMTUDISC_DONT,
		std::chrono::milliseconds	timeout = std::chrono::seconds (5) )

send echo requests to the given destination.

Parameters

source	source address to bind to, wildcard to let the stack choose.
destination	destination address or host name.
size	number of data bytes to send in each echo request.
count	number of echo requests to send.
interval	interval between two echo requests.
df	set the don't fragment flag.
timeout	answer timeout.

Returns

the number of answered echo requests.

ping4()

int Ping::ping4 ( const std::string & destination, int size = _defaultSize, int count = 1, std::chrono::milliseconds interval = std::chrono::milliseconds (500), int ttl = _defaultTtl, int df = IP_PMTUDISC_DONT, std::chrono::milliseconds timeout = std::chrono::seconds (5) )

static

send echo requests to the given destination using the AF_INET address family.

Parameters

destination	destination address or host name.
size	number of data bytes to send in each echo request.
count	number of echo requests to send.
interval	interval between two echo requests.
ttl	maximum number of IP routers the echo requests can go through.
df	set the don't fragment flag.
timeout	answer timeout.

Returns

the number of answered echo requests.

ping6()

int Ping::ping6 ( const std::string & destination, int size = _defaultSize, int count = 1, std::chrono::milliseconds interval = std::chrono::milliseconds (500), int ttl = _defaultTtl, int df = IP_PMTUDISC_DONT, std::chrono::milliseconds timeout = std::chrono::seconds (5) )

static

send echo requests to the given destination using the AF_INET6 address family.

Parameters

destination	destination address or host name.
size	number of data bytes to send in each echo request.
count	number of echo requests to send.
interval	interval between two echo requests.
ttl	maximum number of IP routers the echo requests can go through.
df	set the don't fragment flag.
timeout	answer timeout.

Returns

the number of answered echo requests.

setFilter()

int Ping::setFilter ( Icmp::Socket & socket, PingStats & stats )

staticprotected

restrict the ICMP messages delivered to the given socket.

Parameters

socket	socket to set the filter on.
stats	sequence statistics, receives the outcome.

Returns

0 on success, -1 on failure.

trace()

int Ping::trace	(	const IpAddress &	source,
		const std::string &	destination,
		int	maxHops = _defaultMaxHops,
		int	probes = _defaultProbes,
		int	size = _defaultSize,
		int	df = IP_PMTUDISC_DONT,
		std::chrono::milliseconds	timeout = std::chrono::seconds (5) )

discover the route towards the given destination.

Parameters

source	source address to bind to, wildcard to let the stack choose.
destination	destination address or host name.
maxHops	maximum number of hops to probe.
probes	number of echo requests to send per hop.
size	number of data bytes to send in each echo request.
df	set the don't fragment flag, discovers the MTU of each hop.
timeout	answer timeout.

Returns

the number of hops to the destination, -1 if not reached.

Member Data Documentation

_buffer

std::unique_ptr<char[]> join::Ping::_buffer

protected

receive buffer.

_bufferSize

size_t join::Ping::_bufferSize = 65535

staticconstexprprotected

receive buffer size.

_defaultMaxHops

int join::Ping::_defaultMaxHops = 30

staticconstexprprotected

default maximum number of hops probed by trace.

_defaultProbes

int join::Ping::_defaultProbes = 3

staticconstexprprotected

default number of echo requests sent per hop by trace.

_defaultSize

int join::Ping::_defaultSize = 56

staticconstexprprotected

default number of data bytes sent in each echo request.

_defaultTtl

int join::Ping::_defaultTtl = 60

staticconstexprprotected

default time to live.

_device

const std::string join::Ping::_device

protected

device name to bind to.

_dumpSize

int join::Ping::_dumpSize = 64

staticconstexprprotected

maximum number of bytes dumped in debug builds.

_icmpHeaderSize

int join::Ping::_icmpHeaderSize = 8

staticconstexprprotected

ICMP header size.

_identity

const uint16_t join::Ping::_identity

protected

echo request identifier.

_maxMtuProbes

int join::Ping::_maxMtuProbes = 30

staticconstexprprotected

maximum number of probes sent by pathMtu.

_pending

std::unordered_map<uint16_t, std::unique_ptr<PendingRequest> > join::Ping::_pending

protected

pending echo requests indexed by sequence number.

_reactor

Reactor& join::Ping::_reactor

protected

event loop reactor.

_retryDelay

int join::Ping::_retryDelay = 200

staticconstexprprotected

delay in milliseconds applied before retrying a request that could not be queued.

_sequence

uint16_t join::Ping::_sequence = 0

protected

sequence number of the last echo request sent.

_syncMutex

Mutex join::Ping::_syncMutex

protected

mutex for synchronous operations.

_ttl

const int join::Ping::_ttl

protected

default time to live.

onFailure

PingNotify join::Ping::onFailure

callback called when an echo request failed.

onHop

PingNotify join::Ping::onHop

callback called when all the probes of a hop have been sent.

onStart

PingNotify join::Ping::onStart

callback called when a sequence is going to start.

onStop

PingNotify join::Ping::onStop

callback called when a sequence is going to stop.

onSuccess

PingNotify join::Ping::onSuccess

callback called when an echo request is answered.

---

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

• fabric/include/join/ping.hpp
• fabric/src/ping.cpp