kopete/libkopete/kopetepassword.h

   1 /*
   2     kopetepassword.h - Kopete Password
   3
   4     Copyright (c) 2004      by Richard Smith         <kde@metafoo.co.uk>
   5     Kopete    (c) 2002-2004 by the Kopete developers <kopete-devel@kde.org>
   6
   7     *************************************************************************
   8     *                                                                       *
   9     * This library is free software; you can redistribute it and/or         *
  10     * modify it under the terms of the GNU Lesser General Public            *
  11     * License as published by the Free Software Foundation; either          *
  12     * version 2 of the License, or (at your option) any later version.      *
  13     *                                                                       *
  14     *************************************************************************
  15 */
  16
  17 #ifndef KOPETEPASSWORD_H
  18 #define KOPETEPASSWORD_H
  19
  20 #include <QtCore/QObject>
  21 #include <QtGui/QPixmap>
  22
  23 #include "kopete_export.h"
  24
  25 namespace KWallet { class Wallet; }
  26
  27 class QPixmap;
  28
  29 /** @internal */
  30 class KopetePasswordGetRequest;
  31 /** @internal */
  32 class KopetePasswordSetRequest;
  33 /** @internal */
  34 class KopetePasswordClearRequest;
  35
  36 namespace Kopete
  37 {
  38
  39 /**
  40  * @author Richard Smith       <kde@metafoo.co.uk>
  41  *
  42  * The Kopete::Password object is responsible for storing and retrieving a
  43  * password for a plugin or account object.
  44  *
  45  * If the KWallet is active, passwords will be stored in it, otherwise, they
  46  * will be stored in the KConfig, in a slightly mangled form.
  47  */
  48 class KOPETE_EXPORT Password : public QObject
  49 {
  50         Q_OBJECT
  51
  52 public:
  53         /**
  54          * Create a new Kopete::Password object.
  55          *
  56          * @param configGroup The configuration group to save passwords in.
  57          * @param allowBlankPassword If this password is allowed to be blank
  58          * @param name The name for this object
  59          */
  60         explicit Password( const QString &configGroup, bool allowBlankPassword = false );
  61
  62         /**
  63          * Create a shallow copy of this object
  64          */
  65         Password( const Password &other );
  66         ~Password();
  67
  68         /**
  69          * Assignment operator for passwords: make this object represent a different password
  70          */
  71         Password &operator=( Password &other );
  72
  73         /**
  74          * Returns the preferred size for images passed to the retrieve and request functions.
  75          */
  76         static int preferredImageSize();
  77
  78         /**
  79          * @brief Returns whether the password currently stored by this object is known to be incorrect.
  80          * This flag gets reset whenever the user enters a new password, and is
  81          * expected to be set by the user of this class if it is detected that the
  82          * password the user entered is wrong.
  83          */
  84         bool isWrong();
  85         /**
  86          * Flag the password as being incorrect.
  87          * @see isWrong
  88          */
  89         void setWrong( bool bWrong = true );
  90
  91         /**
  92          * Type of password request to perform:
  93          * FromConfigOrUser : get the password from the config file, or from the user
  94          * if no password in config.
  95          * FromUser : always ask the user for a password (ie, if last password was
  96          * wrong or you know the password has changed).
  97          */
  98         enum PasswordSource { FromConfigOrUser, FromUser };
  99
 100         /**
 101          * @brief Start an asynchronous call to get the password.
 102          * Causes a password entry dialog to appear if the password is not set. Triggers
 103          * a provided slot when done, but not until after this function has returned (you
 104          * don't need to worry about reentrancy or nested event loops).
 105          *
 106          * @param receiver The object to notify when the password request finishes
 107          * @param slot The slot on receiver to call at the end of the request. The signature
 108          *        of this function should be slot( const QString &password ). password will
 109          *        be the password if successful, or QString() if failed.
 110          * @param image The icon to display in the dialog when asking for the password
 111          * @param prompt The message to display to the user, asking for a
 112          *        password. Can be any Qt RichText string.
 113          * @param source The source the password is taken from if a wrong or
 114          *        invalid password is entered or the password could not be found in the wallet
 115          */
 116         void request( QObject *receiver, const char *slot, const QPixmap &image,
 117                 const QString &prompt, PasswordSource source = FromConfigOrUser );
 118
 119         /**
 120          * @brief Start an asynchronous password request without a prompt
 121          *
 122          * Starts an asynchronous password request. Does not pop up a password entry dialog
 123          * if there is no password.
 124          * @see request(QObject*,const char*,const QPixmap&,const QString&,bool,unsigned int)
 125          * The password given to the provided slot will be NULL if no password could be retrieved for
 126          * some reason, such as the user declining to open the wallet, or no password being found.
 127          */
 128         void requestWithoutPrompt( QObject *receiver, const char *slot );
 129
 130         /**
 131          * @return true if the password is remembered, false otherwise.
 132          *
 133          * If it returns false, calling @ref request() will
 134          * pop up an Enter Password window.
 135          */
 136         bool remembered();
 137
 138         /**
 139          * @return true if you are allowed to have a blank password
 140          */
 141         bool allowBlankPassword();
 142
 143         /**
 144          * When a password request succeeds, the password is cached. This function
 145          * returns the cached password, if there is one, or QString() if there
 146          * is not.
 147          */
 148         QString cachedValue();
 149
 150 public slots:
 151         /**
 152          * Set the password for this account.
 153          * @param pass If set to QString(), the password is forgotten unless you
 154          *      specified to allow blank passwords. Otherwise, sets the password to
 155          *      this value.
 156          *
 157          * Note: this function is asynchronous; changes will not be instant.
 158          */
 159         void set( const QString &pass = QString() );
 160
 161         /**
 162          * Unconditionally clears the stored password
 163          */
 164         void clear();
 165
 166 private:
 167         void readConfig();
 168         void writeConfig();
 169
 170         class Private;
 171         Private *d;
 172
 173         //TODO: can we rearrange things so these aren't friends?
 174         friend class ::KopetePasswordGetRequest;
 175         friend class ::KopetePasswordSetRequest;
 176         friend class ::KopetePasswordClearRequest;
 177 };
 178
 179 }
 180
 181 /**
 182  * This class is an implementation detail of KopetePassword.
 183  * @internal
 184  * @see KopetePassword
 185  */
 186 class KopetePasswordRequestBase : public virtual QObject
 187 {
 188         Q_OBJECT
 189 signals:
 190         void requestFinished( const QString &password );
 191 public slots:
 192         virtual void walletReceived( KWallet::Wallet *wallet ) = 0;
 193     virtual void gotPassword(const QString&, bool) =0;
 194         virtual void slotCancelPressed() =0;
 195
 196 };
 197
 198 #endif
 199
 200 // vim: set noet ts=4 sts=4 sw=4: