Debian Codegraph @

thirdparty/kQOAuth/README

raw
1 kQOAuth is a OAuth 1.0 library written for Qt in C++. The goals for the
2 library have been to provide easy integration to existing Qt applications
3 utilizing Qt signals describing the OAuth process, and to provide a
4 convenient approach to OAuth authentication.
5
6 kQOAuth has support for retrieving the user authorization from the service
7 provider's website. kQOAuth will open the user's web browser to the
8 authorization page, give a local URL as the callback URL and setup a HTTP
9 server on this address to listen for the reply from the service and then
10 process it.
11
12 BUILDING kQOAuth
13 ===============================
14 - Make sure that you have Qt 4.7 or greater installed
15
16 For OS X and Linux:
17 - run "qmake"
18 - run "make" to build
19 - Run "sudo make install" to install
20 - To run unit tests you need to set platform specific variable to point
21 correct directory in order to make unit tests to find the library. Note
22 that it doesn't require kQOAuth to be installed in order to run unit tests.
23 * for Linux: export LD_LIBRARY_PATH=/path/to/kQOAuth/lib/dir
24 * for OS X: export DYLD_LIBRARY_PATH=/path/to/kQOAuth/lib/dir
25
26 For Windows with the Visual Studio or Windows SDK Compiler
27 - run "qmake CONFIG+=release"
28 - run "nmake" to build
29 - run "nmake install" to install
30
31
32 COMPONENTS
33 ===============================
34 Below I will present the two fundamental components necessary when using
35 kQOAuth; KQOAuthManager and KQOAuthRequest.
36
37 KQOAuthManager
38 ===============================
39
40 Executes OAuth requests (KQOAuthRequest), parses the replies and emits Qt
41 signals describing the process of the OAuth authentication.
42
43 KQOAuthManager will keep track of the state of the authorization process.
44 This means that the provided convenience methods can be used to achieve the
45 necessary steps in OAuth authentication without explicitly constructing
46 each request.
47
48 Methods
49 -------------------------------
50
51 * void executeRequest(KQOAuthRequest *request)
52 - request: The KQOAuthRequest to process.
53
54 Takes as parameter a pointer to a KQOAuthRequest describing the request
55 that will be executed. The call will return as soon as the HTTP
56 request has been sent.
57
58 When the service responded to this request the signal
59 requestReady(QByteArray) is emitted. This will contain the raw data
60 that the service sent back as a response to the request.
61
62 If an error in the request was detected, this method will set the
63 error code and emit the requestReady(QByteArray) signal with
64 an empty QByteArray. The error code can be retrieved by calling lastError().
65
66 * void executeAuthorizedRequest(KQOAuthRequest *request, int id)
67 - request: The KQOAuthRequest to process.
68 - id: An id that is unique to the request.
69
70 This method is useful for situations where the reponses from a server
71 have different processing requirements.
72
73 The arguments and behavior of this method is similar to executeRequest()
74 with the addition of an id that is mapped to the request. When the service
75 has responded, the signal authorizedRequestReady(QByteArray, int) is emitted
76 where the int is the mapped id.
77
78 * void setHandleUserAuthorization(bool set)
79 - set: A boolean value telling KQOAuthManager to process the user's
80 authorization to protected resources.
81
82 If KQOAuth is to handle user authorization this method must be called
83 with argument set as 'true' before a request for the temporary token has
84 been executed.
85
86 * void getUserAuthorization(QUrl authorizationEndpoint);
87 - authorizationEndpoint: The URL to the service provider's authorization
88 web page.
89
90 A convenience method to retrieve the user authorization to access the
91 protected resources. This method will open user's web browser to the
92 service providers authorization page given as argument and setup a
93 a local HTTP server to process the response.
94
95 This method must be called after temporaryTokenReceived(...) signal
96 is emitted.
97
98 When the user's authentication is processed, the signal
99 authorizationReceived(...) is emitted.
100
101 * void getUserAccessTokens(QUrl accessTokenEndpoint);
102 - accessTokenEndpoint: The URL to the service provider which is used for
103 retrieving the access token.
104
105 A convenience method to retrieve the access token, which is used for
106 accessing the protected resources.
107
108 This method must be called after the signal authorizationReceived(...)
109 is received.
110
111 When the access token request is processed, the signal accessTokenReceived(...)
112 is emitted. After this signal the protected resources can be accessed.
113
114 * void sendAuthorizedRequest(QUrl requestEndpoint,
115 const KQOAuthParameters &requestParameters);
116 - requestEndpoint: The URL to the service provider which can be used for
117 accessing protected resources.
118 - requestParameters: The parameters for this request which are service
119 specific. KQOAuthParameters is a typecasted
120 QMultiMap<QString, QString> for parameter name and value.
121
122 A convenience method for accessing the protected resources. The
123 parameters are given as KQOAuthParameters, which is a typecasted
124 QMultiMap<QString parameterName, QString parameterValue>. Please
125 consult your service provider for which parameters to use.
126
127 * bool hasTemporaryToken()
128 Returns true if the temporary token has been received. Otherwise returns
129 false
130
131 * bool isVerified()
132 Returns true if the user has successfully verified us to access the protected
133 resources. Otherwise returns false.
134
135 * bool isAuthorized()
136 Returns true if we have access tokens to access the protected resources.
137 Otherwise returns false.
138
139 * KQOAuthError lastError()
140 Returns the most recent error code in the authentication process.
141
142
143 Signals
144 -------------------------------
145 * void requestReady(QByteArray networkReply)
146 - networkReply: The response as sent from the service the each request.
147
148 This signal is emitted after each request has been processed. It will
149 return all the request response parameters in the QMultiMap, where
150 the first parameter is the name and the second parameter is the value.
151
152 * void authorizedRequestReady(QByteArray networkReply, int id);
153 - networkReply: The response as sent from the service the each request.
154 - id: The id that is mapped to the original request
155
156 This signal is emitted after each authorizedRequest has been processed.
157
158 * void receivedToken(QString oauth_token, QString oauth_token_secret)
159 - oauth_oken: Token value
160 - oauth_token_secret: Token secret value
161
162 This signal is emitted after a successful request for temporary tokens or
163 access tokens. The requested tokens are sent as parameters in this
164 signal.
165
166 * void temporaryTokenReceived(QString oauth_token, QString oauth_token_secret)
167 - oauth_token: Temporary token value
168 - oauth_token_secret: Temporary token secret value
169
170 This signal is emitted after a successful request for temporary tokens.
171 The tokens are sent as parameters to this signal.
172
173 * void authorizationReceived(QString oauth_token, QString oauth_verifier)
174 - oauth_token: The temporary token that was used when requesting access.
175 - oauth_verifier: The oauth_verifier token received as a reply to the
176 request. This value is necessary when requesting access token.
177
178 This signal is emitted after the user has concluded the authorization request
179 step in the service provider's website.
180
181 Note that setHandleUserAuthorization(true) must be called when requesting for
182 the temporary token.
183
184 * void accessTokenReceived(QString oauth_token, QString oauth_token_secret)
185 - oauth_token: The access token value.
186 - oauth_token_secret: The access token secret value.
187
188 This signal is emitted after a successful request for access tokens. The
189 requested tokens are sent as parameters in this signal. These tokens
190 are necessary when requesting for protected resources.
191
192
193 KQOAuthRequest
194 ====================================
195
196 KQOAuthRequest is given to KQOAuthManager to execute the requested OAuth
197 request. It will also take care of parameter normalization, generating
198 the needed authorization header, and most importantly, generate a
199 OAuth signature.
200
201 Methods
202 ------------------------------------
203
204 * void initRequest(KQOAuthRequest::RequestType type, const QUrl &requestEndpoint)
205 - type: Initializes this request to be of type 'KQOAuthRequest::RequestType'.
206 - requestEndpoint: The URL to the service provider that can handle the
207 requests of type 'KQOAuthRequest::RequestType'.
208
209 Initializes the request to be of a certain type that will be sent to
210 service provider's HTTP location. The request can be of type:
211 - TemporaryCredentials: Requesting the temporary credentials.
212 - AccessToken: Request the access tokens.
213 - AuthorizedRequest: When OAuth process is complete, we can access the
214 protected resources with this request.
215
216 * void setConsumerKey(const QString &consumerKey)
217 Set the consumer key to 'consumerKey'. This is given by the service provider.
218
219 * void setConsumerSecretKey(const QString &consumerSecretKey)
220 Set the consumer key secret to 'consumerSecretKey'. This is given by the
221 service provider.
222
223 * void setCallbackUrl(const QUrl &callbackUrl)
224 If the request type is 'KQOAuthRequest::TemporaryCredentials', then this
225 is the callback URL for the request. This is needed when asking user
226 authorization.
227
228 * void setTokenSecret(const QString &tokenSecret)
229 If the request type is 'KQOAuthRequest::AccessToken' then this is the
230 temporary token secret from the earlier request returned by the service
231 provider.
232
233 * void setToken(const QString &token)
234 If the request type is 'KQOAuthRequest::AccessToken' then this is the
235 temporary token from the earlier request returned by the service provider.
236
237 * void setSignatureMethod(KQOAuthRequest::RequestSignatureMethod)
238 Sets the signature method to be used when signing the requests.
239
240 NOTE: Currently only KQOAuthRequest::::HMAC_SHA1 is supported!
241
242 * void setHttpMethod(KQOAuthRequest::RequestHttpMethod)
243 Sets the HTTP method to be used for this request.
244
245 * void setAdditionalParameters(const KQOAuthParameters &additionalParams);
246 Sets any additional request specific parameters as specified by the
247 service provider.
248
249 * void setRequestBody(const KQOAuthParameters &requestParams);
250 Sets the request body for HTTP POST request as specified by the service
251 provider.
252
253 * bool isValid() const;
254 Returns true if this request is valid (has all the necessary parameters
255 required by the given request type).
256
257 * QByteArray requestBody() const;
258 Returns the raw request body as sent to the service provider.
259
260 * KQOAuthRequest::RequestType requestType() const;
261 Returns the current request type.
262
263 * QUrl requestEndpoint() const;
264 Returns the current request endpoint (URL location).
265
266 * void setContentType(const QString &contentType)
267 By default the POST requests are sent as "application/x-www-form-urlencoded".
268 With this method, however, the content type of the POST request can be changed.
269 If you want to override the content type, please look at setRawData().
270
271 * QString contentType()
272 Returns the current content type.
273
274 * void setRawData(const QByteArray &data);
275 If you send the POST request as anything else but "application/x-www-form-urlencoded"
276 it is assumed that you want to send some manually crafted data that kQOAuth
277 is not responsible of.
278 Set that data here.
279
280 * QByteArray rawData()
281 Returns the raw data you want to se send to the endpoint.
282
283
284 * QList<QByteArray> requestParameters();
285 Returns the request parameters of this request as a list of elements
286 sent to the service.
287
288 * void clearRequest();
289 Deletes all cached data from this request object.
290
291 * void setTimeout(int timeoutMilliseconds);
292 Sets the timeout for this request. If the timeout expires, the request will be aborted.
293
294
295 SOURCE CODE
296 ============================
297
298 The source code is available on Gitorious at:
299 http://www.gitorious.org/kqoauth
300
301 git clone git://gitorious.org/kqoauth/kqoauth.git
302
303
304 EXAMPLE APPLICATION
305 ============================
306 kQOAuth provides as an example application a command line Twitter client.
307 Currently it only supports requesting the authorization and sending status
308 updates, but this should be enough to show the basic usage of kQOAuth with
309 the convenience APIs.
310
311 See example/twittercli/ for source code.
312
313
314 LICENSE AND AUTHOR
315 ============================
316
317 The library and the source code is licensed under the GNU Lesser General Public
318 License (LGPL). For more information, visit http://www.gnu.org/licenses/lgpl.html
319
320 This library is written by Johan Paul ([email protected])
321
322
323 CONTRIBUTORS
324 ============================
325
326 Keith Obenschain ([email protected])
327
328
329 ACKNOWLEDGEMENT
330 ============================
331
332 Thank you to Dominik Kapusta for the original Qt OAuth library, QOAuth. I wanted
333 to improve on this library to better suit my needs.
334
335 Visit his project at http://files.ayoy.net/qoauth/doc/
336
337
338 SO, WHAT'S WITH THE NAME?
339 ============================
340
341 The library is called kQOAuth. I wanted the library to reflect the fact that it
342 is a Qt based library and since QOAuth was already taken, I added a 'k' in
343 front of it. k is for Kypeli, not KDE.