summaryrefslogtreecommitdiffstats
path: root/kopete/libkopete/kopeteaccount.h
diff options
context:
space:
mode:
authortoma <toma@283d02a7-25f6-0310-bc7c-ecb5cbfe19da>2009-11-25 17:56:58 +0000
committertoma <toma@283d02a7-25f6-0310-bc7c-ecb5cbfe19da>2009-11-25 17:56:58 +0000
commitbcb704366cb5e333a626c18c308c7e0448a8e69f (patch)
treef0d6ab7d78ecdd9207cf46536376b44b91a1ca71 /kopete/libkopete/kopeteaccount.h
downloadtdenetwork-bcb704366cb5e333a626c18c308c7e0448a8e69f.tar.gz
tdenetwork-bcb704366cb5e333a626c18c308c7e0448a8e69f.zip
Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.
BUG:215923 git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdenetwork@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da
Diffstat (limited to 'kopete/libkopete/kopeteaccount.h')
-rw-r--r--kopete/libkopete/kopeteaccount.h554
1 files changed, 554 insertions, 0 deletions
diff --git a/kopete/libkopete/kopeteaccount.h b/kopete/libkopete/kopeteaccount.h
new file mode 100644
index 00000000..f3c2d338
--- /dev/null
+++ b/kopete/libkopete/kopeteaccount.h
@@ -0,0 +1,554 @@
+/*
+ kopeteaccount.h - Kopete Account
+
+ Copyright (c) 2003-2004 by Olivier Goffart <ogoffart@ tiscalinet.be>
+ Copyright (c) 2003-2004 by Martijn Klingens <[email protected]>
+ Copyright (c) 2004 by Richard Smith <[email protected]>
+ Kopete (c) 2002-2004 by the Kopete developers <[email protected]>
+
+ *************************************************************************
+ * *
+ * This library is free software; you can redistribute it and/or *
+ * modify it under the terms of the GNU Lesser General Public *
+ * License as published by the Free Software Foundation; either *
+ * version 2 of the License, or (at your option) any later version. *
+ * *
+ *************************************************************************
+*/
+
+#ifndef KOPETEACCOUNT_H
+#define KOPETEACCOUNT_H
+
+#include "kopeteonlinestatus.h"
+
+#include "kopete_export.h"
+
+#include <qobject.h>
+#include <qdict.h>
+
+class QDomNode;
+class KActionMenu;
+class KConfigGroup;
+
+namespace Kopete
+{
+class Contact;
+class Plugin;
+class Protocol;
+class MetaContact;
+class Group;
+class OnlineStatus;
+class BlackLister;
+
+/**
+ * The Kopete::Account class handles one account.
+ * Each protocol should subclass this class in its own custom accounts class.
+ * There are few pure virtual method that the protocol must implement. Examples are:
+ * \li \ref connect()
+ * \li \ref disconnect()
+ * \li \ref createContact()
+ *
+ * If your account requires a password, derive from @ref PasswordedAccount instead of this class.
+ *
+ * The accountId is an @em constant unique id, which represents the login.
+ * The @ref myself() contact is one of the most important contacts, which represents
+ * the user tied to this account. You must create this contact in the contructor of your
+ * account and pass it to @ref setMyself().
+ *
+ * All account data is saved to @ref KConfig. This includes the accountId, the autoconnect flag and
+ * the color. You can save more data using @ref configGroup()
+ *
+ * When you create a new account, you have to register it with the account manager by calling
+ * @ref AccountManager::registerAccount.
+ *
+ * @author Olivier Goffart <[email protected]>
+ */
+class KOPETE_EXPORT Account : public QObject
+{
+ Q_OBJECT
+
+ Q_ENUMS( AddMode )
+ Q_PROPERTY( QString accountId READ accountId )
+ Q_PROPERTY( bool excludeConnect READ excludeConnect WRITE setExcludeConnect )
+ Q_PROPERTY( QColor color READ color WRITE setColor )
+ Q_PROPERTY( QPixmap accountIcon READ accountIcon )
+ Q_PROPERTY( bool isConnected READ isConnected )
+ Q_PROPERTY( bool isAway READ isAway )
+ Q_PROPERTY( bool suppressStatusNotification READ suppressStatusNotification )
+ Q_PROPERTY( uint priority READ priority WRITE setPriority )
+
+public:
+ /**
+ * \brief Describes how the account was disconnected
+ *
+ * Manual means that the disconnection was done by the user and no reconnection
+ * will take place. Any other value will reconnect the account on disconnection.
+ * The case where the password is wrong will be handled differently.
+ * @see @ref disconnected
+ */
+ enum DisconnectReason {
+ OtherClient = -4, ///< connection went down because another client connected the same account
+ BadPassword = -3, ///< connection failed because password was incorrect
+ BadUserName = -2, ///< connection failed because user name was invalid / unknown
+ InvalidHost = -1, ///< connection failed because host is unreachable
+ Manual = 0, ///< the user disconnected normally
+ ConnectionReset = 1, ///< the connection was lost
+ Unknown = 99 ///< the reason for disconnection is unknown
+ };
+
+ /**
+ * @param parent the protocol for this account. The account is a child object of the
+ * protocol, so it will be automatically deleted when the protocol is.
+ * @param accountID the unique ID of this account.
+ * @param name the name of this QObject.
+ */
+ Account(Protocol *parent, const QString &accountID, const char *name=0L);
+ ~Account();
+
+ /**
+ * \return the Protocol for this account
+ */
+ Protocol *protocol() const ;
+
+ /**
+ * \return the unique ID of this account used as the login
+ */
+ QString accountId() const;
+
+ /**
+ * \return The label of this account, for the GUI
+ */
+ QString accountLabel() const;
+
+ /**
+ * \brief Get the priority of this account.
+ *
+ * Used for sorting and determining the preferred account to message a contact.
+ */
+ uint priority() const;
+
+ /**
+ * \brief Set the priority of this account.
+ *
+ * @note This method is called by the UI, and should not be called elsewhere.
+ */
+ void setPriority( uint priority );
+
+ /**
+ * \brief Set if the account should not log in automatically.
+ *
+ * This function can be used by the EditAccountPage. Kopete handles connection automatically.
+ * @sa @ref excludeConnect
+ */
+ void setExcludeConnect(bool);
+
+ /**
+ * \brief Get if the account should not log in.
+ *
+ * @return @c true if the account should not be connected when connectAll at startup, @c false otherwise.
+ */
+ bool excludeConnect() const;
+
+ /**
+ * \brief Get the color for this account.
+ *
+ * The color will be used to visually differentiate this account from other accounts on the
+ * same protocol.
+ *
+ * \return the user color for this account
+ */
+ const QColor color() const;
+
+ /**
+ * \brief Set the color for this account.
+ *
+ * This is called by Kopete's account config page; you don't have to set the color yourself.
+ *
+ * @sa @ref color()
+ */
+ void setColor( const QColor &color);
+
+ /**
+ * \brief Get the icon for this account.
+ *
+ * Generates an image of size @p size representing this account. The result is not cached.
+ *
+ * @param size the size of the icon. If the size is 0, the default size is used.
+ * @return the icon for this account, colored if needed
+ */
+ QPixmap accountIcon( const int size = 0 ) const;
+
+ /**
+ * \brief change the account icon.
+ * by default the icon of an account is the protocol one, but it may be overide it.
+ * Set QString::null to go back to the default (the protocol icon)
+ *
+ * this call will emit colorChanged()
+ */
+ void setCustomIcon( const QString& );
+
+ /**
+ * \brief return the icon base
+ * This is the custom account icon set with setIcon. if this icon is null, then the protocol icon is used
+ * don't use this funciton to get the icon that need to be displayed, use accountIcon
+ */
+ QString customIcon() const;
+
+
+
+
+ /**
+ * \brief Retrieve the 'myself' contact.
+ *
+ * \return a pointer to the Contact object for this account
+ *
+ * \see setMyself().
+ */
+ Contact * myself() const;
+
+ /**
+ * @brief Return the menu for this account
+ *
+ * You have to reimplement this method to return the custom action menu which will
+ * be shown in the statusbar. It is the caller's responsibility to ensure the menu is deleted.
+ *
+ * The default implementation provides a generic menu, with actions generated from the protocol's
+ * registered statuses, and an action to show the account's settings dialog.
+ *
+ * You should call the default implementation from your reimplementation, and add more actions
+ * you require to the resulting action menu.
+ *
+ * @see OnlineStatusManager::registerOnlineStatus
+ */
+ virtual KActionMenu* actionMenu() ;
+
+ /**
+ * @brief Retrieve the list of contacts for this account
+ *
+ * The list is guaranteed to contain only contacts for this account,
+ * so you can safely use static_cast to your own derived contact class
+ * if needed.
+ */
+ const QDict<Contact>& contacts();
+
+ /**
+ * Indicates whether or not we should suppress status notifications
+ * for contacts belonging to this account.
+ *
+ * This is used when we just connected or disconnected, and every contact has their initial
+ * status set.
+ *
+ * @return @c true if notifications should not be used, @c false otherwise
+ */
+ bool suppressStatusNotification() const;
+
+ /**
+ * \brief Describes what should be done when the contact is added to a metacontact
+ * @sa @ref addContact()
+ */
+ enum AddMode {
+ ChangeKABC = 0, ///< The KDE Address book may be updated
+ DontChangeKABC = 1, ///< The KDE Address book will not be changed
+ Temporary = 2 ///< The contact will not be added on the contactlist
+ };
+
+ /**
+ * \brief Create a contact (creating a new metacontact if necessary)
+ *
+ * If a contact for this account with ID @p contactId is not already on the contact list,
+ * a new contact with that ID is created, and added to a new metacontact.
+ *
+ * If @p mode is @c ChangeKABC, MetaContact::updateKABC will be called on the resulting metacontact.
+ * If @p mode is @c Temporary, MetaContact::setTemporary will be called on the resulting metacontact,
+ * and the metacontact will not be added to @p group.
+ * If @p mode is @c DontChangeKABC, no additional action is carried out.
+ *
+ * @param contactId the @ref Contact::contactId of the contact to create
+ * @param displayName the displayname (alias) of the new metacontact. Leave as QString::null if
+ * no alias is known, then by default, the nick will be taken as alias and tracked if changed.
+ * @param group the group to add the created metacontact to, or 0 for the top-level group.
+ * @param mode the mode used to add the contact. Use DontChangeKABC when deserializing.
+ * @return the new created metacontact or 0L if the operation failed
+ */
+ MetaContact* addContact( const QString &contactId, const QString &displayName = QString::null, Group *group = 0, AddMode mode = DontChangeKABC ) ;
+
+ /**
+ * @brief Create a new contact, adding it to an existing metacontact
+ *
+ * If a contact for this account with ID @p contactId is not already on the contact list,
+ * a new contact with that ID is created, and added to the metacontact @p parent.
+ *
+ * @param contactId the @ref Contact::contactId of the contact to create
+ * @param parent the parent metacontact (must not be 0)
+ * @param mode the mode used to add the contact. See addContact(const QString&,const QString&,Group*,AddMode) for details.
+ *
+ * @return @c true if creation of the contact succeeded or the contact was already in the list,
+ * @c false otherwise.
+ */
+ bool addContact( const QString &contactId, MetaContact *parent, AddMode mode = DontChangeKABC );
+
+ /**
+ * @brief Indicate whether the account is connected at all.
+ *
+ * This is a convenience method that calls @ref Contact::isOnline() on @ref myself().
+ * This function is safe to call if @ref setMyself() has not been called yet.
+ *
+ * @see @ref isConnectedChanged()
+ */
+ bool isConnected() const;
+
+ /**
+ * @brief Indicate whether the account is away.
+ *
+ * This is a convenience method that queries @ref Contact::onlineStatus() on @ref myself().
+ * This function is safe to call if @ref setMyself() has not been called yet.
+ */
+ bool isAway() const;
+
+ /**
+ * Return the @ref KConfigGroup used to write and read special properties
+ *
+ * "Protocol", "AccountId" , "Color", "AutoConnect", "Priority", "Enabled" , "Icon" are reserved keyword
+ * already in use in that group.
+ *
+ * for compatibility, try to not use key that start with a uppercase
+ */
+ KConfigGroup *configGroup() const;
+
+ /**
+ * @brief Remove the account from the server.
+ *
+ * Reimplement this if your protocol supports removing the accounts from the server.
+ * This function is called by @ref AccountManager::removeAccount typically when you remove the
+ * account on the account config page.
+ *
+ * You should add a confirmation message box before removing the account. The default
+ * implementation does nothing.
+ *
+ * @return @c false only if the user requested for the account to be deleted, and deleting the
+ * account failed. Returns @c true in all other cases.
+ */
+ virtual bool removeAccount();
+
+ /**
+ * \return a pointer to the blacklist of the account
+ */
+ BlackLister* blackLister();
+
+ /**
+ * \return @c true if the contact with ID @p contactId is in the blacklist, @c false otherwise.
+ */
+ virtual bool isBlocked( const QString &contactId );
+
+protected:
+ /**
+ * \brief Set the 'myself' contact.
+ *
+ * This contact must be defined for every account, because it holds the online status
+ * of the account. You must call this function in the constructor of your account.
+ *
+ * The myself contact can't be deleted as long as the account still exists. The myself
+ * contact is used as a member of every ChatSession involving this account. myself's
+ * contactId should be the accountID. The online status of the myself contact represents
+ * the account's status.
+ *
+ * The myself should have the @ref ContactList::myself() as parent metacontact
+ *
+ */
+ void setMyself( Contact *myself );
+
+ /**
+ * \brief Create a new contact in the specified metacontact
+ *
+ * You shouldn't ever call this method yourself. To add contacts, use @ref addContact().
+ *
+ * This method is called by @ref addContact(). In this method, you should create the
+ * new custom @ref Contact, using @p parentContact as the parent.
+ *
+ * If the metacontact is not temporary and the protocol supports it, you can add the
+ * contact to the server.
+ *
+ * @param contactId the ID of the contact to create
+ * @param parentContact the metacontact to add this contact to
+ * @return @c true if creating the contact succeeded, @c false on failure.
+ */
+ virtual bool createContact( const QString &contactId, MetaContact *parentContact ) =0;
+
+
+ /**
+ * \brief Sets the account label
+ *
+ * @param label The label to set
+ */
+ void setAccountLabel( const QString &label );
+
+protected slots:
+ /**
+ * \brief The service has been disconnected
+ *
+ * You have to call this method when you are disconnected. Depending on the value of
+ * @p reason, this function may attempt to reconnect to the server.
+ *
+ * - BadPassword will ask again for the password
+ * - OtherClient will show a message box
+ *
+ * @param reason the reason for the disconnection.
+ */
+ virtual void disconnected( Kopete::Account::DisconnectReason reason );
+
+ /**
+ * @brief Sets the online status of all contacts in this account to the same value
+ *
+ * Some protocols do not provide status-changed events for all contacts when an account
+ * becomes connected or disconnected. For such protocols, this function may be useful
+ * to set all contacts offline.
+ *
+ * Calls @ref Kopete::Contact::setOnlineStatus on all contacts of this account (except the
+ * @ref myself() contact), passing @p status as the status.
+ *
+ * @param status the status to set all contacts of this account except @ref myself() to.
+ */
+ void setAllContactsStatus( const Kopete::OnlineStatus &status );
+
+signals:
+ /**
+ * The color of the account has been changed
+ *
+ * also emited when the icon change
+ * @todo probably rename to accountIconChanged
+ */
+ void colorChanged( const QColor & );
+
+ /**
+ * Emitted when the account is deleted.
+ * @warning emitted in the Account destructor. It is not safe to call any functions on @p account.
+ */
+ void accountDestroyed( const Kopete::Account *account );
+
+ /**
+ * Emitted whenever @ref isConnected() changes.
+ */
+ void isConnectedChanged();
+
+private:
+ /**
+ * @internal
+ * Reads the configuration information of the account from KConfig.
+ */
+ void readConfig();
+
+public:
+ /**
+ * @internal
+ * Register a new Contact with the account. This should be called @em only from the
+ * @ref Contact constructor, not from anywhere else (not even a derived class).
+ */
+ void registerContact( Contact *c );
+
+public slots:
+ /**
+ * @brief Go online for this service.
+ *
+ * @param initialStatus is the status to connect with. If it is an invalid status for this
+ * account, the default online for the account should be used.
+ */
+ virtual void connect( const Kopete::OnlineStatus& initialStatus = OnlineStatus() ) = 0;
+
+ /**
+ * @brief Go offline for this service.
+ *
+ * If the service is connecting, you should abort the connection.
+ *
+ * You should call the @ref disconnected function from this function.
+ */
+ virtual void disconnect( ) = 0 ;
+
+public slots:
+ /**
+ * If @p away is @c true, set the account away with away message @p reason. Otherwise,
+ * set the account to not be away.
+ *
+ * @todo change ; make use of setOnlineStatus
+ */
+ virtual void setAway( bool away, const QString &reason = QString::null );
+
+ /**
+ * Reimplement this function to set the online status
+ * @param status is the new status
+ * @param reason is the away message to set.
+ * @note If needed, you need to connect. if the offline status is given, you should disconnect
+ */
+ virtual void setOnlineStatus( const Kopete::OnlineStatus& status , const QString &reason = QString::null ) = 0;
+
+ /**
+ * Display the edit account widget for the account
+ */
+ void editAccount( QWidget* parent = 0L );
+
+ /**
+ * Add a user to the blacklist. The default implementation calls
+ * blackList()->addContact( contactId )
+ *
+ * @param contactId the contact to be added to the blacklist
+ */
+ virtual void block( const QString &contactId );
+
+ /**
+ * Remove a user from the blacklist. The default implementation calls
+ * blackList()->removeContact( contactId )
+ *
+ * @param contactId the contact to be removed from the blacklist
+ */
+ virtual void unblock( const QString &contactId );
+
+private slots:
+ /**
+ * Restore online status and status message on reconnect.
+ */
+ virtual void reconnect();
+
+ /**
+ * Track the deletion of a Contact and clean up
+ */
+ void contactDestroyed( Kopete::Contact * );
+
+ /**
+ * The @ref myself() contact's online status changed.
+ */
+ void slotOnlineStatusChanged( Kopete::Contact *contact, const Kopete::OnlineStatus &newStatus, const Kopete::OnlineStatus &oldStatus );
+
+ /**
+ * The @ref myself() contact's property changed.
+ */
+ void slotContactPropertyChanged( Kopete::Contact *, const QString &, const QVariant &, const QVariant & );
+
+ /**
+ * Stop the suppression of status notification (connected to a timer)
+ */
+ void slotStopSuppression();
+
+private:
+ class Private;
+ Private *d;
+
+protected:
+ virtual void virtual_hook( uint id, void* data);
+
+public:
+ /**
+ * @todo remove
+ * @deprecated use configGroup
+ */
+ void setPluginData( Plugin* /*plugin*/, const QString &key, const QString &value ) KDE_DEPRECATED;
+
+ /**
+ * @todo remove
+ * @deprecated use configGroup
+ */
+ QString pluginData( Plugin* /*plugin*/, const QString &key ) const KDE_DEPRECATED;
+};
+
+} //END namespace Kopete
+
+#endif
+