UDP datagram receiver with common command line options. More...

#include <tsUDPReceiver.h>

Inheritance diagram for ts::UDPReceiver:

[legend]

Collaboration diagram for ts::UDPReceiver:

[legend]

Public Member Functions
	UDPReceiver (Report &report=(ts::CerrReport::Instance()))
	Constructor.

bool	addMembership (const IPAddress &multicast, const IPAddress &local, const IPAddress &source=IPAddress(), Report &report=(ts::CerrReport::Instance()))
	Join a multicast group.

bool	addMembership (const IPAddress &multicast, int interface_index, const IPAddress &source=IPAddress(), Report &report=(ts::CerrReport::Instance()))
	Join a multicast group.

bool	addMembershipAll (const IPAddress &multicast, const IPAddress &source=IPAddress(), Report &report=(ts::CerrReport::Instance()))
	Join a multicast group.

bool	addMembershipDefault (const IPAddress &multicast, const IPAddress &source=IPAddress(), Report &report=(ts::CerrReport::Instance()))
	Join a multicast group.

bool	bind (const IPSocketAddress &addr, Report &report=(ts::CerrReport::Instance()))
	Bind to a local address and port.

virtual bool	close (Report &report=(ts::CerrReport::Instance())) override
	Close the socket.

bool	dropMembership (Report &report=(ts::CerrReport::Instance()))
	Drop all multicast membership requests, including source-specific multicast.

IP	generation () const
	Get the IP generation with which the socket was open.

IPSocketAddress	getDefaultDestination () const
	Get the default destination address and port for outgoing messages.

bool	getLocalAddress (IPSocketAddress &addr, Report &report=(ts::CerrReport::Instance()))
	Get local socket address.

SysSocketType	getSocket () const
	Get the underlying socket device handle (use with care).

bool	isOpen () const
	Check if socket is open.

virtual bool	open (IP gen, Report &report=(ts::CerrReport::Instance())) override
	Open the socket.

bool	open (Report &report=(ts::CerrReport::Instance()))
	Open the UDP receiver.

const UDPReceiverArgs &	parameters () const
	Get current UDP reception parameters.

virtual bool	receive (void data, size_t max_size, size_t &ret_size, IPSocketAddress &sender, IPSocketAddress &destination, const AbortInterface abort=nullptr, Report &report=(ts::CerrReport::Instance()), cn::microseconds *timestamp=nullptr) override
	Receive a message.

bool	reusePort (bool reuse_port, Report &report=(ts::CerrReport::Instance()))
	Set the "reuse port" option.

virtual bool	send (const void *data, size_t size, const IPSocketAddress &destination, Report &report=(ts::CerrReport::Instance()))
	Send a message to a destination address and port.

virtual bool	send (const void *data, size_t size, Report &report=(ts::CerrReport::Instance()))
	Send a message to the default destination address and port.

bool	setBroadcast (bool on, Report &report=(ts::CerrReport::Instance()))
	Enable or disable the broadcast option.

bool	setBroadcastIfRequired (const IPAddress destination, Report &report=(ts::CerrReport::Instance()))
	Enable or disable the broadcast option, based on an IP address.

bool	setDefaultDestination (const IPSocketAddress &addr, Report &report=(ts::CerrReport::Instance()))
	Set a default destination address and port for outgoing messages.

bool	setDefaultDestination (const UString &name, Report &report=(ts::CerrReport::Instance()))
	Set a default destination address and port for outgoing messages.

bool	setMulticastLoop (bool on, Report &report=(ts::CerrReport::Instance()))
	Set the multicast loop option.

bool	setOutgoingMulticast (const IPAddress &addr, Report &report=(ts::CerrReport::Instance()))
	Set the outgoing local interface for multicast messages.

bool	setOutgoingMulticast (const UString &name, Report &report=(ts::CerrReport::Instance()))
	Set the outgoing local interface for multicast messages.

void	setParameters (const UDPReceiverArgs &args)
	Set UDP reception parameters.

bool	setReceiveBufferSize (size_t size, Report &report=(ts::CerrReport::Instance()))
	Set the receive buffer size.

bool	setReceiveTimeout (cn::milliseconds timeout, Report &report=(ts::CerrReport::Instance()))
	Set the receive timeout.

void	setReceiveTimeoutArg (cn::milliseconds timeout)
	Get reception timeout in reception parameters.

bool	setReceiveTimestamps (bool on, Report &report=(ts::CerrReport::Instance()))
	Enable or disable the generation of receive timestamps.

bool	setSendBufferSize (size_t size, Report &report=(ts::CerrReport::Instance()))
	Set the send buffer size.

bool	setTOS (int tos, Report &report=(ts::CerrReport::Instance()))
	Set the Type Of Service (TOS) or Traffic Class (IPv6) option.

bool	setTTL (int ttl, bool multicast, Report &report=(ts::CerrReport::Instance()))
	Set the Time To Live (TTL) option.

bool	setTTL (int ttl, Report &report=(ts::CerrReport::Instance()))
	Set the Time To Live (TTL) option.

Protected Member Functions
bool	convert (IPAddress &addr, Report &report) const
	Convert an IP address to make it compatible with the socket IP generation.

bool	createSocket (IP gen, int type, int protocol, Report &report)
	Create the socket.

virtual void	declareOpened (SysSocketType sock, Report &report)
	Set an open socket descriptor from a subclass.

Detailed Description

UDP datagram receiver with common command line options.

Constructor & Destructor Documentation

◆ UDPReceiver()

ts::UDPReceiver::UDPReceiver ( Report & report = (ts::CerrReport::Instance()) )

inlineexplicit

Constructor.

Parameters

[in,out] report Where to report error.

Member Function Documentation

◆ setParameters()

void ts::UDPReceiver::setParameters ( const UDPReceiverArgs & args )

inline

Set UDP reception parameters.

Must be done once before open().

Parameters

[in] args UDP reception parameters.

◆ parameters()

const UDPReceiverArgs & ts::UDPReceiver::parameters ( ) const

inline

Get current UDP reception parameters.

Returns: A constant reference to the current UDP reception parameters.

◆ setReceiveTimeoutArg()

void ts::UDPReceiver::setReceiveTimeoutArg ( cn::milliseconds timeout )

Get reception timeout in reception parameters.

Parameters

[in] timeout Receive timeout in milliseconds. No timeout if zero or negative.

◆ open() [1/2]

bool ts::UDPReceiver::open ( Report & report = (ts::CerrReport::Instance()) )

Open the UDP receiver.

Parameters

[in,out] report Where to report error.

Returns: True on success, false on error.

◆ open() [2/2]

virtual bool ts::UDPReceiver::open	(	IP	gen,
		Report &	report = `(ts::CerrReport::Instance())`
	)

overridevirtual

Open the socket.

Parameters

[in]	gen	IP generation, IPv4 or IPv6. If set to IP::Any, open an IPv6 socket (IPv4 connections allowed).
[in,out]	report	Where to report error.

Returns: True on success, false on error.

Reimplemented from ts::UDPSocket.

◆ receive()

virtual bool ts::UDPReceiver::receive	(	void *	data,
		size_t	max_size,
		size_t &	ret_size,
		IPSocketAddress &	sender,
		IPSocketAddress &	destination,
		const AbortInterface *	abort = `nullptr`,
		Report &	report = `(ts::CerrReport::Instance())`,
		cn::microseconds *	timestamp = `nullptr`
	)

overridevirtual

Receive a message.

Parameters

[out]	data	Address of the buffer for the received message.
[in]	max_size	Size in bytes of the reception buffer.
[out]	ret_size	Size in bytes of the received message. Will never be larger than max_size.
[out]	sender	Socket address of the sender.
[out]	destination	Socket address of the packet destination. Can be useful to check in multicast packets.
[in]	abort	If non-zero, invoked when I/O is interrupted (in case of user-interrupt, return, otherwise retry).
[in,out]	report	Where to report error.
[out]	timestamp	When not null, return the receive timestamp in micro-seconds. Use setReceiveTimestamps() to enable the generation of receive timestamps. If the returned value is negative, no timestamp is available.

Returns: True on success, false on error.

Reimplemented from ts::UDPSocket.

◆ bind()

bool ts::UDPSocket::bind	(	const IPSocketAddress &	addr,
		Report &	report = `(ts::CerrReport::Instance())`
	)

inherited

Bind to a local address and port.

The IP address part of the socket address must one of:

IPAddress::AnyAddress4. Any local interface may be used to send or receive UDP datagrams. For each outgoing packet, the actual interface is selected by the kernel based on the routing rules. Incoming UDP packets for the selected port will be accepted from any local interface.
The IP address of an interface of the local system. Outgoing packets will be unconditionally sent through this interface. Incoming UDP packets for the selected port will be accepted only when they arrive through the selected interface.

Special note for receiving multicast on most Unix systems (at least Linux and macOS): The IP address shall be either AnyAddress4 or the multicast group address. Do not specify a local address to receive multicast on Unix.

The port number part of the socket address must be one of:

IPSocketAddress::AnyPort. The socket is bound to an arbitrary unused local UDP port.
A specific port number. If this UDP port is already bound by another local UDP socket, the bind operation fails, unless the "reuse port" option has already been set.

Parameters

[in]	addr	Local socket address to bind to.
[in,out]	report	Where to report error.

Returns: True on success, false on error.

◆ setDefaultDestination() [1/2]

bool ts::UDPSocket::setDefaultDestination	(	const IPSocketAddress &	addr,
		Report &	report = `(ts::CerrReport::Instance())`
	)

inherited

Set a default destination address and port for outgoing messages.

There are two versions of the send() method. One of them explicitly specifies the destination of the packet to send. The second version does not specify a destination; the packet is sent to the default destination.

Parameters

[in]	addr	Socket address of the destination. Both address and port are mandatory in the socket address, they cannot be set to IPAddress::AnyAddress4 or IPSocketAddress::AnyPort.
[in,out]	report	Where to report error.

Returns: True on success, false on error.

◆ setDefaultDestination() [2/2]

bool ts::UDPSocket::setDefaultDestination	(	const UString &	name,
		Report &	report = `(ts::CerrReport::Instance())`
	)

inherited

Set a default destination address and port for outgoing messages.

There are two versions of the send() method. One of them explicitly specifies the destination of the packet to send. The second version does not specify a destination; the packet is sent to the default destination.

Parameters

[in]	name	A string describing the socket address of the destination. See IPSocketAddress::resolve() for a description of the expected string format.
[in,out]	report	Where to report error.

Returns: True on success, false on error.

◆ getDefaultDestination()

IPSocketAddress ts::UDPSocket::getDefaultDestination ( ) const

inlineinherited

Get the default destination address and port for outgoing messages.

Returns: The default destination address and port for outgoing messages.

◆ setOutgoingMulticast() [1/2]

bool ts::UDPSocket::setOutgoingMulticast	(	const IPAddress &	addr,
		Report &	report = `(ts::CerrReport::Instance())`
	)

inherited

Set the outgoing local interface for multicast messages.

Parameters

[in]	addr	IP address of a local interface.
[in,out]	report	Where to report error.

Returns: True on success, false on error.

◆ setOutgoingMulticast() [2/2]

bool ts::UDPSocket::setOutgoingMulticast	(	const UString &	name,
		Report &	report = `(ts::CerrReport::Instance())`
	)

inherited

Set the outgoing local interface for multicast messages.

Parameters

[in]	name	A string describing the IP address of a local interface. See IPAddress::resolve() for a description of the expected string format.
[in,out]	report	Where to report error.

Returns: True on success, false on error.

◆ setTTL() [1/2]

bool ts::UDPSocket::setTTL	(	int	ttl,
		bool	multicast,
		Report &	report = `(ts::CerrReport::Instance())`
	)

inherited

Set the Time To Live (TTL) option.

Parameters

[in]	ttl	The TTL value, ie. the maximum number of "hops" between routers before an IP packet is dropped.
[in]	multicast	When true, set the multicast TTL option. When false, set the unicast TTL option.
[in,out]	report	Where to report error.

Returns: True on success, false on error.

◆ setTTL() [2/2]

bool ts::UDPSocket::setTTL	(	int	ttl,
		Report &	report = `(ts::CerrReport::Instance())`
	)

inlineinherited

Set the Time To Live (TTL) option.

If the default destination is a multicast address, set the multicast TTL option. Otherwise, set the unicast TTL option.

Parameters

[in]	ttl	The TTL value, ie. the maximum number of "hops" between routers before an IP packet is dropped.
[in,out]	report	Where to report error.

Returns: True on success, false on error.

◆ setTOS()

bool ts::UDPSocket::setTOS	(	int	tos,
		Report &	report = `(ts::CerrReport::Instance())`
	)

inherited

Set the Type Of Service (TOS) or Traffic Class (IPv6) option.

The interpretation of the tos parameter depends in the IP generation. With IPv4, this is a "type of service" value. With IPv6, this is a "traffic class" value.

Note that correct support for this option depends on the operating system. Typically, it never worked correctly on Windows.

Parameters

[in]	tos	The type of service (IPv4) or traffic class (IPv6) value.
[in,out]	report	Where to report error.

Returns: True on success, false on error.

◆ setMulticastLoop()

bool ts::UDPSocket::setMulticastLoop	(	bool	on,
		Report &	report = `(ts::CerrReport::Instance())`
	)

inherited

Set the multicast loop option.

By default, the multicast packets are looped back on local interfaces. Use this to disable multicast loopback.

Parameters

[in]	on	It true, multicast loopback is on. When false, it is off.
[in,out]	report	Where to report error.

Returns: True on success, false on error.

◆ setReceiveTimestamps()

bool ts::UDPSocket::setReceiveTimestamps	(	bool	on,
		Report &	report = `(ts::CerrReport::Instance())`
	)

inherited

Enable or disable the generation of receive timestamps.

When enabled, each received UDP packets comes with a time stamp (see receive()). When possible, a hardware timestamp from the NIC is received. Otherwise, a software timestamp is generated by the kernel.

When enabled, this option is a @æ request, not a requirement. Currently, this option is supported on Linux only. It is ignored on other systems.

Parameters

[in]	on	If true, receive timestamps are activated on the socket. Otherwise, they are disabled.
[in,out]	report	Where to report error.

Returns: True on success, false on error.

◆ setBroadcast()

bool ts::UDPSocket::setBroadcast	(	bool	on,
		Report &	report = `(ts::CerrReport::Instance())`
	)

inherited

Enable or disable the broadcast option.

Parameters

[in]	on	If true, broadcast is activated on the socket. Otherwise, it is disabled.
[in,out]	report	Where to report error.

Returns: True on success, false on error.

◆ setBroadcastIfRequired()

bool ts::UDPSocket::setBroadcastIfRequired	(	const IPAddress	destination,
		Report &	report = `(ts::CerrReport::Instance())`
	)

inherited

Enable or disable the broadcast option, based on an IP address.

Parameters

[in]	destination	An hypothetical destination address. If this address is the broadcast address of a local interface, the broadcast option is set. Otherwise, the broadcast option is unchanged.
[in,out]	report	Where to report error.

Returns: True on success, false on error.

◆ addMembership() [1/2]

bool ts::UDPSocket::addMembership	(	const IPAddress &	multicast,
		const IPAddress &	local,
		const IPAddress &	source = `IPAddress()`,
		Report &	report = `(ts::CerrReport::Instance())`
	)

inlineinherited

Join a multicast group.

This method indicates that the application wishes to receive multicast packets which are sent to a specific multicast address. Specifying a non-default source address, source-specific multicast (SSM) is used. Note that source-specific multicast exists on IPv4 only.

Parameters

[in]	multicast	Multicast IP address to listen to.
[in]	local	IP address of a local interface on which to listen. If set to IPAddress::AnyAddress4, the application lets the system selects the appropriate local interface.
[in]	source	Source address for SSM. Ignored on IPv6 socket.
[in,out]	report	Where to report error.

Returns: True on success, false on error.

◆ addMembership() [2/2]

bool ts::UDPSocket::addMembership	(	const IPAddress &	multicast,
		int	interface_index,
		const IPAddress &	source = `IPAddress()`,
		Report &	report = `(ts::CerrReport::Instance())`
	)

inlineinherited

Join a multicast group.

This method indicates that the application wishes to receive multicast packets which are sent to a specific multicast address. Specifying a non-default source address, source-specific multicast (SSM) is used. Note that source-specific multicast exists on IPv4 only.

Parameters

[in]	multicast	Multicast IP address to listen to.
[in]	interface_index	Index of a local interface on which to listen. If set to zero, the application lets the system selects the appropriate local interface.
[in]	source	Source address for SSM. Ignored on IPv6 socket.
[in,out]	report	Where to report error.

Returns: True on success, false on error.

◆ addMembershipAll()

bool ts::UDPSocket::addMembershipAll	(	const IPAddress &	multicast,
		const IPAddress &	source = `IPAddress()`,
		Report &	report = `(ts::CerrReport::Instance())`
	)

inherited

Join a multicast group.

This method indicates that the application wishes to receive multicast packets which are sent to a specific multicast address. Specifying a non-default source address, source-specific multicast (SSM) is used.

Using this method, the application listens on all local interfaces.

Parameters

[in]	multicast	Multicast IP address to listen to.
[in]	source	Source address for SSM.
[in,out]	report	Where to report error.

Returns: True on success, false on error.

◆ addMembershipDefault()

bool ts::UDPSocket::addMembershipDefault	(	const IPAddress &	multicast,
		const IPAddress &	source = `IPAddress()`,
		Report &	report = `(ts::CerrReport::Instance())`
	)

inlineinherited

Join a multicast group.

This method indicates that the application wishes to receive multicast packets which are sent to a specific multicast address. Specifying a non-default source address, source-specific multicast (SSM) is used.

Using this method, the application lets the system selects the appropriate local interface.

Parameters

[in]	multicast	Multicast IP address to listen to.
[in]	source	Source address for SSM.
[in,out]	report	Where to report error.

Returns: True on success, false on error.

◆ dropMembership()

bool ts::UDPSocket::dropMembership ( Report & report = (ts::CerrReport::Instance()) )

inherited

Drop all multicast membership requests, including source-specific multicast.

Parameters

[in,out] report Where to report error.

Returns: True on success, false on error.

◆ send() [1/2]

virtual bool ts::UDPSocket::send	(	const void *	data,
		size_t	size,
		const IPSocketAddress &	destination,
		Report &	report = `(ts::CerrReport::Instance())`
	)

virtualinherited

Send a message to a destination address and port.

Parameters

[in]	data	Address of the message to send.
[in]	size	Size in bytes of the message to send.
[in]	destination	Socket address of the destination. Both address and port are mandatory in the socket address, they cannot be set to IPAddress::AnyAddress4 or IPSocketAddress::AnyPort.
[in,out]	report	Where to report error.

Returns: True on success, false on error.

◆ send() [2/2]

virtual bool ts::UDPSocket::send	(	const void *	data,
		size_t	size,
		Report &	report = `(ts::CerrReport::Instance())`
	)

virtualinherited

Send a message to the default destination address and port.

Parameters

[in]	data	Address of the message to send.
[in]	size	Size in bytes of the message to send.
[in,out]	report	Where to report error.

Returns: True on success, false on error.

◆ close()

virtual bool ts::UDPSocket::close ( Report & report = (ts::CerrReport::Instance()) )

overridevirtualinherited

Close the socket.

Parameters

[in,out] report Where to report error.

Returns: True on success, false on error.

Reimplemented from ts::Socket.

◆ isOpen()

bool ts::Socket::isOpen ( ) const

inlineinherited

Check if socket is open.

Returns: True if socket is open.

◆ generation()

IP ts::Socket::generation ( ) const

inlineinherited

Get the IP generation with which the socket was open.

Returns: The IP generation used to open the socket. Never IP::Any.

◆ setSendBufferSize()

bool ts::Socket::setSendBufferSize	(	size_t	size,
		Report &	report = `(ts::CerrReport::Instance())`
	)

inherited

Set the send buffer size.

Parameters

[in]	size	Send buffer size in bytes.
[in,out]	report	Where to report error.

Returns: True on success, false on error.

◆ setReceiveBufferSize()

bool ts::Socket::setReceiveBufferSize	(	size_t	size,
		Report &	report = `(ts::CerrReport::Instance())`
	)

inherited

Set the receive buffer size.

Parameters

[in]	size	Receive buffer size in bytes.
[in,out]	report	Where to report error.

Returns: True on success, false on error.

◆ setReceiveTimeout()

bool ts::Socket::setReceiveTimeout	(	cn::milliseconds	timeout,
		Report &	report = `(ts::CerrReport::Instance())`
	)

inherited

Set the receive timeout.

Parameters

[in]	timeout	Receive timeout in milliseconds. If negative, receive timeout is not used.
[in,out]	report	Where to report error.

Returns: True on success, false on error.

◆ reusePort()

bool ts::Socket::reusePort	(	bool	reuse_port,
		Report &	report = `(ts::CerrReport::Instance())`
	)

inherited

Set the "reuse port" option.

Parameters

[in]	reuse_port	If true, the socket is allowed to reuse a local UDP port which is already bound.
[in,out]	report	Where to report error.

Returns: True on success, false on error.

◆ getLocalAddress()

bool ts::Socket::getLocalAddress	(	IPSocketAddress &	addr,
		Report &	report = `(ts::CerrReport::Instance())`
	)

inherited

Get local socket address.

Parameters

[out]	addr	Local socket address of the connection.
[in,out]	report	Where to report error.

Returns: True on success, false on error.

◆ getSocket()

SysSocketType ts::Socket::getSocket ( ) const

inlineinherited

Get the underlying socket device handle (use with care).

This method is reserved for low-level operations and should not be used by normal applications.

Returns: The underlying socket system device handle or file descriptor. Return SYS_SOCKET_INVALID if the socket is not open.

◆ createSocket()

bool ts::Socket::createSocket	(	IP	gen,
		int	type,
		int	protocol,
		Report &	report
	)

protectedinherited

Create the socket.

Parameters

[in]	gen	IP generation.
[in]	type	Socket type: SOCK_STREAM, SOCK_DGRAM
[in]	protocol	Socket protocol: IPPROTO_TCP, IPPROTO_UDP
[in,out]	report	Where to report error.

Returns: True on success, false on error.

See also: open(ge, Report&)

◆ declareOpened()

virtual void ts::Socket::declareOpened	(	SysSocketType	sock,
		Report &	report
	)

protectedvirtualinherited

Set an open socket descriptor from a subclass.

This method is used by a server to declare that a client socket has just become opened.

Parameters

[in]	sock	New socket descriptor.
[in,out]	report	Where to report error.

Reimplemented in ts::TCPSocket.

◆ convert()

bool ts::Socket::convert	(	IPAddress &	addr,
		Report &	report
	)		const

protectedinherited

Convert an IP address to make it compatible with the socket IP generation.

Parameters

	addr	[in,out] The address to convert.
[in,out]	report	Where to report error.

Returns: True on success, false on error.

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

tsUDPReceiver.h

Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ UDPReceiver()

Member Function Documentation

◆ setParameters()

◆ parameters()

◆ setReceiveTimeoutArg()

◆ open() [1/2]

◆ open() [2/2]

◆ receive()

◆ bind()

◆ setDefaultDestination() [1/2]

◆ setDefaultDestination() [2/2]

◆ getDefaultDestination()

◆ setOutgoingMulticast() [1/2]

◆ setOutgoingMulticast() [2/2]

◆ setTTL() [1/2]

◆ setTTL() [2/2]

◆ setTOS()

◆ setMulticastLoop()

◆ setReceiveTimestamps()

◆ setBroadcast()

◆ setBroadcastIfRequired()

◆ addMembership() [1/2]

◆ addMembership() [2/2]

◆ addMembershipAll()

◆ addMembershipDefault()

◆ dropMembership()

◆ send() [1/2]

◆ send() [2/2]

◆ close()

◆ isOpen()

◆ generation()

◆ setSendBufferSize()

◆ setReceiveBufferSize()

◆ setReceiveTimeout()

◆ reusePort()

◆ getLocalAddress()

◆ getSocket()

◆ createSocket()

◆ declareOpened()

◆ convert()