Kourier::TcpSocket Class Reference

The TcpSocket class represents a TCP socket. More...

Public Types
enum class	SocketOption {   LowDelay ,   KeepAlive ,   SendBufferSize ,   ReceiveBufferSize }
	Specifies the socket options that can be set and retrived. More...
enum class	State {   Unconnected ,   Connecting ,   Connected ,   Disconnecting }
	Connection state of TcpSocket. More...

Public Member Functions
	TcpSocket ()
	TcpSocket (int64_t socketDescriptor)
	~TcpSocket () override
void	abort ()
void	connect (std::string_view host, uint16_t port)
Signal	connected ()
Signal	disconnected ()
void	disconnectFromPeer ()
Signal	error ()
std::string_view	errorMessage () const
int	getSocketOption (SocketOption option) const
std::string_view	localAddress () const
uint16_t	localPort () const
std::string_view	peerAddress () const
std::string_view	peerName () const
uint16_t	peerPort () const
size_t	read (char *pBuffer, size_t maxSize) override
std::string_view	readAll () override
size_t	readBufferCapacity () const
void	setBindAddressAndPort (std::string_view address, uint16_t port=0)
bool	setReadBufferCapacity (size_t capacity)
void	setSocketOption (SocketOption option, int value)
size_t	skip (size_t maxSize) override
State	state () const
size_t	write (const char *pData, size_t maxSize) override
Public Member Functions inherited from Kourier::IOChannel
	IOChannel (const size_t readBufferCapacity=0)
	~IOChannel () override=default
void	clear ()
virtual size_t	dataAvailable () const
virtual size_t	dataToWrite () const
std::string_view	peekAll ()
char	peekChar (size_t index) const
virtual size_t	read (char *pBuffer, size_t maxSize)
virtual std::string_view	readAll ()
size_t	readBufferCapacity () const
Signal	receivedData ()
bool	reset ()
Signal	sentData (size_t count)
bool	setReadBufferCapacity (size_t capacity)
virtual size_t	skip (size_t maxSize)
std::string_view	slice (size_t pos, size_t count)
virtual size_t	write (const char *pData, size_t count)
size_t	write (std::string_view data)
Public Member Functions inherited from Kourier::Object
	Object ()
virtual	~Object ()
void	disconnect ()
template<class T_PtrToReceiverOrSignal >
void	disconnect (T_PtrToReceiverOrSignal pReceiverOrSignal)
void	scheduleForDeletion ()
template<class T >
T	tryCast ()
template<class T >
T	tryCast () const

Additional Inherited Members
Static Public Member Functions inherited from Kourier::Object
template<class T_PtrToSignal , class T_PtrToSlot >
static void	connect (MetaInvocable< T_PtrToSignal >::T_Class *pSender, T_PtrToSignal pSignal, MetaInvocable< T_PtrToSlot >::T_Class *pReceiver, T_PtrToSlot pSlot)
template<class T_PtrToSignal , class T_PtrToSlot >
static void	connect (MetaInvocable< T_PtrToSignal >::T_Class *pSender, T_PtrToSignal pSignal, Object *pReceiver, T_PtrToSlot pSlot)
template<class T_PtrToSignal , class T_PtrToSlot >
static void	connect (MetaInvocable< T_PtrToSignal >::T_Class *pSender, T_PtrToSignal pSignal, T_PtrToSlot pSlot)
template<class T_PtrToSignal , class T_PtrToSlot >
static void	disconnect (Object *pSender, T_PtrToSignal pSignal, Object *pReceiver, T_PtrToSlot pSlot)

Detailed Description

The TcpSocket class represents a TCP socket.

TcpSocket is a subclass of IOChannel and extends it to connection-oriented channels. You can use connected TcpSockets as channels for exchanging stream-oriented data with the connected peer.

You can call connect to start connecting to a peer. TcpSocket emits connected when it successfully establishes a connection. Otherwise, if TcpSocket fails to connect to the peer, it emits the error signal. TcpSocket waits for 60 seconds for a connection to be established before aborting. You can call errorMessage to fetch the last error that occurred. Before calling connect to start a connection, you can call setBindAddressAndPort to specify an address and, optionally, a port that TcpSocket should bind to before connecting to the peer.

You can call write to write data to a connected TcpSocket. TcpSocket emits the sentData signal when it writes data to the channel. You can call dataToWrite to know how much data is still pending to be written to the channel.

TcpSocket emits receivedData when it reads data from the channel. You can call read to read data from TcpSocket and dataAvailable to know how much data has been read from the channel and is available for reading.

A connected TcpSocket emits disconnected when the connection finishes. You can start a connection anytime by calling connect, even on slots connected to the error signal.

You can call disconnectFromPeer on a connected TcpSocket to start disconnecting from the peer. TcpSockets always perform a graceful shutdown when disconnecting by first writing all pending data to the channel, then disabling further send operations (by calling shutdown with SHUT_WR) and waiting for the peer to close the connection. TcpSocket only emits disconnected for graceful shutdowns. If any error occurs while disconnecting, TcpSocket emits the error signal. TcpSocket waits 10 seconds for a graceful shutdown before aborting the connection.

TcpSocket integrates epoll into Qt's event system and uses it to detect when TcpSocket is available for IO operations. Kourier can handle millions of sockets even on modest machines, as TcpSocket is very lightweight memory-wise.

Member Enumeration Documentation

SocketOption

enum class Kourier::TcpSocket::SocketOption

strong

Specifies the socket options that can be set and retrived.

Enumerator
LowDelay	Enables/Disables TCP_NODELAY.
KeepAlive	Enables/Disables SO_KEEPALIVE.
SendBufferSize	Sets/Retrieves SO_SNDBUF.
ReceiveBufferSize	Sets/Retrieves SO_RCVBUF.

State

enum class Kourier::TcpSocket::State

strong

Connection state of TcpSocket.

Enumerator
Unconnected	The socket is not connected. You can call connect to initiate a connection.
Connecting	The socket is connecting. TcpSocket emits the connected signal when the connection is established. Otherwise, TcpSocket emits the error signal if it fails to connect to the peer.
Connected	The socket is connected to the peer. You can call peerAddress and peerPort to fetch the connected peer's address and port.
Disconnecting	The socket is disconnecting. TcpSocket emits the disconnected signal when the connection terminates.

Constructor & Destructor Documentation

TcpSocket() [1/2]

Kourier::TcpSocket::TcpSocket

(

)

Creates a TcpSocket. The socket is created in the Unconnected state. You can call connect to connect to a peer.

TcpSocket() [2/2]

Kourier::TcpSocket::TcpSocket

(

int64_t

socketDescriptor

)

Creates a connected TcpSocket with socketDescriptor. TcpSocket aborts and closes the given descriptor if it does not represent a connected socket. You can call state to check if TcpSocket is in the Connected state.

Because TcpSocket takes ownership of the given socketDescriptor, disregarding whether the connection succeeded, you should not close the given descriptor.

~TcpSocket()

Kourier::TcpSocket::~TcpSocket ( )

override

Destroys the object and aborts the connection if TcpSocket is not in the Unconnected state.

Member Function Documentation

abort()

void Kourier::TcpSocket::abort

(

)

Aborts the connection immediately and enters the Unconnected state. Any pending data in the write buffer is discarded and not sent to the peer. TcpSocket does not emit the disconnected signal when the connection is aborted.

connect()

void Kourier::TcpSocket::connect	(	std::string_view	host,
		uint16_t	port
	)

Tries to connect to the peer at the given host and port. The host can be an IP address or a hostname, which TcpSocket will resolve before connecting. If TcpSocket is not in the Unconnected state, it aborts the previous connection before initiating the new one. TcpSocket emits the connected signal when the connection is successfully established. Otherwise, TcpSocket emits the error signal if an error occurs while trying to connect to the peer. You can call errorMessage to retrieve the specific error information. TcpSocket waits for 60 seconds for a connection to be established before aborting.

connected()

Signal Kourier::TcpSocket::connected

(

)

TcpSocket emits the connected signal when it successfully connects to the peer.

disconnected()

Signal Kourier::TcpSocket::disconnected

(

)

A connected TcpSocket emits the disconnected signal when it finishes disconnecting from the peer.

disconnectFromPeer()

void Kourier::TcpSocket::disconnectFromPeer

(

)

If TcpSocket is connected, it starts disconnecting from the peer and enters the Disconnecting state. In this state, TcpSocket ignores further write operations, but TcpSocket writes all data in the write buffer to the channel before disconnecting from the peer.

After writing all pending data in the write buffer to the channel, TcpSocket performs an orderly shutdown by disabling further send operations (by calling shutdown with SHUT_WR) and waiting for the peer to close the connection. TcpSocket emits the disconnected signal when the peer closes the connection, and the disconnection is complete. TcpSocket waits up to 10 seconds for the peer to close the connection before aborting. You can call abort to disconnect immediately.

error()

Signal Kourier::TcpSocket::error

(

)

TcpSocket emits this signal when an error occurs. You can call errorMessage to fetch the last error that occurred.

errorMessage()

std::string_view Kourier::TcpSocket::errorMessage

(

)

const

Returns the message for the last error that occurred.

getSocketOption()

int Kourier::TcpSocket::getSocketOption

(

SocketOption

option

)

const

Returns the value for the given option.

localAddress()

std::string_view Kourier::TcpSocket::localAddress

(

)

const

Returns the local address of the connected socket.

localPort()

uint16_t Kourier::TcpSocket::localPort

(

)

const

Returns the local port of the connected socket.

peerAddress()

std::string_view Kourier::TcpSocket::peerAddress

(

)

const

Returns the address of the connected peer.

peerName()

std::string_view Kourier::TcpSocket::peerName

(

)

const

Returns the name of the connected peer.

peerPort()

uint16_t Kourier::TcpSocket::peerPort

(

)

const

Returns the port of the connected peer.

read()

size_t Kourier::TcpSocket::read ( char *  pBuffer, size_t  maxSize  )

overridevirtual

reads up to maxSize from the read buffer into the buffer pointed by pBuffer. Returns the number of bytes read from the read buffer.

Reimplemented from Kourier::IOChannel.

Reimplemented in Kourier::TlsSocket.

readAll()

std::string_view Kourier::TcpSocket::readAll ( )

overridevirtual

returns all data in the read buffer. Writing to IOChannel after calling this method invalidates the returned data.

Reimplemented from Kourier::IOChannel.

Reimplemented in Kourier::TlsSocket.

readBufferCapacity()

Kourier::TcpSocket::readBufferCapacity ( ) const

inline

Returns the read buffer capacity. A value of zero means that capacity is not limited. If the returned value is positive, the read buffer can grow up to the returned value.

setBindAddressAndPort()

void Kourier::TcpSocket::setBindAddressAndPort	(	std::string_view	address,
		uint16_t	port = 0
	)

Sets the bind address and port that TcpSocket must bind to before connecting to the peer.

setReadBufferCapacity()

Kourier::TcpSocket::setReadBufferCapacity ( size_t  capacity )

inline

Sets the read buffer capacity. A value of zero means that the capacity is not limited. The read buffer can grow to the given value if the capacity is positive.

Returns true if the capacity was successfully changed. Setting a capacity can fail because this method does not delete data in the buffer. Thus, it is impossible to set a capacity to a value smaller than the data available in the read buffer.

setSocketOption()

void Kourier::TcpSocket::setSocketOption	(	SocketOption	option,
		int	value
	)

Sets value for the given option.

skip()

size_t Kourier::TcpSocket::skip ( size_t  maxSize )

overridevirtual

removes up to maxSize from the beginning of the read buffer. Returns the number of bytes removed.

Reimplemented from Kourier::IOChannel.

Reimplemented in Kourier::TlsSocket.

state()

TcpSocket::State Kourier::TcpSocket::state

(

)

const

Returns the state of the TcpSocket.

write()

size_t Kourier::TcpSocket::write ( const char *  pData, size_t  count  )

overridevirtual

writes count bytes from the buffer pointed by pData into the write buffer.

Reimplemented from Kourier::IOChannel.