Debian Codegraph @

thirdparty/kQOAuth/kqoauthmanager.h

raw
1 /**
2 * KQOAuth - An OAuth authentication library for Qt.
3 *
4 * Author: Johan Paul ([email protected])
5 * http://www.johanpaul.com
6 *
7 * This library is free software; you can redistribute it and/or
8 * modify it under the terms of the GNU Lesser General Public
9 * License as published by the Free Software Foundation; either
10 * version 2.1 of the License, or (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 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 ContentOperationNotPermittedError,// Authentication is required, key or auth is invalid
47 ContentNotFound, // Content is not found
48 RequestError, // The given request to KQOAuthManager is invalid: NULL?,
49 ManagerError // Manager error, cannot use for sending requests.
50 };
51
52 explicit KQOAuthManager(QObject *parent = 0);
53 ~KQOAuthManager();
54
55 KQOAuthError lastError();
56
57 /**
58 * The manager executes the given request. It takes the HTTP parameters from the
59 * request and uses QNetworkAccessManager to submit the HTTP request to the net.
60 * When the request is done it will emit signal requestReady(QByteArray networkReply).
61 * NOTE: At the moment there is no timeout for the request.
62 */
63 void executeRequest(KQOAuthRequest *request);
64 void executeAuthorizedRequest(KQOAuthRequest *request, int id);
65 /**
66 * Indicates to the user that KQOAuthManager should handle user authorization by
67 * opening the user's default browser and parsing the reply from the service.
68 * By setting the parameter to true, KQOAuthManager will store intermediate results
69 * of the OAuth 1.0 process in its own opaque request. This information is used in
70 * the user authorization process and also when calling sendAuthorizedRequest().
71 * NOTE: You need to set this to true if you want to use getUserAccessTokens() or
72 * sendAuthorizedRequest().
73 */
74 void setHandleUserAuthorization(bool set);
75
76 /** Indicates whether the KQOAuthManager should launch the browser with the user
77 * authorization page itself.
78 *
79 * If set to true (the default), the KQOAuthManager uses QDesktopServices::openUrl()
80 * for opening the browser. Otherwise it emits the authorizationPageRequested()
81 * signal which must then be handled by the calling code.
82 */
83 void setHandleAuthorizationPageOpening(bool set);
84
85 /**
86 * Returns true if the KQOAuthManager has retrieved the oauth_token value. Otherwise
87 * return false.
88 */
89 bool hasTemporaryToken();
90 /**
91 * Returns true if the user has authorized us to use the protected resources. Otherwise
92 * returns false.
93 * NOTE: In order for KQOAuthManager to know if the user has authorized us to use the
94 * protected resources, KQOAuthManager must be in control of the user authorization
95 * process. Hence, this returns true if setHandleUserAuthorization() is set to true
96 * and the user is authorized with getUserAuthorization().
97 */
98 bool isVerified();
99 /**
100 * Returns true if KQOAuthManager has the access token and hence can access the protected
101 * resources. Otherwise returns false.
102 * NOTE: In order for KQOAuthManager to know if we have access to protected resource
103 * KQOAuthManager must be in control of the user authorization process and requesting
104 * the acess token. Hence, this returns true if setHandleUserAuthorization() is set to true
105 * and the user is authorized with getUserAuthorization() and the access token must be retrieved
106 * with getUserAccessTokens.
107 */
108 bool isAuthorized();
109
110 /**
111 * This is a convenience API for authorizing the user.
112 * The call will open the user's default browser, setup a local HTTP server and parse the reply from the
113 * service after the user has authorized us to access protected resources. If the user authorizes
114 * us to access protected resources, the verifier token is stored in KQOAuthManager for further use.
115 * In order to use this method, you must set setHandleUserAuthorization() to true.
116 */
117 void getUserAuthorization(QUrl authorizationEndpoint);
118 /**
119 * This is a convenience API for retrieving the access token in exchange for the temporary token and the
120 * verifier.
121 * This call will create a KQOAuthRequest and use the previously stored temporary token and verifier to
122 * exchange for the access token, which will be used to access the protected resources.
123 * Note that in order to use this method, KQOAuthManager must be in control of the user authorization process.
124 * Set setHandleUserAuthorization() to true and retrieve user authorization with void getUserAuthorization.
125 */
126 void getUserAccessTokens(QUrl accessTokenEndpoint);
127 /**
128 * This is a conveience API for setting the token verifier.
129 * If setHandleUserAuthorization() is set to false you need to call this function before calling
130 * getUserAccessTokens()
131 */
132 void verifyToken(const QString &token, const QString &verifier);
133 /**
134 * Sends a request to the protected resources. Parameters for the request are service specific and
135 * are given to the 'requestParameters' as parameters.
136 * Note that in order to use this method, KQOAuthManager must be in control of the user authorization process.
137 * Set setHandleUserAuthorization() to true and retrieve user authorization with void getUserAuthorization.
138 */
139 void sendAuthorizedRequest(QUrl requestEndpoint, const KQOAuthParameters &requestParameters);
140
141 /**
142 * Sets a custom QNetworkAccessManager to handle network requests. This method can be useful if the
143 * application is using some proxy settings for example.
144 * The application is responsible for deleting this manager. KQOAuthManager will not delete any
145 * previously given manager.
146 * If the manager is NULL, the manager will not be set and the KQOAuthManager::Error.
147 * If no manager is given, KQOAuthManager will use the default one it will create by itself.
148 */
149 void setNetworkManager(QNetworkAccessManager *manager);
150
151 /**
152 * Returns the given QNetworkAccessManager. Returns NULL if none is given.
153 */
154 QNetworkAccessManager* networkManager() const;
155
156 Q_SIGNALS:
157 // This signal will be emitted after each request has got a reply.
158 // Parameter is the raw response from the service.
159 void requestReady(QByteArray networkReply);
160
161 void authorizedRequestReady(QByteArray networkReply, int id);
162
163 // This signal will be emitted when the authorization page should be opened if
164 // setHandleAuthorizationPageOpening() is set to false.
165 void authorizationPageRequested(QUrl pageUrl);
166
167 // This signal will be emited when we have an request tokens available
168 // (either temporary resource tokens, or authorization tokens).
169 void receivedToken(QString oauth_token, QString oauth_token_secret); // oauth_token, oauth_token_secret
170
171 // This signal is emited when temporary tokens are returned from the service.
172 // Note that this signal is also emited in case temporary tokens are not available.
173 void temporaryTokenReceived(QString oauth_token, QString oauth_token_secret); // oauth_token, oauth_token_secret
174
175 // This signal is emited when the user has authenticated the application to
176 // communicate with the protected resources. Next we need to exchange the
177 // temporary tokens for access tokens.
178 // Note that this signal is also emited if user denies access.
179 void authorizationReceived(QString oauth_token, QString oauth_verifier); // oauth_token, oauth_verifier
180
181 // This signal is emited when access tokens are received from the service. We are
182 // ready to start communicating with the protected resources.
183 void accessTokenReceived(QString oauth_token, QString oauth_token_secret); // oauth_token, oauth_token_secret
184
185 // This signal is emited when the authorized request is done.
186 // This ends the kQOAuth interactions.
187 void authorizedRequestDone();
188
189 private Q_SLOTS:
190 void onRequestReplyReceived();
191 void onAuthorizedRequestReplyReceived();
192 void onVerificationReceived(QMultiMap<QString, QString> response);
193 void slotError(QNetworkReply::NetworkError error);
194 void requestTimeout();
195
196 private:
197 KQOAuthManagerPrivate *d_ptr;
198 Q_DECLARE_PRIVATE(KQOAuthManager);
199 Q_DISABLE_COPY(KQOAuthManager);
200
201 };
202
203 #endif // KQOAUTHMANAGER_H