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     void executeAuthorizedRequest(KQOAuthRequest *request, int id);
  63     /**
  64      * Indicates to the user that KQOAuthManager should handle user authorization by
  65      * opening the user's default browser and parsing the reply from the service.
  66      * By setting the parameter to true, KQOAuthManager will store intermediate results
  67      * of the OAuth 1.0 process in its own opaque request. This information is used in
  68      * the user authorization process and also when calling sendAuthorizedRequest().
  69      * NOTE: You need to set this to true if you want to use getUserAccessTokens() or
  70      *       sendAuthorizedRequest().
  71      */
  72     void setHandleUserAuthorization(bool set);
  73
  74     /**
  75      * Returns true if the KQOAuthManager has retrieved the oauth_token value. Otherwise
  76      * return false.
  77      */
  78     bool hasTemporaryToken();
  79     /**
  80      * Returns true if the user has authorized us to use the protected resources. Otherwise
  81      * returns false.
  82      * NOTE: In order for KQOAuthManager to know if the user has authorized us to use the
  83      *       protected resources, KQOAuthManager must be in control of the user authorization
  84      *       process. Hence, this returns true if setHandleUserAuthorization() is set to true
  85      *       and the user is authorized with getUserAuthorization().
  86      */
  87     bool isVerified();
  88     /**
  89      * Returns true if KQOAuthManager has the access token and hence can access the protected
  90      * resources. Otherwise returns false.
  91      * NOTE: In order for KQOAuthManager to know if we have access to protected resource
  92      *       KQOAuthManager must be in control of the user authorization process and requesting
  93      *       the acess token. Hence, this returns true if setHandleUserAuthorization() is set to true
  94      *       and the user is authorized with getUserAuthorization() and the access token must be retrieved
  95      *       with getUserAccessTokens.
  96      */
  97     bool isAuthorized();
  98
  99     /**
 100      * This is a convenience API for authorizing the user.
 101      * The call will open the user's default browser, setup a local HTTP server and parse the reply from the
 102      * service after the user has authorized us to access protected resources. If the user authorizes
 103      * us to access protected resources, the verifier token is stored in KQOAuthManager for further use.
 104      * In order to use this method, you must set setHandleUserAuthorization() to true.
 105      */
 106     QUrl getUserAuthorization(QUrl authorizationEndpoint);
 107     /**
 108      * This is a convenience API for retrieving the access token in exchange for the temporary token and the
 109      * verifier.
 110      * This call will create a KQOAuthRequest and use the previously stored temporary token and verifier to
 111      * exchange for the access token, which will be used to access the protected resources.
 112      * Note that in order to use this method, KQOAuthManager must be in control of the user authorization process.
 113      * Set setHandleUserAuthorization() to true and retrieve user authorization with void getUserAuthorization.
 114      */
 115     void getUserAccessTokens(QUrl accessTokenEndpoint);
 116     /**
 117      * Sends a request to the protected resources. Parameters for the request are service specific and
 118      * are given to the 'requestParameters' as parameters.
 119      * Note that in order to use this method, KQOAuthManager must be in control of the user authorization process.
 120      * Set setHandleUserAuthorization() to true and retrieve user authorization with void getUserAuthorization.
 121      */
 122     void sendAuthorizedRequest(QUrl requestEndpoint, const KQOAuthParameters &requestParameters);
 123
 124     /**
 125      * Sets a custom QNetworkAccessManager to handle network requests. This method can be useful if the
 126      * application is using some proxy settings for example.
 127      * The application is responsible for deleting this manager. KQOAuthManager will not delete any
 128      * previously given manager.
 129      * If the manager is NULL, the manager will not be set and the KQOAuthManager::Error.
 130      * If no manager is given, KQOAuthManager will use the default one it will create by itself.
 131      */
 132     void setNetworkManager(QNetworkAccessManager *manager);
 133
 134     /**
 135      * Returns the given QNetworkAccessManager. Returns NULL if none is given.
 136      */
 137     QNetworkAccessManager* networkManager() const;
 138
 139 Q_SIGNALS:
 140     // This signal will be emitted after each request has got a reply.
 141     // Parameter is the raw response from the service.
 142     void requestReady(QByteArray networkReply);
 143
 144     void authorizedRequestReady(QByteArray networkReply, int id);
 145
 146     // This signal will be emited when we have an request tokens available
 147     // (either temporary resource tokens, or authorization tokens).
 148     void receivedToken(QString oauth_token, QString oauth_token_secret);   // oauth_token, oauth_token_secret
 149
 150     // This signal is emited when temporary tokens are returned from the service.
 151     // Note that this signal is also emited in case temporary tokens are not available.
 152     void temporaryTokenReceived(QString oauth_token, QString oauth_token_secret);   // oauth_token, oauth_token_secret
 153
 154     // This signal is emited when the user has authenticated the application to
 155     // communicate with the protected resources. Next we need to exchange the
 156     // temporary tokens for access tokens.
 157     // Note that this signal is also emited if user denies access.
 158     void authorizationReceived(QString oauth_token, QString oauth_verifier); // oauth_token, oauth_verifier
 159
 160     // This signal is emited when access tokens are received from the service. We are
 161     // ready to start communicating with the protected resources.
 162     void accessTokenReceived(QString oauth_token, QString oauth_token_secret);  // oauth_token, oauth_token_secret
 163
 164     // This signal is emited when the authorized request is done.
 165     // This ends the kQOAuth interactions.
 166     void authorizedRequestDone();
 167
 168 private Q_SLOTS:
 169     void onRequestReplyReceived( QNetworkReply *reply );
 170     void onAuthorizedRequestReplyReceived( QNetworkReply *reply );
 171     void onVerificationReceived(QMultiMap<QString, QString> response);
 172     void slotError(QNetworkReply::NetworkError error);
 173
 174 private:
 175     KQOAuthManagerPrivate *d_ptr;
 176     Q_DECLARE_PRIVATE(KQOAuthManager);
 177     Q_DISABLE_COPY(KQOAuthManager);
 178
 179 };
 180
 181 #endif // KQOAUTHMANAGER_H