E-MailRelay
Public Types | Public Member Functions | Static Public Member Functions | Protected Member Functions | Static Protected Member Functions | List of all members
GNet::SimpleClient 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 <gsimpleclient.h>

+ Inheritance diagram for GNet::SimpleClient:

Public Types

enum  ConnectStatus { Success, Failure, ImmediateSuccess }
 
enum  State {
  Idle, Resolving, Connecting, Connected,
  Socksing, Testing
}
 
typedef std::string::size_type size_type
 
- Public Types inherited from GNet::EventHandler
enum  Reason {
  reason_closed, reason_down, reason_reset, reason_abort,
  reason_other
}
 

Public Member Functions

 SimpleClient (ExceptionHandler &, const Location &remote_info, bool bind_local_address=false, const Address &local_address=Address::defaultAddress(), bool sync_dns=synchronousDnsDefault(), unsigned int secure_connection_timeout=0U)
 Constructor. Call connect() to start connecting.
 
void connect ()
 Initates a connection to the remote server. More...
 
bool connected () const
 Returns true if connected to the peer.
 
virtual std::pair< bool, Address > localAddress () const override
 Override from Connection. More...
 
virtual std::pair< bool, Address > peerAddress () const override
 Override from Connection. More...
 
virtual std::string connectionState () const override
 Returns the connection state display string. More...
 
virtual std::string peerCertificate () const override
 Returns the peer's TLS certificate. More...
 
Location remoteLocation () const
 Returns a Location structure containing the result of host() and service() name lookup if available. More...
 
void updateLocation (const Location &)
 Updates the constructor's Location object with the given one as long as both objects have the same host and service name. More...
 
virtual void readEvent () override
 Override from GNet::EventHandler.
 
virtual void writeEvent () override
 Override from GNet::EventHandler.
 
virtual void otherEvent (EventHandler::Reason) override
 Override from GNet::EventHandler.
 
bool send (const std::string &data, std::string::size_type offset=0)
 Sends data to the peer. More...
 
- Public Member Functions inherited from GNet::EventHandler
virtual ~EventHandler ()
 Destructor.
 
- Public Member Functions inherited from GNet::Connection
virtual ~Connection ()
 Destructor.
 

Static Public Member Functions

static bool synchronousDnsDefault ()
 Returns true if DNS queries should normally be synchronous on this platform. More...
 
- Static Public Member Functions inherited from GNet::EventHandler
static std::string str (Reason)
 Returns a printable description of the other-event reason. More...
 

Protected Member Functions

virtual ~SimpleClient ()
 Destructor.
 
StreamSocket & socket ()
 Returns a reference to the socket. Throws if not connected.
 
const StreamSocket & socket () const
 Returns a const reference to the socket. Throws if not connected.
 
virtual void onConnect ()=0
 Called once connected.
 
virtual void onConnectImp ()
 An alternative to onConnect() for private implementation classes. More...
 
virtual void onSendComplete ()=0
 Called when all residual data from send() has been sent.
 
virtual void onSendImp ()
 Called from within send().
 
void secureConnect ()
 Starts TLS/SSL client-side negotiation. More...
 
std::string logId () const
 Returns a identification string for logging purposes. More...
 

Static Protected Member Functions

static bool connectError (const std::string &reason)
 Returns true if the reason string implies the SimpleClient::connect() failed. 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 SimpleClient that connects to the same host/service in order to implement name lookup cacheing (see GNet::ClientPtr). However, most operating systems implement their own name lookup cacheing, so this is not terribly useful in practice.

Definition at line 61 of file gsimpleclient.h.

Member Function Documentation

void GNet::SimpleClient::connect ( )

Initates a connection to the remote server.

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

Definition at line 103 of file gsimpleclient.cpp.

bool GNet::SimpleClient::connectError ( const std::string &  reason)
staticprotected

Returns true if the reason string implies the SimpleClient::connect() failed.

Definition at line 280 of file gsimpleclient.cpp.

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

Returns the connection state display string.

Override from GNet::Connection.

Implements GNet::Connection.

Definition at line 329 of file gsimpleclient.cpp.

std::pair< bool, GNet::Address > GNet::SimpleClient::localAddress ( ) const
overridevirtual

Override from Connection.

Returns the local address. Pair.first is false on error. Override from GNet::Connection.

Implements GNet::Connection.

Definition at line 313 of file gsimpleclient.cpp.

std::string GNet::SimpleClient::logId ( ) const
protected

Returns a identification string for logging purposes.

Not guaranteed to stay the same during the lifetime of the object.

Definition at line 67 of file gsimpleclient.cpp.

void GNet::SimpleClient::onConnectImp ( )
protectedvirtual

An alternative to onConnect() for private implementation classes.

The default implementation does nothing.

Reimplemented in GNet::Client.

Definition at line 354 of file gsimpleclient.cpp.

std::pair< bool, GNet::Address > GNet::SimpleClient::peerAddress ( ) const
overridevirtual

Override from Connection.

Returns the peer address. Pair.first is false on error. Override from GNet::Connection.

Implements GNet::Connection.

Definition at line 321 of file gsimpleclient.cpp.

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

Returns the peer's TLS certificate.

Override from GNet::Connection.

Implements GNet::Connection.

Definition at line 342 of file gsimpleclient.cpp.

GNet::Location GNet::SimpleClient::remoteLocation ( ) const

Returns a Location structure containing the result of host() and service() name lookup if available.

Definition at line 75 of file gsimpleclient.cpp.

void GNet::SimpleClient::secureConnect ( )
protected

Starts TLS/SSL client-side negotiation.

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

Definition at line 347 of file gsimpleclient.cpp.

bool GNet::SimpleClient::send ( const std::string &  data,
std::string::size_type  offset = 0 
)

Sends data to the peer.

Returns true if all sent, or false if flow control was asserted. Throws on error.

Definition at line 358 of file gsimpleclient.cpp.

bool GNet::SimpleClient::synchronousDnsDefault ( )
static

Returns true if DNS queries should normally be synchronous on this platform.

Used to default the relevant constructor parameter.

Definition at line 369 of file gsimpleclient.cpp.

void GNet::SimpleClient::updateLocation ( const Location &  update)

Updates the constructor's Location object with the given one as long as both objects have the same host and service name.

This is only useful immediately after construction and before re-entering the event loop.

Definition at line 80 of file gsimpleclient.cpp.


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