clientbase.h

Jabber code library, developed with c

/*
  Copyright (c) 2005-2008 by Jakob Schroeter <[e-mail]>
  This file is part of the gloox library. http://camaya.net/gloox

  This software is distributed under a license. The full license
  agreement can be found in the file LICENSE in this distribution.
  This software may not be copied, modified, sold or distributed
  other than expressed in the named license agreement.

  This software is distributed without any warranty.
*/



#ifndef CLIENTBASE_H__
#define CLIENTBASE_H__

#include "macros.h"
#include "gloox.h"
#include "jid.h"
#include "logsink.h"
#include "taghandler.h"
#include "statisticshandler.h"
#include "tlshandler.h"
#include "compressiondatahandler.h"
#include "connectiondatahandler.h"

#include <string>
#include <list>
#include <map>

namespace gloox
{

  class Disco;
  class Tag;
  class Stanza;
  class Parser;
  class MessageSessionHandler;
  class ConnectionListener;
  class IqHandler;
  class MessageHandler;
  class MessageSession;
  class PresenceHandler;
  class SubscriptionHandler;
  class MUCInvitationHandler;
  class TagHandler;
  class TLSBase;
  class ConnectionBase;
  class CompressionBase;

  /**
   * @brief 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 <[e-mail]>
   * @since 0.3
   */
  class GLOOX_API ClientBase : public TagHandler, public ConnectionDataHandler,
                               public CompressionDataHandler, public TLSHandler
  {

    friend class RosterManager;

    public:
      /**
       * Constructs a new ClientBase.
       * You should not need to use this class directly. Use Client or Component instead.
       * @param ns The namespace which qualifies the stream. Either jabber:client or jabber:component:*
       * @param server The server to connect to.
       * @param 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.
       */
      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.
       * @param ns The namespace which qualifies the stream. Either jabber:client or jabber:component:*
       * @param password The password to use for further authentication.
       * @param server The server to connect to.
       * @param 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.
       */
      ClientBase( const std::string& ns, const std::string& password,
                  const std::string& server, int port = -1 );

      /**
       * Virtual destrcuctor.
       */
      virtual ~ClientBase();

      /**
       * 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 @ref recv() every now
       * and then to actually receive data from the socket and to feed the parser.
       * @param block @b True for blocking, @b false for non-blocking connect. Defaults to @b true.
       * @return @b False if prerequisits are not met (server not set) or if the connection was refused,
       * @b true otherwise.
       * @note Since 0.9 @link ConnectionListener::onDisconnect() onDisconnect() @endlink is called
       * in addition to a return value of @b false.
       */
      bool connect( bool block = true );

      /**
       * 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.
       * @param timeout The timeout in microseconds to use for select. Default of -1 means blocking
       * until data was available.
       * @return The state of the connection.
       */
      ConnectionError recv( int timeout = -1 );

      /**
       * Reimplement this function to provide a username for connection purposes.
       * @return The username.
       */
      virtual const std::string& username() const { return m_jid.username(); }

      /**
       * Returns the current Jabber ID. If an authentication ID has been set (using setAuthzid())
       * this authzid is returned.
       * @return 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 @ref setServer().
       */
      const JID& jid() { return m_authzid ? m_authzid : m_jid; }

      /**
       * Switches usage of SASL on/off. Default: on. SASL should only be disabled if there are
       * problems with using it.
       * @param sasl Whether to switch SASL usage on or off.
       */
      void setSasl( bool sasl ) { m_sasl = sasl; }

      /**
       * Switches usage of TLS on/off (if available). Default: on if available. TLS should only be
       * disabled if there are problems with using it.
       * @param tls Whether to switch TLS usage on or off.
       */
      GLOOX_DEPRECATED void setTls( bool tls ) { m_tls = (TLSPolicy)tls; }

      /**
       * Sets the TLS policy. Default: TLS will be used if available. TLS should only be
       * disabled if there are problems with using it.
       * @param tls The TLS policy.
       */
      void setTls( TLSPolicy tls ) { m_tls = tls; }

      /**
       * Switches usage of Stream Compression on/off (if available). Default: on if available. Stream
       * Compression should only be disabled if there are problems with using it.
       * @param compression Whether to switch Stream Compression usage on or off.
       */
      void setCompression( bool compression ) { m_compress = compression; }

      /**
       * 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.
       * @param port The port to connect to.
       */
      void setPort( int port ) { m_port = port; }

      /**
       * Sets the XMPP server to connect to.
       * @param 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 @ref jid() and @ref JID::setServer().
       * @note This function also sets the server of the Connection(Base) in use.
       */
      void setServer( const std::string &server );

      /**
       * Sets the password to use to connect to the XMPP server.
       * @param password The password to use for authentication.
       */
      void setPassword( const std::string &password ) { m_password = password; }

      /**
       * Returns the current prepped server.
       * @return The server used to connect.
       */
      const std::string& server() const { return m_server; }

      /**
       * Returns whether SASL is currently enabled (not necessarily used).
       * @return The current SASL status.
       */
      bool sasl() const { return m_sasl; }

      /**
       * Returns whether TLS is currently enabled (not necessarily used).
       * @return The current TLS status.
       */
      bool tls() const { return (bool)m_tls; }

      /**
       * Returns whether Stream Compression is currently enabled (not necessarily used).
       * @return The current Stream Compression status.
       */
      bool compression() const { return m_compress; }

      /**
       * 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.
       * @return The port used to connect.
       */
      int port() const { return m_port; }

      /**
       * Returns the current password.
       * @return The password used to connect.
       */
      virtual const std::string& password() const { return m_password; }

      /**
       * This function gives access to the @c Disco object.
       * @return A pointer to the Disco object.
       */
      virtual Disco* disco() const { return m_disco; }

      /**
       * Creates a string which is unique in the current instance and
       * can be used as an ID for queries.
       * @return A unique string suitable for query IDs.
       */
      const std::string getID();

      /**
       * 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. If you still need
       * it after sending it, use Tag::clone() to create a deep copy.
       * @param tag The Tag to send.
       */
      virtual void send( Tag *tag );

      /**
       * Returns whether authentication has taken place and was successful.
       * @return @b True if authentication has been carried out @b and was successful, @b false otherwise.
       */
      bool authed() const { return m_authed; }

      /**
       * Returns the current connection status.
       * @return The status of the connection.
       */
      ConnectionState state() const;

      /**
       * Retrieves the value of the xml:lang attribute of the initial stream.
       * Default is 'en', i.e. if not changed by a call to @ref setXmlLang().
       */
      const std::string& xmlLang() const { return m_xmllang; }

      /**
       * Sets the value for the xml:lang attribute of the initial stream.
       * @param xmllang The language identifier for the stream. It must conform to
       * section 2.12 of the XML specification and RFC 3066.
       * Default is 'en'.
       */
      void setXmlLang( const std::string& xmllang ) { m_xmllang = xmllang; }

      /**
       * This function returns the concrete connection implementation currently in use.
       * @return The concrete connection implementation.
       * @since 0.9
       */
      ConnectionBase* connectionImpl() const { return m_connection; }

      /**
       * Use this function if you have a class implementing a UDP, SCTP (or whatever)
       * connection. This should be called before calling connect(). If there already is a
       * connection implementation set (either manually or automatically), it gets deleted.
       * @param cb The connection to use.
       * @since 0.9
       */
      void setConnectionImpl( ConnectionBase *cb );

      /**
       * This function returns the concrete encryption implementation currently in use.
       * @return The concrete encryption implementation.
       * @since 0.9
       */
      TLSBase* encryptionImpl() const { return m_encryption; }

      /**
       * Use this function if you have a class supporting hardware encryption (or whatever).
       * This should be called before calling connect(). If there already is a
       * encryption implementation set (either manually or automatically), it gets deleted.
       * @param tb The encryption implementation to use.
       * @since 0.9
       */
      void setEncryptionImpl( TLSBase *tb );

      /**
       * This function returns the concrete compression implementation currently in use.
       * @return The concrete compression implementation.
       * @since 0.9
       */
      CompressionBase* compressionImpl() const { return m_compression; }

      /**
       * Use this function if you have a class supporting some fancy compression algorithm.
       * This should be called before calling connect(). If there already is a
       * compression implementation set (either manually or automatically), it gets deleted.
       * @param cb The compression implementation to use.
       * @since 0.9
       */
      void setCompressionImpl( CompressionBase *cb );

      /**
       * Sends a whitespace ping to the server.
       * @since 0.9
       */
      void whitespacePing();

      /**
       * Sends a XMPP Ping (XEP-0199) to the given JID. There is currently no way to know
       * whether the remote entity answered (other than registering an IQ handler for the
       * urn:xmpp:ping namespace).
       * @since 0.9
       */
      void xmppPing( const JID& to );

      /**
       * Use this function to set an authorization ID (authzid). Provided the server supports it
       * and the user has sufficient rights, they could then authenticate as [e-mail] but
       * act as [e-mail].
       * @param authzid The JID to authorize as. Only the bare JID is used.
       * @since 0.9
       */
      void setAuthzid( const JID& authzid ) { m_authzid = authzid; }

      /**
       * Use this function to limit SASL mechanisms gloox can use. By default, all
       * supported mechanisms are allowed. To exclude one (or more) mechanisms, remove
       * it from SaslMechAll like so:
       * @code
       * int mymechs = SaslMechAll ^ SaslMechDigestMd5;
       * @endcode
       * @param mechanisms Bitwise ORed @ref SaslMechanism.
       * @since 0.9
       */
      void setSASLMechanisms( int mechanisms ) { m_availableSaslMechs = mechanisms; }

      /**
       * Registers @c cl as object that receives connection notifications.
       * @param cl The object to receive connection notifications.
       */
      void registerConnectionListener( ConnectionListener *cl );

      /**
       * Registers @c ih as object that receives Iq stanza notifications for namespace
       * @c xmlns. Only one handler per namespace is possible.
       * @param ih The object to receive Iq stanza notifications.
       * @param xmlns The namespace the object handles.
       */
      void registerIqHandler( IqHandler *ih, const std::string& xmlns );

      /**
       * Use this function to be notified of incoming IQ stanzas with the given value of the @b id
       * attribute.
       * Since IDs are supposed to be unique, this notification works only once.
       * @param ih The IqHandler to receive notifications.
       * @param id The id to track.
       * @param context A value that allows for restoring context.
       */
      void trackID( IqHandler *ih, const std::string& id, int context );

      /**
       * 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.
       * @param ih The IqHandler to remove.