Connection Class Reference

This is an implementation of a TLS- and Stream Compression-aware connection handler. More...

#include <connection.h>

Collaboration diagram for Connection:

Collaboration graph
[legend]
List of all members.

Public Member Functions

 Connection (Parser *parser, const LogSink &logInstance, const std::string &server, unsigned short port=-1)
virtual ~Connection ()
ConnectionState connect ()
ConnectionError recv (int timeout=-1)
bool send (const std::string &data)
ConnectionError receive ()
void disconnect (ConnectionError e)
bool isSecure () const
ConnectionState state () const
int fileDescriptor ()
bool initCompression (StreamFeature method)
void enableCompression ()
bool tlsHandshake ()
void setCACerts (const StringList &cacerts)
const CertInfofetchTLSInfo () const
void setClientCert (const std::string &clientKey, const std::string &clientCerts)

Detailed Description

This is an implementation of a TLS- and Stream Compression-aware connection handler.

Author:
Jakob Schroeter <js@camaya.net>
Since:
0.4

Definition at line 59 of file connection.h.


Constructor & Destructor Documentation

Connection ( Parser parser,
const LogSink logInstance,
const std::string &  server,
unsigned short  port = -1 
)

Constructs a new Connection object. You should not need to use this function directly.

Parameters:
parser A parser to feed with incoming data.
logInstance A LogSink to use for logging.
server A server to connect to.
port The port to connect to. The default of -1 means that SRV records will be used to find out about the actual host:port.

Definition at line 51 of file connection.cpp.

~Connection (  )  [virtual]

Virtual destructor

Definition at line 64 of file connection.cpp.


Member Function Documentation

ConnectionState connect (  ) 

Used to initiate the connection.

Returns:
Returns the connection state.

Definition at line 903 of file connection.cpp.

Referenced by ClientBase::connect().

ConnectionError recv ( int  timeout = -1  ) 

Use this periodically to receive data from the socket and to feed the parser.

Parameters:
timeout The timeout to use for select in microseconds. Default of -1 means blocking.
Returns:
The state of the connection.

Definition at line 983 of file connection.cpp.

Referenced by Connection::receive(), and ClientBase::recv().

bool send ( const std::string &  data  ) 

Use this function to send a string of data over the wire. The function returns only after all data has been sent.

Parameters:
data The data to send.

Definition at line 1080 of file connection.cpp.

ConnectionError receive (  ) 

Use this function to put the connection into 'receive mode'.

Returns:
Returns a value indicating the disconnection reason.

Definition at line 1061 of file connection.cpp.

Referenced by ClientBase::connect().

void disconnect ( ConnectionError  e  ) 

Disconnects an established connection. NOOP if no active connection exists.

Parameters:
e A ConnectionError decribing why the connection is terminated. Well, its not really an error here, but...

Definition at line 940 of file connection.cpp.

Referenced by ClientBase::disconnect().

bool isSecure (  )  const [inline]

Use this function to determine whether an esatblished connection is encrypted.

Returns:
True if the connection is encrypted, false otherwise.

Definition at line 116 of file connection.h.

ConnectionState state (  )  const [inline]

Returns the current connection state.

Returns:
The state of the connection.

Definition at line 122 of file connection.h.

Referenced by ClientBase::recv(), and ClientBase::state().

int fileDescriptor (  ) 

Gives access to the raw file descriptor of a connection. Use it wisely. Especially, you should not recv() any data from it. There is no way to feed that back into the parser. You can select()/poll() it and use Connection::recv( -1 ) to fetch the data.

Returns:
The file descriptor of the active connection, or -1 if no connection is established.

Definition at line 949 of file connection.cpp.

Referenced by ClientBase::fileDescriptor().

bool initCompression ( StreamFeature  method  ) 

This function is used to init or de-init stream compression. You must call this before enabling compression using setCompression().

Parameters:
method The desired stream compression method (e.g. zlib, lzw, ...)
Returns:
Returns true if compression was successfully initialized/de-initialized, false otherwise.

Definition at line 886 of file connection.cpp.

void enableCompression (  ) 

This function is used to enable stream compression as defined in JEP-0138. It is necessary because when compression is negotiated it is not enabled instantly.

Definition at line 894 of file connection.cpp.

bool tlsHandshake (  ) 

Call this function to start a TLS handshake over an established connection.

Definition at line 179 of file connection.cpp.

void setCACerts ( const StringList cacerts  )  [inline]

Use this function to set a number of trusted root CA certificates which shall be used to verify a servers certificate.

Parameters:
cacerts A list of absolute paths to CA root certificate files in PEM format.

Definition at line 160 of file connection.h.

Referenced by ClientBase::connect().

const CertInfo& fetchTLSInfo (  )  const [inline]

This function is used to retrieve certificate and connection info of a encrypted connection.

Returns:
Certificate information.

Definition at line 166 of file connection.h.

void setClientCert ( const std::string &  clientKey,
const std::string &  clientCerts 
)

Use this function to set the user's certificate and private key. The certificate will be presented to the server upon request and can be used for SASL EXTERNAL authentication. The user's certificate file should be a bundle of more than one certificate in PEM format. The first one in the file should be the user's certificate, each cert following that one should have signed the previous one.

Note:
These certificates are not necessarily the same as those used to verify the server's certificate.
Parameters:
clientKey The absolute path to the user's private key in PEM format.
clientCerts A path to a certificate bundle in PEM format.

Definition at line 73 of file connection.cpp.

Referenced by ClientBase::connect().


The documentation for this class was generated from the following files:
Generated on Tue May 1 14:20:22 2007 for gloox by  doxygen 1.5.1