Branch data     Line data    Source code

       1                 :            : /***************************************************************************
       2                 :            :     qgscredentials.h  -  interface for requesting credentials
       3                 :            :     ----------------------
       4                 :            :     begin                : February 2010
       5                 :            :     copyright            : (C) 2010 by Juergen E. Fischer
       6                 :            :     email                : jef at norbit dot de
       7                 :            :  ***************************************************************************
       8                 :            :  *                                                                         *
       9                 :            :  *   This program is free software; you can redistribute it and/or modify  *
      10                 :            :  *   it under the terms of the GNU General Public License as published by  *
      11                 :            :  *   the Free Software Foundation; either version 2 of the License, or     *
      12                 :            :  *   (at your option) any later version.                                   *
      13                 :            :  *                                                                         *
      14                 :            :  ***************************************************************************/
      15                 :            : 
      16                 :            : 
      17                 :            : #ifndef QGSCREDENTIALS_H
      18                 :            : #define QGSCREDENTIALS_H
      19                 :            : 
      20                 :            : #include <QMap>
      21                 :            : #include <QMutex>
      22                 :            : #include <QObject>
      23                 :            : #include <QPair>
      24                 :            : #include <QString>
      25                 :            : 
      26                 :            : #include "qgis_core.h"
      27                 :            : #include "qgis_sip.h"
      28                 :            : 
      29                 :            : /**
      30                 :            :  * \ingroup core
      31                 :            :  * \brief Interface for requesting credentials in QGIS in GUI independent way.
      32                 :            :  *
      33                 :            :  * This class provides abstraction of a dialog for requesting credentials to the user.
      34                 :            :  * By default QgsCredentials will be used if not overridden with other
      35                 :            :  * credential creator function.
      36                 :            : 
      37                 :            :  * QGIS application uses QgsCredentialDialog class for displaying a dialog to the user.
      38                 :            : 
      39                 :            :  * Caller can use the mutex to synchronize authentications to avoid requesting
      40                 :            :  * credentials for the same resource several times.
      41                 :            : 
      42                 :            :  * Object deletes itself when it's not needed anymore. Children should use
      43                 :            :  * signal destroyed() to be notified of the deletion
      44                 :            : */
      45                 :            : class CORE_EXPORT QgsCredentials
      46                 :            : {
      47                 :            :   public:
      48                 :            : 
      49                 :            :     /**
      50                 :            :      * Destructor.
      51                 :            :      */
      52                 :          0 :     virtual ~QgsCredentials() = default;
      53                 :            : 
      54                 :            :     /**
      55                 :            :      * Requests credentials for the specified \a realm.
      56                 :            :      *
      57                 :            :      * If existing credentials exist for the given \a realm, these will be returned. Otherwise the credential
      58                 :            :      * handler will prompt for the correct username and password.
      59                 :            :      *
      60                 :            :      * The retrieved or user-entered details will be stored in \a username and \a password.
      61                 :            :      *
      62                 :            :      * Optionally, a specific \a message can be used to advise users of the context for the credentials request.
      63                 :            :      *
      64                 :            :      * \note This method will not automatically store the newly obtained credentials. Callers must
      65                 :            :      * manually call put() after verifying that the obtained credentials are correct.
      66                 :            :      *
      67                 :            :      * \see put()
      68                 :            :      */
      69                 :            :     bool get( const QString &realm, QString &username SIP_INOUT, QString &password SIP_INOUT, const QString &message = QString() );
      70                 :            : 
      71                 :            :     /**
      72                 :            :      * Stores the correct \a username and \a password for the specified \a realm.
      73                 :            :      *
      74                 :            :      * These values will be used for all future calls to get() for the same \a realm, without requesting
      75                 :            :      * users to re-enter them. It is the caller's responsibility to ensure that only valid \a username and \a password
      76                 :            :      * combinations are used with this method.
      77                 :            :      *
      78                 :            :      * \see get()
      79                 :            :      */
      80                 :            :     void put( const QString &realm, const QString &username, const QString &password );
      81                 :            : 
      82                 :            :     bool getMasterPassword( QString &password SIP_INOUT, bool stored = false );
      83                 :            : 
      84                 :            :     //! retrieves instance
      85                 :            :     static QgsCredentials *instance();
      86                 :            : 
      87                 :            :     /**
      88                 :            :      * Lock the instance against access from multiple threads. This does not really lock access to get/put methods,
      89                 :            :      * it will just prevent other threads to lock the instance and continue the execution. When the class is used
      90                 :            :      * from non-GUI threads, they should call lock() before the get/put calls to avoid race conditions.
      91                 :            :      * \since QGIS 2.4
      92                 :            :      */
      93                 :            :     void lock();
      94                 :            : 
      95                 :            :     /**
      96                 :            :      * Unlock the instance after being locked.
      97                 :            :      * \since QGIS 2.4
      98                 :            :      */
      99                 :            :     void unlock();
     100                 :            : 
     101                 :            :     /**
     102                 :            :      * Returns pointer to mutex
     103                 :            :      * \since QGIS 2.4
     104                 :            :      */
     105                 :            :     QMutex *mutex() { return &mAuthMutex; }
     106                 :            : 
     107                 :            :   protected:
     108                 :            : 
     109                 :            :     /**
     110                 :            :      * Constructor for QgsCredentials.
     111                 :            :      */
     112                 :          0 :     QgsCredentials() = default;
     113                 :            : 
     114                 :            :     //! request a password
     115                 :            :     virtual bool request( const QString &realm, QString &username SIP_INOUT, QString &password SIP_INOUT, const QString &message = QString() ) = 0;
     116                 :            : 
     117                 :            :     //! request a master password
     118                 :            :     virtual bool requestMasterPassword( QString &password SIP_INOUT, bool stored = false ) = 0;
     119                 :            : 
     120                 :            :     //! register instance
     121                 :            :     void setInstance( QgsCredentials *instance );
     122                 :            : 
     123                 :            :   private:
     124                 :            :     Q_DISABLE_COPY( QgsCredentials )
     125                 :            : 
     126                 :            : #ifdef SIP_RUN
     127                 :            :     QgsCredentials( const QgsCredentials & );
     128                 :            : #endif
     129                 :            : 
     130                 :            :     //! cache for already requested credentials in this session
     131                 :            :     QMap< QString, QPair<QString, QString> > mCredentialCache;
     132                 :            : 
     133                 :            :     //! Pointer to the credential instance
     134                 :            :     static QgsCredentials *sInstance;
     135                 :            : 
     136                 :            :     //! Mutex to synchronize authentications
     137                 :            :     QMutex mAuthMutex;
     138                 :            : 
     139                 :            :     //! Mutex to guard the cache
     140                 :            :     QMutex mCacheMutex;
     141                 :            : };
     142                 :            : 
     143                 :            : 
     144                 :            : /**
     145                 :            :  * \ingroup core
     146                 :            :  * \brief Default implementation of credentials interface
     147                 :            :  *
     148                 :            :  * This class doesn't prompt or return credentials
     149                 :            : */
     150                 :            : class CORE_EXPORT QgsCredentialsNone : public QObject, public QgsCredentials
     151                 :            : {
     152                 :            :     Q_OBJECT
     153                 :            : 
     154                 :            :   public:
     155                 :            :     QgsCredentialsNone();
     156                 :            : 
     157                 :            :   signals:
     158                 :            :     //! signals that object will be destroyed and shouldn't be used anymore
     159                 :            :     void destroyed();
     160                 :            : 
     161                 :            :   protected:
     162                 :            :     bool request( const QString &realm, QString &username SIP_INOUT, QString &password SIP_INOUT, const QString &message = QString() ) override;
     163                 :            :     bool requestMasterPassword( QString &password SIP_INOUT, bool stored = false ) override;
     164                 :            : };
     165                 :            : 
     166                 :            : 
     167                 :            : /**
     168                 :            :  * \ingroup core
     169                 :            :  * \brief Implementation of credentials interface for the console
     170                 :            :  *
     171                 :            :  * This class outputs message to the standard output and retrieves input from
     172                 :            :  * standard input. Therefore it won't be the right choice for apps without
     173                 :            :  * GUI.
     174                 :            : */
     175                 :            : class CORE_EXPORT QgsCredentialsConsole : public QObject, public QgsCredentials
     176                 :            : {
     177                 :            :     Q_OBJECT
     178                 :            : 
     179                 :            :   public:
     180                 :            :     QgsCredentialsConsole();
     181                 :            : 
     182                 :            :   signals:
     183                 :            :     //! signals that object will be destroyed and shouldn't be used anymore
     184                 :            :     void destroyed();
     185                 :            : 
     186                 :            :   protected:
     187                 :            :     bool request( const QString &realm, QString &username SIP_INOUT, QString &password SIP_INOUT, const QString &message = QString() ) override;
     188                 :            :     bool requestMasterPassword( QString &password SIP_INOUT, bool stored = false ) override;
     189                 :            : };
     190                 :            : 
     191                 :            : #endif