SSL/TLS connected socket, for data communication. More...

#include <tsTLSConnection.h>

Inheritance diagram for ts::TLSConnection:

[legend]

Collaboration diagram for ts::TLSConnection:

[legend]

Public Types
using	SuperClass = TCPSocket
	Reference to the superclass.

Public Member Functions
	TLSConnection (Report *report)
	Constructor.

	TLSConnection (Report *report, const TLSArgs &args)
	Constructor with initial client arguments.

	TLSConnection (ReporterBase *delegate)
	Constructor.

	TLSConnection (ReporterBase *delegate, const TLSArgs &args)
	Constructor with initial client arguments.

const UStringList &	additionalServerNames () const
	For a client connection, get all addition host names for the server's certificate verification during connect().

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

void	addVerifyServer (const UString &name)
	For a client connection, add another accepted host name for the server's certificate verification during connect().

virtual bool	asyncCompletedStream (IOSB *iosb) override
	Update the status of an asynchronous readStream() or writeStream() after it completed.

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.

virtual bool	closeWriter (bool silent=false) override
	Close the write direction of the connection.

virtual bool	connect (const IPSocketAddress &, IOSB *=nullptr) override
	Connect to a remote address and port.

virtual bool	disconnect (bool silent=false) override
	Disconnect from remote partner.

virtual bool	endOfStream () override
	Check if the end of stream was reached while reading.

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.

bool	getPeer (IPSocketAddress &addr)
	Get the connected remote peer.

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	isConnected () const
	Check if the socket is connected.

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

bool	isOpen () const
	Check if socket is open.

virtual bool	isReadStream () override
	Check if the stream is open for read.

bool	isServerSide () const
	Check if the socket is the server-side end of a connection.

bool	isSupportedByReactor (bool recheck=false)
	Check if the device is supported by a reactor for non-blocking or asynchronous I/O.

virtual bool	isWriteStream () override
	Check if the stream is open for write.

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.

UString	peerName ()
	Get the connected remote peer as a string.

virtual bool	readStream (void addr, size_t max_size, size_t &ret_size, const AbortInterface abort=nullptr, IOSB *iosb=nullptr) override
	Read some data from the stream.

virtual bool	readStream (void addr, size_t size, const AbortInterface abort=nullptr) override
	Read complete data from the stream.

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

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

const UString &	serverName () const
	For a client connection, get the server name to be used in SNI (Server Name Indication).

void	setArgs (const TLSArgs &args)
	Set command line arguments for the client.

bool	setConnectStatus (IOSB *iosb, int error_code)
	Update the status of an asynchronous connect().

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.

void	setServerName (const UString &server_name)
	For a client connection, specify the server name to be used in SNI (Server Name Indication).

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

void	setVerifyPeer (bool on)
	Define if the peer's certificate shall be verified.

bool	verifyPeer () const
	Check if the peer's certificate shall be verified.

virtual bool	writeStream (const void addr, size_t size, IOSB iosb=nullptr) override
	Write data to the stream.

virtual bool	writeStream (const void addr, size_t size, size_t &written_size, IOSB iosb=nullptr) override
	Write some data to the stream.

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.

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.

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) override
	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.

Static Protected Member Functions
template<class T > requires std::derived_from<T, StreamInterface>
static bool	ReadStreamHelper (T obj, void addr, size_t size, const AbortInterface *abort)
	Implementation helper for fixed-size version of readStream().

template<class T > requires std::derived_from<T, StreamInterface>
static bool	WriteStreamHelper (T obj, const void addr, size_t size, NonBlockingDevice::IOSB *iosb)
	Implementation helper for fixed-size version of writeStream().

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

Detailed Description

SSL/TLS connected socket, for data communication.

This class is used in two contexts:

A TLS client creates a TLSConnection instance and connects to a server.
A TLS server creates a TLSServer instance and waits for clients. For each client session, a TLSConnection instance is created.

Possible public servers to test various invalid certificates:

Constructor & Destructor Documentation

◆ TLSConnection() [1/4]

ts::TLSConnection::TLSConnection ( Report * report )

explicit

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.

◆ TLSConnection() [2/4]

ts::TLSConnection::TLSConnection ( ReporterBase * delegate )

explicit

Constructor.

Parameters

[in] delegate Use the report of another ReporterBase. If delegate is null, log messages are discarded.

◆ TLSConnection() [3/4]

ts::TLSConnection::TLSConnection	(	Report *	report,
		const TLSArgs &	args
	)

inline

Constructor with initial client arguments.

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]	args	Initial TLS client arguments.

◆ TLSConnection() [4/4]

ts::TLSConnection::TLSConnection	(	ReporterBase *	delegate,
		const TLSArgs &	args
	)

inline

Constructor with initial client arguments.

Parameters

[in]	delegate	Use the report of another ReporterBase. If delegate is null, log messages are discarded.
[in]	args	Initial TLS client arguments.

Member Function Documentation

◆ connect()

virtual bool ts::TLSConnection::connect	(	const IPSocketAddress &	addr,
		IOSB *	iosb = `nullptr`
	)

overridevirtual

Connect to a remote address and port.

Use this method when acting as TCP client. Do not use on server side: the TCPConnection object is passed to TCPServer::accept() which establishes the connection.

Parameters

[in]	addr	IP address and port of the server to connect to.
[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 connection is successfully started but still pending, iosb->pending is set to true and the method returns true.

Reimplemented from ts::TCPConnection.

◆ closeWriter()

virtual bool ts::TLSConnection::closeWriter ( bool silent = false )

overridevirtual

Close the write direction of the connection.

The application shall call this routine after sending the last message but may still want to receive messages, waiting for the peer to voluntary disconnect.

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::TCPConnection.

◆ disconnect()

virtual bool ts::TLSConnection::disconnect ( bool silent = false )

overridevirtual

Disconnect from remote partner.

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::TCPConnection.

◆ readStream() [1/2]

virtual bool ts::TLSConnection::readStream	(	void *	addr,
		size_t	size,
		const AbortInterface *	abort = `nullptr`
	)

overridevirtual

Read complete data from the stream.

Read exactly size bytes, waiting if necessary.

Synchronization: There is no iosb parameter because this method uses blocking I/O by design. An error is returned if the instance of the class which implements StreamInterface is in non-blocking mode.

Parameters

[out]	addr	Address of the buffer for the incoming data.
[in]	size	Size in bytes of the buffer.
[in]	abort	If non-zero, invoked when I/O is interrupted (in case of user-interrupt, return, otherwise retry).

Returns: True on success, false on error or it less than size bytes could be read.

Reimplemented from ts::TCPConnection.

◆ readStream() [2/2]

virtual bool ts::TLSConnection::readStream	(	void *	addr,
		size_t	max_size,
		size_t &	ret_size,
		const AbortInterface *	abort = `nullptr`,
		IOSB *	iosb = `nullptr`
	)

overridevirtual

Read some data from the stream.

Wait and read at least one byte. Don't try to read exactly max_size bytes. If ret_size is less than max_bytes, it is possible to read more.

Parameters

[out]	addr	Address of the buffer for the incoming data.
[in]	max_size	Maximum size in bytes of the buffer.
[out]	ret_size	Returned input size in bytes. If zero, end of file has been reached or an error occurred.
[in]	abort	If non-zero, invoked when I/O is interrupted (in case of user-interrupt, return, otherwise retry).
[in,out]	iosb	Address 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. 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 I/O is successfully started but still pending, iosb->pending is set to true and the method returns true.

Reimplemented from ts::TCPConnection.

◆ writeStream() [1/2]

virtual bool ts::TLSConnection::writeStream	(	const void *	addr,
		size_t	size,
		IOSB *	iosb = `nullptr`
	)

overridevirtual

Write data to the stream.

All bytes are written to the stream, blocking or retrying when necessary when the stream is in blocking mode. The base implementation of writeStream() uses the virtual version with a written_size output parameter.

Parameters

[in]	addr	Address of the data to write.
[in]	size	Size in bytes of the data to write.
[in,out]	iosb	Address 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. 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 or it less than size bytes could be written. In case of non-blocking mode, if the I/O is successfully started but still pending, iosb->pending is set to true and the method returns true.

Reimplemented from ts::TCPConnection.

◆ writeStream() [2/2]

virtual bool ts::TLSConnection::writeStream	(	const void *	addr,
		size_t	size,
		size_t &	written_size,
		IOSB *	iosb = `nullptr`
	)

overridevirtual

Write some data to the stream.

All bytes are written to the stream, blocking or retrying when necessary when the stream is in blocking mode. Return the number of actually written bytes if some error occurred before writing everything.

Parameters

[in]	addr	Address of the data to write.
[in]	size	Size in bytes of the data to write.
[out]	written_size	Actually written size in bytes. Can be less than size in case of error in the middle of the write.
[in,out]	iosb	Address 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. 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 I/O is successfully started but still pending, iosb->pending is set to true and the method returns true.

Reimplemented from ts::TCPConnection.

◆ setConnectStatus()

bool ts::TCPConnection::setConnectStatus	(	IOSB *	iosb,
		int	error_code
	)

inherited

Update the status of an asynchronous connect().

With non-blocking I/O, error_code shall be the error from the write-ready notification.
With asynchronous I/O, iosb is used to complete the socket state.
Parameters

[in,out] iosb Address of the IOSB structure which was used when connect() was called.

[in] error_code Error code in the context of the connection.

Returns
True on success, false on error.

◆ isConnected()

bool ts::TCPConnection::isConnected ( ) const

inlineinherited

Check if the socket is connected.

Returns: True if the socket was successfully connected to the peer.

◆ isServerSide()

bool ts::TCPConnection::isServerSide ( ) const

inlineinherited

Check if the socket is the server-side end of a connection.

Returns: True if the socket is the server-side end of a connection, where the connection is the result of an accept(). False if the socket is the client-side end of a connection, where the connection used connect().

◆ getPeer()

bool ts::TCPConnection::getPeer ( IPSocketAddress & addr )

inherited

Get the connected remote peer.

Parameters

[out] addr IP address and port of the remote socket.

Returns: True on success, false on error.

◆ peerName()

UString ts::TCPConnection::peerName ( )

inherited

Get the connected remote peer as a string.

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

◆ asyncCompletedStream()

virtual bool ts::TCPConnection::asyncCompletedStream ( IOSB * iosb )

overridevirtualinherited

Update the status of an asynchronous readStream() or writeStream() after it completed.

This method applies to asynchronous I/O only (Windows), not non-blocking I/O (UNIX).

Parameters

[in,out] iosb Address of the IOSB structure which was used when readStream() or writeStream() was called.

Returns: True on success, false on error.

Implements ts::StreamInterface.

◆ isReadStream()

virtual bool ts::TCPConnection::isReadStream ( )

overridevirtualinherited

Check if the stream is open for read.

Returns: True if readStream() is possible, false otherwise (write-only, closed, or disconnected stream).

Implements ts::StreamInterface.

◆ isWriteStream()

virtual bool ts::TCPConnection::isWriteStream ( )

overridevirtualinherited

Check if the stream is open for write.

Returns: True if writeStream() is possible, false otherwise (read-only, closed, or disconnected stream).

Implements ts::StreamInterface.

◆ endOfStream()

virtual bool ts::TCPConnection::endOfStream ( )

overridevirtualinherited

Check if the end of stream was reached while reading.

Returns: True on end of stream, false otherwise.

Implements ts::StreamInterface.

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

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

◆ getReadHandle()

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

overridevirtualinherited

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

overridevirtualinherited

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.

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

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

◆ 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] recheck If 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_code System 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_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 ( bool non_blocking )

protectedinherited

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

Parameters

[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

◆ 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]	addr	Address of the data to write.
[in]	size	Size in bytes of the data to write.
[out]	written_size	Actually written size in bytes. Can be less than size in case of error in the middle of the write.
[in,out]	iosb	Address 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]	position	This 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]	addr	Address of the buffer for the incoming data.
[in]	max_size	Maximum size in bytes of the buffer.
[out]	ret_size	Returned input size in bytes. If zero, end of file has been reached or an error occurred.
[in]	abort	If non-zero, invoked when I/O is interrupted (in case of user-interrupt, return, otherwise retry).
[in,out]	iosb	Address 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]	position	This 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] 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,
		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]	silent	If true, do not report errors, report debug messages instead.
[in]	default_severity	Default 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] handler The object to call on open() and close().

◆ cancelSubscription()

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

inherited

Remove a subscriber to open/close events.

Parameters

[in] handler The 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] func Function to call as lambda expression.

◆ WriteStreamHelper()

template<class T >
requires std::derived_from<T, StreamInterface>

static bool ts::StreamInterface::WriteStreamHelper	(	T *	obj,
		const void *	addr,
		size_t	size,
		NonBlockingDevice::IOSB *	iosb
	)

inlinestaticprotectedinherited

Implementation helper for fixed-size version of writeStream().

Often, the fixed-size version can be implemented using the variable-size version. However, this works well at a given derivation stage only.

Assume that:

We implement the fixed-size version inside StreamInterface, using the virtual variable-size version.
Class A implements StreamInterface and implements the variable-size version only. The base fixed-size version StreamInterface::writeStream() uses the virtual variable-size version A::writeStream() and it works well.
Class B derives from A. It is an encrypted version of A (think A=TCP, B=TLS). If the implementation of B wants to write raw data (after encryption) calling the fixed-size version A::writeStream(), then this will end up calling the virtual variable-size version B::writeStream(), which will try to encrypt already encrypted data. This is why it is important that each layer of inheritance calls its own version of writeStream().

Template Parameters

T	A subclass of StreamInterface. Write data to the stream. All bytes are written to the stream, blocking or retrying when necessary when the stream is in blocking mode. The base implementation of writeStream() uses the virtual version with a written_size output parameter.

Parameters

[in,out]	obj	Object of class T.
[in]	addr	Address of the data to write.
[in]	size	Size in bytes of the data to write.
[in,out]	iosb	Address 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. 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 or it less than size bytes could be written. In case of non-blocking mode, if the I/O is successfully started but still pending, iosb->pending is set to true and the method returns true.

◆ ReadStreamHelper()

template<class T >
requires std::derived_from<T, StreamInterface>

static bool ts::StreamInterface::ReadStreamHelper	(	T *	obj,
		void *	addr,
		size_t	size,
		const AbortInterface *	abort
	)

inlinestaticprotectedinherited

Implementation helper for fixed-size version of readStream().

See writeStreamHelper() for a rationale.

Template Parameters

T	A subclass of StreamInterface.

Parameters

[in,out]	obj	Object of class T.
[out]	addr	Address of the buffer for the incoming data.
[in]	size	Size in bytes of the buffer.
[in]	abort	If non-zero, invoked when I/O is interrupted (in case of user-interrupt, return, otherwise retry).

Returns: True on success, false on error or it less than size bytes could be read.

◆ setArgs()

void ts::TLSConnectionBase::setArgs ( const TLSArgs & args )

inherited

Set command line arguments for the client.

Parameters

[in] args TLS arguments.

◆ setVerifyPeer()

void ts::TLSConnectionBase::setVerifyPeer ( bool on )

inlineinherited

Define if the peer's certificate shall be verified.

Parameters

[in] on If true, the peer's certificate will be verified.

◆ verifyPeer()

bool ts::TLSConnectionBase::verifyPeer ( ) const

inlineinherited

Check if the peer's certificate shall be verified.

Returns: True if the peer's certificate will be verified.

◆ setServerName()

void ts::TLSConnectionBase::setServerName ( const UString & server_name )

inherited

For a client connection, specify the server name to be used in SNI (Server Name Indication).

Parameters

[in] server_name Main server name, as specified in SNI (Server Name Indication). Also used to verify the server's certificate when setVerifyPeer() is true.

◆ serverName()

const UString & ts::TLSConnectionBase::serverName ( ) const

inlineinherited

For a client connection, get the server name to be used in SNI (Server Name Indication).

Returns: A constant reference to the main server name.

◆ addVerifyServer()

void ts::TLSConnectionBase::addVerifyServer ( const UString & name )

inherited

For a client connection, add another accepted host name for the server's certificate verification during connect().

The list is reset by setServerName().

Parameters

[in] name Additional accepted host name used to verify the server's certificate.

See also: setServerName()

◆ additionalServerNames()

const UStringList & ts::TLSConnectionBase::additionalServerNames ( ) const

inlineinherited

For a client connection, get all addition host names for the server's certificate verification during connect().

Returns: A constant reference to all addition host names.

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

tsTLSConnection.h

[in,out]	iosb	Address of the IOSB structure which was used when connect() was called.
[in]	error_code	Error code in the context of the connection.

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ TLSConnection() [1/4]

◆ TLSConnection() [2/4]

◆ TLSConnection() [3/4]

◆ TLSConnection() [4/4]

Member Function Documentation

◆ connect()

◆ closeWriter()

◆ disconnect()

◆ readStream() [1/2]

◆ readStream() [2/2]

◆ writeStream() [1/2]

◆ writeStream() [2/2]

◆ setConnectStatus()

◆ isConnected()

◆ isServerSide()

◆ getPeer()

◆ peerName()

◆ asyncCompletedStream()

◆ isReadStream()

◆ isWriteStream()

◆ endOfStream()

◆ setTTL()

◆ setNoLinger()

◆ setLingerTime()

◆ setKeepAlive()

◆ setNoDelay()

◆ openImplementation()

◆ open()

◆ close()

◆ isOpen()

◆ generation()

◆ setSendBufferSize()

◆ setReceiveBufferSize()

◆ setReceiveTimeout()

◆ reusePort()

◆ bind()

◆ getLocalAddress()

◆ localName()

◆ getReadHandle()

◆ getWriteHandle()

◆ createSocket()

◆ convert()

◆ allowSetNonBlocking()

◆ setNonBlocking()

◆ isNonBlocking()

◆ isSupportedByReactor()

◆ IsPendingStatus()

◆ getHandle()

◆ getSocket()

◆ getReadSocket()

◆ getWriteSocket()

◆ checkNonBlocking() [1/2]

◆ checkNonBlocking() [2/2]

◆ setSystemNonBlocking()

◆ genericSystemWrite()

◆ genericSystemRead()

◆ report()

◆ setReport() [1/2]

◆ setReport() [2/2]

◆ muteReport()

◆ SilentLevel()

◆ addSubscription()

◆ cancelSubscription()

◆ callSubscribers()

◆ WriteStreamHelper()

◆ ReadStreamHelper()

◆ setArgs()

◆ setVerifyPeer()

◆ verifyPeer()

◆ setServerName()

◆ serverName()

◆ addVerifyServer()