2 * KQOAuth - An OAuth authentication library for Qt.
4 * Author: Johan Paul (johan.paul@d-pointer.com)
5 * http://www.d-pointer.com
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.
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.
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/>.
20 #ifndef KQOAUTHMANAGER_H
21 #define KQOAUTHMANAGER_H
25 #include <QNetworkReply>
27 #include "kqoauthrequest.h"
30 class KQOAuthManagerThread;
31 class KQOAuthManagerPrivate;
32 class QNetworkAccessManager;
35 class KQOAUTH_EXPORT KQOAuthManager : public QObject
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.
50 explicit KQOAuthManager(QObject *parent = 0);
53 KQOAuthError lastError();
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.
61 void executeRequest(KQOAuthRequest *request);
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().
71 void setHandleUserAuthorization(bool set);
74 * Returns true if the KQOAuthManager has retrieved the oauth_token value. Otherwise
77 bool hasTemporaryToken();
79 * Returns true if the user has authorized us to use the protected resources. Otherwise
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().
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.
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.
105 QUrl getUserAuthorization(QUrl authorizationEndpoint);
107 * This is a convenience API for retrieving the access token in exchange for the temporary token and the
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.
114 void getUserAccessTokens(QUrl accessTokenEndpoint);
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.
121 void sendAuthorizedRequest(QUrl requestEndpoint, const KQOAuthParameters &requestParameters);
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.
131 void setNetworkManager(QNetworkAccessManager *manager);
134 * Returns the given QNetworkAccessManager. Returns NULL if none is given.
136 QNetworkAccessManager* networkManager() const;
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);
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
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
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
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
161 // This signal is emited when the authorized request is done.
162 // This ends the kQOAuth interactions.
163 void authorizedRequestDone();
166 void onRequestReplyReceived( QNetworkReply *reply );
167 void onVerificationReceived(QMultiMap<QString, QString> response);
168 void slotError(QNetworkReply::NetworkError error);
171 KQOAuthManagerPrivate *d_ptr;
172 Q_DECLARE_PRIVATE(KQOAuthManager);
173 Q_DISABLE_COPY(KQOAuthManager);
177 #endif // KQOAUTHMANAGER_H