- Main Page
- Namespaces
- Classes
- Files

- Class List
- Class Hierarchy
- Class Members

Public Types | Public Member Functions | Static Public Member Functions | Protected Member Functions | Static Protected Member Functions | Friends | 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, Retry, ImmediateSuccess }
enum | State { Idle, Resolving, Connecting, Connected, Socksing }
typedef std::string::size_type | size_type

## Public Member Functions
| SimpleClient (const ResolverInfo &remote_info, const Address &local_address=Address(0U), bool privileged=false, bool sync_dns=synchronousDnsDefault(), unsigned int secure_connection_timeout=0U)
| Constructor. More...
void | connect ()
| Initates a connection to the remote server. More...
bool | connected () const
| Returns true if connected to the peer. More...
virtual std::pair< bool, Address > | localAddress () const
| Override from Connection. More...
virtual std::pair< bool, Address > | peerAddress () const
| Override from Connection. More...
virtual std::string | peerCertificate () const
| Returns the peer's TLS certificate. More...
ResolverInfo | resolverInfo () const
| Returns a ResolverInfo structure containing the result of host() and service() name lookup if available. More...
void | updateResolverInfo (const ResolverInfo &)
| Updates the constructor's ResolverInfo object with the given one as long as both objects have the same host and service name. More...
virtual void | readEvent ()
| Final override from GNet::EventHandler. More...
virtual void | writeEvent ()
| Final override from GNet::EventHandler. More...
bool | send (const std::string &data, std::string::size_type offset=0)
| Returns true if all sent, or false if flow control was asserted. More...
Public Member Functions inherited from GNet::EventHandler
virtual | ~EventHandler ()
| Destructor. More...
virtual void | exceptionEvent ()
| Called for an exception event. More...
virtual void | onException (std::exception &)=0
| Called when an exception is thrown out of readEvent(), writeEvent() or exceptionEvent(). More...
Public Member Functions inherited from GNet::Connection
virtual | ~Connection ()
| Destructor. More...
Public Member Functions inherited from GNet::SocketProtocolSink
virtual | ~SocketProtocolSink ()
| Destructor. More...

## Static Public Member Functions
static bool | synchronousDnsDefault ()
| Returns true if DNS queries should normally be synchronous on this platform. More...

## Protected Member Functions
virtual | ~SimpleClient ()
| Destructor. More...
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...
virtual void | onConnect ()=0
| Called once connected. More...
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. More...
virtual void | onSendImp ()
| Called from within send(). More...
void | sslConnect ()
| Starts TLS/SSL client-side negotiation. More...
std::string | logId () const
| Returns a identification string for logging purposes. More...
Protected Member Functions inherited from GNet::SocketProtocolSink
virtual void | onData (const char *, std::string::size_type)=0
| Called when data is read from the socket. More...
virtual void | onSecure (const std::string &peer_certificate)=0
| Called once the secure socket protocol has been successfully negotiated. More...

## Static Protected Member Functions
static bool | canRetry (const std::string &reason)
| Parses the given failure reason and returns true if the client can reasonably retry at some later time. More...

## Friends
class | ClientResolver

## 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 sslConnect().

Name-to-address lookup is performed if the supplied ResolverInfo object does not contain an address. This can be done synchronously or asynchronously. The results of the lookup can be obtained via the resolverInfo() 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 81 of file gsimpleclient.h.

## Member Typedef Documentation

typedef std::string::size_type GNet::SimpleClient::size_type

Definition at line 86 of file gsimpleclient.h.

## Member Enumeration Documentation

enum GNet::SimpleClient::ConnectStatus

Enumerator
Success |
Failure |
Retry |
ImmediateSuccess |

Definition at line 84 of file gsimpleclient.h.

enum GNet::SimpleClient::State

Enumerator
Idle |
Resolving |
Connecting |
Connected |
Socksing |

Definition at line 85 of file gsimpleclient.h.

## Constructor & Destructor Documentation

GNet::SimpleClient::SimpleClient | ( | const ResolverInfo & | remote_info,
|  | const Address & | local_address = `Address(0U)`,
|  | bool | privileged = `false`,
|  | bool | sync_dns = `synchronousDnsDefault()`,
|  | unsigned int | secure_connection_timeout = `0U`
| ) |  |

Constructor.

If the 'privileged' parameter is true then the given 'local_address' is used to bind the local socket once its port number has been overwritten with a privileged port number (ie. < 1024) selected at random.

Otherwise, if the given 'local_address' is not the default value then it is used to bind the local socket.

Definition at line 47 of file gsimpleclient.cpp.

References GNet::Monitor::addClient(), G_DEBUG, and GNet::Monitor::instance().

GNet::SimpleClient::~SimpleClient | ( |  | ) |
| protected virtual

Destructor.

Definition at line 61 of file gsimpleclient.cpp.

References GNet::Monitor::instance(), and GNet::Monitor::removeClient().

## Member Function Documentation

bool GNet::SimpleClient::canRetry | ( | const std::string & | reason | ) |
| static protected

Parses the given failure reason and returns true if the client can reasonably retry at some later time.

(Not used?)

Definition at line 161 of file gsimpleclient.cpp.

void GNet::SimpleClient::connect | ( |  | ) |

Initates a connection to the remote server.

This default implementation throws on error, and may call onConnect() synchronously before returning. To ensure onConnect() is always called asynchronously it can be a good idea to call connect() from a zero-length timer (as HeapClient does).

Definition at line 103 of file gsimpleclient.cpp.

References G_DEBUG, G_WARNING, and GNet::Resolver::resolve().

bool GNet::SimpleClient::connected | ( |  | ) | const

Returns true if connected to the peer.

Definition at line 188 of file gsimpleclient.cpp.

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

Override from Connection.

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

Implements GNet::Connection.

Definition at line 372 of file gsimpleclient.cpp.

References GNet::Address::invalidAddress().

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.

virtual void GNet::SimpleClient::onConnect | ( |  | ) |
| protected pure virtual

Called once connected.

May (unfortunately) be called from within connect().

Implemented in GSmtp::Client, GSmtp::RequestClient, GSmtp::SpamClient, and GNet::ResolverImp.

void GNet::SimpleClient::onConnectImp | ( |  | ) |
| protected virtual

An alternative to onConnect() for private implementation classes.

The default implementation does nothing.

Reimplemented in GNet::Client.

Definition at line 400 of file gsimpleclient.cpp.

virtual void GNet::SimpleClient::onSendComplete | ( |  | ) |
| protected pure virtual

Called when all residual data from send() has been sent.

Implemented in GSmtp::Client, GSmtp::RequestClient, GSmtp::SpamClient, and GNet::ResolverImp.

void GNet::SimpleClient::onSendImp | ( |  | ) |
| protected virtual

Called from within send().

Reimplemented in GNet::Client.

Definition at line 411 of file gsimpleclient.cpp.

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

Override from Connection.

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

Implements GNet::Connection.

Definition at line 380 of file gsimpleclient.cpp.

References GNet::Address::invalidAddress().

std::string GNet::SimpleClient::peerCertificate | ( |  | ) | const
| virtual

Returns the peer's TLS certificate.

Final override from GNet::Connection.

Implements GNet::Connection.

Definition at line 388 of file gsimpleclient.cpp.

void GNet::SimpleClient::readEvent | ( |  | ) |
| virtual

Final override from GNet::EventHandler.

Reimplemented from GNet::EventHandler.

Definition at line 347 of file gsimpleclient.cpp.

References G_ASSERT.

GNet::ResolverInfo GNet::SimpleClient::resolverInfo | ( |  | ) | const

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

Definition at line 75 of file gsimpleclient.cpp.

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

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

Throws on error.

Definition at line 404 of file gsimpleclient.cpp.

GNet::StreamSocket & GNet::SimpleClient::socket | ( |  | ) |
| protected

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

Definition at line 89 of file gsimpleclient.cpp.

const GNet::StreamSocket & GNet::SimpleClient::socket | ( |  | ) | const
| protected

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

Definition at line 96 of file gsimpleclient.cpp.

void GNet::SimpleClient::sslConnect | ( |  | ) |
| protected

Starts TLS/SSL client-side negotiation.

Definition at line 393 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 26 of file gsimpleclient_unix.cpp.

References G::Test::enabled().

void GNet::SimpleClient::updateResolverInfo | ( | const ResolverInfo & | update | ) |

Updates the constructor's ResolverInfo 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.

References GNet::ResolverInfo::displayString(), G_DEBUG, GNet::ResolverInfo::hasAddress(), GNet::ResolverInfo::host(), and GNet::ResolverInfo::service().

void GNet::SimpleClient::writeEvent | ( |  | ) |
| virtual

Final override from GNet::EventHandler.

Reimplemented from GNet::EventHandler.

Definition at line 314 of file gsimpleclient.cpp.

References G_DEBUG.

## Friends And Related Function Documentation

friend class ClientResolver
| friend

Definition at line 200 of file gsimpleclient.h.

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

- gsimpleclient.h
- gsimpleclient.cpp
- gsimpleclient_unix.cpp