clientbase.h

Jabber code library, developed with c

       * @since 0.8.7
       */
      void removeIDHandler( IqHandler *ih );

      /**
       * Registers @c mh as object that receives Message stanza notifications.
       * @param mh The object to receive Message stanza notifications.
       */
      void registerMessageHandler( MessageHandler *mh );

      /**
       * Removes the given object from the list of message handlers.
       * @param mh The object to remove from the list.
       */
      void removeMessageHandler( MessageHandler *mh );

      /**
       * 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().
       * @param session The MessageSession to register.
       * @note Since a MessageSession automatically registers itself with the ClientBase, there is no
       * need to call this function directly.
       */
      void registerMessageSession( MessageSession *session );

      /**
       * Removes the given MessageSession from the  list of MessageSessions and deletes it.
       * @param session The MessageSession to be deleted.
       */
      void disposeMessageSession( MessageSession *session );

      /**
       * Registers @c ph as object that receives Presence stanza notifications.
       * @param ph The object to receive Presence stanza notifications.
       */
      void registerPresenceHandler( 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.
       * @param jid The JID to 'watch'.
       * @param ph The PresenceHandler to inform about presence changes from @c jid.
       * @since 0.9
       */
      void registerPresenceHandler( const JID& jid, PresenceHandler *ph );

      /**
       * Registers @c sh as object that receives Subscription stanza notifications.
       * @param sh The object to receive Subscription stanza notifications.
       */
      void registerSubscriptionHandler( SubscriptionHandler *sh );

      /**
       * Registers @c th as object that receives incoming packts with a given root tag
       * qualified by the given namespace.
       * @param th The object to receive Subscription packet notifications.
       * @param tag The element's name.
       * @param xmlns The element's namespace.
       */
      void registerTagHandler( TagHandler *th, const std::string& tag,
                                               const std::string& xmlns );

      /**
       * Registers @c 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.
       * @param sh The StatisticsHandler to register.
       */
      void registerStatisticsHandler( StatisticsHandler *sh );

      /**
       * Removes the given object from the list of connection listeners.
       * @param cl The object to remove from the list.
       */
      void removeConnectionListener( ConnectionListener *cl );

      /**
       * Removes the handler for the given namespace from the list of Iq handlers.
       * @param xmlns The namespace to remove from the list.
       */
      void removeIqHandler( const std::string& xmlns );

      /**
       * Removes the given object from the list of presence handlers.
       * @param ph The object to remove from the list.
       */
      void removePresenceHandler( PresenceHandler *ph );

      /**
       * Removes the given object from the list of presence handlers for the given JID.
       * @param jid The JID to remove the PresenceHandler(s) for.
       * @param ph The PresenceHandler to remove from the list. If @c ph is 0,
       * all handlers for the given JID will be removed.
       */
      void removePresenceHandler( const JID& jid, PresenceHandler *ph );

      /**
       * Removes the given object from the list of subscription handlers.
       * @param sh The object to remove from the list.
       */
      void removeSubscriptionHandler( SubscriptionHandler *sh );

      /**
       * Removes the given object from the list of tag handlers for the given element and namespace.
       * @param th The object to remove from the list.
       * @param tag The element to remove the handler for.
       * @param xmlns The namespace qualifying the element.
       */
      void removeTagHandler( TagHandler *th, const std::string& tag,
                                             const std::string& xmlns );

      /**
       * Removes the current StatisticsHandler.
       */
      void removeStatisticsHandler();

      /**
       * Use this function to set a number of trusted root CA certificates which shall be
       * used to verify a servers certificate.
       * @param cacerts A list of absolute paths to CA root certificate files in PEM format.
       */
      void setCACerts( const StringList& cacerts ) { m_cacerts = cacerts; }

      /**
       * 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.
       * @param clientKey The absolute path to the user's private key in PEM format.
       * @param clientCerts A path to a certificate bundle in PEM format.
       */
      void setClientCert( const std::string& clientKey, const std::string& clientCerts );

      /**
       * 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.<br>
       * A MessageSession will be created for every incoming
       * message stanza if there is no MessageHandler registered for the originating JID.
       * @param msh The MessageSessionHandler that will receive the newly created MessageSession.
       * @param 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).
       */
      void registerMessageSessionHandler( MessageSessionHandler *msh, int types = 0 );

      /**
       * Returns the LogSink instance for this ClientBase and all related objects.
       * @return The LogSink instance used in the current ClientBase.
       */
      LogSink& logInstance();

      /**
       * Use this function to retrieve the type of the stream error after it occurs and you received a
       * ConnectionError of type @b ConnStreamError from the ConnectionListener.
       * @return The StreamError.
       * @note The return value is only meaningful when called from ConnectionListener::onDisconnect().
       */
      StreamError streamError() const { return m_streamError; }

      /**
       * 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.
       * @param 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.
       * @return The describing text of a stream error. Empty if no stream error occured.
       */
      const std::string streamErrorText( const std::string& lang = "default" ) const;

      /**
       * 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.
       * @return The cdata of the stream error's text element (only for see-other-host).
       */
      const std::string& streamErrorCData() const { return m_streamErrorCData; }

      /**
       * This function can be used to retrieve the application-specific error condition of a stream error.
       * @return The application-specific error element of a stream error. 0 if no respective element was
       * found or no error occured.
       */
      const Tag* streamErrorAppCondition() const { return m_streamErrorAppCondition; }

      /**
       * Use this function to retrieve the type of the authentication error after it occurs and you
       * received a ConnectionError of type @b ConnAuthenticationFailed from the ConnectionListener.
       * @return The type of the authentication, if any, @b AuthErrorUndefined otherwise.
       */
      AuthenticationError authError() const { return m_authError; }

      /**
       * Returns a StatisticsStruct containing byte and stanza counts for the current
       * active connection.
       * @return A struct containing the current connection's statistics.
       */
      StatisticsStruct getStatistics();

      /**
       * Registers a MUCInvitationHandler with the ClientBase.
       * @param mih The MUCInvitationHandler to register.
       */
      void registerMUCInvitationHandler( MUCInvitationHandler *mih );

      /**
       * Removes the currently registered MUCInvitationHandler.
       */
      void removeMUCInvitationHandler();

      // reimplemented from ParserHandler
      virtual void handleTag( Tag *tag );

      // reimplemented from CompressionDataHandler
      virtual void handleCompressedData( const std::string& data );

      // reimplemented from CompressionDataHandler
      virtual void handleDecompressedData( const std::string& data );

      // reimplemented from ConnectionDataHandler
      virtual void handleReceivedData( const ConnectionBase* connection, const std::string& data );

      // reimplemented from ConnectionDataHandler
      virtual void handleConnect( const ConnectionBase* connection );

      // reimplemented from ConnectionDataHandler
      virtual void handleDisconnect( const ConnectionBase* connection, ConnectionError reason );

      // reimplemented from TLSHandler
      virtual void handleEncryptedData( const TLSBase *base, const std::string& data );

      // reimplemented from TLSHandler
      virtual void handleDecryptedData( const TLSBase *base, const std::string& data );

      // reimplemented from TLSHandler
      virtual void handleHandshakeResult( const TLSBase *base, bool success, CertInfo &certinfo );

    protected:
      void notifyOnResourceBindError( ResourceBindError error );
      void notifyOnSessionCreateError( SessionCreateError error );
      bool notifyOnTLSConnect( const CertInfo& info );
      void notifyOnConnect();
      void notifyStreamEvent( StreamEvent event );
      virtual void disconnect( ConnectionError reason );
      void header();
      void setAuthed( bool authed ) { m_authed = authed; }
      void setAuthFailure( AuthenticationError e ) { m_authError = e; }
      virtual bool checkStreamVersion( const std::string& version );

      void startSASL( SaslMechanism type );
      void processSASLChallenge( const std::string& challenge );
      void processSASLError( Stanza *stanza );
      void startTls();
      bool hasTls();

      JID m_jid;
      JID m_authzid;
      ConnectionBase *m_connection;
      TLSBase *m_encryption;
      CompressionBase *m_compression;
      Disco *m_disco;

      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_compressionActive;
      bool m_encryptionActive;
      bool m_compress;
      bool m_authed;
      bool m_block;
      bool m_sasl;
      TLSPolicy m_tls;
      int m_port;

      int m_availableSaslMechs;

    private:
      ClientBase( const ClientBase& );
      ClientBase& operator=( const ClientBase& );

      virtual void handleStartNode() = 0;
      virtual bool handleNormalNode( Stanza *stanza ) = 0;
      virtual void rosterFilled() = 0;
      virtual void cleanup() {}
      void parse( const std::string& data );
      void init();
      void handleStreamError( Stanza *stanza );
      TLSBase* getDefaultEncryption();
      CompressionBase* getDefaultCompression();

      void notifyIqHandlers( Stanza *stanza );
      void notifyMessageHandlers( Stanza *stanza );
      void notifyPresenceHandlers( Stanza *stanza );
      void notifySubscriptionHandlers( Stanza *stanza );
      void notifyTagHandlers( Tag *tag );
      void notifyOnDisconnect( ConnectionError e );
      void send( const std::string& xml );

      struct TrackStruct
      {
        IqHandler *ih;
        int context;
      };

      struct TagHandlerStruct
      {
        TagHandler *th;
        std::string xmlns;
        std::string tag;
      };

      struct JidPresHandlerStruct
      {
        JID *jid;
        PresenceHandler* ph;
      };

      typedef std::list<ConnectionListener*>               ConnectionListenerList;
      typedef std::map<const std::string, IqHandler*>      IqHandlerMap;
      typedef std::map<const std::string, TrackStruct>     IqTrackMap;
      typedef std::map<const std::string, MessageHandler*> MessageHandlerMap;
      typedef std::list<MessageSession*>                   MessageSessionList;
      typedef std::list<MessageHandler*>                   MessageHandlerList;
      typedef std::list<PresenceHandler*>                  PresenceHandlerList;
      typedef std::list<JidPresHandlerStruct>              PresenceJidHandlerList;
      typedef std::list<SubscriptionHandler*>              SubscriptionHandlerList;
      typedef std::list<TagHandlerStruct>                  TagHandlerList;

      ConnectionListenerList   m_connectionListeners;
      IqHandlerMap             m_iqNSHandlers;
      IqTrackMap               m_iqIDHandlers;
      MessageSessionList       m_messageSessions;
      MessageHandlerList       m_messageHandlers;
      PresenceHandlerList      m_presenceHandlers;
      PresenceJidHandlerList   m_presenceJidHandlers;
      SubscriptionHandlerList  m_subscriptionHandlers;
      TagHandlerList           m_tagHandlers;
      StringList               m_cacerts;
      StatisticsHandler       *m_statisticsHandler;
      MUCInvitationHandler    *m_mucInvitationHandler;
      MessageSessionHandler   *m_messageSessionHandlerChat;
      MessageSessionHandler   *m_messageSessionHandlerGroupchat;
      MessageSessionHandler   *m_messageSessionHandlerHeadline;
      MessageSessionHandler   *m_messageSessionHandlerNormal;

      Parser *m_parser;
      LogSink m_logInstance;

      AuthenticationError m_authError;
      StreamError m_streamError;
      StringMap m_streamErrorText;
      std::string m_streamErrorCData;
      Tag *m_streamErrorAppCondition;

      StatisticsStruct m_stats;

      SaslMechanism m_selectedSaslMech;

      int m_idCount;
      bool m_autoMessageSession;

  };

}

#endif // CLIENTBASE_H__