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

UDP Socket. More...

#include <tsUDPSocket.h>

Inheritance diagram for ts::UDPSocket:
Collaboration diagram for ts::UDPSocket:

Public Member Functions

 UDPSocket (bool auto_open=false, Report &report=(ts::CerrReport::Instance()))
 Constructor.
 
virtual ~UDPSocket () override
 Destructor.
 
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.
 
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.
 
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)
 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 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.
 
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.
 
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 Socket.

Constructor & Destructor Documentation

◆ UDPSocket()

ts::UDPSocket::UDPSocket ( bool  auto_open = false,
Report report = (ts::CerrReport::Instance()) 
)

Constructor.

Parameters
[in]auto_openIf true, call open() immediately.
[in,out]reportWhere to report error.

Member Function Documentation

◆ bind()

bool ts::UDPSocket::bind ( const IPv4SocketAddress addr,
Report report = (ts::CerrReport::Instance()) 
)

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()) 
)

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()) 
)

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
inline

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()) 
)

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()) 
)

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()) 
)

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()) 
)
inline

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()) 
)

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()) 
)

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()) 
)

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()) 
)

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()) 
)

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()) 
)

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()) 
)

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()) 
)

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()))

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()) 
)
virtual

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()) 
)
virtual

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.

◆ receive()

virtual bool ts::UDPSocket::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 
)
virtual

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 in ts::UDPReceiver.

◆ open()

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

Open the socket.

Parameters
[in,out]reportWhere to report error.
Returns
True on success, false on error.

Implements ts::Socket.

Reimplemented in ts::UDPReceiver.

◆ close()

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

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: