/* kopeteaccount.h - Kopete Account Copyright (c) 2003-2004 by Olivier Goffart Copyright (c) 2003-2004 by Martijn Klingens Copyright (c) 2004 by Richard Smith Kopete (c) 2002-2004 by the Kopete developers ************************************************************************* * * * 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 #include class TQDomNode; class TDEActionMenu; class TDEConfigGroup; 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 TDEConfig. 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 */ class KOPETE_EXPORT Account : public TQObject { Q_OBJECT TQ_ENUMS( AddMode ) TQ_PROPERTY( TQString accountId READ accountId ) TQ_PROPERTY( bool excludeConnect READ excludeConnect WRITE setExcludeConnect ) TQ_PROPERTY( TQColor color READ color WRITE setColor ) TQ_PROPERTY( TQPixmap accountIcon READ accountIcon ) TQ_PROPERTY( bool isConnected READ isConnected ) TQ_PROPERTY( bool isAway READ isAway ) TQ_PROPERTY( bool suppressStatusNotification READ suppressStatusNotification ) TQ_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 TQObject. */ Account(Protocol *parent, const TQString &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 */ TQString accountId() const; /** * \return The label of this account, for the GUI */ TQString 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 TQColor 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 TQColor &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 */ TQPixmap 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 TQString() to go back to the default (the protocol icon) * * this call will emit colorChanged() */ void setCustomIcon( const TQString& ); /** * \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 */ TQString 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 TDEActionMenu* 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 TQDict& 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 TQString() 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 TQString &contactId, const TQString &displayName = TQString(), 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 TQString&,const TQString&,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 TQString &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 TDEConfigGroup 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 */ TDEConfigGroup *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 TQString &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 TQString &contactId, MetaContact *parentContact ) =0; /** * \brief Sets the account label * * @param label The label to set */ void setAccountLabel( const TQString &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 TQColor & ); /** * 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 TDEConfig. */ 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 TQString &reason = TQString() ); /** * 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 TQString &reason = TQString() ) = 0; /** * Display the edit account widget for the account */ void editAccount( TQWidget* 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 TQString &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 TQString &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 TQString &, const TQVariant &, const TQVariant & ); /** * 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 TQString &key, const TQString &value ) KDE_DEPRECATED; /** * @todo remove * @deprecated use configGroup */ TQString pluginData( Plugin* /*plugin*/, const TQString &key ) const KDE_DEPRECATED; }; } //END namespace Kopete #endif