Implementation of a TCP/IP server. More...

#include <tsTCPServer.h>

Inheritance diagram for ts::TCPServer:

[legend]

Collaboration diagram for ts::TCPServer:

[legend]

Public Types
using	SuperClass = TCPSocket
	Reference to the superclass.

Public Member Functions
	TCPServer (Report report=nullptr, bool non_blocking=false, Object owner=nullptr)
	Constructor.

	TCPServer (ReporterBase delegate, bool non_blocking=false, Object owner=nullptr)
	Constructor.

virtual bool	accept (TCPConnection &client, IPSocketAddress &client_address, IOSB *iosb=nullptr)
	Wait for an incoming client connection.

void	addSubscription (SocketHandlerInterface *handler)
	Add a subscriber to open/close events.

bool	bind (const IPSocketAddress &addr)
	Bind to a local address and port.

void	cancelSubscription (SocketHandlerInterface *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.

bool	getLocalAddress (IPSocketAddress &addr) const
	Get local socket address.

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

bool	isNonBlocking () const
	Check if the device is in non-blocking mode.

bool	isOpen () const
	Check if socket is open.

bool	isOwned ()
	Check if the object is owned.

template<class OBJECT > requires std::derived_from<OBJECT, ts::Object>
bool	isOwned ()
	Check if the object is owned by an object of a given type.

virtual bool	listen (int backlog)
	Start the server.

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.

Object *	owner ()
	Get the address of the optional "owner" object which was specified in the constructor.

template<class OBJECT > requires std::derived_from<OBJECT, ts::Object>
OBJECT *	owner ()
	Get the address of the "owner" object which was specified in the constructor.

Report &	report () const
	Access the Report which is associated with this object.

bool	reusePort (bool reuse_port)
	Set the "reuse port" option.

bool	setAcceptStatus (TCPConnection &client, IPSocketAddress &client_address, IOSB *iosb)
	Update the status of an asynchronous accept().

bool	setKeepAlive (bool active)
	Set the "keep alive" option.

bool	setLingerTime (int seconds)
	Set the linger time option.

bool	setNoDelay (bool active)
	Set the "no delay" option.

bool	setNoLinger ()
	Remove the linger time 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.

Report *	setReport (Report *report)
	Associate this object with another Report to log errors.

ReporterBase *	setReport (ReporterBase *delegate)
	Associate this object with another ReporterBase to log errors.

bool	setSendBufferSize (size_t size)
	Set the send buffer size.

bool	setTTL (int ttl)
	Set the Time To Live (TTL) option.

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)
	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 F >
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) override
	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) override
	Set an open socket descriptor from a subclass.

virtual bool	openImplementation (IP gen) override
	Open the socket, actual implementation which must be overriden by subclasses.

bool	setSystemNonBlocking (SysSocketType fd, bool non_blocking)
	Low-level method to set a system file or socket descriptor in non-blocking mode.

Protected Attributes
std::recursive_mutex	_mutex {}
	Mutex protecting this object.

Detailed Description

Implementation of a TCP/IP server.

The following lists the typical server-side scenario in the correct order. Many steps such as setting socket options are optional. The symbol [*] means mandatory. Depending on the platform, some options settings are sensitive to the order. The following order has proven to work on most platforms.

Invoking close() is optional since the destructor of the class will properly close the socket if not already done.

Constructor & Destructor Documentation

◆ TCPServer() [1/2]

ts::TCPServer::TCPServer	(	Report *	report = `nullptr`,
		bool	non_blocking = `false`,
		Object *	owner = `nullptr`
	)

inlineexplicit

Constructor.

Parameters

[in]	report	Where 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_blocking	It true, the device is initially set in non-blocking mode.
[in]	owner	Optional address of an "owner" object, typically an instance of class containing this object.

◆ TCPServer() [2/2]

ts::TCPServer::TCPServer	(	ReporterBase *	delegate,
		bool	non_blocking = `false`,
		Object *	owner = `nullptr`
	)

inlineexplicit

Constructor.

Parameters

[in]	delegate	Use the report of another ReporterBase. If delegate is null, log messages are discarded.
[in]	non_blocking	It true, the device is initially set in non-blocking mode.
[in]	owner	Optional address of an "owner" object, typically an instance of class containing this object.

Member Function Documentation

◆ listen()

virtual bool ts::TCPServer::listen ( int backlog )

virtual

Start the server.

Here, starting the server means starting to listen to incoming client connections. Internally to the kernel, the incoming connections are queued up to backlog. When the method accept() is invoked and some incoming connections are already queued in the kernel, the oldest one is immediately accepted. Otherwise, accept() blocks until a new incoming connection arrives.

Parameters

[in] backlog Maximum number of incoming connections which allowed to queue in the kernel until the next call to accept(). Note that this value is a minimum queue size. But the kernel may accept more. There is no guarantee that additional incoming connections will be rejected if more than backlog are already queueing.

Returns: True on success, false on error.

Reimplemented in ts::TLSServer.

◆ accept()

virtual bool ts::TCPServer::accept	(	TCPConnection &	client,
		IPSocketAddress &	client_address,
		IOSB *	iosb = `nullptr`
	)

virtual

Wait for an incoming client connection.

Parameters

[out]	client	This object receives the new connection. Upon successful return from accept(), the TCPConnection object is a properly connected TCP session. Once the connection is completed, the TCPConnection objects on the client side and the server side are symmetric and can be used the same way. In case of asynchronous I/O, the object must remain valid until the accept() completes or is canceled.
[out]	client_address	This object receives the socket address of the client. If the server wants to filter client connections based on their IP address, it may use addr for that.
[in,out]	iosb	Address of an IOSB structure. If non-null, the socket must be in non-blocking mode. When null, the socket must be in blocking mode (the default). See the description of IOSB. Important: The parameter iosb should not be used by applications. It should be used only by "reactive classes", which work in combination with a Reactor.

Returns: True on success, false on error. In case of non-blocking mode, if the accept is successfully started but still pending (no available client), iosb->pending is set to true and the method returns true.

See also: listen()

Reimplemented in ts::TLSServer.

◆ setAcceptStatus()

bool ts::TCPServer::setAcceptStatus	(	TCPConnection &	client,
		IPSocketAddress &	client_address,
		IOSB *	iosb
	)

Update the status of an asynchronous accept().

This method shall be used with asynchronous I/O only. It returns an error when the system uses non-blocking I/O instead of asynchronous I/O.

Parameters

[in,out]	client	The socket which received the new connection.
[out]	client_address	This object receives the socket address of the client.
[in,out]	iosb	Address of the IOSB structure which was used when connect() was called.

Returns: True on success, false on error.

◆ closeImplementation()

virtual bool ts::TCPServer::closeImplementation ( bool silent )

overrideprotectedvirtual

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] silent If 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 from ts::TCPSocket.

Reimplemented in ts::TLSServer.

◆ setTTL()

bool ts::TCPSocket::setTTL ( int ttl )

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.

Returns: True on success, false on error.

◆ setNoLinger()

bool ts::TCPSocket::setNoLinger ( )

inherited

Remove the linger time option.

Returns: True on success, false on error.

◆ setLingerTime()

bool ts::TCPSocket::setLingerTime ( int seconds )

inherited

Set the linger time option.

Parameters

[in] seconds Number of seconds to wait after shuting down the socket.

Returns: True on success, false on error.

◆ setKeepAlive()

bool ts::TCPSocket::setKeepAlive ( bool active )

inherited

Set the "keep alive" option.

Parameters

[in] active If true, the socket periodically sends "keep alive" packets when the connection is idle.

Returns: True on success, false on error.

◆ setNoDelay()

bool ts::TCPSocket::setNoDelay ( bool active )

inherited

Set the "no delay" option.

Parameters

[in] active If true, the socket immediately sends outgoing packets. By default, a TCP socket waits a small amount of time after a send() operation to get a chance to group outgoing data from successive send() operations into one single packet.

Returns: True on success, false on error.

◆ openImplementation()

virtual bool ts::TCPSocket::openImplementation ( IP gen )

overrideprotectedvirtualinherited

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] gen IP generation, IPv4 or IPv6. If set to IP::Any, open an IPv6 socket (IPv4 connections allowed).

Returns: True on success, false on error.

Implements ts::Socket.

◆ declareOpened()

virtual void ts::TCPSocket::declareOpened ( SysSocketType sock )

overrideprotectedvirtualinherited

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.

Reimplemented from ts::Socket.

◆ open()

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

finalvirtualinherited

Open the socket.

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

Parameters

[in] gen IP 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 )

finalvirtualinherited

Close the socket.

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

Parameters

[in] silent If 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

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 )

inherited

Set the send buffer size.

Parameters

[in] size Send buffer size in bytes.

Returns: True on success, false on error.

◆ setReceiveBufferSize()

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

inherited

Set the receive buffer size.

Parameters

[in] size Receive buffer size in bytes.

Returns: True on success, false on error.

◆ setReceiveTimeout()

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

inherited

Set the receive timeout.

Parameters

[in] timeout Receive 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 )

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.

Returns: True on success, false on error.

◆ bind()

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

inherited

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] addr Local socket address to bind to.

Returns: True on success, false on error.

◆ getLocalAddress()

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

inherited

Get local socket address.

Parameters

[out] addr Local socket address of the connection.

Returns: True on success, false on error.

◆ localName()

UString ts::Socket::localName ( )

inherited

Get the local address as a string.

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

◆ 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.

◆ addSubscription()

void ts::Socket::addSubscription ( SocketHandlerInterface * handler )

inherited

Add a subscriber to open/close events.

Parameters

[in] handler The object to call on open() and close().

◆ cancelSubscription()

void ts::Socket::cancelSubscription ( SocketHandlerInterface * handler )

inherited

Remove a subscriber to open/close events.

Parameters

[in] handler The object to no longer call on open() and close().

◆ createSocket()

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

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

Returns: True on success, false on error.

See also: open(ge, Report&)

◆ convert()

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

protectedinherited

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.

◆ callSubscribers()

template<typename F >

void ts::Socket::callSubscribers ( F && func )

inlineprotectedinherited

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

Parameters

[in] func Function to call as lambda expression.

◆ allowSetNonBlocking()

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

overrideprotectedvirtualinherited

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

◆ IsPendingStatus()

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

staticinherited

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_code System error code.

Returns: True if error_code is an in-progress/would-block one.

◆ 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_blocking	The required non-blocking mode.
[in]	opname	Name 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]	iosb	Address 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]	opname	Name of the operation, for the error message.

Returns: True on success, false on error.

◆ setSystemNonBlocking()

bool ts::NonBlockingDevice::setSystemNonBlocking	(	SysSocketType	fd,
		bool	non_blocking
	)

protectedinherited

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

Parameters

[in]	fd	System file or socket descriptor.
[in]	non_blocking	It 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

◆ report()

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

inherited

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.

◆ setReport() [1/2]

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

inherited

Associate this object with another Report to log errors.

Parameters

[in] report Where 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] delegate Use 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] mute It 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 )

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] silent If true, do not report errors, report debug messages instead.

Returns: Error when silent is false, Debug otherwise.

◆ owner() [1/2]

Object * ts::OwnedObject::owner ( )

inlineinherited

Get the address of the optional "owner" object which was specified in the constructor.

Returns: Address of the "owner" object or a null pointer if there was none.

◆ owner() [2/2]

template<class OBJECT >
requires std::derived_from<OBJECT, ts::Object>

OBJECT * ts::OwnedObject::owner ( )

inherited

Get the address of the "owner" object which was specified in the constructor.

This template version requires that the owner objet is set and of type OBJECT, or some subclass of it. If there is no owner object or if it is not compatible with the template class OBJECT, this is a fatal error and the application is terminated.

Template Parameters

OBJECT A subclass of Object

Returns: Address of the "owner" object or a null pointer if there was none.

◆ isOwned() [1/2]

bool ts::OwnedObject::isOwned ( )

inlineinherited

Check if the object is owned.

Returns: True if this object has an owner, false otherwise.

◆ isOwned() [2/2]

template<class OBJECT >
requires std::derived_from<OBJECT, ts::Object>

bool ts::OwnedObject::isOwned ( )

inlineinherited

Check if the object is owned by an object of a given type.

Template Parameters

OBJECT A subclass of Object

Returns: True if this object has an owner by an object of type OBJECT, false otherwise.

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

tsTCPServer.h

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ TCPServer() [1/2]

◆ TCPServer() [2/2]

Member Function Documentation

◆ listen()

◆ accept()

◆ setAcceptStatus()

◆ closeImplementation()

◆ setTTL()

◆ setNoLinger()

◆ setLingerTime()

◆ setKeepAlive()

◆ setNoDelay()

◆ openImplementation()

◆ declareOpened()

◆ open()

◆ close()

◆ isOpen()

◆ generation()

◆ setSendBufferSize()

◆ setReceiveBufferSize()

◆ setReceiveTimeout()

◆ reusePort()

◆ bind()

◆ getLocalAddress()

◆ localName()

◆ getSocket()

◆ addSubscription()

◆ cancelSubscription()

◆ createSocket()

◆ convert()

◆ callSubscribers()

◆ allowSetNonBlocking()

◆ setNonBlocking()

◆ isNonBlocking()

◆ IsPendingStatus()

◆ checkNonBlocking() [1/2]

◆ checkNonBlocking() [2/2]

◆ setSystemNonBlocking()

◆ report()

◆ setReport() [1/2]

◆ setReport() [2/2]

◆ muteReport()

◆ SilentLevel()

◆ owner() [1/2]

◆ owner() [2/2]

◆ isOwned() [1/2]

◆ isOwned() [2/2]