QOAuth Class Reference

This class provides means for interaction with network services supporting OAuth authorization scheme. More...

#include <QtOAuth>

List of all members.

Public Types

enum  SignatureMethod { HMAC_SHA1, RSA_SHA1, PLAINTEXT }
 This enum type describes the signature method used by the request. More...
enum  HttpMethod {
  GET, POST, HEAD, PUT,
  DELETE
}
 This enum type specifies the HTTP method used for creating a Signature Base String and/or sending a request. More...
enum  ParsingMode { ParseForInlineQuery, ParseForHeaderArguments, ParseForSignatureBaseString }
 This enum type specifies the method of parsing parameters into a parameter string. More...
enum  ErrorCode {
  NoError = 200, BadRequest = 400, Unauthorized = 401, Forbidden = 403,
  Timeout = 1, ConsumerKeyEmpty, ConsumerSecretEmpty, UnsupportedSignatureMethod,
  UnsupportedHttpMethod, OtherError
}
 This enum type defines error types that are assigned to the error property. More...
typedef QMultiMap< QByteArray,
QByteArray > 
ParamMap
 A typedef of a data structure to store request paramters.

Public Member Functions

 QOAuth (QObject *parent=0)
 Creates a new QOAuth class instance with the given parent.
virtual ~QOAuth ()
 Destroys the QOAuth object.
ParamMap requestToken (const QString &requestUrl, HttpMethod httpMethod, SignatureMethod signatureMethod=HMAC_SHA1, const ParamMap &params=ParamMap())
ParamMap accessToken (const QString &requestUrl, HttpMethod httpMethod, const QByteArray &token, const QByteArray &tokenSecret, SignatureMethod signatureMethod=HMAC_SHA1, const ParamMap &params=ParamMap())
QByteArray createParametersString (const QString &requestUrl, QOAuth::HttpMethod httpMethod, const QByteArray &token, const QByteArray &tokenSecret, QOAuth::SignatureMethod signatureMethod, const QOAuth::ParamMap &params, QOAuth::ParsingMode mode)
QByteArray inlineParameters (const QOAuth::ParamMap &params)

Static Public Attributes

static const QByteArray OAuthVersion = "1.0"
 The supported OAuth scheme version.
static const QByteArray ParamToken = "oauth_token"
 The token request parameter string.
static const QByteArray ParamTokenSecret = "oauth_token_secret"
 The token secret request parameter string.

Properties

QByteArray consumerKey
 This property holds the consumer key.
QByteArray consumerSecret
 This property holds the consumer secret.
uint requestTimeout
 This property holds the timeout value for issued network requests.
int error
 This property holds the error code.


Detailed Description

The QOAuth class is meant to enable OAuth support in applications in as simple way as possible. It provides 4 basic methods, two of which serve for authorization purposes: and the other two help with creation of requests for accessing Protected Resources:

OAuth authorization scheme

According to OAuth 1.0 Core specification, the OAuth protocol enables websites or applications (Consumers) to access Protected Resources from a web service (Service Provider) via an API, without requiring Users to disclose their Service Provider credentials to the Consumers. Simply, OAuth is a way of connecting an application to the Service Provider's API without needing to provide User's login or password. The authorization is based on an exchange of a Token (user-specific) together with a Consumer Key (application-specific), encrypted with a combination of so called Token Secret and Customer Secret. Getting access to Protected Resources consists in three basic steps:
  1. obtaining an unauthorized Request Token from the Service Provider,
  2. asking the User to authorize the Request Token,
  3. exchanging the Request Token for an Access Token.
Details are covered in Section 6 of the OAuth 1.0 Core Specification. As the authorization procedure is quite complex, the QOAuth library helps to simplify it by doing all the dirty work behind the scenes.

OAuth authorization with QOAuth

First step of OAuth authorization can be done in one line using QOAuth library. Consult the example:

QByteArray token;
QByteArray tokenSecret;

QOAuth qoauth = new QOAuth;
// set the consumer key and secret
qoauth->setConsumerKey( "75b3d557c9268c49cfdf041a" );
qoauth->setConsumerSecret( "fd12803fbf0760d34cd2ceb9955199ce" );
// set a timeout for requests (in msecs)
qoauth->setRequestTimeout( 10000 );

// send a request for an unauthorized token
QOAuth::ParamMap reply =
    qoauth->requestToken( "http://example.com/request_token",
                          QOAuth::GET, QOAuth::HMAC_SHA1 );

// if no error occurred, read the received token and token secret
if ( qoauth->error() == QOAuth::NoError ) {
  token = reply.value( QOAuth::ParamToken );
  tokenSecret = reply.value( QOAuth::ParamTokenSecret );
}

After the unauthorized Request Token is received, User has to authorize it using Service Provider-defined method. This is beyond the scope of this library. Once User authorizes the Request Token, it can be exchanged for an Access Token that authorizes the application to access User's Protected Resources. This can be done with another one line:

// if necessary, create a map of additional arguments required by the Service Provider
QOAuth::ParamMap otherArgs;
otherArgs.insert( "misc_arg1", "value1" );
otherArgs.insert( "misc_arg2", "value2" );

// send a request to exchange Request Token for an Access Token
QOAuth::ParamMap reply =
    qoauth->accessToken( "http://example.com/access_token", QOAuth::POST, token,
                         tokenSecret, QOAuth::HMAC_SHA1, otherArgs );

// if no error occurred, read the Access Token (and other arguments, if applicable)
if ( qoauth->error() == QOAuth::NoError ) {
  token = reply.value( QOAuth::ParamToken );
  tokenSecret = reply.value( QOAuth::ParamTokenSecret );
  otherInfo = reply.value( "misc_arg3" );
}

Once the Access Token is received, the application is authorized.

Requesting Protected Resources with QOAuth

In order to access Protected Resources, the application has to send a request containing arguments including Customer Key and Access Token, and encrypt them with Customer Secret and Token Secret. The process of constructing such a request can be reduced to another one-line call with QOAuth:

QByteArray url( "http://example.com/get_photo");
// create a request parameters map
QOAuth::ParamMap map;
map.insert( "file", "flower_48.jpg" );
map.insert( "size", "small" );

// construct the parameters string
QByteArray content =
    qoauth->createParametersString( requestUrl, QOAuth::GET, QOAuth::HMAC_SHA1,
                                    token, tokenSecret, map,
                                    QOAuth::ParseForInlineQuery );
// append parameters string to the URL
url.append( content );
QNetworkRequest request( QUrl( url ) );
// etc...

Capabilities

Out of 3 signature methods supported by OAuth protocol, QOAuth library supports only HMAC-SHA1 at the moment. This is subject to change in future releases.

Member Enumeration Documentation

This error codes collection contains both network-related errors and those that can occur when incorrect arguments are provided to any of the class's methods.

See also:
error
Enumerator:
NoError  No error occured (so far :-) ).
BadRequest  Represents HTTP status code 400 (Bad Request).
Unauthorized  Represents HTTP status code 401 (Unauthorized).
Forbidden  Represents HTTP status code 403 (Forbidden).
Timeout  Represents a request timeout error.
ConsumerKeyEmpty  Consumer key has not been provided.
ConsumerSecretEmpty  Consumer secret has not been provided.
UnsupportedSignatureMethod  The signature method is not supported by the library.
UnsupportedHttpMethod  The HTTP method is not supported by the request. Note that requestToken() and accessToken() accept only HTTP GET and POST requests.
OtherError  A network-related error not specified above.

The HTTP method has to be specified in QOAuth class for two reasons:

Note:
For requestToken() and accessToken() methods only GET and POST methods are allowed.
Enumerator:
GET  Sets the HTTP method to GET.
POST  Sets the HTTP method to POST.
HEAD  Sets the HTTP method to HEAD.
PUT  Sets the HTTP method to PUT.
DELETE  Sets the HTTP method to DELETE.

When creating a parameters string for a custom request using createParametersString() the parsing mode must be defined in order to prepare the string correctly.

According to what is stated in OAuth 1.0 Core specification, parameters can be passed in a request to the Service Provider in 3 different ways. When using createParametersString(), choose the one that suits you by setting ParsingMode appropriatelly.

See also:
createParametersString()
Enumerator:
ParseForInlineQuery  Inlne query format (parameters appended to the request URL).
ParseForHeaderArguments  HTTP request header format (parameters to be put inside a request header).
ParseForSignatureBaseString  Signature Base String format, meant for internal use.

There are 3 different signature methods defined by the OAuth protocol. This enum is used to specify the method used by a specific request. Hence, one of its values must be passed as a parameter in any of the requestToken(), accessToken() or createParametersString() method.

Note:
The current implementation of the library supports only HMAC-SHA1 signature algorithm.
Enumerator:
HMAC_SHA1  Sets the signature method to HMAC-SHA1.
RSA_SHA1  Sets the signature method to RSA-SHA1 (not implemented yet).
PLAINTEXT  Sets the signature method to PLAINTEXT (not implemented yet).


Member Function Documentation

QOAuth::ParamMap QOAuth::accessToken ( const QString &  requestUrl,
HttpMethod  httpMethod,
const QByteArray &  token,
const QByteArray &  tokenSecret,
SignatureMethod  signatureMethod = HMAC_SHA1,
const ParamMap params = ParamMap() 
)

This method constructs and sends a request for exchanging a Request Token (obtained previously with a call to requestToken()) for an Access Token, that authorizes the application to access Protected Resources. This is the third step of the OAuth authentication flow, according to OAuth 1.0 Core specification. At the moment only HMAC-SHA1 signature method is supported. The HMAC-SHA1 Signature Base String is created using the given requestUrl, httpMethod, token and tokenSecret. The optional request parameters specified by the Service Provider can be passed in the params ParamMap.

The Signature Base String contains the consumerKey and uses consumerSecret for encrypting the message, so it's necessary to provide them both before issuing this request. The method will check if both consumerKey and consumerSecret are provided, and fail if any of them is missing.

When the signature is created, the appropriate request is sent to the Service Provider (namely, the requestUrl). Depending on the type of the request, the parameters are passed according to the Consumer Request Parametes section of the OAuth specification, i.e.:

  • for GET requests, in the HTTP Authorization header, as defined in OAuth HTTP Authorization Scheme,
  • for POST requests, as a request body with content-type set to application/x-www-form-urlencoded.
Once the request is sent, a local event loop is executed and set up to wait for the request to complete. If the requestTimeout property is set to a non-zero value, its vaue is applied as a request timeout, after which the request is aborted.

Returns:
If request succeded, the method returns all the data passed in the Service Provider response (including an authorized Access Token and Token Secret), formed in a ParamMap. This request ends the authorization process, and the obtained Access Token and Token Secret should be kept by the application and provided with every future request authorized by OAuth, e.g. using createParametersString(). If request fails, the error property is set to an appropriate value, and an empty ParamMap is returned.
See also:
requestToken(), createParametersString(), error

QByteArray QOAuth::createParametersString ( const QString &  requestUrl,
QOAuth::HttpMethod  httpMethod,
const QByteArray &  token,
const QByteArray &  tokenSecret,
QOAuth::SignatureMethod  signatureMethod,
const QOAuth::ParamMap params,
QOAuth::ParsingMode  mode 
)

This method generates a parameters string required to access Protected Resources using OAuth authorization. According to OAuth 1.0 Core specification, every outgoing request for accessing Protected Resources must contain information like consumer key and Access Token, and has to be signed using one of the supported signature methods.

At the moment only HMAC-SHA1 signature method is supported by the library. The HMAC-SHA1 Signature Base String is created using the given requestUrl, httpMethod, token and tokenSecret. The optional request parameters specified by the Service Provider can be passed in the params ParamMap.

The Signature Base String contains the consumerKey and uses consumerSecret for encrypting the message, so it's necessary to provide them both before issuing this request. The method will check if both consumerKey and consumerSecret are provided, and fail if any of them is missing.

The mode parameter specifies the format of the parameter string.

Returns:
The parsed parameters string, that depending on mode and httpMethod is:
mode httpMode outcome
QOAuth::ParseForInlineQueryQOAuth::GETprepended with a '?' and ready to be appended to the requestUrl
others ready to be posted as a request body
QOAuth::ParseForHeaderArguments irrelevant ready to be set as an argument for the Authorization HTTP header
QOAuth::ParseForSignatureBaseString irrelevant meant for internal use

See also:
inlineParameters()

QByteArray QOAuth::inlineParameters ( const QOAuth::ParamMap params  ) 

This method is provided for convenience. It generates an inline query string out of given parameter map and prepends it with '?'. The resulting string can be appended directly to a request URL as a query string.

Use this method together with createParametersString(), when you request a header parameters string (QOAuth::ParseForHeaderArguments) together with HTTP GET method. In such case, apart from header arguments, you must provide a query string containing custom request parameters (i.e. not OAuth-related). Pass the custom parameters map to this method to receive a query string to be appended to the URL.

See also:
createParametersString()

QOAuth::ParamMap QOAuth::requestToken ( const QString &  requestUrl,
HttpMethod  httpMethod,
SignatureMethod  signatureMethod = HMAC_SHA1,
const ParamMap params = ParamMap() 
)

This method constructs and sends a request for obtaining an unauthorized Request Token from the Service Provider. This is the first step of the OAuth authentication flow, according to OAuth 1.0 Core specification. At the moment only HMAC-SHA1 signature method is supported. The HMAC-SHA1 Signature Base String is created using the given requestUrl and httpMethod. The optional request parameters specified by the Service Provider can be passed in the params ParamMap.

The Signature Base String contains the consumerKey and uses consumerSecret for encrypting the message, so it's necessary to provide them both before issuing this request. The method will check if both consumerKey and consumerSecret are provided, and fail if any of them is missing.

When the signature is created, the appropriate request is sent to the Service Provider (namely, the requestUrl). Depending on the type of the request, the parameters are passed according to the Consumer Request Parametes section of the OAuth specification, i.e.:

  • for GET requests, in the HTTP Authorization header, as defined in OAuth HTTP Authorization Scheme,
  • for POST requests, as a request body with content-type set to application/x-www-form-urlencoded.
Once the request is sent, a local event loop is executed and set up to wait for the request to complete. If the requestTimeout property is set to a non-zero value, its vaue is applied as a request timeout, after which the request is aborted.

Returns:
If request succeded, the method returns all the data passed in the Service Provider response (including a Request Token and Token Secret), formed in a ParamMap. If request fails, the error property is set to an appropriate value, and an empty ParamMap is returned.
See also:
accessToken(), error


Property Documentation

QByteArray QOAuth::consumerKey [read, write]

The consumer key is used by the application to identify itself to the Service Provider

Access functions:

  • QByteArray consumerKey() const
  • void setConsumerKey( const QByteArray &consumerKey )

QByteArray QOAuth::consumerSecret [read, write]

The consumerSecret is used by the application for signing outgoing requests

Access functions:

  • QByteArray consumerSecret() const
  • void setConsumerSecret( const QByteArray &consumerSecret )

int QOAuth::error [read]

The error code is initially set to NoError, and its value is updated with every request, i.e. requestToken(), accessToken() or createParametersString().

Access functions:

  • int error() const
See also:
ErrorCode

uint QOAuth::requestTimeout [read, write]

The QOAuth class can send network requests when asked to do so by calling either requestToken() or accessToken() method. By defining the requestTimeout, requests can have the time constraint applied, after which they fail, setting error to Timeout. The requestTimeout value is initially set to 0, which in this case means that no timeout is applied to outgoing requests.

Access functions:

  • uint requestTimeout() const
  • void setRequestTimeout( uint requestTimeout )


The documentation for this class was generated from the following files:

Generated on Wed Jun 24 01:24:03 2009 for QOAuth by  doxygen 1.5.8