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 ( )

protectedvirtual

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 )

staticprotected

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 ( )

protectedpure 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 ( )

protectedvirtual

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 ( )

protectedpure 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 ( )

protectedvirtual

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:

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Static Protected Member Functions

Friends

Detailed Description

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation