git.maemo.org Git - googlelatitude/blob - libkqoauth/kqoauthmanager.h

   1 /**
   2  * KQOAuth - An OAuth authentication library for Qt.
   3  *
   4  * Author: Johan Paul (johan.paul@d-pointer.com)
   5  *         http://www.d-pointer.com
   6  *
   7  *  KQOAuth is free software: you can redistribute it and/or modify
   8  *  it under the terms of the GNU Lesser General Public License as published by
   9  *  the Free Software Foundation, either version 3 of the License, or
  10  *  (at your option) any later version.
  11  *
  12  *  KQOAuth is distributed in the hope that it will be useful,
  13  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15  *  GNU Lesser General Public License for more details.
  16  *
  17  *  You should have received a copy of the GNU Lesser General Public License
  18  *  along with KQOAuth.  If not, see <http://www.gnu.org/licenses/>.
  19  */
  20 #ifndef KQOAUTHMANAGER_H
  21 #define KQOAUTHMANAGER_H
  22
  23 #include <QObject>
  24 #include <QMultiMap>
  25 #include <QNetworkReply>
  26
  27 #include "kqoauthrequest.h"
  28
  29 class KQOAuthRequest;
  30 class KQOAuthManagerThread;
  31 class KQOAuthManagerPrivate;
  32 class QNetworkAccessManager;
  33 class QUrl;
  34 class QByteArray;
  35 class KQOAUTH_EXPORT KQOAuthManager : public QObject
  36 {
  37     Q_OBJECT
  38 public:
  39
  40     enum KQOAuthError {
  41         NoError,                    // No error
  42         NetworkError,               // Network error: timeout, cannot connect.
  43         RequestEndpointError,       // Request endpoint is not valid.
  44         RequestValidationError,     // Request is not valid: some parameter missing?
  45         RequestUnauthorized,        // Authorization error: trying to access a resource without tokens.
  46         RequestError,               // The given request to KQOAuthManager is invalid: NULL?,
  47         ManagerError                // Manager error, cannot use for sending requests.
  48     };
  49
  50     explicit KQOAuthManager(QObject *parent = 0);
  51     ~KQOAuthManager();
  52
  53     KQOAuthError lastError();
  54
  55     /**
  56      * The manager executes the given request. It takes the HTTP parameters from the
  57      * request and uses QNetworkAccessManager to submit the HTTP request to the net.
  58      * When the request is done it will emit signal requestReady(QByteArray networkReply).
  59      * NOTE: At the moment there is no timeout for the request.
  60      */
  61     void executeRequest(KQOAuthRequest *request);
  62     /**
  63      * Indicates to the user that KQOAuthManager should handle user authorization by
  64      * opening the user's default browser and parsing the reply from the service.
  65      * By setting the parameter to true, KQOAuthManager will store intermediate results
  66      * of the OAuth 1.0 process in its own opaque request. This information is used in
  67      * the user authorization process and also when calling sendAuthorizedRequest().
  68      * NOTE: You need to set this to true if you want to use getUserAccessTokens() or
  69      *       sendAuthorizedRequest().
  70      */
  71     void setHandleUserAuthorization(bool set);
  72
  73     /**
  74      * Returns true if the KQOAuthManager has retrieved the oauth_token value. Otherwise
  75      * return false.
  76      */
  77     bool hasTemporaryToken();
  78     /**
  79      * Returns true if the user has authorized us to use the protected resources. Otherwise
  80      * returns false.
  81      * NOTE: In order for KQOAuthManager to know if the user has authorized us to use the
  82      *       protected resources, KQOAuthManager must be in control of the user authorization
  83      *       process. Hence, this returns true if setHandleUserAuthorization() is set to true
  84      *       and the user is authorized with getUserAuthorization().
  85      */
  86     bool isVerified();
  87     /**
  88      * Returns true if KQOAuthManager has the access token and hence can access the protected
  89      * resources. Otherwise returns false.
  90      * NOTE: In order for KQOAuthManager to know if we have access to protected resource
  91      *       KQOAuthManager must be in control of the user authorization process and requesting
  92      *       the acess token. Hence, this returns true if setHandleUserAuthorization() is set to true
  93      *       and the user is authorized with getUserAuthorization() and the access token must be retrieved
  94      *       with getUserAccessTokens.
  95      */
  96     bool isAuthorized();
  97
  98     /**
  99      * This is a convenience API for authorizing the user.
 100      * The call will open the user's default browser, setup a local HTTP server and parse the reply from the
 101      * service after the user has authorized us to access protected resources. If the user authorizes
 102      * us to access protected resources, the verifier token is stored in KQOAuthManager for further use.
 103      * In order to use this method, you must set setHandleUserAuthorization() to true.
 104      */
 105     QUrl getUserAuthorization(QUrl authorizationEndpoint);
 106     /**
 107      * This is a convenience API for retrieving the access token in exchange for the temporary token and the
 108      * verifier.
 109      * This call will create a KQOAuthRequest and use the previously stored temporary token and verifier to
 110      * exchange for the access token, which will be used to access the protected resources.
 111      * Note that in order to use this method, KQOAuthManager must be in control of the user authorization process.
 112      * Set setHandleUserAuthorization() to true and retrieve user authorization with void getUserAuthorization.
 113      */
 114     void getUserAccessTokens(QUrl accessTokenEndpoint);
 115     /**
 116      * Sends a request to the protected resources. Parameters for the request are service specific and
 117      * are given to the 'requestParameters' as parameters.
 118      * Note that in order to use this method, KQOAuthManager must be in control of the user authorization process.
 119      * Set setHandleUserAuthorization() to true and retrieve user authorization with void getUserAuthorization.
 120      */
 121     void sendAuthorizedRequest(QUrl requestEndpoint, const KQOAuthParameters &requestParameters);
 122
 123     /**
 124      * Sets a custom QNetworkAccessManager to handle network requests. This method can be useful if the
 125      * application is using some proxy settings for example.
 126      * The application is responsible for deleting this manager. KQOAuthManager will not delete any
 127      * previously given manager.
 128      * If the manager is NULL, the manager will not be set and the KQOAuthManager::Error.
 129      * If no manager is given, KQOAuthManager will use the default one it will create by itself.
 130      */
 131     void setNetworkManager(QNetworkAccessManager *manager);
 132
 133     /**
 134      * Returns the given QNetworkAccessManager. Returns NULL if none is given.
 135      */
 136     QNetworkAccessManager* networkManager() const;
 137
 138 Q_SIGNALS:
 139     // This signal will be emitted after each request has got a reply.
 140     // Parameter is the raw response from the service.
 141     void requestReady(QByteArray networkReply);
 142
 143     // This signal will be emited when we have an request tokens available
 144     // (either temporary resource tokens, or authorization tokens).
 145     void receivedToken(QString oauth_token, QString oauth_token_secret);   // oauth_token, oauth_token_secret
 146
 147     // This signal is emited when temporary tokens are returned from the service.
 148     // Note that this signal is also emited in case temporary tokens are not available.
 149     void temporaryTokenReceived(QString oauth_token, QString oauth_token_secret);   // oauth_token, oauth_token_secret
 150
 151     // This signal is emited when the user has authenticated the application to
 152     // communicate with the protected resources. Next we need to exchange the
 153     // temporary tokens for access tokens.
 154     // Note that this signal is also emited if user denies access.
 155     void authorizationReceived(QString oauth_token, QString oauth_verifier); // oauth_token, oauth_verifier
 156
 157     // This signal is emited when access tokens are received from the service. We are
 158     // ready to start communicating with the protected resources.
 159     void accessTokenReceived(QString oauth_token, QString oauth_token_secret);  // oauth_token, oauth_token_secret
 160
 161     // This signal is emited when the authorized request is done.
 162     // This ends the kQOAuth interactions.
 163     void authorizedRequestDone();
 164
 165 private Q_SLOTS:
 166     void onRequestReplyReceived( QNetworkReply *reply );
 167     void onVerificationReceived(QMultiMap<QString, QString> response);
 168     void slotError(QNetworkReply::NetworkError error);
 169
 170 private:
 171     KQOAuthManagerPrivate *d_ptr;
 172     Q_DECLARE_PRIVATE(KQOAuthManager);
 173     Q_DISABLE_COPY(KQOAuthManager);
 174
 175 };
 176
 177 #endif // KQOAUTHMANAGER_H