kopete/libkopete/kopeteaccountmanager.h

   1 /*
   2     kopeteaccountmanager.h - Kopete Account Manager
   3
   4     Copyright (c) 2002-2003 by Martijn Klingens      <klingens@kde.org>
   5     Copyright (c) 2003-2005 by Olivier Goffart       <ogoffart@kde.org>
   6
   7     Kopete    (c) 2002-2007 by the Kopete developers <kopete-devel@kde.org>
   8
   9     *************************************************************************
  10     *                                                                       *
  11     * This library is free software; you can redistribute it and/or         *
  12     * modify it under the terms of the GNU Lesser General Public            *
  13     * License as published by the Free Software Foundation; either          *
  14     * version 2 of the License, or (at your option) any later version.      *
  15     *                                                                       *
  16     *************************************************************************
  17 */
  18
  19 #ifndef __kopeteaccountmanager_h__
  20 #define __kopeteaccountmanager_h__
  21
  22 #include <QObject>
  23 #include <QColor>
  24 #include "kopete_export.h"
  25
  26
  27 namespace Kopete {
  28
  29 class Account;
  30 class Plugin;
  31 class Protocol;
  32 class Contact;
  33 class OnlineStatus;
  34
  35 /**
  36  * AccountManager manages all defined accounts in Kopete. You can
  37  * query them and globally set them all online or offline from here.
  38  *
  39  * AccountManager is a singleton, you may uses it with @ref AccountManager::self()
  40  *
  41  * @author Martijn Klingens <klingens@kde.org>
  42  * @author Olivier Goffart <ogoffart\@kde.org>
  43  */
  44 class KOPETE_EXPORT AccountManager : public QObject
  45 {
  46         Q_OBJECT
  47
  48 public:
  49         /**
  50          * \brief Retrieve the instance of AccountManager.
  51          *
  52          * The account manager is a singleton class of which only a single
  53          * instance will exist. If no manager exists yet this function will
  54          * create one for you.
  55          *
  56          * \return the instance of the AccountManager
  57          */
  58         static AccountManager* self();
  59
  60         ~AccountManager();
  61
  62         /**
  63          * \brief Retrieve the list of accounts
  64          * \return a list of all the accounts
  65          */
  66         const QList<Account *> & accounts() const;
  67
  68         /**
  69          * \brief Retrieve a list of accounts per protocol
  70          *
  71          * Provides a list of accounts for a certain protocol. If there are
  72          * no accounts for that protocol then the list is empty.
  73          * \param protocol the protocol to get accounts for
  74          * \return the list of accounts that belong to the @p protocol protocol
  75          */
  76         QList<Account*> accounts( Kopete::Protocol* protocol ) const;
  77
  78         /**
  79          * \brief Return the account asked
  80          * \param protocolId is the ID for the protocol
  81          * \param accountId is the ID for the account you want
  82          * \return the Account object found or NULL if no account was found
  83          */
  84         Account* findAccount( const QString &protocolId, const QString &accountId );
  85
  86         /**
  87          * \brief Delete the account and clean the config data
  88          *
  89          * This is praticaly called by the account config page when you remove the account.
  90          */
  91         void removeAccount( Account *account );
  92
  93         /**
  94          * \brief Guess the color for a new account
  95          *
  96          * Guesses a color for the next account of a given protocol based on the already registered colors
  97          * \return the color guessed for the account
  98          */
  99         QColor guessColor( Protocol *protocol ) const ;
 100
 101         /**
 102          * @brief Register the account.
 103          *
 104          * This adds the account in the manager's account list.
 105          * It will check no accounts already exist with the same ID, if any, the account is deleted. and not added
 106          *
 107          * @return @p account, or 0L if the account was deleted because id collision
 108          */
 109         Account *registerAccount( Account *account );
 110
 111
 112         /**
 113          * Flag to be used in setOnlineStatus
 114          *
 115          * @c ConnectIfOffline : if set, this will connect offlines account with the status.
 116          */
 117         enum SetOnlineStatusFlag { ConnectIfOffline=0x01 };
 118
 119
 120 public slots:
 121         /**
 122          * @deprecated  use setOnlineStatus
 123          */
 124         void connectAll();
 125
 126         /**
 127          * @deprecated  use setOnlineStatus
 128          */
 129         void disconnectAll();
 130
 131         /**
 132          * @brief Set all accounts a status in the specified category
 133          *
 134          * Account that are offline will not be connected, unless the ConnectIfOffline flag is set.
 135          *
 136          * @param category is one of the Kopete::OnlineStatusManager::Categories
 137          * @param awayMessage is the new away message
 138          * @param flags is a bitmask of SetOnlineStatusFlag
 139          */
 140         void setOnlineStatus( /*Kopete::OnlineStatusManager::Categories*/ uint category,
 141                                                   const QString& awayMessage = QString::null, uint flags=0);
 142
 143         /**
 144          * @deprecated  use setOnlineStatus
 145          */
 146         void setAwayAll( const QString &awayReason = QString::null, bool away=true );
 147
 148         /**
 149          * @deprecated  use setOnlineStatus
 150          */
 151         void setAvailableAll( const QString &awayReason = QString::null );
 152
 153         /**
 154          * \internal
 155          * Save the account data to KConfig
 156          */
 157         void save();
 158
 159         /**
 160          * \internal
 161          * Load the account data from KConfig
 162          */
 163         void load();
 164
 165
 166
 167 signals:
 168         /**
 169          * \brief Signals when an account is ready for use
 170          */
 171         void accountRegistered( Kopete::Account *account );
 172
 173         /**
 174          * \brief Signals when an account has been unregistered
 175          *
 176          * At this state, we are already in the Account destructor.
 177          */
 178         void accountUnregistered( const Kopete::Account *account );
 179
 180         /**
 181          * \brief An account has changed its onlinestatus
 182          * Technically this monitors Account::myself() onlinestatus changes
 183          * \param account Account which changed its onlinestatus
 184          * \param oldStatus The online status before the change
 185          * \param newStatus The new online status
 186          */
 187         void accountOnlineStatusChanged(Kopete::Account *account,
 188                 const Kopete::OnlineStatus &oldStatus, const Kopete::OnlineStatus &newStatus);
 189
 190 private:
 191         /**
 192          * Private constructor, because we're a singleton
 193          */
 194         AccountManager();
 195
 196 private slots:
 197         void slotPluginLoaded( Kopete::Plugin *plugin );
 198         void slotAccountOnlineStatusChanged(Kopete::Contact *c,
 199                 const Kopete::OnlineStatus &oldStatus, const Kopete::OnlineStatus &newStatus);
 200
 201         /**
 202          * \internal
 203          * Unregister the account.
 204          */
 205         void unregisterAccount( const Kopete::Account *account );
 206
 207 private:
 208         bool isAnyAccountConnected();
 209         static AccountManager *s_self;
 210         class Private;
 211         Private *d;
 212 };
 213
 214 } //END namespace Kopete
 215
 216
 217 #endif
 218
 219