TSDuck v3.45-4766
MPEG Transport Stream Toolkit
Loading...
Searching...
No Matches
ts::Socket Class Referenceabstract

Base class for TCP and UDP sockets. More...

#include <tsSocket.h>

Inheritance diagram for ts::Socket:
Collaboration diagram for ts::Socket:

Public Member Functions

 Socket (Report *report, bool non_blocking=false)
 Constructor.
 
 Socket (ReporterBase *delegate, bool non_blocking=false)
 Constructor.
 
virtual ~Socket () override
 Destructor.
 
void addSubscription (SubscriptionHandlerInterface *handler)
 Add a subscriber to open/close events.
 
bool bind (const IPSocketAddress &addr)
 Bind to a local address and port.
 
void cancelSubscription (SubscriptionHandlerInterface *handler)
 Remove a subscriber to open/close events.
 
virtual bool close (bool silent=false) final
 Close the socket.
 
IP generation () const
 Get the IP generation with which the socket was open.
 
SysHandleType getHandle () const
 Get the underlying file descriptor or device handle.
 
bool getLocalAddress (IPSocketAddress &addr) const
 Get local socket address.
 
virtual SysHandleType getReadHandle () const override
 Get the underlying file descriptor or device handle for read operations.
 
SysSocketType getReadSocket () const
 Get the underlying file descriptor or device handle as a system socket handle for read operations.
 
SysSocketType getSocket () const
 Get the underlying file descriptor or device handle as a system socket handle.
 
virtual SysHandleType getWriteHandle () const override
 Get the underlying file descriptor or device handle for write operations.
 
SysSocketType getWriteSocket () const
 Get the underlying file descriptor or device handle as a system socket handle for write operations.
 
bool isNonBlocking () const
 Check if the device is in non-blocking mode.
 
bool isOpen () const
 Check if socket is open.
 
bool isSupportedByReactor (bool recheck=false)
 Check if the device is supported by a reactor for non-blocking or asynchronous I/O.
 
UString localName ()
 Get the local address as a string.
 
bool muteReport (bool mute)
 Temporarily mute the associated report.
 
virtual bool open (IP gen=IP::Any) final
 Open the socket.
 
virtual Reportreport () const override
 Access the Report which is associated with this object.
 
bool reusePort (bool reuse_port)
 Set the "reuse port" option.
 
bool setNonBlocking (bool non_blocking)
 Set the device in non-blocking mode.
 
bool setReceiveBufferSize (size_t size)
 Set the receive buffer size.
 
bool setReceiveTimeout (cn::milliseconds timeout)
 Set the receive timeout.
 
ReportsetReport (Report *report)
 Associate this object with another Report to log errors.
 
ReporterBasesetReport (ReporterBase *delegate)
 Associate this object with another ReporterBase to log errors.
 
bool setSendBufferSize (size_t size)
 Set the send buffer size.
 

Static Public Member Functions

static bool IsPendingStatus (int error_code)
 This static method checks if a system error code means "I/O in progress" (asynchronous I/O) or "I/O would block" (non-blocking I/O).
 
static int SilentLevel (bool silent, int default_severity=Severity::Error)
 Compute a log severity level from a "silent" parameter.
 

Protected Member Functions

virtual bool allowSetNonBlocking () const override
 Check that the non-blocking mode can be set.
 
template<typename HANDLER , typename F >
requires std::derived_from<HANDLER, SubscriptionHandlerInterface>
void callSubscribers (F &&func)
 Call a handler on all subscribers, using a lambda expression.
 
bool checkNonBlocking (bool non_blocking, const UChar *opname)
 Check the blocking mode of a device.
 
bool checkNonBlocking (IOSB *iosb, const UChar *opname)
 Check the blocking mode of a device.
 
virtual bool closeImplementation (bool silent)
 Close the socket, actual implementation which may be overriden by subclasses.
 
bool convert (IPAddress &addr) const
 Convert an IP address to make it compatible with the socket IP generation.
 
bool createSocket (IP gen, int type, int protocol)
 Create the socket.
 
virtual void declareOpened (SysSocketType sock)
 Set an open socket descriptor from a subclass.
 
int genericSystemRead (void *addr, size_t max_size, size_t &ret_size, const AbortInterface *abort, NonBlockingDevice::IOSB *iosb, uint64_t position)
 Generic system read operation.
 
int genericSystemWrite (const void *addr, size_t size, size_t &written_size, NonBlockingDevice::IOSB *iosb, uint64_t position)
 Generic system write operation.
 
virtual bool openImplementation (IP gen)=0
 Open the socket, actual implementation which must be overriden by subclasses.
 
bool setSystemNonBlocking (bool non_blocking)
 Low-level method to set the system file or socket descriptor in non-blocking mode.
 

Detailed Description

Base class for TCP and UDP sockets.

Subscription to open/close and connect/disconnect is possible using SocketHandlerInterface.

See also
SubscriptionBase

Constructor & Destructor Documentation

◆ Socket() [1/2]

ts::Socket::Socket ( Report report,
bool  non_blocking = false 
)
explicit

Constructor.

Parameters
[in]reportWhere to report errors. The report object must remain valid as long as this object exists or setReport() is used with another Report object. If report is null, log messages are discarded.
[in]non_blockingIt true, the device is initially set in non-blocking mode.

◆ Socket() [2/2]

ts::Socket::Socket ( ReporterBase delegate,
bool  non_blocking = false 
)
explicit

Constructor.

Parameters
[in]delegateUse the report of another ReporterBase. If delegate is null, log messages are discarded.
[in]non_blockingIt true, the device is initially set in non-blocking mode.

Member Function Documentation

◆ open()

virtual bool ts::Socket::open ( IP  gen = IP::Any)
finalvirtual

Open the socket.

Subclasses are not permitted to override this one, they should implement openImplementation().

Parameters
[in]genIP generation, IPv4 or IPv6. If set to IP::Any, open an IPv6 socket (IPv4 connections allowed).
Returns
True on success, false on error.

◆ close()

virtual bool ts::Socket::close ( bool  silent = false)
finalvirtual

Close the socket.

Subclasses are not permitted to override this one, they should implement closeImplementation().

Parameters
[in]silentIf true, do not report errors through the logger. This is typically useful when the socket is in some error condition and closing it is necessary although it may generate additional meaningless errors.
Returns
True on success, false on error.

◆ isOpen()

bool ts::Socket::isOpen ( ) const
inline

Check if socket is open.

Returns
True if socket is open.

◆ generation()

IP ts::Socket::generation ( ) const
inline

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)

Set the send buffer size.

Parameters
[in]sizeSend buffer size in bytes.
Returns
True on success, false on error.

◆ setReceiveBufferSize()

bool ts::Socket::setReceiveBufferSize ( size_t  size)

Set the receive buffer size.

Parameters
[in]sizeReceive buffer size in bytes.
Returns
True on success, false on error.

◆ setReceiveTimeout()

bool ts::Socket::setReceiveTimeout ( cn::milliseconds  timeout)

Set the receive timeout.

Parameters
[in]timeoutReceive timeout in milliseconds. If negative or zero, receive timeout is not used, reception waits forever.
Returns
True on success, false on error.

◆ reusePort()

bool ts::Socket::reusePort ( bool  reuse_port)

Set the "reuse port" option.

Parameters
[in]reuse_portIf true, the socket is allowed to reuse a local UDP port which is already bound.
Returns
True on success, false on error.

◆ bind()

bool ts::Socket::bind ( const IPSocketAddress addr)

Bind to a local address and port.

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

  • IPAddress::AnyAddress4.
    • UDP: 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.
    • TCP client: Any local interface may be used to connect to a server.
    • TCP server: Any local interface may be used to receive incoming client connections.
  • The IP address of an interface of the local system.
    • UDP: 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.
    • TCP client: Outgoing connections will be only allowed through this interface.
    • TCP server: Incoming client connections 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 or TCP port. This is the usual configuration for a TCP client.
  • A specific port number. If this UDP or TCP port is already bound by another local socket of the same type, the bind operation fails, unless the "reuse port" option has already been set.
Parameters
[in]addrLocal socket address to bind to.
Returns
True on success, false on error.

◆ getLocalAddress()

bool ts::Socket::getLocalAddress ( IPSocketAddress addr) const

Get local socket address.

Parameters
[out]addrLocal socket address of the connection.
Returns
True on success, false on error.

◆ localName()

UString ts::Socket::localName ( )

Get the local address as a string.

Returns
A string representation of the IP address and port of the socket.

◆ getReadHandle()

virtual SysHandleType ts::Socket::getReadHandle ( ) const
overridevirtual

Get the underlying file descriptor or device handle for read operations.

Subclasses should override this method.

Returns
The underlying file descriptor for read operations or SYS_HANDLE_INVALID if the device is not open for read.
See also
getHandle()

Reimplemented from ts::NonBlockingDevice.

◆ getWriteHandle()

virtual SysHandleType ts::Socket::getWriteHandle ( ) const
overridevirtual

Get the underlying file descriptor or device handle for write operations.

Subclasses should override this method.

Returns
The underlying file descriptor for write operations or SYS_HANDLE_INVALID if the device is not open for write.
See also
getHandle()

Reimplemented from ts::NonBlockingDevice.

◆ openImplementation()

virtual bool ts::Socket::openImplementation ( IP  gen)
protectedpure virtual

Open the socket, actual implementation which must be overriden by subclasses.

Never called when the application tries to open a socket which is already open.

Parameters
[in]genIP generation, IPv4 or IPv6. If set to IP::Any, open an IPv6 socket (IPv4 connections allowed).
Returns
True on success, false on error.

Implemented in ts::TCPSocket, ts::UDPReceiver, and ts::UDPSocket.

◆ closeImplementation()

virtual bool ts::Socket::closeImplementation ( bool  silent)
protectedvirtual

Close the socket, actual implementation which may be overriden by subclasses.

Never called when the application tries to close a socket which is not open. If overridden by a subclass, the superclass must be called at the end of the overridden close().

Parameters
[in]silentIf true, do not report errors through the logger. This is typically useful when the socket is in some error condition and closing it is necessary although it may generate additional meaningless errors.
Returns
True on success, false on error.

Reimplemented in ts::TCPServer, ts::TCPSocket, ts::UDPSocket, and ts::TLSServer.

◆ createSocket()

bool ts::Socket::createSocket ( IP  gen,
int  type,
int  protocol 
)
protected

Create the socket.

Parameters
[in]genIP generation.
[in]typeSocket type: SOCK_STREAM, SOCK_DGRAM
[in]protocolSocket protocol: IPPROTO_TCP, IPPROTO_UDP
Returns
True on success, false on error.
See also
open(ge, Report&)

◆ declareOpened()

virtual void ts::Socket::declareOpened ( SysSocketType  sock)
protectedvirtual

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.

Reimplemented in ts::TCPSocket.

◆ convert()

bool ts::Socket::convert ( IPAddress addr) const
protected

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

Parameters
addr[in,out] The address to convert.
Returns
True on success, false on error.

◆ allowSetNonBlocking()

virtual bool ts::Socket::allowSetNonBlocking ( ) const
overrideprotectedvirtual

Check that the non-blocking mode can be set.

Must be implemented by subclasses which do not support setting the non-blocking in certain states, such as after being opened. The default implementation always allows setting the non-blocking mode.

Returns
True if setting the non-blocking mode is allowed, false otherwise.

Reimplemented from ts::NonBlockingDevice.

◆ setNonBlocking()

bool ts::NonBlockingDevice::setNonBlocking ( bool  non_blocking)
inherited

Set the device in non-blocking mode.

Important: Usually, this method must be called before opening the device, whatever it means. Otherwise it is ignored and the device blocking mode is unchanged.

Parameters
[in]non_blockingIt true, the device is set in non-blocking mode.
Returns
True on success, false if the device is already open and the non-blocking mode is unchanged.

◆ isNonBlocking()

bool ts::NonBlockingDevice::isNonBlocking ( ) const
inlineinherited

Check if the device is in non-blocking mode.

Returns
True if the device is in non-blocking mode, false otherwise.
See also
setNonBlocking()

◆ isSupportedByReactor()

bool ts::NonBlockingDevice::isSupportedByReactor ( bool  recheck = false)
inherited

Check if the device is supported by a reactor for non-blocking or asynchronous I/O.

Parameters
[in]recheckIf true, force a recheck. If false and the device was previously checked, return the previous cached value.
Returns
True if the device is supported by a reactor for non-blocking or asynchronous I/O, false otherwise.

◆ IsPendingStatus()

static bool ts::NonBlockingDevice::IsPendingStatus ( int  error_code)
inlinestaticinherited

This static method checks if a system error code means "I/O in progress" (asynchronous I/O) or "I/O would block" (non-blocking I/O).

Parameters
[in]error_codeSystem error code.
Returns
True if error_code is an in-progress/would-block one.

◆ getHandle()

SysHandleType ts::NonBlockingDevice::getHandle ( ) const
inherited

Get the underlying file descriptor or device handle.

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

On UNIX systems, sockets are standard file descriptors. On Windows systems, sockets and devices handles are two distinct types (SOCKET, an integer type, and HANDLE, a pointer type). However, SOCKET and HANDLE have the same size and can be converted between each other. In practice, all Windows device handles are pointers. When Microsoft decided to implement the BSD socket API, they needed to represent sockets as integers. The integer is simply a cast of the HANDLE pointer.

In practice, the methods getHandle() and getSocket() return the same value, represented as two different portable types, SysHandleType and SysSocketType. Note that this types are defined as their real representation. On UNIX systems, both are defined as int and are compatible. However, on Windows systems, they are defined as HANDLE and SOCKET and are not compatible. So, accidentally mixing the two compiles on UNIX but not on Windows. Be careful to use the right type for the right usage.

There is one important difference between getHandle() and getSocket(): the error values, SYS_HANDLE_INVALID and SYS_SOCKET_INVALID. Be careful, these constants have distinct binary values on Windows. This is the only case were it is not possible to cast between a SysHandleType value and a SysSocketType value. This is why it is recommended to always use getHandle() when a SysHandleType is required and getSocket() when a SysSocketType is required.

A subclass which uses file descriptors or device handles for read, write, or both, must override the methods getReadHandle(), getWriteHandle(), or both. If the two types of operations use the same file descriptor, the two methods must return the same value.

An application should call getReadHandle() for read operations and getWriteHandle() for write operations. The method getHandle() returns getReadHandle() if its returns a valid value, and getWriteHandle() otherwise.

Returns
The underlying file descriptor or device handler. Return SYS_HANDLE_INVALID if the socket is not open.

◆ getSocket()

SysSocketType ts::NonBlockingDevice::getSocket ( ) const
inherited

Get the underlying file descriptor or device handle as a system socket handle.

Returns
The underlying socket descriptor. Return SYS_SOCKET_INVALID if the socket is not open.
See also
getHandle()

◆ getReadSocket()

SysSocketType ts::NonBlockingDevice::getReadSocket ( ) const
inherited

Get the underlying file descriptor or device handle as a system socket handle for read operations.

Returns
The underlying file descriptor for read operations or SYS_SOCKET_INVALID if the socket is not open for read.
See also
getHandle()

◆ getWriteSocket()

SysSocketType ts::NonBlockingDevice::getWriteSocket ( ) const
inherited

Get the underlying file descriptor or device handle as a system socket handle for write operations.

Returns
The underlying file descriptor for read operations or SYS_SOCKET_INVALID if the socket is not open for write.
See also
getHandle()

◆ checkNonBlocking() [1/2]

bool ts::NonBlockingDevice::checkNonBlocking ( bool  non_blocking,
const UChar opname 
)
protectedinherited

Check the blocking mode of a device.

Called by subclass methods which are explicitly called in blocking or non-blocking mode.

Parameters
[in]non_blockingThe required non-blocking mode.
[in]opnameName of the operation, for the error message.
Returns
True on success, false on error.

◆ checkNonBlocking() [2/2]

bool ts::NonBlockingDevice::checkNonBlocking ( IOSB iosb,
const UChar opname 
)
protectedinherited

Check the blocking mode of a device.

Called by subclass methods which are explicitly called in blocking or non-blocking mode.

Parameters
[in,out]iosbAddress of an IOSB structure. If non-null, we are in non-blocking mode. When null, we are in blocking mode. When non-null, pending is reset to false and overlap is zeroed.
[in]opnameName of the operation, for the error message.
Returns
True on success, false on error.

◆ setSystemNonBlocking()

bool ts::NonBlockingDevice::setSystemNonBlocking ( bool  non_blocking)
protectedinherited

Low-level method to set the system file or socket descriptor in non-blocking mode.

Parameters
[in]non_blockingIt true, the device is set in non-blocking mode.
Returns
True on success, false on error.

Summary: Do not use this method unless you exactly know what you are doing.

UNIX: Depending on the way a file descriptor is created, it may be possible to specify the non-blocking mode from the beginning. Or it can be somehow inherited. However, this is not portable.

Examples:

  • On Linux and FreeBSD, a socket can be directly created in non-blocking mode using the flag SOCK_NONBLOCK in the 'type' parameter of the socket() system call. However, it does not work on macOS.
  • On macOS (and maybe FreeBSD), when a server socket is in non-blocking mode, all client session sockets which are created by accept() are also in non-blocking mode. However, on Linux, they are in blocking mode.

In all cases, it is possible to set a file descriptor in non-blocking mode at any time using the method setSystemNonBlocking(). This method uses fcntl(F_SETFL) to alter the file descriptor's flags.

Windows: The natural way of not being blocked on I/O on Windows is asynchronous I/O. To increase the general confusion, there is some form of non-blocking mode on Windows sockets, and only sockets, not other forms of file handles. This mode is activated using "ioctlsocket(fd, FIONBIO, &mode)". When this mode is active, socket I/O become similar to UNIX: they immediately either succeed or fail, but never block. However, there is no way to get notified when the I/O becomes possible. There is no equivalent to epoll (Linux) or kqueue (macOS and BSD). The Windows I/O Completion Ports can only work on asynchronous I/O, using OVERLAPPED structures. Because this form of non-blocking mode is mostly useless in practice, we do not use it and the method setSystemNonBlocking() does nothing on Windows.

See also
https://learn.microsoft.com/en-us/archive/blogs/csliu/io-concept-blockingnon-blocking-vs-syncasync

◆ genericSystemWrite()

int ts::NonBlockingDevice::genericSystemWrite ( const void *  addr,
size_t  size,
size_t &  written_size,
NonBlockingDevice::IOSB iosb,
uint64_t  position 
)
protectedinherited

Generic system write operation.

This is a convenience method which can be used (or not) by subclasses when the system calls write() (UNIX) or WriteFile() (Windows) are appropriate.

Parameters
[in]addrAddress of the data to write.
[in]sizeSize in bytes of the data to write.
[out]written_sizeActually written size in bytes. Can be less than size in case of error in the middle of the write.
[in,out]iosbAddress of an IOSB structure. If non-null, the stream must be in non-blocking mode. When null, the stream must be in blocking mode (the default). See the description of ts::NonBlockingDevice::IOSB.
[in]positionThis value is only used on Windows with asynchronous I/O on disk file. On Windows, when asynchronous I/O are used on random access files, the file position is not maintained. Each read or write operation is performed at the specified absolute position.
Returns
Error code. When the I/O is non-blocking/asynchronous and pending, return SYS_SUCCESS and iosb->pending is true. Return SYS_EOF when it is no longer possible to write (e.g. broken pipe).

◆ genericSystemRead()

int ts::NonBlockingDevice::genericSystemRead ( void *  addr,
size_t  max_size,
size_t &  ret_size,
const AbortInterface abort,
NonBlockingDevice::IOSB iosb,
uint64_t  position 
)
protectedinherited

Generic system read operation.

This is a convenience method which can be used (or not) by subclasses when the system calls read() (UNIX) or ReadFile() (Windows) are appropriate.

Parameters
[out]addrAddress of the buffer for the incoming data.
[in]max_sizeMaximum size in bytes of the buffer.
[out]ret_sizeReturned input size in bytes. If zero, end of file has been reached or an error occurred.
[in]abortIf non-zero, invoked when I/O is interrupted (in case of user-interrupt, return, otherwise retry).
[in,out]iosbAddress of an IOSB structure. If non-null, the stream must be in non-blocking mode. When null, the stream must be in blocking mode (the default). See the description of ts::NonBlockingDevice::IOSB.
[in]positionThis value is only used on Windows with asynchronous I/O on disk file. On Windows, when asynchronous I/O are used on random access files, the file position is not maintained. Each read or write operation is performed at the specified absolute position.
Returns
Error code. When the I/O is non-blocking/asynchronous and pending, return SYS_SUCCESS and iosb->pending is true. Return SYS_EOF when it is no longer possible to read.

◆ report()

virtual Report & ts::ReporterBase::report ( ) const
overridevirtualinherited

Access the Report which is associated with this object.

Can be called from another thread only if the Report object is thread-safe.

Returns
A reference to the associated report.

Implements ts::ReporterInterface.

◆ setReport() [1/2]

Report * ts::ReporterBase::setReport ( Report report)
inherited

Associate this object with another Report to log errors.

Parameters
[in]reportWhere to report errors. The report object must remain valid as long as this object exists or setReport() is used with another Report object. If report is null, log messages are discarded.
Returns
The address of the previous Report object or a null pointer if there was none.

◆ setReport() [2/2]

ReporterBase * ts::ReporterBase::setReport ( ReporterBase delegate)
inherited

Associate this object with another ReporterBase to log errors.

Parameters
[in]delegateUse the report of another ReporterBase. If delegate is null, the previous explicit Report is used..
Returns
The address of the previous ReporterBase object or a null pointer if there was none.

◆ muteReport()

bool ts::ReporterBase::muteReport ( bool  mute)
inherited

Temporarily mute the associated report.

Parameters
[in]muteIt true, report() will return a null report (log messages are discarded), until muteReport() is invoked again with mute set to false.
Returns
Previous state of the mute field.

◆ SilentLevel()

static int ts::ReporterBase::SilentLevel ( bool  silent,
int  default_severity = Severity::Error 
)
inlinestaticinherited

Compute a log severity level from a "silent" parameter.

Some subclass methods have a "silent" parameter to avoid reporting errors which may be insignificant, typically when closing a device after an error, in which case the close operation may produce other errors if the previous error left the device in an inconsistent state. While those errors should not be displayed as errors, we still display them at debug level.

Parameters
[in]silentIf true, do not report errors, report debug messages instead.
[in]default_severityDefault severity, in non-silent mode (error by default).
Returns
Error when silent is false, Debug otherwise.

◆ addSubscription()

void ts::SubscriptionBase::addSubscription ( SubscriptionHandlerInterface handler)
inherited

Add a subscriber to open/close events.

Parameters
[in]handlerThe object to call on open() and close().

◆ cancelSubscription()

void ts::SubscriptionBase::cancelSubscription ( SubscriptionHandlerInterface handler)
inherited

Remove a subscriber to open/close events.

Parameters
[in]handlerThe object to no longer call on open() and close().

◆ callSubscribers()

template<typename HANDLER , typename F >
requires std::derived_from<HANDLER, SubscriptionHandlerInterface>
void ts::SubscriptionBase::callSubscribers ( F &&  func)
inlineprotectedinherited

Call a handler on all subscribers, using a lambda expression.

Parameters
[in]funcFunction to call as lambda expression.

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