E-MailRelay
Classes | Public Member Functions | Protected Member Functions | List of all members
GNet::Client Class Referenceabstract

A class for making an outgoing connection to a remote server, with support for socket-level protocols such as TLS/SSL and SOCKS 4a. More...

#include <gclient.h>

+ Inheritance diagram for GNet::Client:
+ Collaboration diagram for GNet::Client:

Classes

struct  Config
 A structure containing GNet::Client configuration parameters. More...
 

Public Member Functions

 Client (EventState, const Location &remote_location, const Config &)
 Constructor. More...
 
 ~Client () override
 Destructor. More...
 
void connect ()
 Initiates a connection to the remote server. More...
 
bool connected () const
 Returns true if connected to the peer. More...
 
bool hasConnected () const
 Returns true if ever connected(). More...
 
std::string peerAddressString (bool with_port=true) const
 Returns the peer address display string or the empty string if not connected(). More...
 
void disconnect ()
 Aborts the connection and destroys the object's internal state, resulting in a zombie object. More...
 
Address localAddress () const override
 Returns the local address. More...
 
Address peerAddress () const override
 Returns the peer address. More...
 
std::string connectionState () const override
 Returns the connection state display string. More...
 
std::string peerCertificate () const override
 Returns the peer's TLS certificate. More...
 
Location remoteLocation () const
 Returns a Location structure, including the result of name lookup if available. More...
 
bool send (const std::string &data)
 Sends data to the peer and starts the response timer (if configured). More...
 
bool send (std::string_view data)
 Overload for string_view. More...
 
bool send (const std::vector< std::string_view > &data, std::size_t offset=0)
 Overload for scatter/gather segments. More...
 
G::Slot::Signal< const std::string &, const std::string &, const std::string & > & eventSignal () noexcept
 Returns a signal that indicates that something interesting has happened. More...
 
void doOnDelete (const std::string &reason, bool done)
 This should be called by the Client owner (typically ClientPtr) just before this Client object is deleted as the result of an exception. More...
 
bool finished () const
 Returns true if finish() has been called. More...
 
LineBufferState lineBuffer () const
 Returns information about the state of the internal line-buffer. More...
 
bool secureConnectCapable () const
 Returns true if currently connected and secureConnect() can be used. More...
 
 Client (const Client &)=delete
 
 Client (Client &&)=delete
 
Clientoperator= (const Client &)=delete
 
Clientoperator= (Client &&)=delete
 
bool send (const char *, std::size_t)=delete
 
bool send (const char *)=delete
 
bool send (const std::string &, std::size_t)=delete
 
- Public Member Functions inherited from GNet::Connection
virtual ~Connection ()=default
 Destructor.
 
virtual Address localAddress () const =0
 Returns the connection's local address. More...
 
virtual Address peerAddress () const =0
 Returns the connection's peer address. More...
 
virtual std::string connectionState () const =0
 Returns the connection state as a display string. More...
 
virtual std::string peerCertificate () const =0
 Returns the peer's TLS certificate. More...
 
- Public Member Functions inherited from GNet::ExceptionSource
virtual ~ExceptionSource ()
 Destructor.
 
 ExceptionSource (const ExceptionSource &)=delete
 
 ExceptionSource (ExceptionSource &&)=delete
 
ExceptionSourceoperator= (const ExceptionSource &)=delete
 
ExceptionSourceoperator= (ExceptionSource &&)=delete
 

Protected Member Functions

StreamSocketsocket ()
 Returns a reference to the socket. Throws if not connected. More...
 
const StreamSocketsocket () const
 Returns a const reference to the socket. Throws if not connected. More...
 
void finish ()
 Indicates that the last data has been sent and the client is expecting a peer disconnect. More...
 
void clearInput ()
 Clears the input LineBuffer and cancels the response timer if running. More...
 
virtual bool onReceive (const char *data, std::size_t size, std::size_t eolsize, std::size_t linesize, char c0)=0
 Called with received data. More...
 
virtual void onConnect ()=0
 Called once connected.
 
virtual void onSendComplete ()=0
 Called when all residual data from send() has been sent.
 
virtual void onDelete (const std::string &reason)=0
 Called from doOnDelete(), typically just before a ClientPtr destroys the Client as the result of handling an exception. More...
 
void secureConnect ()
 Starts TLS/SSL client-side negotiation. More...
 

Detailed Description

A class for making an outgoing connection to a remote server, with support for socket-level protocols such as TLS/SSL and SOCKS 4a.

The class handles name-to-address resolution, deals with connection issues, reads incoming data, and manages flow-control when sending. The implementation uses the SocketProtocol class in order to do TLS/SSL; see secureConnect().

Name-to-address lookup is performed if the supplied Location object does not contain an address. This can be done synchronously or asynchronously. The results of the lookup can be obtained via the remoteLocation() method and possibly fed back to the next Client that connects to the same host/service in order to implement name lookup cacheing.

Received data is delivered through a virtual method onReceive(), with optional line-buffering.

Clients should normally be instantiated on the heap and managed by a ClientPtr so that the onDelete() mechanism works as advertised: the ExceptionHandler passed to the Client constructor via the EventState object should be the ClientPtr instance. Clients that decide to terminate themselves cleanly should call Client::finish() and then throw a GNet::Done exception. If finish() has not been called then a disconnection results in an exception being thrown.

Definition at line 77 of file gclient.h.

Constructor & Destructor Documentation

◆ Client()

GNet::Client::Client ( EventState  es,
const Location remote_location,
const Config config 
)

Constructor.

If not auto-starting then connect() is required to start connecting. The EventState exception handler should delete this Client object when an exception is delivered to it, otherwise the the underlying socket might continue to raise events.

Definition at line 37 of file gclient.cpp.

◆ ~Client()

GNet::Client::~Client ( )
override

Destructor.

Definition at line 54 of file gclient.cpp.

Member Function Documentation

◆ clearInput()

void GNet::Client::clearInput ( )
protected

Clears the input LineBuffer and cancels the response timer if running.

Definition at line 103 of file gclient.cpp.

◆ connect()

void GNet::Client::connect ( )

Initiates a connection to the remote server.

Calls back to onConnect() when complete (non-reentrantly). Throws on immediate failure.

Definition at line 115 of file gclient.cpp.

◆ connected()

bool GNet::Client::connected ( ) const

Returns true if connected to the peer.

Definition at line 395 of file gclient.cpp.

◆ connectionState()

std::string GNet::Client::connectionState ( ) const
overridevirtual

Returns the connection state display string.

Override from GNet::Connection.

Implements GNet::Connection.

Definition at line 456 of file gclient.cpp.

◆ disconnect()

void GNet::Client::disconnect ( )

Aborts the connection and destroys the object's internal state, resulting in a zombie object.

After disconnect() only calls to hasConnected(), finished() and the dtor are allowed.

Definition at line 60 of file gclient.cpp.

◆ doOnDelete()

void GNet::Client::doOnDelete ( const std::string &  reason,
bool  done 
)

This should be called by the Client owner (typically ClientPtr) just before this Client object is deleted as the result of an exception.

A Client onDelete() call only ever comes from something external calling doOnDelete().

The 'done' argument should be true if the current exception is GNet::Done. The 'reason' string passed to onDelete() will be the given 'reason' or the empty string if 'done||finished()'.

See also GNet::ExceptionHandler::onException(), GNet::ServerPeer::onDelete().

Definition at line 233 of file gclient.cpp.

◆ eventSignal()

G::Slot::Signal< const std::string &, const std::string &, const std::string & > & GNet::Client::eventSignal ( )
noexcept

Returns a signal that indicates that something interesting has happened.

The first signal parameter is one of "resolving", "connecting", or "connected", but other classes may inject the own events into this channel.

Definition at line 79 of file gclient.cpp.

◆ finish()

void GNet::Client::finish ( )
protected

Indicates that the last data has been sent and the client is expecting a peer disconnect.

Any subsequent onDelete() callback from doOnDelete() will have an empty reason string.

Definition at line 209 of file gclient.cpp.

◆ finished()

bool GNet::Client::finished ( ) const

Returns true if finish() has been called.

Definition at line 223 of file gclient.cpp.

◆ hasConnected()

bool GNet::Client::hasConnected ( ) const

Returns true if ever connected().

Definition at line 228 of file gclient.cpp.

◆ lineBuffer()

GNet::LineBufferState GNet::Client::lineBuffer ( ) const

Returns information about the state of the internal line-buffer.

Definition at line 509 of file gclient.cpp.

◆ localAddress()

GNet::Address GNet::Client::localAddress ( ) const
overridevirtual

Returns the local address.

Override from GNet::Connection.

Implements GNet::Connection.

Definition at line 426 of file gclient.cpp.

◆ onDelete()

virtual void GNet::Client::onDelete ( const std::string &  reason)
protectedpure virtual

Called from doOnDelete(), typically just before a ClientPtr destroys the Client as the result of handling an exception.

The reason parameter will be forced to be the empty string rather than the doOnDelete() value if caused by a GNet::Done exception or after finish() or disconnect(). Consider making the implementation non-throwing, in the spirit of a destructor, since the Client object is about to be deleted.

◆ onReceive()

virtual bool GNet::Client::onReceive ( const char *  data,
std::size_t  size,
std::size_t  eolsize,
std::size_t  linesize,
char  c0 
)
protectedpure virtual

Called with received data.

If configured with no line buffering then only the first two parameters are relevant. The implementation should return false if it needs to stop further onReceive() calls being generated from data already received and buffered.

◆ peerAddress()

GNet::Address GNet::Client::peerAddress ( ) const
overridevirtual

Returns the peer address.

Throws if not connected(). Override from GNet::Connection.

Implements GNet::Connection.

Definition at line 431 of file gclient.cpp.

◆ peerAddressString()

std::string GNet::Client::peerAddressString ( bool  with_port = true) const

Returns the peer address display string or the empty string if not connected().

Definition at line 443 of file gclient.cpp.

◆ peerCertificate()

std::string GNet::Client::peerCertificate ( ) const
overridevirtual

Returns the peer's TLS certificate.

Override from GNet::Connection.

Implements GNet::Connection.

Definition at line 464 of file gclient.cpp.

◆ remoteLocation()

GNet::Location GNet::Client::remoteLocation ( ) const

Returns a Location structure, including the result of name lookup if available.

Definition at line 84 of file gclient.cpp.

◆ secureConnect()

void GNet::Client::secureConnect ( )
protected

Starts TLS/SSL client-side negotiation.

Uses a profile called "client" by default; see GSsl::Library::addProfile(). The callback GNet::SocketProtocolSink::onSecure() is triggered when the secure session is established.

Definition at line 476 of file gclient.cpp.

◆ secureConnectCapable()

bool GNet::Client::secureConnectCapable ( ) const

Returns true if currently connected and secureConnect() can be used.

Typically called from within the onConnect() callback.

Definition at line 470 of file gclient.cpp.

◆ send() [1/3]

bool GNet::Client::send ( const std::string &  data)

Sends data to the peer and starts the response timer (if configured).

Returns true if all sent. Returns false if flow control was asserted, in which case the unsent portion is copied internally and onSendComplete() called when complete. Throws on error.

Definition at line 483 of file gclient.cpp.

◆ send() [2/3]

bool GNet::Client::send ( const std::vector< std::string_view > &  data,
std::size_t  offset = 0 
)

Overload for scatter/gather segments.

Definition at line 498 of file gclient.cpp.

◆ send() [3/3]

bool GNet::Client::send ( std::string_view  data)

Overload for string_view.

Definition at line 490 of file gclient.cpp.

◆ socket() [1/2]

GNet::StreamSocket & GNet::Client::socket ( )
protected

Returns a reference to the socket. Throws if not connected.

Definition at line 89 of file gclient.cpp.

◆ socket() [2/2]

const GNet::StreamSocket & GNet::Client::socket ( ) const
protected

Returns a const reference to the socket. Throws if not connected.

Definition at line 96 of file gclient.cpp.


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