TSDuck Version 3.15-964 (TSDuck - The MPEG Transport Stream Toolkit)
ts::TCPConnection Class Reference

Base class for a TCP/IP session. More...

Inheritance diagram for ts::TCPConnection:
Collaboration diagram for ts::TCPConnection:

Public Types

typedef TCPSocket SuperClass
 Reference to the superclass.
 

Public Member Functions

 TCPConnection ()
 Constructor.
 
bool bind (const SocketAddress &addr, Report &report=(*ts::CerrReport::Instance()))
 Bind to a local address and port. More...
 
virtual bool close (Report &report=(*ts::CerrReport::Instance())) override
 Close the socket. More...
 
bool closeWriter (Report &report=(*ts::CerrReport::Instance()))
 Close the write direction of the connection. More...
 
bool connect (const SocketAddress &addr, Report &report=(*ts::CerrReport::Instance()))
 Connect to a remote address and port. More...
 
bool disconnect (Report &report=(*ts::CerrReport::Instance()))
 Disconnect from remote partner. More...
 
bool getLocalAddress (SocketAddress &addr, Report &report=(*ts::CerrReport::Instance()))
 Get local socket address. More...
 
bool getPeer (SocketAddress &addr, Report &report=(*ts::CerrReport::Instance())) const
 Get the connected remote peer. More...
 
platform_specific getSocket () const
 Get the underlying socket device handle (use with care). More...
 
bool isConnected () const
 Check if the socket is connected. More...
 
bool isOpen () const
 Check if socket is open. More...
 
virtual bool open (Report &report=(*ts::CerrReport::Instance())) override
 Open the socket. More...
 
UString peerName () const
 Get the connected remote peer as a string. More...
 
bool receive (void *buffer, size_t max_size, size_t &ret_size, const AbortInterface *abort=0, Report &report=(*ts::CerrReport::Instance()))
 Receive data. More...
 
bool receive (void *buffer, size_t size, const AbortInterface *abort=0, Report &report=(*ts::CerrReport::Instance()))
 Receive data until buffer is full. More...
 
bool reusePort (bool reuse_port, Report &report=(*ts::CerrReport::Instance()))
 Set the "reuse port" option. More...
 
bool send (const void *data, size_t size, Report &report=(*ts::CerrReport::Instance()))
 Send data. More...
 
bool setKeepAlive (bool active, Report &report=(*ts::CerrReport::Instance()))
 Set the "keep alive" option. More...
 
bool setLingerTime (int seconds, Report &report=(*ts::CerrReport::Instance()))
 Set the linger time option. More...
 
bool setNoDelay (bool active, Report &report=(*ts::CerrReport::Instance()))
 Set the "no delay" option. More...
 
bool setNoLinger (Report &report=(*ts::CerrReport::Instance()))
 Remove the linger time option. More...
 
bool setReceiveBufferSize (size_t size, Report &report=(*ts::CerrReport::Instance()))
 Set the receive buffer size. More...
 
bool setReceiveTimeout (MilliSecond timeout, Report &report=(*ts::CerrReport::Instance()))
 Set the receive timeout. More...
 
bool setSendBufferSize (size_t size, Report &report=(*ts::CerrReport::Instance()))
 Set the send buffer size. More...
 
bool setTTL (int ttl, Report &report=(*ts::CerrReport::Instance()))
 Set the Time To Live (TTL) option. More...
 

Protected Member Functions

bool createSocket (int domain, int type, int protocol, Report &report)
 Create the socket. More...
 
virtual void declareOpened (platform_specific sock, Report &report) override
 Set an open socket descriptor from a subclass. More...
 
virtual void handleClosed (Report &report=(*ts::CerrReport::Instance())) override
 This virtual method can be overriden by subclasses to be notified of close. More...
 
virtual void handleConnected (Report &report=(*ts::CerrReport::Instance()))
 This virtual method can be overriden by subclasses to be notified of connection. More...
 
virtual void handleDisconnected (Report &report=(*ts::CerrReport::Instance()))
 This virtual method can be overriden by subclasses to be notified of disconnection. More...
 
virtual void handleOpened (Report &report)
 This virtual method can be overriden by subclasses to be notified of open. More...
 

Protected Attributes

Mutex _mutex
 Mutex protecting this object.
 

Detailed Description

Base class for a TCP/IP session.

This class can be used directly by applications or can be derived to create specific sub-classes which handle application protocols.

This class is used in two contexts:

  • A TCP/IP client creates a TCPConnection instance and connects to a server.
  • A TCP/IP server creates a TCPServer instance and waits for clients. For each client session, a TCPConnection instance is created.

For a detailed scenario of the server side, see the class TCPServer.

The following lists the typical client-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. Invoking disconnect() is also optional but is highly recommended. Closing a socket without prior disconnect is considered as a session abort by the remote peer. The peer may thus consider that something went wrong may take unexpected corrective or rollback actions.

Member Function Documentation

◆ connect()

bool ts::TCPConnection::connect ( const SocketAddress addr,
Report report = (*ts::CerrReport::Instance()) 
)

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]addrIP address and port of the server to connect.
[in,out]reportWhere to report error.
Returns
True on success, false on error.

◆ isConnected()

bool ts::TCPConnection::isConnected ( ) const
inline

Check if the socket is connected.

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

◆ getPeer()

bool ts::TCPConnection::getPeer ( SocketAddress addr,
Report report = (*ts::CerrReport::Instance()) 
) const

Get the connected remote peer.

Parameters
[out]addrIP address and port of the remote socket.
[in,out]reportWhere to report error.
Returns
True on success, false on error.

◆ peerName()

UString ts::TCPConnection::peerName ( ) const

Get the connected remote peer as a string.

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

◆ closeWriter()

bool ts::TCPConnection::closeWriter ( Report report = (*ts::CerrReport::Instance()))

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,out]reportWhere to report error.
Returns
True on success, false on error.

◆ disconnect()

bool ts::TCPConnection::disconnect ( Report report = (*ts::CerrReport::Instance()))

Disconnect from remote partner.

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

◆ send()

bool ts::TCPConnection::send ( const void *  data,
size_t  size,
Report report = (*ts::CerrReport::Instance()) 
)

Send data.

Parameters
[in]dataAddress of the data to send.
[in]sizeSize in bytes of the data to send.
[in,out]reportWhere to report error.
Returns
True on success, false on error.

◆ receive() [1/2]

bool ts::TCPConnection::receive ( void *  buffer,
size_t  max_size,
size_t &  ret_size,
const AbortInterface abort = 0,
Report report = (*ts::CerrReport::Instance()) 
)

Receive data.

This version of receive() returns when "some" data are received into the user buffer. The actual received data may be shorter than the user buffer size.

The version is typically useful when the application cannot predict how much data will be received and must respond even if the user buffer is not full.

Parameters
[out]bufferAddress of the buffer for the received data.
[in]max_sizeSize in bytes of the reception buffer.
[out]ret_sizeSize in bytes of the received data. Will never be larger than max_size.
[in]abortIf non-zero, invoked when I/O is interrupted (in case of user-interrupt, return, otherwise retry).
[in,out]reportWhere to report error.
Returns
True on success, false on error.

◆ receive() [2/2]

bool ts::TCPConnection::receive ( void *  buffer,
size_t  size,
const AbortInterface abort = 0,
Report report = (*ts::CerrReport::Instance()) 
)

Receive data until buffer is full.

This version of receive() returns only when sufficient data are received to completely fill the user buffer. The size of the actual received data is identical to the user buffer size.

The version is typically useful when the application knows that a certain amount of data is expected and must wait for them.

Parameters
[out]bufferAddress of the buffer for the received data.
[in]sizeSize in bytes of the buffer.
[in]abortIf non-zero, invoked when I/O is interrupted (in case of user-interrupt, return, otherwise retry).
[in,out]reportWhere to report error.
Returns
True on success, false on error.

◆ handleConnected()

virtual void ts::TCPConnection::handleConnected ( Report report = (*ts::CerrReport::Instance()))
inlineprotectedvirtual

This virtual method can be overriden by subclasses to be notified of connection.

All subclasses should explicitly invoke their superclass' handlers.

Parameters
[in,out]reportWhere to report error.

Reimplemented in ts::tlv::Connection< MUTEX >, and ts::tlv::Connection< ts::Mutex >.

◆ handleDisconnected()

virtual void ts::TCPConnection::handleDisconnected ( Report report = (*ts::CerrReport::Instance()))
inlineprotectedvirtual

This virtual method can be overriden by subclasses to be notified of disconnection.

All subclasses should explicitly invoke their superclass' handlers.

Parameters
[in,out]reportWhere to report error.

◆ handleClosed()

virtual void ts::TCPConnection::handleClosed ( Report report = (*ts::CerrReport::Instance()))
overrideprotectedvirtual

This virtual method can be overriden by subclasses to be notified of close.

All subclasses should explicitly invoke their superclass' handlers.

Parameters
[in,out]reportWhere to report error.

Reimplemented from ts::TCPSocket.

◆ setTTL()

bool ts::TCPSocket::setTTL ( int  ttl,
Report report = (*ts::CerrReport::Instance()) 
)
inherited

Set the Time To Live (TTL) option.

Parameters
[in]ttlThe TTL value, ie. the maximum number of "hops" between routers before an IP packet is dropped.
[in,out]reportWhere to report error.
Returns
True on success, false on error.

◆ setNoLinger()

bool ts::TCPSocket::setNoLinger ( Report report = (*ts::CerrReport::Instance()))
inherited

Remove the linger time option.

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

◆ setLingerTime()

bool ts::TCPSocket::setLingerTime ( int  seconds,
Report report = (*ts::CerrReport::Instance()) 
)
inherited

Set the linger time option.

Parameters
[in]secondsNumber of seconds to wait after shuting down the socket.
[in,out]reportWhere to report error.
Returns
True on success, false on error.

◆ setKeepAlive()

bool ts::TCPSocket::setKeepAlive ( bool  active,
Report report = (*ts::CerrReport::Instance()) 
)
inherited

Set the "keep alive" option.

Parameters
[in]activeIf true, the socket periodically sends "keep alive" packets when the connection is idle.
[in,out]reportWhere to report error.
Returns
True on success, false on error.

◆ setNoDelay()

bool ts::TCPSocket::setNoDelay ( bool  active,
Report report = (*ts::CerrReport::Instance()) 
)
inherited

Set the "no delay" option.

Parameters
[in]activeIf 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.
[in,out]reportWhere to report error.
Returns
True on success, false on error.

◆ bind()

bool ts::TCPSocket::bind ( const SocketAddress addr,
Report report = (*ts::CerrReport::Instance()) 
)
inherited

Bind to a local address and port.

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

  • IPAddress::AnyAddress. Any local interface may be used to connect to a server (client side) or to receive incoming client connections (server side).
  • The IP address of an interface of the local system. Outgoing connections (client side) will be only allowed through this interface. Incoming client connections (server side) will be accepted only when they arrive through the selected interface.

The port number part of the socket address must be one of:

  • SocketAddress::AnyPort. The socket is bound to an arbitrary unused local TCP port. This is the usual configuration for a TCP client.
  • A specific port number. This is the usual configuration for a TCP server. If this TCP port is already bound by another local TCP socket, the bind operation fails, unless the "reuse port" option has already been set.
Parameters
[in]addrLocal socket address to bind to.
[in,out]reportWhere to report error.
Returns
True on success, false on error.

◆ open()

virtual bool ts::TCPSocket::open ( Report report = (*ts::CerrReport::Instance()))
overridevirtualinherited

Open the socket.

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

Implements ts::Socket.

◆ close()

virtual bool ts::TCPSocket::close ( Report report = (*ts::CerrReport::Instance()))
overridevirtualinherited

Close the socket.

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

Reimplemented from ts::Socket.

Reimplemented in ts::TCPServer.

◆ handleOpened()

virtual void ts::TCPSocket::handleOpened ( Report report)
inlineprotectedvirtualinherited

This virtual method can be overriden by subclasses to be notified of open.

All subclasses should explicitly invoke their superclass' handlers.

Parameters
[in,out]reportWhere to report error.

◆ declareOpened()

virtual void ts::TCPSocket::declareOpened ( platform_specific  sock,
Report report 
)
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]sockNew socket descriptor.
[in,out]reportWhere to report error.

Reimplemented from ts::Socket.

◆ isOpen()

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

Check if socket is open.

Returns
True if socket is open.

◆ setSendBufferSize()

bool ts::Socket::setSendBufferSize ( size_t  size,
Report report = (*ts::CerrReport::Instance()) 
)
inherited

Set the send buffer size.

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

◆ setReceiveBufferSize()

bool ts::Socket::setReceiveBufferSize ( size_t  size,
Report report = (*ts::CerrReport::Instance()) 
)
inherited

Set the receive buffer size.

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

◆ setReceiveTimeout()

bool ts::Socket::setReceiveTimeout ( MilliSecond  timeout,
Report report = (*ts::CerrReport::Instance()) 
)
inherited

Set the receive timeout.

Parameters
[in]timeoutReceive timeout in milliseconds. If negative, receive timeout is not used.
[in,out]reportWhere to report error.
Returns
True on success, false on error.

◆ reusePort()

bool ts::Socket::reusePort ( bool  reuse_port,
Report report = (*ts::CerrReport::Instance()) 
)
inherited

Set the "reuse port" option.

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

◆ getLocalAddress()

bool ts::Socket::getLocalAddress ( SocketAddress addr,
Report report = (*ts::CerrReport::Instance()) 
)
inherited

Get local socket address.

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

◆ getSocket()

platform_specific ts::Socket::getSocket ( ) const
inlineinherited

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

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

Returns
The underlying socket system device handle or file descriptor. Return TS_SOCKET_T_INVALID if the socket is not open.

◆ createSocket()

bool ts::Socket::createSocket ( int  domain,
int  type,
int  protocol,
Report report 
)
protectedinherited

Create the socket.

Parameters
[in]domainSocket domain: PF_INET
[in]typeSocket type: SOCK_STREAM, SOCK_DGRAM
[in]protocolSocket protocol: IPPROTO_TCP, IPPROTO_UDP
[in,out]reportWhere to report error.
Returns
True on success, false on error.

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