| 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. |