TSDuck v3.38-3703
MPEG Transport Stream Toolkit
Loading...
Searching...
No Matches
ts::UDPReceiver Class Reference

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

#include <tsUDPReceiver.h>

Inheritance diagram for ts::UDPReceiver:
Collaboration diagram for ts::UDPReceiver:

Public Member Functions

 UDPReceiver (Report &report=(ts::CerrReport::Instance()))
 Constructor.
 
bool addMembership (const IPv4Address &multicast, const IPv4Address &local, const IPv4Address &source=IPv4Address(), Report &report=(ts::CerrReport::Instance()))
 Join a multicast group.
 
bool addMembershipAll (const IPv4Address &multicast, const IPv4Address &source=IPv4Address(), Report &report=(ts::CerrReport::Instance()))
 Join a multicast group.
 
bool addMembershipDefault (const IPv4Address &multicast, const IPv4Address &source=IPv4Address(), Report &report=(ts::CerrReport::Instance()))
 Join a multicast group.
 
bool bind (const IPv4SocketAddress &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.
 
void defineArgs (Args &args, bool with_short_options, bool destination_is_parameter, bool multiple_receivers)
 Add command line option definitions in an Args.
 
bool dropMembership (Report &report=(ts::CerrReport::Instance()))
 Drop all multicast membership requests, including source-specific multicast.
 
IPv4SocketAddress getDefaultDestination () const
 Get the default destination address and port for outgoing messages.
 
bool getLocalAddress (IPv4SocketAddress &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.
 
bool loadArgs (bool destination_is_parameter, DuckContext &duck, Args &args, size_t index=0)
 Load arguments from command line, when defineArgs() was not called on this object.
 
bool loadArgs (DuckContext &duck, Args &args, size_t index=0)
 Load arguments from command line.
 
virtual bool open (Report &report=(ts::CerrReport::Instance())) override
 Open the socket.
 
virtual bool receive (void *data, size_t max_size, size_t &ret_size, IPv4SocketAddress &sender, IPv4SocketAddress &destination, const AbortInterface *abort=nullptr, Report &report=(ts::CerrReport::Instance()), cn::microseconds *timestamp=nullptr) override
 Receive a message.
 
size_t receiverCount () const
 Get the number of receivers on the command line.
 
size_t receiverIndex () const
 Get the index of the selected receiver on the command line.
 
bool receiverSpecified () const
 Check if a UDP receiver is specified.
 
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 IPv4SocketAddress &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 IPv4Address destination, Report &report=(ts::CerrReport::Instance()))
 Enable or disable the broadcast option, based on an IP address.
 
bool setDefaultDestination (const IPv4SocketAddress &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 IPv4Address &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 IPv4SocketAddress &localAddress, bool reusePort, size_t bufferSize=0)
 Set application-specified parameters to receive unicast traffic.
 
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)
 Set reception timeout as if it comes from command line.
 
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) 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 createSocket (int domain, 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]reportWhere to report error.

Member Function Documentation

◆ defineArgs()

void ts::UDPReceiver::defineArgs ( Args args,
bool  with_short_options,
bool  destination_is_parameter,
bool  multiple_receivers 
)

Add command line option definitions in an Args.

Parameters
[in,out]argsCommand line arguments to update.
[in]with_short_optionsWhen true, define one-letter short options.
[in]destination_is_parameterWhen true, the destination [address:]port is defined as a parameter. When false, it is defined as option –ip–udp.
[in]multiple_receiversWhen true, multiple destination [address:]port are allowed.

◆ loadArgs() [1/2]

bool ts::UDPReceiver::loadArgs ( DuckContext duck,
Args args,
size_t  index = 0 
)

Load arguments from command line.

Args error indicator is set in case of incorrect arguments.

Parameters
[in,out]duckTSDuck execution context.
[in,out]argsCommand line arguments.
[in]indexWhen multiple_receivers was true in defineArgs(), specify the index of the occurence of the set of options to return. Zero designates the first occurence.
Returns
True on success, false on error in argument line.

◆ loadArgs() [2/2]

bool ts::UDPReceiver::loadArgs ( bool  destination_is_parameter,
DuckContext duck,
Args args,
size_t  index = 0 
)
inline

Load arguments from command line, when defineArgs() was not called on this object.

This version of loadArgs() is typically called when the command line syntax was defined in args using another instance of UDPReceiver. Args error indicator is set in case of incorrect arguments.

Parameters
[in]destination_is_parameterWhen true, the destination [address:]port is defined as a parameter. When false, it is defined as option –ip–udp.
[in,out]duckTSDuck execution context.
[in,out]argsCommand line arguments.
[in]indexWhen multiple_receivers was true in defineArgs(), specify the index of the occurence of the set of options to return. Zero designates the first occurence.
Returns
True on success, false on error in argument line.

◆ receiverCount()

size_t ts::UDPReceiver::receiverCount ( ) const
inline

Get the number of receivers on the command line.

Returns
The number of receivers on the command line during the last call to loadArgs().

◆ receiverIndex()

size_t ts::UDPReceiver::receiverIndex ( ) const
inline

Get the index of the selected receiver on the command line.

Returns
The number of the selected receiver on the command line during the last call to loadArgs().

◆ receiverSpecified()

bool ts::UDPReceiver::receiverSpecified ( ) const
inline

Check if a UDP receiver is specified.

When dest_as_param is false in the constructor, the UDP parameters are optional and it is legitimate to not use UDP.

Returns
True if UDP parameters are present.

◆ setParameters()

void ts::UDPReceiver::setParameters ( const IPv4SocketAddress localAddress,
bool  reusePort,
size_t  bufferSize = 0 
)

Set application-specified parameters to receive unicast traffic.

This method is used when command line parameters are not used.

Parameters
[in]localAddressOptional local address and required UDP port.
[in]reusePortReuse-port option.
[in]bufferSizeOptional socket receive buffer size.

◆ setReceiveTimeoutArg()

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

Set reception timeout as if it comes from command line.

Parameters
[in]timeoutReceive timeout in milliseconds. No timeout if zero or negative.

◆ open()

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

Open the socket.

Parameters
[in,out]reportWhere 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,
IPv4SocketAddress sender,
IPv4SocketAddress destination,
const AbortInterface abort = nullptr,
Report report = (ts::CerrReport::Instance()),
cn::microseconds *  timestamp = nullptr 
)
overridevirtual

Receive a message.

Parameters
[out]dataAddress of the buffer for the received message.
[in]max_sizeSize in bytes of the reception buffer.
[out]ret_sizeSize in bytes of the received message. Will never be larger than max_size.
[out]senderSocket address of the sender.
[out]destinationSocket address of the packet destination. Can be useful to check in multicast packets.
[in]abortIf non-zero, invoked when I/O is interrupted (in case of user-interrupt, return, otherwise retry).
[in,out]reportWhere to report error.
[out]timestampWhen 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 IPv4SocketAddress 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:

  • IPv4Address::AnyAddress. 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 AnyAddress 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:

  • IPv4SocketAddress::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]addrLocal socket address to bind to.
[in,out]reportWhere to report error.
Returns
True on success, false on error.

◆ setDefaultDestination() [1/2]

bool ts::UDPSocket::setDefaultDestination ( const IPv4SocketAddress 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]addrSocket address of the destination. Both address and port are mandatory in the socket address, they cannot be set to IPv4Address::AnyAddress or IPv4SocketAddress::AnyPort.
[in,out]reportWhere 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]nameA string describing the socket address of the destination. See IPv4SocketAddress::resolve() for a description of the expected string format.
[in,out]reportWhere to report error.
Returns
True on success, false on error.

◆ getDefaultDestination()

IPv4SocketAddress 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 IPv4Address addr,
Report report = (ts::CerrReport::Instance()) 
)
inherited

Set the outgoing local interface for multicast messages.

Parameters
[in]addrIP address of a local interface.
[in,out]reportWhere 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]nameA string describing the IP address of a local interface. See IPv4Address::resolve() for a description of the expected string format.
[in,out]reportWhere 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]ttlThe TTL value, ie. the maximum number of "hops" between routers before an IP packet is dropped.
[in]multicastWhen true, set the multicast TTL option. When false, set the unicast TTL option.
[in,out]reportWhere 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]ttlThe TTL value, ie. the maximum number of "hops" between routers before an IP packet is dropped.
[in,out]reportWhere 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) option.

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

Parameters
[in]tosThe TOS value.
[in,out]reportWhere 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]onIt true, multicast loopback is on. When false, it is off.
[in,out]reportWhere 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]onIf true, receive timestamps are activated on the socket. Otherwise, they are disabled.
[in,out]reportWhere 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]onIf true, broadcast is activated on the socket. Otherwise, it is disabled.
[in,out]reportWhere to report error.
Returns
True on success, false on error.

◆ setBroadcastIfRequired()

bool ts::UDPSocket::setBroadcastIfRequired ( const IPv4Address  destination,
Report report = (ts::CerrReport::Instance()) 
)
inherited

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

Parameters
[in]destinationAn 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]reportWhere to report error.
Returns
True on success, false on error.

◆ addMembership()

bool ts::UDPSocket::addMembership ( const IPv4Address multicast,
const IPv4Address local,
const IPv4Address source = IPv4Address(),
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.

Parameters
[in]multicastMulticast IP address to listen to.
[in]localIP address of a local interface on which to listen. If set to IPv4Address::AnyAddress, the application lets the system selects the appropriate local interface.
[in]sourceSource address for SSM.
[in,out]reportWhere to report error.
Returns
True on success, false on error.

◆ addMembershipAll()

bool ts::UDPSocket::addMembershipAll ( const IPv4Address multicast,
const IPv4Address source = IPv4Address(),
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]multicastMulticast IP address to listen to.
[in]sourceSource address for SSM.
[in,out]reportWhere to report error.
Returns
True on success, false on error.

◆ addMembershipDefault()

bool ts::UDPSocket::addMembershipDefault ( const IPv4Address multicast,
const IPv4Address source = IPv4Address(),
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 lets the system selects the appropriate local interface.

Parameters
[in]multicastMulticast IP address to listen to.
[in]sourceSource address for SSM.
[in,out]reportWhere 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]reportWhere 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 IPv4SocketAddress destination,
Report report = (ts::CerrReport::Instance()) 
)
virtualinherited

Send a message to a destination address and port.

Parameters
[in]dataAddress of the message to send.
[in]sizeSize in bytes of the message to send.
[in]destinationSocket address of the destination. Both address and port are mandatory in the socket address, they cannot be set to IPv4Address::AnyAddress or IPv4SocketAddress::AnyPort.
[in,out]reportWhere 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]dataAddress of the message to send.
[in]sizeSize in bytes of the message to send.
[in,out]reportWhere 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]reportWhere 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.

◆ setSendBufferSize()

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

Set the send buffer size.

Parameters
[in]sizeSend buffer size in bytes.
[in,out]reportWhere 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]sizeReceive buffer size in bytes.
[in,out]reportWhere 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]timeoutReceive timeout in milliseconds. If negative, receive timeout is not used.
[in,out]reportWhere 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_portIf true, the socket is allowed to reuse a local UDP port which is already bound.
[in,out]reportWhere to report error.
Returns
True on success, false on error.

◆ getLocalAddress()

bool ts::Socket::getLocalAddress ( IPv4SocketAddress addr,
Report report = (ts::CerrReport::Instance()) 
)
inherited

Get local socket address.

Parameters
[out]addrLocal socket address of the connection.
[in,out]reportWhere 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 ( int  domain,
int  type,
int  protocol,
Report report 
)
protectedinherited

Create the socket.

Parameters
[in]domainSocket domain: PF_INET
[in]typeSocket type: SOCK_STREAM, SOCK_DGRAM
[in]protocolSocket protocol: IPPROTO_TCP, IPPROTO_UDP
[in,out]reportWhere to report error.
Returns
True on success, false on error.

◆ 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]sockNew socket descriptor.
[in,out]reportWhere to report error.

Reimplemented in ts::TCPSocket.


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