E-MailRelay
|
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>
Classes | |
struct | Config |
A structure containing GNet::Client configuration parameters. More... | |
Public Member Functions | |
Client (ExceptionSink, 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 (G::string_view data) |
Overload for string_view. More... | |
bool | send (const std::vector< G::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 | |
Client & | operator= (const Client &)=delete |
Client & | operator= (Client &&)=delete |
bool | send (const char *, std::size_t)=delete |
bool | send (const char *)=delete |
bool | send (const std::string &, std::size_t)=delete |
![]() | |
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... | |
![]() | |
virtual std::string | exceptionSourceId () const |
Returns an identifying string for logging purposes, or the empty string. More... | |
virtual | ~ExceptionSource () |
Destructor. More... | |
ExceptionSource (const ExceptionSource &)=delete | |
ExceptionSource (ExceptionSource &&)=delete | |
ExceptionSource & | operator= (const ExceptionSource &)=delete |
ExceptionSource & | operator= (ExceptionSource &&)=delete |
Protected Member Functions | |
StreamSocket & | socket () |
Returns a reference to the socket. Throws if not connected. More... | |
const StreamSocket & | socket () 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 just before ClientPtr destroys the Client as the result of handling an exception. More... | |
void | secureConnect () |
Starts TLS/SSL client-side negotiation. More... | |
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 ExceptionSink object should be the ClientPtr instance. Clients that decide to terminate themselves cleanly should call Client::finish() and then throw a GNet::Done exception.
GNet::Client::Client | ( | ExceptionSink | es, |
const Location & | remote_location, | ||
const Config & | config | ||
) |
Constructor.
If not auto-starting then connect() is required to start connecting. The ExceptionSink 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.
|
override |
Destructor.
Definition at line 57 of file gclient.cpp.
|
protected |
Clears the input LineBuffer and cancels the response timer if running.
Definition at line 106 of file gclient.cpp.
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 118 of file gclient.cpp.
bool GNet::Client::connected | ( | ) | const |
Returns true if connected to the peer.
Definition at line 398 of file gclient.cpp.
|
overridevirtual |
Returns the connection state display string.
Override from GNet::Connection.
Implements GNet::Connection.
Definition at line 459 of file gclient.cpp.
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 63 of file gclient.cpp.
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 236 of file gclient.cpp.
|
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 82 of file gclient.cpp.
|
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 212 of file gclient.cpp.
bool GNet::Client::finished | ( | ) | const |
Returns true if finish() has been called.
Definition at line 226 of file gclient.cpp.
bool GNet::Client::hasConnected | ( | ) | const |
Returns true if ever connected().
Definition at line 231 of file gclient.cpp.
GNet::LineBufferState GNet::Client::lineBuffer | ( | ) | const |
Returns information about the state of the internal line-buffer.
Definition at line 512 of file gclient.cpp.
|
overridevirtual |
Returns the local address.
Override from GNet::Connection.
Implements GNet::Connection.
Definition at line 429 of file gclient.cpp.
|
protectedpure virtual |
Called just before ClientPtr destroys the Client as the result of handling an exception.
The reason is the empty string 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.
|
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.
|
overridevirtual |
Returns the peer address.
Throws if not connected(). Override from GNet::Connection.
Implements GNet::Connection.
Definition at line 434 of file gclient.cpp.
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 446 of file gclient.cpp.
|
overridevirtual |
Returns the peer's TLS certificate.
Override from GNet::Connection.
Implements GNet::Connection.
Definition at line 467 of file gclient.cpp.
GNet::Location GNet::Client::remoteLocation | ( | ) | const |
Returns a Location structure, including the result of name lookup if available.
Definition at line 87 of file gclient.cpp.
|
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 479 of file gclient.cpp.
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 473 of file gclient.cpp.
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 486 of file gclient.cpp.
bool GNet::Client::send | ( | const std::vector< G::string_view > & | data, |
std::size_t | offset = 0 |
||
) |
Overload for scatter/gather segments.
Definition at line 501 of file gclient.cpp.
bool GNet::Client::send | ( | G::string_view | data | ) |
Overload for string_view.
Definition at line 493 of file gclient.cpp.
|
protected |
Returns a reference to the socket. Throws if not connected.
Definition at line 92 of file gclient.cpp.
|
protected |
Returns a const reference to the socket. Throws if not connected.
Definition at line 99 of file gclient.cpp.