Permalink
Browse files

- updated documentation

- moved loadPersistentSession concept to MKFacebookSession
  • Loading branch information...
1 parent a9bd14d commit 9ef143cf8219d1c15ad9e7d9f6f2bbeec8f7fc7e @ferhoodle ferhoodle committed Sep 27, 2009
Showing with 124 additions and 103 deletions.
  1. +6 −6 MKEventsRequest.h
  2. +21 −26 MKFacebook.h
  3. +42 −55 MKFacebook.m
  4. +9 −1 MKFacebookSession.h
  5. +38 −7 MKFacebookSession.m
  6. +8 −8 MKPhotosRequest.h
View
12 MKEventsRequest.h
@@ -35,7 +35,7 @@ typedef enum{
} MKEventsFacebookMethod;
-/*!
+/*
@brief Convenience class for event related requests.
@class MKEventsRequest
@@ -50,33 +50,33 @@ typedef enum{
}
#pragma mark MKFacebookProtocol Requirements
-/*!
+/*
@version 0.8 and later
*/
+(id)requestUsingFacebookConnection:(MKFacebook *)facebookConnection delegate:(id)delegate;
-/*!
+/*
@version 0.8 and later
*/
-(id)initWithFacebookConnection:(MKFacebook *)facebookConnection delegate:(id)delegate;
#pragma mark Supported Methods
-/*!
+/*
@version 0.8 and later
*/
-(void)eventsGet;
-/*!
+/*
@version 0.8 and later
*/
-(void)eventsGet:(NSString *)uid eids:(NSArray *)eids startTime:(NSDate *)startTime endTime:(NSDate *)endTime rsvp_status:(MKEventRSVPStatus)rsvp_status;
-/*!
+/*
@version 0.8 and later
*/
View
47 MKFacebook.h
@@ -24,19 +24,21 @@
extern NSString *MKAPIServerURL;
extern NSString *MKLoginUrl;
+extern NSString *MKExtendPermissionsURL;
extern NSString *MKFacebookAPIVersion;
extern NSString *MKFacebookResponseFormat;
/*!
@class MKFacebook
MKFacebook is the starting point for logging in and communicating with Facebook. It handles displaying a login window for the user and notifying your application when a login has been successful.
- To provide a user with a login window for you application do the following:
+ To provide a user with a login window for your application you must do the following:
1. initialize a new MKFacebook object with your API key and a delegate object
2. call login or loginWithPermissions:forSheet:
+ 3. receive confirmation of a successful login via the userLoginSuccessful delegate method
Delegate Methods
@@ -65,10 +67,9 @@ extern NSString *MKFacebookResponseFormat;
@brief Setup new MKFacebook object.
@param anAPIKey Your API key issued by Facebook.
- @param aSecret Your secret key issued by Facebook.
@param aDelegate A delegate object that will receive calls from the MKFacebook object.
- The delegate object must implement a userLoggedIn: method that is called after a user has logged in and closed the login window. It may optionally implement a userLoginFaild method that will be called if the login fails.
+ The delegate object must implement a userLoginSuccessful method that will called after a user has successfully logged in.
@result Returns allocated and initiated MKFacebook object ready to be used to log into the Facebook API.
@version 0.7 and later
@@ -81,10 +82,9 @@ extern NSString *MKFacebookResponseFormat;
@brief Setup new MKFacebook object.
@param anAPIKey Your API key issued by Facebook.
- @param aSecret Your secret key issued by Facebook.
@param aDelegate A delegate object that will receive calls from the MKFacebook object.
- The delegate object must implement a userLoggedIn: method that is called after a user has logged in and closed the login window. It may optionally implement a userLoginFaild method that will be called if the login fails.
+ The delegate object must implement a userLoginSuccessful method that will called after a user has successfully logged in.
@result Returns initiated MKFacebook object ready to be used to log into the Facebook API.
@version 0.7 and later
@@ -106,48 +106,40 @@ extern NSString *MKFacebookResponseFormat;
/*!
@brief Load existing session if available or display a login window.
+ Tries to load existing session. If no session is available a login window will be displayed. If a user logs in successfully the session will automatically be saved to the application NSUserDefaults.
+
This is the same as calling loginWithPermisisons:nil forSheet:NO.
*/
- (void)login;
/*!
@brief Attempts to log a user in using existing session. If no session is available a login window is diplayed.
- Tries to load existing session. If no session is available a login window will be displayed.
+ Tries to load existing session. If no session is available a login window will be displayed. If a user logs in successfully the session will automatically be saved to the application NSUserDefaults.
+
@param permissions List of permisisons to offer the user.
@param sheet If YES is passed in a NSWindow will be returned, otherwise a login window will appear and nil will be returned.
@return Either a NSWindow to be attached as a sheet or nil.
*/
- (NSWindow *)loginWithPermissions:(NSArray *)permissions forSheet:(BOOL)sheet;
-/*!
- @brief Logs in a user from a saved session.
-
- Attempts to load a stored infinte session for the application. This method checks NSUserDefaults for a stored sessionKey and sessionSecret. It uses a synchronous request to try to authenticate the stored session. Note: The MKFacebook class only allows a persistent session to be loaded once per instance. For example, if a persistent session is successfully loaded then the resetFacebookConnection method is called that instance of MKFacebook will return false for every call to loadPersistentSession for the remainder of its existence. This behavior may change in the future.
-
- In order for a user to receive what appears to be an infinite session they must grant the application "offline_access" using -(void)grantExtendedPermisison:(NSString *)aString;. Unfortunately the user will have to login one more time after this is called before -(void)loadPersistentSession; will work.
-
- Trying to load a persistent session will use a synchronous request, your application might hang if the connectionTimeoutInterval is set to a high number of seconds.
-
- @result Returns true if stored session information is valid and a user id is successfully returned from Facebook otherwise it returns false.
- */
-- (BOOL)loadPersistentSession;
/*!
- @brief Returns TRUE if valid session exists.
+ @brief Checks for a valid session in NSUserDefaults.
+
- @result Checks to see if auth token, session key, session secret and uid are set. Returns true if everything is set and it's safe to assume a user has logged in.
+ @result Returns TRUE if valid session exists.
*/
- (BOOL)userLoggedIn;
/*!
@brief Get the UID of the logged in user.
- @result Returns uid of user currently logged in.
+ @result Returns uid of user currently logged in, returns nil if no user is logged in.
*/
- (NSString *)uid;
@@ -183,8 +175,7 @@ extern NSString *MKFacebookResponseFormat;
@param aString Name of extended permission to grant. See Facebook documentation for allowed extended permissions.
- This method will display a new window and load the Facebook URL http://www.facebook.com/authorize.php?api_key=YOUR_API_KEY&v=1.0&ext_perm=PERMISSION_NAME
- with authentication information is filled in automatically. If no user is logged in an alert message will be displayed unless they have been turned off. Unfortunately the user will have to login again to grant the permissions.
+ This method will display a new window and load the Facebook URL http://www.facebook.com/connect/prompt_permissions.php to extend permissions of the application.
@version 0.7.4 and later
*/
- (void)grantExtendedPermission:(NSString *)aString;
@@ -195,10 +186,14 @@ extern NSString *MKFacebookResponseFormat;
@brief Display a window and a Facebook page to extend permisisons.
@param aString Name of extended permission to grant. See Facebook documentation for allowed extended permissions.
- @result Returns NSWindow with WebView that loads the grant extended permissions request.
+ @param forSheet BOOL to request a NSWindow that can be attached as a sheet, pass in NO to simply display the window.
+
+ This method will display a new window and load the Facebook URL http://www.facebook.com/connect/prompt_permissions.php to extend permissions of the application.
+
+ @result Returns NSWindow or displays window.
@version 0.8.2 and later
*/
-- (NSWindow *)grantExtendedPermissionForSheet:(NSString *)aString;
+- (NSWindow *)grantExtendedPermission:(NSString *)aString forSheet:(BOOL)forSheet;
//@} //ENDS Extend Permissions group
@@ -222,7 +217,7 @@ extern NSString *MKFacebookResponseFormat;
/*!
- @result Returns YES if login alerts are enabled, maybe so (but actually NO) if they are not.
+ @result Returns YES if login alerts are enabled, NO if they are not.
@version 0.8 and later
*/
- (BOOL)displayLoginAlerts;
View
97 MKFacebook.m
@@ -27,6 +27,7 @@
NSString *MKAPIServerURL = @"http://api.facebook.com/restserver.php";
NSString *MKLoginUrl = @"http://www.facebook.com/login.php";
+NSString *MKExtendPermissionsURL = @"http://www.facebook.com/connect/prompt_permissions.php";
NSString *MKFacebookAPIVersion = @"1.0";
NSString *MKFacebookResponseFormat = @"XML";
@@ -89,8 +90,12 @@ - (void)login
- (NSWindow *)loginWithPermissions:(NSArray *)permissions forSheet:(BOOL)sheet
{
//try to use existing session
- if ([self loadPersistentSession] == NO) {
-
+ if ([[MKFacebookSession sharedMKFacebookSession] loadSession] == YES)
+ {
+ [self userLoginSuccessful];
+ return nil;
+ }else
+ {
//prepare loginwindow
loginWindow = [[MKLoginWindow alloc] init]; //will be released when closed
[[loginWindow window] setTitle:@"Login"];
@@ -122,38 +127,6 @@ - (NSWindow *)loginWithPermissions:(NSArray *)permissions forSheet:(BOOL)sheet
-- (BOOL)loadPersistentSession
-{
- //load any existing sessions
- MKFacebookSession *session = [MKFacebookSession sharedMKFacebookSession];
- if ([session loadSession]) {
-
- MKFacebookRequest *request = [[MKFacebookRequest alloc] init];
-
- NSXMLDocument *user = [request fetchFacebookData:[request generateFacebookURL:[NSDictionary dictionaryWithObjectsAndKeys:@"facebook.users.getLoggedInUser", @"method", nil]]];
- [request release];
-
- if([user validFacebookResponse] == NO)
- {
- DLog(@"persistent login failed, here's why...");
- DLog(@"%@", [user description]);
- [self logout];
- return NO;
- }
-
- //check to see if the uid returned is the same as our existing session
- if ([[[user rootElement] stringValue] isEqualToString:[session uid]] ) {
- [self userLoginSuccessful];
- return YES;
- }
-
- }
- return NO;
-}
-
-
-
-
- (BOOL)userLoggedIn
{
return [[MKFacebookSession sharedMKFacebookSession] validSession];
@@ -186,28 +159,32 @@ - (void)userLoginSuccessful
- (void)grantExtendedPermission:(NSString *)aString
{
- if([self userLoggedIn] == NO)
- {
- if(_displayLoginAlerts == YES)
- {
- MKErrorWindow *errorWindow = [MKErrorWindow errorWindowWithTitle:@"No user logged in!" message:@"Permissions cannot be extended if no one is logged in." details:nil];
- [errorWindow display];
- }
- return;
- }
+// if([self userLoggedIn] == NO)
+// {
+// if(_displayLoginAlerts == YES)
+// {
+// MKErrorWindow *errorWindow = [MKErrorWindow errorWindowWithTitle:@"No user logged in!" message:@"Permissions cannot be extended if no one is logged in." details:nil];
+// [errorWindow display];
+// }
+// return;
+// }
+//
+// loginWindow = [[MKLoginWindow alloc] init]; //will be released when closed
+// [[loginWindow window] setTitle:@"Extended Permissions"];
+// [loginWindow showWindow:self];
+// //[loginWindow setWindowSize:NSMakeSize(GRANT_PERMISSIONS_WINDOW_WIDTH, GRANT_PERMISSIONS_WINDOW_HEIGHT)];
+//
+// NSURL *url = [NSURL URLWithString:[NSString stringWithFormat:@"%@?api_key=%@&v=%@&ext_perm=%@&popup", MKExtendPermissionsURL, [[MKFacebookSession sharedMKFacebookSession] apiKey], MKFacebookAPIVersion, aString]];
+// [loginWindow loadURL:url];
- loginWindow = [[MKLoginWindow alloc] init]; //will be released when closed
- [[loginWindow window] setTitle:@"Extended Permissions"];
- [loginWindow showWindow:self];
- //[loginWindow setWindowSize:NSMakeSize(GRANT_PERMISSIONS_WINDOW_WIDTH, GRANT_PERMISSIONS_WINDOW_HEIGHT)];
- NSURL *url = [NSURL URLWithString:[NSString stringWithFormat:@"http://www.facebook.com/authorize.php?api_key=%@&v=%@&ext_perm=%@&popup", [[MKFacebookSession sharedMKFacebookSession] apiKey], MKFacebookAPIVersion, aString]];
- [loginWindow loadURL:url];
+ [self grantExtendedPermission:aString forSheet:NO];
+
}
-- (NSWindow *)grantExtendedPermissionForSheet:(NSString *)aString
+- (NSWindow *)grantExtendedPermission:(NSString *)aString forSheet:(BOOL)forSheet
{
if([self userLoggedIn] == NO)
{
@@ -220,14 +197,24 @@ - (NSWindow *)grantExtendedPermissionForSheet:(NSString *)aString
}
loginWindow = [[MKLoginWindow alloc] init];
- loginWindow._loginWindowIsSheet = YES;
- //[loginWindow setWindowSize:NSMakeSize(GRANT_PERMISSIONS_WINDOW_WIDTH, GRANT_PERMISSIONS_WINDOW_HEIGHT)];
- NSURL *url = [NSURL URLWithString:[NSString stringWithFormat:@"http://www.facebook.com/authorize.php?api_key=%@&v=%@&ext_perm=%@&popup", [[MKFacebookSession sharedMKFacebookSession] apiKey], MKFacebookAPIVersion, aString]];
[[loginWindow window] setTitle:@"Extended Permissions"];
- [loginWindow loadURL:url];
+ loginWindow._loginWindowIsSheet = forSheet;
- return [loginWindow window];
+ NSURL *url = [NSURL URLWithString:[NSString stringWithFormat:@"%@?api_key=%@&v=%@&ext_perm=%@&display=popup&fbconnect=true&http://www.facebook.com/connect/login_success.html?xxRESULTTOKENxx", MKExtendPermissionsURL, [[MKFacebookSession sharedMKFacebookSession] apiKey], MKFacebookAPIVersion, aString]];
+
+ [loginWindow loadURL:url];
+
+ if (forSheet == YES) {
+
+ return [loginWindow window];
+ }else {
+ [[loginWindow window] center];
+ [loginWindow showWindow:self];
+ return nil;
+ }
+
+ return nil;
}
View
10 MKFacebookSession.h
@@ -29,6 +29,7 @@ extern NSString *MKFacebookSessionKey;
NSDictionary *session;
NSString *apiKey;
NSString *secretKey;
+ BOOL _validSession;
}
@@ -42,10 +43,17 @@ extern NSString *MKFacebookSessionKey;
- (void)saveSession:(NSDictionary *)aSession;
-// Loads any saved session from application defaults. Returns false if no session could be loaded.
+/*
+Logs in a user from a saved session.
+
+Attempts to load a stored infinte session for the application. This method checks NSUserDefaults for a stored sessionKey and sessionSecret. It uses a synchronous request to try to authenticate the stored session. Used internally when login or loginWithPermissions:forSheet: are called.
+
+Returns true if stored session information is valid and a user id is successfully returned from Facebook otherwise it returns false.
+*/
- (BOOL)loadSession;
+
// Destroys any saved session.
- (void)destroySession;
View
45 MKFacebookSession.m
@@ -19,6 +19,9 @@
*/
#import "MKFacebookSession.h"
+#import "MKFacebookRequest.h"
+#import "NSXMLDocumentAdditions.h"
+#import "NSXMLElementAdditions.h"
NSString *MKFacebookSessionKey = @"MKFacebookSession";
@@ -47,33 +50,61 @@ - (void)saveSession:(NSDictionary *)aSession{
NSUserDefaults *defaults = [NSUserDefaults standardUserDefaults];
[defaults setObject:aSession forKey:MKFacebookSessionKey];
self.session = aSession;
+ _validSession = YES;
}
}
-- (BOOL)loadSession{
+
+- (BOOL)loadSession
+{
NSUserDefaults *defaults = [NSUserDefaults standardUserDefaults];
NSDictionary *savedSession = [defaults objectForKey:MKFacebookSessionKey];
- //TODO: check for valid session before returning yes
+ //TODO: use asynchronous request instead of synchronous
if(savedSession != nil)
{
+
self.session = savedSession;
- return YES;
- }else {
- self.session = nil;
- return NO;
+
+ MKFacebookRequest *request = [[MKFacebookRequest alloc] init];
+
+ NSXMLDocument *user = [request fetchFacebookData:[request generateFacebookURL:[NSDictionary dictionaryWithObjectsAndKeys:@"facebook.users.getLoggedInUser", @"method", nil]]];
+ [request release];
+
+ if([user validFacebookResponse] == NO)
+ {
+ DLog(@"persistent login failed, here's why...");
+ DLog(@"%@", [user description]);
+ return NO;
+ }
+
+ //check to see if the uid returned is the same as our existing session
+ if ([[[user rootElement] stringValue] isEqualToString:[self uid]] ) {
+ _validSession = YES;
+ return YES;
+ }else {
+ self.session = nil;
+ return NO;
+ }
}
+ return NO;
}
+
+//TODO: verify session by sending a request to Facebook using session information
- (BOOL)validSession{
if([[NSUserDefaults standardUserDefaults] objectForKey:MKFacebookSessionKey] != nil)
- return YES;
+ {
+ return _validSession;
+ }
+
return NO;
}
- (void)destroySession{
DLog(@"session was destroyed");
[[NSUserDefaults standardUserDefaults] removeObjectForKey:MKFacebookSessionKey];
self.session = nil;
+ _validSession = NO;
}
- (NSString *)sessionKey{
View
16 MKPhotosRequest.h
@@ -28,7 +28,7 @@ typedef enum{
} MKPhotosFacebookMethod;
-/*!
+/*
@brief Convenience for photo related requests.
@class MKPhotosRequest
@@ -44,46 +44,46 @@ typedef enum{
}
#pragma mark MKFacebookProtocol Requirements
-/*!
+/*
@version 0.8 and later
*/
+(id)requestUsingFacebookConnection:(MKFacebook *)facebookConnection delegate:(id)delegate;
-/*!
+/*
@version 0.8 and later
*/
-(id)initWithFacebookConnection:(MKFacebook *)facebookConnection delegate:(id)delegate;
#pragma mark Supported Methods
-/*!
+/*
@version 0.8 and later
*/
-(void)photosGet:(NSArray *)pids aid:(NSString *)aid subjId:(NSString *)subj_id;
-/*!
+/*
@version 0.8 and later
*/
-(void)photosGet:(NSString *)aid;
-/*!
+/*
@version 0.8 and later
*/
-(void)photosGetTags:(NSArray *)pids;
//UPLOADING METHODS
-/*!
+/*
@version 0.8 and later
*/
-(void)photosUpload:(NSImage *)photo aid:(NSString *)aid caption:(NSString *)caption;
-/*!
+/*
@version 0.8 and later
*/

0 comments on commit 9ef143c

Please sign in to comment.