#include <QtOAuth>
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 ¶ms=ParamMap()) |
ParamMap | accessToken (const QString &requestUrl, HttpMethod httpMethod, const QByteArray &token, const QByteArray &tokenSecret, SignatureMethod signatureMethod=HMAC_SHA1, const ParamMap ¶ms=ParamMap()) |
QByteArray | createParametersString (const QString &requestUrl, QOAuth::HttpMethod httpMethod, const QByteArray &token, const QByteArray &tokenSecret, QOAuth::SignatureMethod signatureMethod, const QOAuth::ParamMap ¶ms, QOAuth::ParsingMode mode) |
QByteArray | inlineParameters (const QOAuth::ParamMap ¶ms) |
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. |
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.
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...
enum QOAuth::ErrorCode |
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.
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. |
enum QOAuth::HttpMethod |
The HTTP method has to be specified in QOAuth class for two reasons:
enum QOAuth::ParsingMode |
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.
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.
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.:
content-type
set to application/x-www-form-urlencoded
.
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.
mode | httpMode | outcome |
QOAuth::ParseForInlineQuery | QOAuth::GET | prepended 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 |
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.
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.:
content-type
set to application/x-www-form-urlencoded
.
QByteArray QOAuth::consumerKey [read, write] |
The consumer key is used by the application to identify itself to the Service Provider
Access functions:
QByteArray QOAuth::consumerSecret [read, write] |
The consumerSecret is used by the application for signing outgoing requests
Access functions:
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:
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: