Branch data     Line data    Source code

       1                 :            : /***************************************************************************
       2                 :            :     qgsauthmethod.h
       3                 :            :     ---------------------
       4                 :            :     begin                : September 1, 2015
       5                 :            :     copyright            : (C) 2015 by Boundless Spatial, Inc. USA
       6                 :            :     author               : Larry Shaffer
       7                 :            :     email                : lshaffer at boundlessgeo dot com
       8                 :            :  ***************************************************************************
       9                 :            :  *                                                                         *
      10                 :            :  *   This program is free software; you can redistribute it and/or modify  *
      11                 :            :  *   it under the terms of the GNU General Public License as published by  *
      12                 :            :  *   the Free Software Foundation; either version 2 of the License, or     *
      13                 :            :  *   (at your option) any later version.                                   *
      14                 :            :  *                                                                         *
      15                 :            :  ***************************************************************************/
      16                 :            : 
      17                 :            : #ifndef QGSAUTHMETHOD_H
      18                 :            : #define QGSAUTHMETHOD_H
      19                 :            : 
      20                 :            : #include <QObject>
      21                 :            : #include <QFlags>
      22                 :            : #include <QNetworkReply>
      23                 :            : #include <QNetworkRequest>
      24                 :            : #include <QStringList>
      25                 :            : #include <QUrl>
      26                 :            : #include <QMutex>
      27                 :            : 
      28                 :            : #include "qgis_core.h"
      29                 :            : 
      30                 :            : class QgsAuthMethodConfig;
      31                 :            : 
      32                 :            : /**
      33                 :            :  * \ingroup core
      34                 :            :  * \brief Abstract base class for authentication method plugins
      35                 :            :  */
      36                 :            : class CORE_EXPORT QgsAuthMethod : public QObject
      37                 :            : {
      38                 :            :     Q_OBJECT
      39                 :            : 
      40                 :            :   public:
      41                 :            : 
      42                 :            :     /**
      43                 :            :      * Flags that represent the update points (where authentication configurations are expanded)
      44                 :            :      * supported by an authentication method. These equate to the 'update*()' virtual functions
      45                 :            :      * below, and allow for update point code to skip calling an unused update by a method, because
      46                 :            :      * the base virtual function will always return TRUE, giving a false impression an update occurred.
      47                 :            :      * \note When adding an 'update' member function, also add the corresponding Expansion flag.
      48                 :            :      * \note These flags will be added to as new update points are added
      49                 :            :      */
      50                 :            :     enum Expansion
      51                 :            :     {
      52                 :            :       // TODO: Figure out all different authentication expansions current layer providers use
      53                 :            :       NetworkRequest       = 0x1,
      54                 :            :       NetworkReply         = 0x2,
      55                 :            :       DataSourceUri        = 0x4,
      56                 :            :       GenericDataSourceUri = 0x8,
      57                 :            :       NetworkProxy                = 0x16,
      58                 :            :       All = NetworkRequest | NetworkReply | DataSourceUri | GenericDataSourceUri | NetworkProxy
      59                 :            :     };
      60                 :            :     Q_DECLARE_FLAGS( Expansions, Expansion )
      61                 :            : 
      62                 :            :     //! A non-translated short name representing the auth method
      63                 :            :     virtual QString key() const = 0;
      64                 :            : 
      65                 :            :     //! A non-translated short description representing the auth method for use in debug output and About dialog
      66                 :            :     virtual QString description() const = 0;
      67                 :            : 
      68                 :            :     //! Translatable display version of the 'description()'
      69                 :            :     virtual QString displayDescription() const = 0;
      70                 :            : 
      71                 :            :     //! Increment this if method is significantly updated, allow updater code to be written for previously stored authcfg
      72                 :            :     int version() const { return mVersion; }
      73                 :            : 
      74                 :            :     /**
      75                 :            :      * Flags that represent the update points (where authentication configurations are expanded)
      76                 :            :      * supported by an authentication method.
      77                 :            :      * \note These should directly correlate to existing 'update*()' member functions
      78                 :            :      */
      79                 :          0 :     QgsAuthMethod::Expansions supportedExpansions() const { return mExpansions; }
      80                 :            : 
      81                 :            :     /**
      82                 :            :      * The data providers that the method supports, allowing for filtering out authcfgs that are not
      83                 :            :      * applicable to a given provider, or where the updating code is not currently implemented.
      84                 :            :      */
      85                 :          0 :     QStringList supportedDataProviders() const { return mDataProviders; }
      86                 :            : 
      87                 :            :     /**
      88                 :            :      * Update a network request with authentication components
      89                 :            :      * \param request The network request to update
      90                 :            :      * \param authcfg Authentication configuration ID
      91                 :            :      * \param dataprovider Textual key for a data provider, e.g. 'postgres', that allows
      92                 :            :      * for custom updater code specific to the provider
      93                 :            :      * \returns Whether the update succeeded
      94                 :            :      */
      95                 :            :     virtual bool updateNetworkRequest( QNetworkRequest &request, const QString &authcfg,
      96                 :            :                                        const QString &dataprovider = QString() )
      97                 :            :     {
      98                 :            :       Q_UNUSED( request )
      99                 :            :       Q_UNUSED( authcfg )
     100                 :            :       Q_UNUSED( dataprovider )
     101                 :            :       return true; // noop
     102                 :            :     }
     103                 :            : 
     104                 :            :     /**
     105                 :            :      * Update a network reply with authentication components
     106                 :            :      * \param reply The network reply object to update
     107                 :            :      * \param authcfg Authentication configuration ID
     108                 :            :      * \param dataprovider Textual key for a data provider, e.g. 'postgres', that allows
     109                 :            :      * for custom updater code specific to the provider
     110                 :            :      * \returns Whether the update succeeded
     111                 :            :      */
     112                 :            :     virtual bool updateNetworkReply( QNetworkReply *reply, const QString &authcfg,
     113                 :            :                                      const QString &dataprovider = QString() )
     114                 :            :     {
     115                 :            :       Q_UNUSED( reply )
     116                 :            :       Q_UNUSED( authcfg )
     117                 :            :       Q_UNUSED( dataprovider )
     118                 :            :       return true; // noop
     119                 :            :     }
     120                 :            : 
     121                 :            :     /**
     122                 :            :      * Update data source connection items with authentication components
     123                 :            :      * \param connectionItems QStringlist of 'key=value' pairs, as utilized in QgsDataSourceUri::connectionInfo()
     124                 :            :      * \param authcfg Authentication configuration ID
     125                 :            :      * \param dataprovider Textual key for a data provider, e.g. 'postgres', that allows
     126                 :            :      * for custom updater code specific to the provider
     127                 :            :      * \returns Whether the update succeeded
     128                 :            :      */
     129                 :            :     virtual bool updateDataSourceUriItems( QStringList &connectionItems, const QString &authcfg,
     130                 :            :                                            const QString &dataprovider = QString() )
     131                 :            :     {
     132                 :            :       Q_UNUSED( connectionItems )
     133                 :            :       Q_UNUSED( authcfg )
     134                 :            :       Q_UNUSED( dataprovider )
     135                 :            :       return true; // noop
     136                 :            :     }
     137                 :            : 
     138                 :            :     /**
     139                 :            :      * Update proxy settings with authentication components
     140                 :            :      * \param proxy
     141                 :            :      * \param authcfg Authentication configuration ID
     142                 :            :      * \param dataprovider Textual key for a data provider, e.g. 'proxy', that allows
     143                 :            :      * for custom updater code specific to the provider
     144                 :            :      * \returns Whether the update succeeded
     145                 :            :      */
     146                 :            :     virtual bool updateNetworkProxy( QNetworkProxy &proxy, const QString &authcfg,
     147                 :            :                                      const QString &dataprovider = QString() )
     148                 :            :     {
     149                 :            :       Q_UNUSED( proxy )
     150                 :            :       Q_UNUSED( authcfg )
     151                 :            :       Q_UNUSED( dataprovider )
     152                 :            :       return true; // noop
     153                 :            :     }
     154                 :            : 
     155                 :            :     /**
     156                 :            :      * Clear any cached configuration. Called when the QgsAuthManager deletes an authentication configuration (authcfg).
     157                 :            :      * \note It is highly recommended that a cache of authentication components (per requested authcfg)
     158                 :            :      * be implemented, to avoid excessive queries on the auth database. Such a cache could be as
     159                 :            :      * simple as a QHash or QMap of authcfg -> QgsAuthMethodConfig. See 'Basic' auth method plugin for example.
     160                 :            :      */
     161                 :            :     virtual void clearCachedConfig( const QString &authcfg ) = 0;
     162                 :            : 
     163                 :            :     /**
     164                 :            :      * Update an authentication configuration in place
     165                 :            :      * \note Useful for updating previously stored authcfgs, when an authentication method has been significantly updated
     166                 :            :      */
     167                 :            :     virtual void updateMethodConfig( QgsAuthMethodConfig &mconfig ) = 0;
     168                 :            : 
     169                 :            :   protected:
     170                 :            : 
     171                 :            :     /**
     172                 :            :      * Construct a default authentication method
     173                 :            :      * \note Non-public since this is an abstract base class
     174                 :            :      */
     175                 :            :     explicit QgsAuthMethod()
     176                 :            :       : mMutex( QMutex::RecursionMode::Recursive )
     177                 :            :     {}
     178                 :            : 
     179                 :            : 
     180                 :            :     //! Tag signifying that this is an authentcation method (e.g. for use as title in message log panel output)
     181                 :            :     static QString authMethodTag() { return QObject::tr( "Authentication method" ); }
     182                 :            : 
     183                 :            :     //! Sets the version of the auth method (useful for future upgrading)
     184                 :            :     void setVersion( int version ) { mVersion = version; }
     185                 :            : 
     186                 :            :     //! Sets the support expansions (points in providers where the authentication is injected) of the auth method
     187                 :            :     void setExpansions( QgsAuthMethod::Expansions expansions ) { mExpansions = expansions; }
     188                 :            :     //! Sets list of data providers this auth method supports
     189                 :            :     void setDataProviders( const QStringList &dataproviders ) { mDataProviders = dataproviders; }
     190                 :            : 
     191                 :            :     QgsAuthMethod::Expansions mExpansions = QgsAuthMethod::Expansions();
     192                 :            :     QStringList mDataProviders;
     193                 :            :     int mVersion = 0;
     194                 :            :     QMutex mMutex;
     195                 :            : 
     196                 :            : };
     197                 :            : Q_DECLARE_OPERATORS_FOR_FLAGS( QgsAuthMethod::Expansions )
     198                 :            : 
     199                 :            : typedef QHash<QString, QgsAuthMethod *> QgsAuthMethodsMap;
     200                 :            : 
     201                 :            : #endif // QGSAUTHMETHOD_H