ClientBase Class Reference

This is the common base class for a jabber Client and a jabber Component. More...

#include <clientbase.h>

Inherited by Client, and Component.

Inheritance diagram for ClientBase:

Inheritance graph
[legend]
Collaboration diagram for ClientBase:

Collaboration graph
[legend]
List of all members.

Public Member Functions

 ClientBase (const std::string &ns, const std::string &server, int port=-1)
 ClientBase (const std::string &ns, const std::string &password, const std::string &server, int port=-1)
virtual ~ClientBase ()
bool connect (bool block=true)
ConnectionError recv (int timeout=-1)
virtual const std::string username () const=0
JIDjid ()
void setSasl (bool sasl)
void setTls (bool tls)
void setPort (int port)
void setServer (const std::string &server)
void setPassword (const std::string &password)
const std::string server () const
bool sasl () const
bool tls () const
int port () const
virtual const std::string password () const
const std::string getID ()
virtual void send (Tag *tag)
bool authed () const
ConnectionState state () const
const std::string & xmlLang () const
void setXmlLang (const std::string &xmllang)
int fileDescriptor ()
void ping ()
void registerConnectionListener (ConnectionListener *cl)
void registerIqHandler (IqHandler *ih, const std::string &xmlns)
void trackID (IqHandler *ih, const std::string &id, int context)
void removeIDHandler (IqHandler *ih)
void registerMessageHandler (MessageHandler *mh)
void registerMessageHandler (const std::string &jid, MessageHandler *mh, bool wantUpgrade)
void registerPresenceHandler (PresenceHandler *ph)
void registerSubscriptionHandler (SubscriptionHandler *sh)
void registerTagHandler (TagHandler *th, const std::string &tag, const std::string &xmlns)
void removeConnectionListener (ConnectionListener *cl)
void removeIqHandler (const std::string &xmlns)
void removeMessageHandler (MessageHandler *mh)
void removeMessageHandler (const std::string &jid)
void removePresenceHandler (PresenceHandler *ph)
void removeSubscriptionHandler (SubscriptionHandler *sh)
void removeTagHandler (TagHandler *th, const std::string &tag, const std::string &xmlns)
void setCACerts (const StringList &cacerts)
void setClientCert (const std::string &clientKey, const std::string &clientCerts)
void setAutoMessageSession (bool autoMS, MessageSessionHandler *msh)
LogSinklogInstance ()
StreamError streamError () const
const std::string streamErrorText (const std::string &lang="default") const
const std::string streamErrorCData () const
const TagstreamErrorAppCondition () const
AuthenticationError authError () const

Protected Types

enum  SaslMechanisms { SaslDigestMd5, SaslPlain, SaslAnonymous, SaslExternal }

Protected Member Functions

void notifyOnResourceBindError (ResourceBindError error)
void notifyOnSessionCreateError (SessionCreateError error)
bool notifyOnTLSConnect (const CertInfo &info)
void notifyOnConnect ()
virtual void disconnect (ConnectionError reason)
void header ()
void setAuthed (bool authed)
void setAuthFailure (AuthenticationError e)
virtual bool checkStreamVersion (const std::string &version)
void startSASL (SaslMechanisms type)
void processSASLChallenge (const std::string &challenge)
void processSASLError (Stanza *stanza)
void startTls ()
bool hasTls ()

Protected Attributes

JID m_jid
Connectionm_connection
std::string m_clientCerts
std::string m_clientKey
std::string m_namespace
std::string m_password
std::string m_xmllang
std::string m_server
std::string m_sid
bool m_authed
bool m_sasl
bool m_tls
int m_port

Friends

class Parser
class RosterManager

Detailed Description

This is the common base class for a jabber Client and a jabber Component.

It manages connection establishing, authentication, filter registration and invocation.

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

Definition at line 51 of file clientbase.h.


Member Enumeration Documentation

enum SaslMechanisms [protected]

Enumerator:
SaslDigestMd5  SASL Digest-MD5 according to RFC 2831.
SaslPlain  SASL PLAIN according to RFC 2595 Section 6.
SaslAnonymous  SASL ANONYMOUS according to draft-ietf-sasl-anon-05.txt/ RFC 2245 Section 6.
SaslExternal  SASL EXTERNAL according to RFC 2222 Section 7.4.

Definition at line 433 of file clientbase.h.


Constructor & Destructor Documentation

ClientBase ( const std::string &  ns,
const std::string &  server,
int  port = -1 
)

Constructs a new ClientBase. You should not need to use this class directly. Use Client or Component instead.

Parameters:
ns The namespace which qualifies the stream. Either jabber:client or jabber:component:*
server The server to connect to.
port The port to connect to. The default of -1 means to look up the port via DNS SRV or to use a default port of 5222 as defined in XMPP: Core.

Definition at line 49 of file clientbase.cpp.

ClientBase ( const std::string &  ns,
const std::string &  password,
const std::string &  server,
int  port = -1 
)

Constructs a new ClientBase. You should not need to use this class directly. Use Client or Component instead.

Parameters:
ns The namespace which qualifies the stream. Either jabber:client or jabber:component:*
password The password to use for further authentication.
server The server to connect to.
port The port to connect to. The default of -1 means to look up the port via DNS SRV or to use a default port of 5222 as defined in XMPP: Core.

Definition at line 59 of file clientbase.cpp.

~ClientBase (  )  [virtual]

Virtual destrcuctor.

Definition at line 70 of file clientbase.cpp.


Member Function Documentation

bool connect ( bool  block = true  ) 

Initiates the connection to a server. This function blocks as long as a connection is established. You can have the connection block 'til the end of the connection, or you can have it return immediately. If you choose the latter, its your responsibility to call recv() every now and then to actually receive data from the socket and to feed the parser.

Parameters:
block True for blocking, false for non-blocking connect. Defaults to true.
Returns:
False if prerequisits are not met (server not set) or if the connection was refused, true otherwise.

Definition at line 87 of file clientbase.cpp.

ConnectionError recv ( int  timeout = -1  ) 

Use this periodically to receive data from the socket and to feed the parser. You need to use this only if you chose to connect in non-blocking mode.

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

Definition at line 76 of file clientbase.cpp.

virtual const std::string username (  )  const [pure virtual]

Reimplement this function to provide a username for connection purposes.

Returns:
The username.

Implemented in Client, and Component.

JID& jid (  )  [inline]

Returns the current jabber id.

Returns:
The Jabber ID.
Note:
I you change the server part of the JID, the server of the connection is not synced. You have to do that manually using setServer().

Definition at line 118 of file clientbase.h.

Referenced by RosterManager::ackSubscriptionRequest(), FlexibleOffline::checkSupport(), Client::Client(), NonSaslAuth::doAuth(), FlexibleOffline::fetchHeaders(), Disco::getDiscoInfo(), Disco::getDiscoItems(), FlexibleOffline::getMsgCount(), Disco::handleIq(), NonSaslAuth::handleIqID(), RosterManager::handleSubscription(), Registration::removeAccount(), RosterManager::RosterManager(), MessageSession::send(), RosterManager::subscribe(), and RosterManager::unsubscribe().

void setSasl ( bool  sasl  )  [inline]

Switches usage of SASL on/off. Default: on

Parameters:
sasl Whether to switch SASL usage on or off.

Definition at line 124 of file clientbase.h.

void setTls ( bool  tls  )  [inline]

Switches usage of TLS on/off (if available). Default: on

Parameters:
tls Whether to switch TLS usage on or off.

Definition at line 130 of file clientbase.h.

void setPort ( int  port  )  [inline]

Sets the port to connect to. This is not necessary if either the default port (5222) is used or SRV records exist which will be resolved.

Parameters:
port The port to connect to.

Definition at line 137 of file clientbase.h.

void setServer ( const std::string &  server  )  [inline]

Sets the XMPP server to connect to.

Parameters:
server The server to connect to. Either IP or fully qualified domain name.
Note:
If you change the server, the server part of the JID is not synced. You have to do that manually using jid() and JID::setServer().

Definition at line 145 of file clientbase.h.

void setPassword ( const std::string &  password  )  [inline]

Sets the password to use to connect to the XMPP server.

Parameters:
password The password to use for authentication.

Definition at line 151 of file clientbase.h.

const std::string server (  )  const [inline]

Returns the current prepped server.

Returns:
The server used to connect.

Definition at line 157 of file clientbase.h.

bool sasl (  )  const [inline]

Returns the current SASL status.

Returns:
The current SASL status.

Definition at line 163 of file clientbase.h.

bool tls (  )  const [inline]

Returns the current TLS status.

Returns:
The current TLS status.

Definition at line 169 of file clientbase.h.

int port (  )  const [inline]

Returns the port. The default of -1 means that the actual port will be looked up using SRV records, or the XMPP default port of 5222 will be used.

Returns:
The port used to connect.

Definition at line 176 of file clientbase.h.

virtual const std::string password (  )  const [inline, virtual]

Returns the current password.

Returns:
The password used to connect.

Reimplemented in Component.

Definition at line 182 of file clientbase.h.

Referenced by NonSaslAuth::handleIqID().

const std::string getID (  ) 

Creates a string which is unique in the current instance and can be used as an ID for queries.

Returns:
A unique string suitable for query IDs.

Definition at line 411 of file clientbase.cpp.

Referenced by RosterManager::add(), Registration::changePassword(), Registration::createAccount(), NonSaslAuth::doAuth(), FlexibleOffline::fetchMessages(), Registration::fetchRegistrationFields(), Search::fetchSearchFields(), VCardManager::fetchVCard(), RosterManager::fill(), Disco::getDiscoInfo(), Disco::getDiscoItems(), NonSaslAuth::handleIqID(), MessageSession::MessageSession(), LastActivity::query(), Registration::removeAccount(), PrivacyManager::removeList(), FlexibleOffline::removeMessages(), InBandBytestreamManager::requestInBandBytestream(), PrivacyManager::requestList(), PrivacyManager::requestListNames(), PrivateXML::requestXML(), Search::search(), InBandBytestream::sendBlock(), PrivacyManager::setActive(), PrivacyManager::setDefault(), ClientBase::startSASL(), PrivacyManager::store(), VCardManager::storeVCard(), PrivateXML::storeXML(), RosterManager::synchronize(), PrivacyManager::unsetActive(), PrivacyManager::unsetDefault(), and RosterManager::unsubscribe().

void send ( Tag tag  )  [virtual]

Sends a given Tag over an established connection. The ClientBase object becomes the owner of this Tag and will delete it after sending it. You should not rely on the existance of the Tag after it's been sent.

Parameters:
tag The Tag to send.

Definition at line 373 of file clientbase.cpp.

Referenced by RosterManager::ackSubscriptionRequest(), RosterManager::add(), Client::bindResource(), Registration::changePassword(), Registration::createAccount(), ClientBase::disconnect(), NonSaslAuth::doAuth(), FlexibleOffline::fetchMessages(), Registration::fetchRegistrationFields(), Search::fetchSearchFields(), VCardManager::fetchVCard(), RosterManager::fill(), Disco::getDiscoInfo(), Disco::getDiscoItems(), RosterManager::handleIq(), PrivacyManager::handleIq(), LastActivity::handleIq(), InBandBytestreamManager::handleIq(), Disco::handleIq(), NonSaslAuth::handleIqID(), Component::handleStartNode(), RosterManager::handleSubscription(), ClientBase::header(), ClientBase::ping(), ClientBase::processSASLChallenge(), LastActivity::query(), Registration::removeAccount(), PrivacyManager::removeList(), FlexibleOffline::removeMessages(), InBandBytestreamManager::requestInBandBytestream(), PrivacyManager::requestList(), PrivacyManager::requestListNames(), PrivateXML::requestXML(), Search::search(), MessageSession::send(), InBandBytestream::sendBlock(), PrivacyManager::setActive(), PrivacyManager::setDefault(), ClientBase::startSASL(), ClientBase::startTls(), PrivacyManager::store(), VCardManager::storeVCard(), PrivateXML::storeXML(), RosterManager::subscribe(), RosterManager::synchronize(), PrivacyManager::unsetActive(), PrivacyManager::unsetDefault(), and RosterManager::unsubscribe().

bool authed (  )  const [inline]

Returns whether authentication has taken place and was successful.

Returns:
True if authentication has been carried out and was successful, false otherwise.

Definition at line 203 of file clientbase.h.

Referenced by Registration::changePassword(), and Registration::removeAccount().

ConnectionState state (  )  const

Returns the current connection status.

Returns:
The status of the connection.

Definition at line 399 of file clientbase.cpp.

Referenced by Registration::createAccount(), and Registration::fetchRegistrationFields().

const std::string& xmlLang (  )  const [inline]

Retrieves the value of the xml:lang attribute of the initial stream. Default is 'en', i.e. if not changed by a call to setXmlLang().

Definition at line 215 of file clientbase.h.

void setXmlLang ( const std::string &  xmllang  )  [inline]

Sets the value for the xml:lang attribute of the initial stream.

Parameters:
xmllang The language identifier for the stream. It must conform to section 2.12 of the XML specification and RFC 3066. Default is 'en'.

Definition at line 223 of file clientbase.h.

int fileDescriptor (  ) 

Gives access to the raw file descriptor of the current 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 use select() on 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 540 of file clientbase.cpp.

void ping (  ) 

Sends a whitespace ping to the server.

Definition at line 406 of file clientbase.cpp.

void registerConnectionListener ( ConnectionListener cl  ) 

Registers cl as object that receives connection notifications.

Parameters:
cl The object to receive connection notifications.

Definition at line 653 of file clientbase.cpp.

void registerIqHandler ( IqHandler ih,
const std::string &  xmlns 
)

Registers ih as object that receives Iq stanza notifications for namespace xmlns. Only one handler per namespace is possible.

Parameters:
ih The object to receive Iq stanza notifications.
xmlns The namespace the object handles.

Definition at line 563 of file clientbase.cpp.

Referenced by Adhoc::Adhoc(), InBandBytestreamManager::InBandBytestreamManager(), NonSaslAuth::NonSaslAuth(), PrivacyManager::PrivacyManager(), PrivateXML::PrivateXML(), Registration::Registration(), RosterManager::RosterManager(), and VCardManager::VCardManager().

void trackID ( IqHandler ih,
const std::string &  id,
int  context 
)

Use this function to be notified of incoming IQ stanzas with the given value of the id attribute. Since IDs are supposed to be unique, this notification works only once.

Parameters:
ih The IqHandler to receive notifications.
id The id to track.
context A value that allows for restoring context.

Definition at line 569 of file clientbase.cpp.

Referenced by Registration::changePassword(), Registration::createAccount(), NonSaslAuth::doAuth(), FlexibleOffline::fetchMessages(), Registration::fetchRegistrationFields(), Search::fetchSearchFields(), VCardManager::fetchVCard(), Disco::getDiscoInfo(), Disco::getDiscoItems(), NonSaslAuth::handleIqID(), LastActivity::query(), Registration::removeAccount(), PrivacyManager::removeList(), FlexibleOffline::removeMessages(), InBandBytestreamManager::requestInBandBytestream(), PrivacyManager::requestList(), PrivacyManager::requestListNames(), PrivateXML::requestXML(), Search::search(), PrivacyManager::setActive(), PrivacyManager::setDefault(), PrivacyManager::store(), VCardManager::storeVCard(), PrivateXML::storeXML(), PrivacyManager::unsetActive(), and PrivacyManager::unsetDefault().

void removeIDHandler ( IqHandler ih  ) 

Removes the given IqHandler from the list of handlers of pending operations, added using trackID(). Necessary, for example, when closing a GUI elelemnt that has an operation pending.

Parameters:
ih The IqHandler to remove.
Since:
0.8.7

Definition at line 580 of file clientbase.cpp.

Referenced by VCardManager::~VCardManager().

void registerMessageHandler ( MessageHandler mh  ) 

Registers mh as object that receives Message stanza notifications.

Parameters:
mh The object to receive Message stanza notifications.

Definition at line 610 of file clientbase.cpp.

Referenced by MessageSession::MessageSession().

void registerMessageHandler ( const std::string &  jid,
MessageHandler mh,
bool  wantUpgrade 
)

Registers mh as object that receives Message stanza notifications for the given JID. Only one message handler per (full) JID is possible. You should not need to use this functionality directly. Instead use a MessageSession.

Parameters:
jid Messages from this full JID will be sent to the given MessageHandler.
mh The object to receive Message stanza notifications.
wantUpgrade Indicates whether the registered MessageSession wants upgrades from bare JID to full JID.

Definition at line 599 of file clientbase.cpp.

void registerPresenceHandler ( PresenceHandler ph  ) 

Registers ph as object that receives Presence stanza notifications.

Parameters:
ph The object to receive Presence stanza notifications.

Definition at line 551 of file clientbase.cpp.

Referenced by RosterManager::RosterManager().

void registerSubscriptionHandler ( SubscriptionHandler sh  ) 

Registers sh as object that receives Subscription stanza notifications.

Parameters:
sh The object to receive Subscription stanza notifications.

Definition at line 629 of file clientbase.cpp.

Referenced by RosterManager::RosterManager().

void registerTagHandler ( TagHandler th,
const std::string &  tag,
const std::string &  xmlns 
)

Registers th as object that receives incoming packts with a given root tag qualified by the given namespace.

Parameters:
th The object to receive Subscription packet notifications.
tag The element's name.
xmlns The element's namespace.

Definition at line 635 of file clientbase.cpp.

void removeConnectionListener ( ConnectionListener cl  ) 

Removes the given object from the list of connection listeners.

Parameters:
cl The object to remove from the list.

Definition at line 659 of file clientbase.cpp.

void removeIqHandler ( const std::string &  xmlns  ) 

Removes the handler for the given namespace from the list of Iq handlers.

Parameters:
xmlns The namespace to remove from the list.

Definition at line 593 of file clientbase.cpp.

Referenced by Adhoc::~Adhoc(), InBandBytestreamManager::~InBandBytestreamManager(), NonSaslAuth::~NonSaslAuth(), PrivacyManager::~PrivacyManager(), PrivateXML::~PrivateXML(), Registration::~Registration(), RosterManager::~RosterManager(), and VCardManager::~VCardManager().

void removeMessageHandler ( MessageHandler mh  ) 

Removes the given object from the list of message handlers.

Parameters:
mh The object to remove from the list.

Definition at line 623 of file clientbase.cpp.

Referenced by MessageSession::~MessageSession().

void removeMessageHandler ( const std::string &  jid  ) 

Removes the message handler for the given JID.

Parameters:
jid The JID for which listening shall end.

Definition at line 616 of file clientbase.cpp.

void removePresenceHandler ( PresenceHandler ph  ) 

Removes the given object from the list of presence handlers.

Parameters:
ph The object to remove from the list.

Definition at line 557 of file clientbase.cpp.

Referenced by RosterManager::~RosterManager().

void removeSubscriptionHandler ( SubscriptionHandler sh  ) 

Removes the given object from the list of subscription handlers.

Parameters:
sh The object to remove from the list.

Definition at line 647 of file clientbase.cpp.

Referenced by RosterManager::~RosterManager().

void removeTagHandler ( TagHandler th,
const std::string &  tag,
const std::string &  xmlns 
)

Removes the given object from the list of tag handlers for the given element and namespace.

Parameters:
th The object to remove from the list.
tag The element to remove the handler for.
xmlns The namespace qualifying the element.

Definition at line 665 of file clientbase.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 360 of file clientbase.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 222 of file clientbase.cpp.

void setAutoMessageSession ( bool  autoMS,
MessageSessionHandler msh 
)

Use this function to turn the Auto-MessageSession feature on or off. If this is enabled, a MessageSession will be created for every incoming message stanza if there is no MessageHandler registered for the originating JID. If you disable automatic MessageSession creation, the MessageSessionHandler will be cleared. You have to set it anew the next time you want to enable it. You cannot enable this feature without a valid MessageSessionHandler.

Parameters:
autoMS Whether to enable automatic MessageSession creation.
msh The MessageSessionHandler that will receive the newly created MessageSession.

Definition at line 526 of file clientbase.cpp.

LogSink & logInstance (  ) 

Returns the LogSink instance for this ClientBase and all related objects.

Returns:
The LogSink instance used in the current ClientBase.

Definition at line 440 of file clientbase.cpp.

StreamError streamError (  )  const [inline]

Use this function to retrieve the type of the stream error after it occurs and you received a ConnectionError of type CONN_STREAM_ERROR from the ConnectionListener.

Definition at line 397 of file clientbase.h.

const std::string streamErrorText ( const std::string &  lang = "default"  )  const

Returns the text of a stream error for the given language if available. If the requested language is not available, the default text (without a xml:lang attribute) will be returned.

Parameters:
lang The language identifier for the desired language. It must conform to section 2.12 of the XML specification and RFC 3066. If empty, the default body will be returned, if any.
Returns:
The describing text of a stream error. Empty if no stream error occured.

Definition at line 517 of file clientbase.cpp.

const std::string streamErrorCData (  )  const [inline]

In case the defined-condition element of an stream error contains XML character data you can use this function to retrieve it. RFC 3920 only defines one condition (see-other-host)where this is possible.

Returns:
The cdata of the stream error's text element (only for see-other-host).

Definition at line 416 of file clientbase.h.

const Tag* streamErrorAppCondition (  )  const [inline]

This function can be used to retrieve the application-specific error condition of a stream error.

Returns:
The application-specific error element of a stream error. 0 if no respective element was found or no error occured.

Definition at line 423 of file clientbase.h.

AuthenticationError authError (  )  const [inline]

Use this function to retrieve the type of the authentication error after it occurs and you received a ConnectionError of type CONN_AUTHENTICATION_FAILED from the ConnectionListener.

Returns:
The type of the authentication, if any, AUTH_ERROR_UNDEFINED otherwise.

Definition at line 430 of file clientbase.h.


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