Warning, /pim/kdepim-runtime/resources/tomboynotes/o2/README.md is written in an unsupported language. File is not indexed.
0001 # OAuth 1.0 and 2.0 for Qt 0002 0003 This library encapsulates the OAuth 1.0 and 2.0 client authentication flows, and the sending of authenticated HTTP requests. 0004 0005 The primary target is Qt Quick applications on embedded devices. 0006 0007 Notes to contributors: 0008 0009 * Please follow the coding style of the existing source 0010 * Code contributions are released under Simplified BSD License, as specified in LICENSE. Do not contribute if this license does not suit your code 0011 0012 ## Classes 0013 0014 Class | Header | Purpose 0015 :-- | :-- | :-- 0016 O0AbstractStore | o0abstractstore.h | Base class of persistent stores 0017 O0BaseAuth | o0baseauth.h | Base class of OAuth authenticators 0018 O0SettingsStore | o2settingsstore.h | QSettings-based persistent store 0019 O0SimpleCrypt | o0simplecrypt.h | Simple encryption and decryption by Andre Somers 0020 O1 | o1.h | Generic OAuth 1.0 authenticator 0021 O1Dropbox | o1dropbox.h | Dropbox OAuth specialization 0022 O1Flickr | o1flickr.h | Flickr OAuth specialization 0023 O1Freshbooks | o1freshbooks.h | Freshbooks OAuth specialization 0024 O1Requestor | o1requestor.h | Makes authenticated OAuth 1.0 requests: GET, POST or PUT, handles timeouts 0025 O1RequestParameter | o1.h | An extra request parameter participating in request signing 0026 O1Twitter | o1twitter.h | Twitter OAuth specialization 0027 O2 | o2.h | Generic OAuth 2.0 authenticator 0028 O2Facebook | o2facebook.h | Facebook OAuth specialization 0029 O2Gft | o2gft.h | Google Fusion Tables OAuth specialization 0030 O2Hubic | o2hubic.h | Hubic OAuth specialization 0031 O2Reply | o2reply.h | A network request/reply that can time out 0032 O2ReplyServer | o2replyserver.h | HTTP server to process authentication responses 0033 O2Requestor | o2requestor.h | Makes authenticated OAuth 2.0 requests (GET, POST or PUT), handles timeouts and token expiry 0034 O2Skydrive | o2skydrive.h | OneDrive OAuth specialization 0035 O2SurveyMonkey | o2surveymonkey.h | SurveyMonkey OAuth specialization 0036 OXTwitter | oxtwitter.h | Twitter XAuth specialization 0037 0038 ## Installation 0039 0040 Clone the Github repository, then add all files in *src* to your Qt project, by including *src/src.pri*. 0041 0042 ## Basic Usage 0043 0044 This example assumes a hypothetical Twitter client that will post tweets. Twitter is using OAuth 1.0. 0045 0046 ### Setup 0047 0048 Include the required header files, and have some member variables that will be used for authentication and sending requests: 0049 0050 #include "o1twitter.h" 0051 #include "o1requestor.h" 0052 O1Twitter *o1; 0053 0054 ### Initialization 0055 0056 Instantiate one of the authenticator classes, like O1Twitter, set your application ID and application secret, and install the signal handlers: 0057 0058 o1 = new O1Twitter(this); 0059 o1->setClientId(MY_CLIENT_ID); 0060 o1->setClientSecret(MY_CLIENT_SECRET); 0061 connect(o1, SIGNAL(linkedChanged()), this, SLOT(onLinkedChanged())); 0062 connect(o1, SIGNAL(linkingFailed()), this, SLOT(onLinkingFailed())); 0063 connect(o1, SIGNAL(linkingSucceeded()), this, SLOT(onLinkingSucceeded())); 0064 connect(o1, SIGNAL(openBrowser(QUrl)), this, SLOT(onOpenBrowser(QUrl))); 0065 connect(o1, SIGNAL(closeBrowser()), this, SLOT(onCloseBrowser())); 0066 0067 **Note:** For browserless Twitter authentication, you can use the OXTwitter specialized class which can do Twitter XAuth. You will need to additionally provide your Twitter login credentials (username & password) before calling *link()*. 0068 0069 ### Handling Signals 0070 0071 O2 is an asynchronous library. It will send signals at various stages of authentication and request processing. 0072 0073 To handle these signals, implement the following slots in your code: 0074 0075 void onLinkedChanged() { 0076 // Linking (login) state has changed. 0077 // Use o1->linked() to get the actual state 0078 } 0079 0080 void onLinkingFailed() { 0081 // Login has failed 0082 } 0083 0084 void onLinkingSucceeded() { 0085 // Login has succeeded 0086 } 0087 0088 void onOpenBrowser(const QUrl *url) { 0089 // Open a web browser or a web view with the given URL. 0090 // The user will interact with this browser window to 0091 // enter login name, password, and authorize your application 0092 // to access the Twitter account 0093 } 0094 0095 void onCloseBrowser() { 0096 // Close the browser window opened in openBrowser() 0097 } 0098 0099 ### Logging In 0100 0101 To log in (e.g. to link your application to the OAuth service), call the link() method: 0102 0103 o1->link(); 0104 0105 This initiates the authentication sequence. Your signal handlers above will be called at various stages. Lastly, if linking succeeds, onLinkingSucceeded() will be called. 0106 0107 ### Logging Out 0108 0109 To log out, call the unlink() method: 0110 0111 o1->unlink(); 0112 0113 Logging out always succeeds, and requires no user interaction. 0114 0115 ### Sending Authenticated Requests 0116 0117 Once linked, you can start sending authenticated requests to the service. We start with a simple example of sending a text-only tweet or as it's known in Twitter docs, a 'status update'. 0118 0119 First we need a Qt network manager and an O1 requestor object: 0120 0121 QNetworkAccessManager *manager = new QNetworkAccessManager(this); 0122 O1Requestor *requestor = new O1Requestor(manager, o1, this); 0123 0124 Next, create parameters for posting the update: 0125 0126 QByteArray paramName("status"); 0127 QByteArray tweetText("My first tweet!"); 0128 0129 QList<O1RequestParameter> requestParams = QList<O1RequestParameter>(); 0130 requestParams << O1RequestParameter(paramName, tweetText); 0131 0132 QByteArray postData = O1::createQueryParams(requestParams); 0133 0134 // Using Twitter's REST API ver 1.1 0135 QUrl url = QUrl("https://api.twitter.com/1.1/statuses/update.json"); 0136 0137 QNetworkRequest request(url); 0138 request.setHeader(QNetworkRequest::ContentTypeHeader, O2_MIME_TYPE_XFORM); 0139 0140 Finally we authenticate and send the request using the O1 requestor object: 0141 0142 QNetworkReply *reply = requestor->post(request, reqestParams, postData); 0143 0144 Continuing with the example, we will now send a tweet containing an image as well as a message. 0145 0146 We create an HTTP request containing the image and the message, in the format specified by Twitter: 0147 0148 QString imagePath("/tmp/image.jpg"); 0149 QString message("My tweet with an image!"); 0150 0151 QFileInfo fileInfo(imagePath); 0152 QFile file(imagePath); 0153 file.open(QIODevice::ReadOnly); 0154 0155 QString boundary("7d44e178b0439"); 0156 QByteArray data(QString("--" + boundary + "\r\n").toAscii()); 0157 data += "Content-Disposition: form-data; name=\"media[]\"; filename=\"" + fileInfo.fileName() + "\"\r\n"; 0158 data += "Content-Transfer-Encoding: binary\r\n"; 0159 data += "Content-Type: application/octet-stream\r\n\r\n"; 0160 data += file.readAll(); 0161 file.close(); 0162 data += QString("\r\n--") + boundary + "\r\n"; 0163 data += "Content-Disposition: form-data; name=\"status\"\r\n"; 0164 data += "Content-Transfer-Encoding: binary\r\n"; 0165 data += "Content-Type: text/plain; charset=utf-8\r\n\r\n"; 0166 data += message.toUtf8(); 0167 data += QString("\r\n--") + boundary + "--\r\n"; 0168 0169 QNetworkRequest request; 0170 // Using Twitter's REST API ver 1.1 0171 request.setUrl(QUrl("https://api.twitter.com/1.1/statuses/update_with_media.json")); 0172 request.setHeader(QNetworkRequest::ContentTypeHeader, "multipart/form-data; boundary=" + boundary); 0173 request.setHeader(QNetworkRequest::ContentLengthHeader, data.length()); 0174 0175 QNetworkReply *reply = requestor->post(request, QList<O1RequestParameter>(), data); 0176 0177 That's it. Tweets using the O2 library! 0178 0179 ### Storing OAuth Tokens 0180 0181 O2 provides simple storage classes for writing OAuth tokens in a persistent location. Currently, a QSettings based backing store **O2SettingsStore** is provided in O2. O2SettingsStore keeps all token values in an encrypted form. You have to specify the encryption key to use while constructing the object: 0182 0183 O0SettingsStore settings = new O0SettingsStore("myencryptionkey"); 0184 // Set the store before starting OAuth, i.e before calling link() 0185 o1->setStore(settings); 0186 ... 0187 0188 You can also create it with your customized QSettings object. O2SettingsStore will then use that QSettings object for storing the tokens: 0189 0190 O0SettingsStore settings = new O0SettingsStore(mySettingsObject, "myencryptionkey"); 0191 0192 Once set, O2SettingsStore takes ownership of the QSettings object. 0193 0194 **Note:** If you do not specify a storage object to use, O2 will create one by default (which QSettings based), and use it. In such a case, a default encryption key is used for encrypting the data. 0195 0196 ### Extra OAuth Tokens 0197 0198 Some OAuth service providers provide additional information in the access token response. Eg: Twitter returns 2 additional tokens in it's access token response - *screen_name* and *user_id*. 0199 0200 O2 provides all such tokens via the property - *extraTokens*. You can query this property after a successful OAuth exchange, i.e after the *linkingSucceeded()* signal has been emitted. 0201 0202 ## More Examples 0203 0204 The *examples* folder contains complete example applications: 0205 0206 Name | Description 0207 :-- | :-- 0208 facebookdemo | Command line application authenticating with Facebook 0209 sialis | QT Quick Twitter client using OAuth 1 0210 twitterdemo | Command line client for authenticating with Twitter and posting status updates. Uses OAuth 1 or Twitter XAuth 0211 0212