Documentation and easier more clear initialization and authorization

README.md

@@ -0,0 +1,114 @@
+twitter-xauth
+============
+
+This is an extremely simple twitter client for Mac OS X and iOS, which
+uses xauth for authentication. The only other feature provided are
+status updates. I created this project because I wanted something
+small and simple, and need only to be able to do status updates on
+twitter. I'm posting it in hopes that it might be of use to someone
+else.
+
+See twitter-xauth.m for example usage. Fill in values for
+CONSUMER_KEY, CONSUMER_SECRET, TWITTER_USERNAME, and
+TWITTER_PASSWORD. Compiles on Mac OS X using gnu make.
+
+
+Requisites
+==========
+
+Your Twitter app must have XAuth enabled.  To do so, follow the 
+instructions on this page:
+https://dev.twitter.com/docs/oauth/xauth
+
+Don't be intimidated.  As long as you provide all the necessary info 
+to Twitter they will likely grant you access.  XAuth will save you a 
+lot of time compared to implementing MGTwitterEngine and represents a 
+good solution for integrating iOS with Twitter until iOS 5.0 arrives. 
+
+Installation
+===========
+
+You'll need to copy the following files into your project:
+* TwitterXAuth.h
+* TwitterXAuth.m
+* NSData+Base64.h (assuming you're not already using this)
+* NSData+Base64.m (assuming you're not already using this)
+
+Then make sure you import in whatever controllers you need:
+
+```objective-c
+#import "TwitterXAuth.h"
+```
+Usage
+=====
+
+####Initialize TwitterXAuth
+
+```objective-c
+TwitterXAuth *twitter = [[TwitterXAuth alloc] initWithConsumerKey:@"your key" secret:@"your secret" andDelegate:self];
+```
+Make sure you implement the delegate methods you need:
+
+```objective-c
+# pragma mark - TwitterXAuth
+
+- (void) twitterXAuthAuthorizationDidFail:(TwitterXAuth *)twitterXAuth
+{
+    NSLog(@"auth failed");
+}
+
+- (void) twitterXAuthDidAuthorize:(TwitterXAuth *)twitterXAuth
+{
+    NSLog(@"auth succeeded");
+}
+```
+#### Authenticate user
+
+```objective-c
+[twitter authorizeWithUsername:loginObject.userName andPassword:loginObject.password];
+```
+
+#### Tweet on the user's behalf
+
+```objective-c
+[twitter tweet:@"Hi from Twitter-XAuth"];
+```
+Make sure you implement the tweet delegate methods if you need:
+
+```objective-c
+- (void) twitterXAuthTweetDidFail:(TwitterXAuth *)twitterXAuth
+{
+    NSLog(@"tweet failed";
+}
+
+- (void) twitterXAuthDidTweet:(TwitterXAuth *)twitterXAuth
+{
+    NSLog(@"tweet succeeded");
+}
+```
+#### Single Sign On
+Should you need to log a user in to your backend with Twitter, you'll need to grab the user's token and tokenSecret from the TwitterXAuth object.  The easiest way to do this is to implement the `twitterXAuthDidRetrieveToken:andSecret` method:
+
+```objective-c
+- (void) twitterXAuthDidRetrieveToken:(NSString *)token andTokenSecret:(NSString *)secret
+{
+  // Do something useful with the token and secret
+}
+```
+It's important to note that you probably want to choose to implement either `twitterXAuthDidAuthorize` OR `twitterXAuthDidRetrieveToken:andSecret` because they both will be called upon authorization if they are implemented.
+
+More
+====
+
+See more documentation about XAuth using the links below:
+
+* http://weblog.bluedonkey.org/?p=959
+* http://cocoawithlove.com/2009/06/base64-encoding-options-on-mac-and.html
+* http://www.getsharekit.com/
+* http://www.gigliwood.com/weblog/Cocoa/Q__When_is_an_conne.html
+* http://dev.twitter.com/pages/xauth
+* http://dev.twitter.com/doc/post/oauth/access_token
+* http://dev.twitter.com/pages/auth#auth-request
+
+Special thanks to Matt Gallagher of cocoawithlove.com for providing an
+Objective-C implementation of Base64 encoding for Mac and iPhone.

TwitterXAuth.h

@@ -23,6 +23,12 @@
 - (void) twitterXAuthDidAuthorize:(TwitterXAuth *)twitterXAuth;
 - (void) twitterXAuthTweetDidFail:(TwitterXAuth *)twitterXAuth;
 - (void) twitterXAuthDidTweet:(TwitterXAuth *)twitterXAuth;
+
+/*
+ * Implement this method if you want to get the token and secret immediately
+ * after authorization
+ */
+- (void) twitterXAuthDidRetrieveToken:(NSString *)token andTokenSecret:(NSString *)secret;
 @end
 
 typedef enum {
@@ -54,6 +60,23 @@ typedef enum {
 @property (nonatomic,copy) NSString * token; //oauth_token
 @property (nonatomic,copy) NSString * tokenSecret; //oauth_token_secret
 @property (nonatomic,assign) id<TwitterXAuthDelegate> delegate;
-- (void) authorize;
+
+/*
+ * Use this to create your TwitterXAuth object.  Then call authorizeWithUsername:andPassword:
+ * when the user has entered his/her credentials
+ */
+- (id) initWithConsumerKey:(NSString *)key secret:(NSString *)secret andDelegate:(id<TwitterXAuthDelegate>)del;
+
+/*
+ * Send an authentication request to Twitter
+ * @param username the user's twitter handle
+ * @param password the user's twitter password
+ */
+- (void) authorizeWithUsername:(NSString *)username andPassword:(NSString *)password;
+
+/*
+ * Send a status update to twitter on behalf of authenticated user
+ * @param status the tweet text
+ */
 - (void) tweet:(NSString *)status;
 @end

TwitterXAuth.m

@@ -52,11 +52,18 @@ @implementation TwitterXAuth
 
 - (id) init
 {
-  if ((self = [super init])) {
-    state = TwitterXAuthStateDefault;
-    data = [[NSMutableData alloc] init];
-    self.tokenSecret = @"";
-  }
+  [NSException raise:@"Initialization Error" format:@"you must initialize with initWithConsumerKey:secret:andDelegate:"];
+  return nil;
+}
+
+- (id) initWithConsumerKey:(NSString *)key secret:(NSString *)secret andDelegate:(id<TwitterXAuthDelegate>)del
+{
+  self = [super init];
+  state = TwitterXAuthStateDefault;
+  data = [[NSMutableData alloc] init];
+  self.consumerKey = key;
+  self.consumerSecret = secret;
+  self.delegate = del;
   return self;
 }
 
@@ -144,7 +151,8 @@ - (NSString *) baseString
 
 - (NSString *) signature
 {
-  NSString * secret = [NSString stringWithFormat:@"%@&%@", self.consumerSecret, self.tokenSecret];
+  if(!self.tokenSecret) self.tokenSecret = @"";
+  NSString *secret = [NSString stringWithFormat:@"%@&%@", self.consumerSecret, self.tokenSecret];
 
   NSData * secretData = [secret dataUsingEncoding:NSUTF8StringEncoding];
   NSData * baseData = [self.baseString dataUsingEncoding:NSUTF8StringEncoding];
@@ -173,8 +181,10 @@ - (NSString *) authorizationHeader
   return [NSString stringWithFormat:@"OAuth %@", [keysAndValues componentsJoinedByString:@", "]];
 }
 
-- (void) authorize
+- (void) authorizeWithUsername:(NSString *)_username andPassword:(NSString *)_password
 {
+  self.username = _username;
+  self.password = _password;
   //send POST to https://api.twitter.com/oauth/access_token with parameters: x_auth_username, x_auth_password, x_auth_mode
 
   [self resetTimestamp];
@@ -231,6 +241,7 @@ - (void) tweet:(NSString *)status
 
 - (void)connection:(NSURLConnection *)connection didFailWithError:(NSError *)error
 {
+  NSLog(@"error %@", [error localizedDescription]);
   if (state == TwitterXAuthStateAuthorize && delegate && [delegate respondsToSelector:@selector(twitterXAuthAuthorizationDidFail:)])
     [delegate twitterXAuthAuthorizationDidFail:self];
   if (state == TwitterXAuthStateTweet && delegate && [delegate respondsToSelector:@selector(twitterXAuthTweetDidFail:)])
@@ -267,6 +278,8 @@ - (void)connectionDidFinishLoading:(NSURLConnection *)connection
     NSString * response = [[[NSString alloc] initWithData:data
 						 encoding:NSUTF8StringEncoding] autorelease];
     NSArray * parameters = [response componentsSeparatedByString:@"&"];
+    NSLog(@"response parameters %@", parameters);
+
     NSMutableDictionary * dictionary = [NSMutableDictionary dictionary];
     for (NSString * parameter in parameters) {
       NSArray * keyAndValue = [parameter componentsSeparatedByString:@"="];
@@ -287,6 +300,10 @@ - (void)connectionDidFinishLoading:(NSURLConnection *)connection
     if (delegate && [delegate respondsToSelector:@selector(twitterXAuthDidTweet:)])
       [delegate twitterXAuthDidTweet:self];
   }
+  if(self.token && ![self.tokenSecret isEqualToString:@""]){
+    if([self.delegate respondsToSelector:@selector(twitterXAuthDidRetrieveToken:andTokenSecret:)])
+      [self.delegate twitterXAuthDidRetrieveToken:self.token andTokenSecret:self.tokenSecret];
+  }
 }
 
 @end