TSDuck Version 3.16-1064 (TSDuck - The MPEG Transport Stream Toolkit)
ts::UDPSocket Class Reference

UDP Socket. More...

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

Public Member Functions

 UDPSocket (bool auto_open=false, Report &report=(*ts::CerrReport::Instance()))
 Constructor. More...
 
virtual ~UDPSocket ()
 Destructor.
 
bool addMembership (const IPAddress &multicast, const IPAddress &local, const IPAddress &source=IPAddress(), Report &report=(*ts::CerrReport::Instance()))
 Join a multicast group. More...
 
bool addMembershipAll (const IPAddress &multicast, const IPAddress &source=IPAddress(), Report &report=(*ts::CerrReport::Instance()))
 Join a multicast group. More...
 
bool addMembershipDefault (const IPAddress &multicast, const IPAddress &source=IPAddress(), Report &report=(*ts::CerrReport::Instance()))
 Join a multicast group. More...
 
bool bind (const SocketAddress &addr, Report &report=(*ts::CerrReport::Instance()))
 Bind to a local address and port. More...
 
virtual bool close (Report &report=(*ts::CerrReport::Instance())) override
 Close the socket. More...
 
bool dropMembership (Report &report=(*ts::CerrReport::Instance()))
 Drop all multicast membership requests, including source-specific multicast. More...
 
SocketAddress getDefaultDestination () const
 Get the default destination address and port for outgoing messages. More...
 
bool getLocalAddress (SocketAddress &addr, Report &report=(*ts::CerrReport::Instance()))
 Get local socket address. More...
 
platform_specific getSocket () const
 Get the underlying socket device handle (use with care). More...
 
bool isOpen () const
 Check if socket is open. More...
 
virtual bool open (Report &report=(*ts::CerrReport::Instance())) override
 Open the socket. More...
 
virtual bool receive (void *data, size_t max_size, size_t &ret_size, SocketAddress &sender, SocketAddress &destination, const AbortInterface *abort=nullptr, Report &report=(*ts::CerrReport::Instance()))
 Receive a message. More...
 
bool reusePort (bool reuse_port, Report &report=(*ts::CerrReport::Instance()))
 Set the "reuse port" option. More...
 
virtual bool send (const void *data, size_t size, const SocketAddress &destination, Report &report=(*ts::CerrReport::Instance()))
 Send a message to a destination address and port. More...
 
virtual bool send (const void *data, size_t size, Report &report=(*ts::CerrReport::Instance()))
 Send a message to the default destination address and port. More...
 
bool setBroadcast (bool on, Report &report=(*ts::CerrReport::Instance()))
 Enable or disable the broadcast option. More...
 
bool setBroadcastIfRequired (const IPAddress destination, Report &report=(*ts::CerrReport::Instance()))
 Enable or disable the broadcast option, based on an IP address. More...
 
bool setDefaultDestination (const SocketAddress &addr, Report &report=(*ts::CerrReport::Instance()))
 Set a default destination address and port for outgoing messages. More...
 
bool setDefaultDestination (const UString &name, Report &report=(*ts::CerrReport::Instance()))
 Set a default destination address and port for outgoing messages. More...
 
bool setOutgoingMulticast (const IPAddress &addr, Report &report=(*ts::CerrReport::Instance()))
 Set the outgoing local interface for multicast messages. More...
 
bool setOutgoingMulticast (const UString &name, Report &report=(*ts::CerrReport::Instance()))
 Set the outgoing local interface for multicast messages. More...
 
bool setReceiveBufferSize (size_t size, Report &report=(*ts::CerrReport::Instance()))
 Set the receive buffer size. More...
 
bool setReceiveTimeout (MilliSecond timeout, Report &report=(*ts::CerrReport::Instance()))
 Set the receive timeout. More...
 
bool setSendBufferSize (size_t size, Report &report=(*ts::CerrReport::Instance()))
 Set the send buffer size. More...
 
bool setTOS (int tos, Report &report=(*ts::CerrReport::Instance()))
 Set the Type Of Service (TOS) option. More...
 
bool setTTL (int ttl, bool multicast, Report &report=(*ts::CerrReport::Instance()))
 Set the Time To Live (TTL) option. More...
 
bool setTTL (int ttl, Report &report=(*ts::CerrReport::Instance()))
 Set the Time To Live (TTL) option. More...
 

Protected Member Functions

bool createSocket (int domain, int type, int protocol, Report &report)
 Create the socket. More...
 
virtual void declareOpened (platform_specific sock, Report &report)
 Set an open socket descriptor from a subclass. More...
 

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 SocketAddress addr,
Report report = (*ts::CerrReport::Instance()) 
)

Bind to a local address and port.

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

  • IPAddress::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:

  • SocketAddress::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 SocketAddress 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 IPAddress::AnyAddress or SocketAddress::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 SocketAddress::resolve() for a description of the expected string format.
[in,out]reportWhere to report error.
Returns
True on success, false on error.

◆ getDefaultDestination()

SocketAddress 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 IPAddress 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 IPAddress::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.

◆ 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 IPAddress  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 IPAddress multicast,
const IPAddress local,
const IPAddress source = IPAddress(),
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 IPAddress::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 IPAddress multicast,
const IPAddress source = IPAddress(),
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 IPAddress multicast,
const IPAddress source = IPAddress(),
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 SocketAddress 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 IPAddress::AnyAddress or SocketAddress::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()) 
)
inlinevirtual

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,
SocketAddress sender,
SocketAddress destination,
const AbortInterface abort = nullptr,
Report report = (*ts::CerrReport::Instance()) 
)
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.
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 ( MilliSecond  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 ( SocketAddress 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()

platform_specific 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 TS_SOCKET_T_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 ( platform_specific  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: