Main Page | Namespace List | Class Hierarchy | Alphabetical List | Class List | Directories | File List | Namespace Members | Class Members | Related Pages
gloox::ClientBase

ClientBase Class Reference

This is the common base class for a Jabber/XMPP Client and a Jabber Component. More...

#include <clientbase.h>

Inherits TagHandler, ConnectionDataHandler, CompressionDataHandler, TLSHandler, and IqHandler.

Inherited by Client, and Component.

Inheritance diagram for ClientBase:

Inheritance 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
const JID & jid ()
void setSasl (bool sasl)
void setTls (TLSPolicy tls)
void setCompression (bool compression)
void setPort (int port)
void setServer (const std::string &server)
void setPassword (const std::string &password)
const std::string & server () const
bool sasl () const
TLSPolicy tls () const
bool compression () const
int port () const
virtual const std::string & password () const
virtual Disco * disco () const
const std::string getID ()
void send (Tag *tag)
void send (IQ &iq, IqHandler *ih, int context, bool del=false)
void send (const IQ &iq)
void send (const Message &msg)
void send (const Subscription &sub)
void send (const Presence &pres)
bool authed () const
ConnectionState state () const
const std::string & xmlLang () const
void setXmlLang (const std::string &xmllang)
ConnectionBase * connectionImpl () const
void setConnectionImpl (ConnectionBase *cb)
TLSBase * encryptionImpl () const
void setEncryptionImpl (TLSBase *tb)
CompressionBase * compressionImpl () const
void setCompressionImpl (CompressionBase *cb)
void whitespacePing ()
void xmppPing (const JID &to, EventHandler *eh)
void setAuthzid (const JID &authzid)
void setSASLMechanisms (int mechanisms)
void registerStanzaExtension (StanzaExtension *ext)
bool removeStanzaExtension (int ext)
void registerConnectionListener (ConnectionListener *cl)
GLOOX_DEPRECATED void registerIqHandler (IqHandler *ih, const std::string &xmlns)
void registerIqHandler (IqHandler *ih, int exttype)
GLOOX_DEPRECATED void trackID (IqHandler *ih, const std::string &id, int context)
void removeIDHandler (IqHandler *ih)
void registerMessageHandler (MessageHandler *mh)
void removeMessageHandler (MessageHandler *mh)
void registerMessageSession (MessageSession *session)
void disposeMessageSession (MessageSession *session)
void registerPresenceHandler (PresenceHandler *ph)
void registerPresenceHandler (const JID &jid, PresenceHandler *ph)
void registerSubscriptionHandler (SubscriptionHandler *sh)
void registerTagHandler (TagHandler *th, const std::string &tag, const std::string &xmlns)
void registerStatisticsHandler (StatisticsHandler *sh)
void removeConnectionListener (ConnectionListener *cl)
GLOOX_DEPRECATED void removeIqHandler (IqHandler *ih, const std::string &xmlns)
void removeIqHandler (IqHandler *ih, int exttype)
void removePresenceHandler (PresenceHandler *ph)
void removePresenceHandler (const JID &jid, PresenceHandler *ph)
void removeSubscriptionHandler (SubscriptionHandler *sh)
void removeTagHandler (TagHandler *th, const std::string &tag, const std::string &xmlns)
void removeStatisticsHandler ()
void setCACerts (const StringList &cacerts)
void setClientCert (const std::string &clientKey, const std::string &clientCerts)
void registerMessageSessionHandler (MessageSessionHandler *msh, int types=0)
LogSink & logInstance ()
StreamError streamError () const
const std::string & streamErrorText (const std::string &lang="default") const
const std::string & streamErrorCData () const
const Tag * streamErrorAppCondition () const
AuthenticationError authError () const
StatisticsStruct getStatistics ()
void registerMUCInvitationHandler (MUCInvitationHandler *mih)
void removeMUCInvitationHandler ()
virtual void handleTag (Tag *tag)
virtual void handleCompressedData (const std::string &data)
virtual void handleDecompressedData (const std::string &data)
virtual void handleReceivedData (const ConnectionBase *connection, const std::string &data)
virtual void handleConnect (const ConnectionBase *connection)
virtual void handleDisconnect (const ConnectionBase *connection, ConnectionError reason)
virtual void handleEncryptedData (const TLSBase *base, const std::string &data)
virtual void handleDecryptedData (const TLSBase *base, const std::string &data)
virtual void handleHandshakeResult (const TLSBase *base, bool success, CertInfo &certinfo)

Protected Member Functions

void notifyOnResourceBindError (const Error *error)
void notifyOnResourceBind (const std::string &resource)
void notifyOnSessionCreateError (const Error *error)
bool notifyOnTLSConnect (const CertInfo &info)
void notifyOnConnect ()
virtual bool checkStreamVersion (const std::string &version)

Detailed Description

This is the common base class for a Jabber/XMPP 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 67 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 90 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 105 of file clientbase.cpp.

~ClientBase (   )  [virtual]
 

Virtual destrcuctor.

Definition at line 141 of file clientbase.cpp.

Member Function Documentation

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 281 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 ConnAuthenticationFailed from the ConnectionListener.

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

Definition at line 651 of file clientbase.h.

bool checkStreamVersion (  const std::string &  version  )  [protected, virtual]
 

Implementors of this function can check if they support the advertized stream version. The return value indicates whether or not the stream can be handled. A default implementation is provided.

Parameters:
version The advertized stream version.
Returns:
True if the stream can be handled, false otherwise.

Reimplemented in Component.

Definition at line 814 of file clientbase.cpp.

bool compression (   )  const [inline]
 

Returns whether Stream Compression is currently enabled (not necessarily used).

Returns:
The current Stream Compression status.

Definition at line 205 of file clientbase.h.

CompressionBase* compressionImpl (   )  const [inline]
 

This function returns the concrete compression implementation currently in use.

Returns:
The concrete compression implementation.
Since:
0.9

Definition at line 340 of file clientbase.h.

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.
Note:
Since 0.9 onDisconnect() is called in addition to a return value of false.

Definition at line 176 of file clientbase.cpp.

ConnectionBase* connectionImpl (   )  const [inline]
 

This function returns the concrete connection implementation currently in use.

Returns:
The concrete connection implementation.
Since:
0.9

Definition at line 308 of file clientbase.h.

virtual Disco* disco (   )  const [inline, virtual]
 

This function gives access to the Disco object.

Returns:
A pointer to the Disco object.

Definition at line 224 of file clientbase.h.

void disposeMessageSession (  MessageSession *  session  ) 
 

Removes the given MessageSession from the list of MessageSessions and deletes it.

Parameters:
session The MessageSession to be deleted.

Definition at line 1087 of file clientbase.cpp.

TLSBase* encryptionImpl (   )  const [inline]
 

This function returns the concrete encryption implementation currently in use.

Returns:
The concrete encryption implementation.
Since:
0.9

Definition at line 324 of file clientbase.h.

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 800 of file clientbase.cpp.

StatisticsStruct getStatistics (   ) 
 

Returns a StatisticsStruct containing byte and stanza counts for the current active connection.

Returns:
A struct containing the current connection's statistics.

Definition at line 750 of file clientbase.cpp.

void handleCompressedData (  const std::string &  data  )  [virtual]
 

This function is called when compression is finished.

Parameters:
data The compressed data.

Implements CompressionDataHandler.

Definition at line 288 of file clientbase.cpp.

void handleConnect (  const ConnectionBase *  connection  )  [virtual]
 

This function is called when e.g. the raw TCP connection was established.

Parameters:
connection The connection.

Implements ConnectionDataHandler.

Definition at line 351 of file clientbase.cpp.

void handleDecompressedData (  const std::string &  data  )  [virtual]
 

This function is called when decompression is finished.

Parameters:
data The decompressed data.

Implements CompressionDataHandler.

Definition at line 298 of file clientbase.cpp.

void handleDecryptedData (  const TLSBase *  base,
const std::string &  data
)  [virtual]
 

Reimplement this function to receive decrypted data from a TLSBase implementation.

Parameters:
base The encryption implementation which called this function.
data The decrypted data (e.g. to parse).

Implements TLSHandler.

Definition at line 311 of file clientbase.cpp.

void handleDisconnect (  const ConnectionBase *  connection,
ConnectionError  reason
)  [virtual]
 

This connection is called when e.g. the raw TCP connection was closed.

Parameters:
connection The connection.
reason The reason for the disconnect.

Implements ConnectionDataHandler.

Definition at line 360 of file clientbase.cpp.

void handleEncryptedData (  const TLSBase *  base,
const std::string &  data
)  [virtual]
 

Reimplement this function to receive encrypted data from a TLSBase implementation.

Parameters:
base The encryption implementation which called this function.
data The encrypted data (e.g. to send over the wire).

Implements TLSHandler.

Definition at line 303 of file clientbase.cpp.

void handleHandshakeResult (  const TLSBase *  base,
bool  success,
CertInfo &  certinfo
)  [virtual]
 

Reimplement this function to receive the result of a TLS handshake.

Parameters:
base The encryption implementation which called this function.
success Whether or not the handshake was successful.
certinfo Information about the server's certificate.

Implements TLSHandler.

Definition at line 319 of file clientbase.cpp.

void handleReceivedData (  const ConnectionBase *  connection,
const std::string &  data
)  [virtual]
 

This function is called for received from the underlying transport.

Parameters:
connection The connection that received the data.
data The data received.

Implements ConnectionDataHandler.

Definition at line 341 of file clientbase.cpp.

void handleTag (  Tag *  tag  )  [virtual]
 

This function is called when a registered XML element arrives. As with every handler in gloox, the Tag is going to be deleted after this function returned. If you need a copy afterwards, create it using Tag::clone().

Parameters:
tag The complete Tag.

Implements TagHandler.

Definition at line 205 of file clientbase.cpp.

const JID& jid (   )  [inline]
 

Returns the current Jabber ID. If an authentication ID has been set (using setAuthzid()) this authzid is returned.

Returns:
A reference to the Jabber ID.
Note:
If 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 138 of file clientbase.h.

LogSink& logInstance (   )  [inline]
 

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

Returns:
The LogSink instance used in the current ClientBase.

Definition at line 610 of file clientbase.h.

void notifyOnConnect (   )  [protected]
 

This function is called to notify about successful connection.

Definition at line 1189 of file clientbase.cpp.

void notifyOnResourceBind (  const std::string &  resource  )  [protected]
 

This function is called when binding a resource succeeded.

Parameters:
resource The bound resource.

Definition at line 1213 of file clientbase.cpp.

void notifyOnResourceBindError (  const Error *  error  )  [protected]
 

This function is called when resource binding yieled an error.

Parameters:
error A pointer to an Error object that contains more information. May be 0.

Definition at line 1208 of file clientbase.cpp.

void notifyOnSessionCreateError (  const Error *  error  )  [protected]
 

This function is called when session creation yieled an error.

Parameters:
error A pointer to an Error object that contains more information. May be 0.

Definition at line 1218 of file clientbase.cpp.

bool notifyOnTLSConnect (  const CertInfo &  info  )  [protected]
 

This function is called when the TLS handshake completed correctly. The return value is used to determine whether or not the client accepted the server's certificate. If false is returned the connection is closed.

Parameters:
info Information on the server's certificate.
Returns:
True if the certificate seems trustworthy, false otherwise.

Definition at line 1200 of file clientbase.cpp.

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

Returns the current password.

Returns:
The password used to connect.

Definition at line 218 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 212 of file clientbase.h.

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 168 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 1177 of file clientbase.cpp.

void registerIqHandler (  IqHandler *  ih,
int  exttype
) 
 

Registers ih as object that receives notifications for IQ stanzas that contain StanzaExtensions of the given type. The number of handlers per extension type is not limited.

Parameters:
ih The object to receive IQ stanza notifications.
exttype The extension type. See StanzaExtension and StanzaExtensionType .
Since:
1.0

Definition at line 1033 of file clientbase.cpp.

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

Registers ih as object that receives Iq stanza notifications for namespace xmlns. As of 1.0, the number of handlers per namespace is not limited.

Parameters:
ih The object to receive Iq stanza notifications.
xmlns The namespace the object handles.
Deprecated:
Will be removed for 1.1. Use registerIqHandler( IqHandler*, int ) instead.

Definition at line 1019 of file clientbase.cpp.

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 1102 of file clientbase.cpp.

void registerMessageSession (  MessageSession *  session  ) 
 

Registers the given MessageSession to receive Messages incoming from the session's target JID.

Note:
The ClientBase instance becomes the owner of the MessageSession, it will be deleted in ClientBase's destructor. To get rid of the session before that, use disposeMessageSession().
Parameters:
session The MessageSession to register.
Note:
Since a MessageSession automatically registers itself with the ClientBase, there is no need to call this function directly.

Definition at line 1081 of file clientbase.cpp.

void registerMessageSessionHandler (  MessageSessionHandler *  msh,
int  types = 0
) 
 

Use this function to register a MessageSessionHandler with the Client. Optionally the MessageSessionHandler can receive only MessageSessions with a given message type. There can be only one handler per message type.
A MessageSession will be created for every incoming message stanza if there is no MessageHandler registered for the originating JID.

Parameters:
msh The MessageSessionHandler that will receive the newly created MessageSession.
types ORed StanzaSubType's that describe the desired message types the handler shall receive. Only StanzaMessage* types are valid. A value of 0 means any type (default).

Definition at line 941 of file clientbase.cpp.

void registerMUCInvitationHandler (  MUCInvitationHandler *  mih  ) 
 

Registers a MUCInvitationHandler with the ClientBase.

Parameters:
mih The MUCInvitationHandler to register.

Definition at line 1162 of file clientbase.cpp.

void registerPresenceHandler (  const JID &  jid,
PresenceHandler *  ph
) 
 

Registers a new PresenceHandler for the given JID. Presences received for this particular JID will not be forwarded to the generic PresenceHandler (and therefore the Roster). This functionality is primarily intended for the MUC implementation.

Parameters:
jid The JID to 'watch'.
ph The PresenceHandler to inform about presence changes from jid.
Since:
0.9

Definition at line 968 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 956 of file clientbase.cpp.

void registerStanzaExtension (  StanzaExtension *  ext  ) 
 

Registers a new StanzaExtension with the StanzaExtensionFactory.

Parameters:
ext The extension to register.

Definition at line 734 of file clientbase.cpp.

void registerStatisticsHandler (  StatisticsHandler *  sh  ) 
 

Registers sh as object that receives up-to-date connection statistics each time a Stanza is received or sent. Alternatively, you can use getStatistics() manually. Only one StatisticsHandler per ClientBase at a time is possible.

Parameters:
sh The StatisticsHandler to register.

Definition at line 1151 of file clientbase.cpp.

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 1114 of file clientbase.cpp.

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 1126 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 1183 of file clientbase.cpp.

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 element that has an operation pending.

Parameters:
ih The IqHandler to remove.
Since:
0.8.7

Definition at line 1006 of file clientbase.cpp.

void removeIqHandler (  IqHandler *  ih,
int  exttype
) 
 

Removes the given IQ handler for the given extension type.

Parameters:
ih The IqHandler.
exttype The extension type. See StanzaExtensionType .
Since:
1.0

Definition at line 1064 of file clientbase.cpp.

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

Removes the given IQ handler for the given namespace.

Parameters:
ih The IqHandler.
xmlns The namespace to remove from the list.

Deprecated:
Will be removed for 1.1. Use removeIqHandler( IqHandler*, int ) instead.
Since:
1.0

Definition at line 1047 of file clientbase.cpp.

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 1108 of file clientbase.cpp.

void removeMUCInvitationHandler (   ) 
 

Removes the currently registered MUCInvitationHandler.

Definition at line 1171 of file clientbase.cpp.

void removePresenceHandler (  const JID &  jid,
PresenceHandler *  ph
) 
 

Removes the given object from the list of presence handlers for the given JID.

Parameters:
jid The JID to remove the PresenceHandler(s) for.
ph The PresenceHandler to remove from the list. If ph is 0, all handlers for the given JID will be removed.

Definition at line 979 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 962 of file clientbase.cpp.

bool removeStanzaExtension (  int  ext  ) 
 

Removes the given StanzaExtension type from the StanzaExtensionFactory.

Parameters:
ext The extension type.
Returns:
True if the given type was found (and removed), false otherwise.

Definition at line 742 of file clientbase.cpp.

void removeStatisticsHandler (   ) 
 

Removes the current StatisticsHandler.

Definition at line 1157 of file clientbase.cpp.

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 1120 of file clientbase.cpp.

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 1138 of file clientbase.cpp.

bool sasl (   )  const [inline]
 

Returns whether SASL is currently enabled (not necessarily used).

Returns:
The current SASL status.

Definition at line 193 of file clientbase.h.

void send (  const Presence &  pres  ) 
 

A convenience function that sends the given Presence stanza.

Parameters:
pres The Presence stanza to send.

Definition at line 688 of file clientbase.cpp.

void send (  const Subscription &  sub  ) 
 

A convenience function that sends the given Subscription stanza.

Parameters:
sub The Subscription stanza to send.

Definition at line 680 of file clientbase.cpp.

void send (  const Message &  msg  ) 
 

A convenience function that sends the given Message stanza.

Parameters:
msg The Message stanza to send.

Definition at line 672 of file clientbase.cpp.

void send (  const IQ &  iq  ) 
 

A convenience function that sends the given IQ stanza.

Parameters:
iq The IQ stanza to send.

Definition at line 664 of file clientbase.cpp.

void send (  IQ &  iq,
IqHandler *  ih,
int  context,
bool