You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
556 lines
18 KiB
556 lines
18 KiB
/*
|
|
kopeteaccount.h - Kopete Account
|
|
|
|
Copyright (c) 2003-2004 by Olivier Goffart <ogoffart@ tiscalinet.be>
|
|
Copyright (c) 2003-2004 by Martijn Klingens <klingens@kde.org>
|
|
Copyright (c) 2004 by Richard Smith <kde@metafoo.co.uk>
|
|
Kopete (c) 2002-2004 by the Kopete developers <kopete-devel@kde.org>
|
|
|
|
*************************************************************************
|
|
* *
|
|
* 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 <tqobject.h>
|
|
#include <tqdict.h>
|
|
|
|
class TQDomNode;
|
|
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 <ogoffart@tiscalinet.be>
|
|
*/
|
|
class KOPETE_EXPORT Account : public TQObject
|
|
{
|
|
Q_OBJECT
|
|
|
|
|
|
Q_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 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 TQDict<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 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 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 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 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 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
|
|
|