forked from facebook/facebook-ios-sdk
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Header spec for FBSession + POR for next rev iOS SDK
Summary: This diff contains a header-spec for FBSession, as well as a header and POR for the next rev of the sdk Test Plan: n/a Reviewers: mmarucheck, vijaye, gregschechte, ekoneil Reviewed By: vijaye Differential Revision: https://phabricator.fb.com/D424291
- Loading branch information
Showing
2 changed files
with
254 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,153 @@ | ||
/* | ||
* Copyright 2012 Facebook | ||
* | ||
* Licensed under the Apache License, Version 2.0 (the "License"); | ||
* you may not use this file except in compliance with the License. | ||
* You may obtain a copy of the License at | ||
* | ||
* http://www.apache.org/licenses/LICENSE-2.0 | ||
* | ||
* Unless required by applicable law or agreed to in writing, software | ||
* distributed under the License is distributed on an "AS IS" BASIS, | ||
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | ||
* See the License for the specific language governing permissions and | ||
* limitations under the License. | ||
*/ | ||
|
||
#import <Foundation/Foundation.h> | ||
|
||
// up-front decl's | ||
@class FBSession; | ||
@class FBSessionTokenCachingStrategy; | ||
|
||
// FBSessionStatus enum | ||
// | ||
// Summary: | ||
// Passed to handler block when a login call has completed | ||
typedef enum _FBSessionStatus { | ||
// initial pre-valid invalid state | ||
FBSessionStatusInitial = 0, | ||
|
||
// valid session status values | ||
FBSessionStatusLoggedIn = 1001, | ||
FBSessionStatusTokenExtended = 1002, | ||
FBSessionStatusValidCachedToken = 1003, | ||
|
||
// invalid session status values | ||
FBSessionStatusLoggedOut = 1, | ||
FBSessionStatusLoginFailed = 2, // NSError obj w/more info | ||
FBSessionStatusSessionInvalidated = 3, // " | ||
|
||
} FBSessionStatus; | ||
|
||
typedef void (^FBSessionStatusCallback)(FBSession *session, | ||
FBSessionStatus status, | ||
NSError *error); | ||
|
||
// FBSession class | ||
// | ||
// Summary: | ||
// FBSession object is used to authenticate/authorize a user, as well | ||
// as to manage the related access token. An FBSession object is required | ||
// for all authenticated uses of FBRequest. | ||
// | ||
// Behavior notes: | ||
// Instances of the FBSession class notifiy of state changes in these ways; | ||
// a) callers of certain session* methods may provide a block to be called | ||
// back in the course of processing the single operation (e.g. login) | ||
// b) session instances post the "FBSessionLogin" and "FBSessionInvalid" | ||
// notifications, which may be observed via NSNotificationCenter | ||
// c) the object supports KVO for property changes | ||
@interface FBSession : NSObject | ||
|
||
// creating a session | ||
|
||
// session/sessionWithPermissions returns a session instance | ||
// | ||
// Summary: | ||
// The simplest factory method requires only an appId to initiate a session with | ||
// Facebook. Following are the descriptions of the arguments along with | ||
// their defaults when ommitted. | ||
// permissions: - array of strings naming permissions to authorize; a | ||
// nil value indicates access to basic information; | ||
// default=nil | ||
// appId: - returns a session object for the given app id; nil | ||
// specifies that the appId should be pulled from the | ||
// plist; default=nil | ||
// urlSchemeSuffix: - suffix, used for cases where multiple iOS apps use | ||
// a single appid; nil indicates the urlSchemeSuffix | ||
// should be pulled from plist; default=nil | ||
// tokenCachingStrategy: - policy object for fetching and storing a cached | ||
// token value; when nil, the token and expiration date | ||
// are stored using NSUserDefaults with the names | ||
// "FBAccessTokenKey", and "FBExpirationDateKey"; | ||
// default=nil | ||
// | ||
// Behavior notes: For a first cut at this, we are removing the public ability | ||
// to force an extension to an access token; instead we will implicitly do this | ||
// when requests are made. | ||
- (id)init; | ||
|
||
- (id)initWithPermissions:(NSArray*)permissions; | ||
|
||
- (id)initWithAppID:(NSString*)appID | ||
permissions:(NSArray*)permissions | ||
urlSchemeSuffix:(NSString*)urlSchemeSuffix | ||
tokenCacheStrategy:(FBSessionTokenCachingStrategy*)tokenCachingStrategy; | ||
|
||
// instance readonly properties | ||
@property(readonly) BOOL isValid; | ||
@property(readonly) FBSessionStatus status; | ||
@property(nonatomic, readonly) NSString *appID; | ||
@property(nonatomic, readonly) NSString *urlSchemeSuffix; | ||
@property(retain, readonly) NSString *accessToken; | ||
@property(retain, readonly) NSDate *expirationDate; | ||
@property(copy, readonly) NSArray *permissions; | ||
|
||
// instance methods | ||
|
||
// loginWithCompletionBlock logs a user on to Facebook | ||
// | ||
// Summary: | ||
// Login using Facebook | ||
// WithCompletionBlock - a block to call with the login result; default=nil | ||
- (void)loginWithCompletionBlock:(FBSessionStatusCallback)handler; | ||
|
||
// invalidate | ||
// | ||
// Summary: | ||
// Invalidates the local session object | ||
- (void)invalidate; | ||
|
||
// logout | ||
// | ||
// Summary: | ||
// Logout invalidates the in-memory session, and clears any persisted cache | ||
- (void)logout; | ||
|
||
// handleOpenURL | ||
// | ||
// Summary: | ||
// Helper method, used to provide an implementation for | ||
// [UIApplicationDelegate application:openUrl:*] capable of updating a session | ||
// based on the url | ||
- (BOOL)handleOpenURL:(NSURL*)url; | ||
|
||
@end | ||
|
||
// FBSessionTokenCachingStrategy | ||
// | ||
// Summary: | ||
// Implementors execute token and expiration-date caching and fetching logic | ||
// for a Facebook integrated application | ||
@interface FBSessionTokenCachingStrategy : NSObject | ||
|
||
+ (id)init; | ||
+ (id)initWithNSUserDefaultAccessTokenKeyName:(NSString*)tokenKeyName | ||
expirationDateKeyName:(NSString*)dateKeyName; | ||
|
||
- (void)cacheToken:(NSString*)token expirationDate:(NSDate*)date; | ||
- (NSString*)fetchTokenAndExpirationDate:(NSDate**)date; | ||
- (void)clearToken:(NSString*)token; | ||
|
||
@end |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,101 @@ | ||
/* | ||
* Copyright 2012 Facebook | ||
* | ||
* Licensed under the Apache License, Version 2.0 (the "License"); | ||
* you may not use this file except in compliance with the License. | ||
* You may obtain a copy of the License at | ||
* | ||
* http://www.apache.org/licenses/LICENSE-2.0 | ||
* | ||
* Unless required by applicable law or agreed to in writing, software | ||
* distributed under the License is distributed on an "AS IS" BASIS, | ||
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | ||
* See the License for the specific language governing permissions and | ||
* limitations under the License. | ||
*/ | ||
|
||
#import "FBSession.h" | ||
|
||
//////////////////////////////////////////////////////////////////////////////// | ||
|
||
/* | ||
Summary: this diff summarizes changes to the Facebook iOS SDK that we are | ||
considering for the next few months. This is a header-only diff, and is not | ||
a complete description of our thinking, but is meant to provide context | ||
sufficient for review by others. | ||
Files: | ||
FacebookSDK.h - this file, high-level description of the effort and goals | ||
FBSession.h - example spec for FBSession class | ||
Goals: | ||
* Leverage and work well with modern features of iOS (e.g. blocks, ARC, etc.) | ||
* Patterned after best of breed iOS frameworks (e.g. naming, pattern-use, etc.) | ||
* Light and/or commodity integration experience is painless & easy to describe | ||
* Deep support for at least one "key scenario" (e.g. publishing OG app) | ||
Notes on approaches: | ||
1) We are using our key scenario (owned by Eddie O'Neil) to drive | ||
prioritization of work | ||
2) We will be building-atop/refactoring the existing iOS SDK implementation | ||
3) We have prototyped an incremental approach where we can choose to maintain | ||
as little or as much compatibility with the existing SDK needed | ||
3.a) and so we will be developing to this approach | ||
3.b) and then at push-time we will decide when/what to break on a | ||
feature by feature basis | ||
4) Some light but critical infrastructure is needed to support both the goals | ||
and the execution of this change (e.g. a build/package/deploy process) | ||
Design points: | ||
We will move to a more object-oriented approach, in order to facilitate the | ||
addition of a different class of objects, such as controls and visual helpers | ||
(e.g. FBLikeView, FBPersonView), as well as sub-frameworks to enable scenarios | ||
such (e.g. FBOpenGraphEntity, FBLocalEntityCache, etc.) | ||
As we add features, it will no longer be appropriate to host all functionality | ||
in the Facebook class. We may (presently undecided) keep the Facebook class to | ||
aid the ultra-simple use cases, and to perhaps preserve compatibility with the | ||
existing SDK. However, it will cease to be the central design point of the | ||
and will become a lighter-weight helper class, that wraps other public objects. | ||
*------------* *----------* *----------------* *---* | ||
Scenario --> |FBPersonView| |FBLikeView| |FBLocationFinder| | F | | ||
*------------* *----------* *----------------* | a | | ||
*-------------------* *----------* *--------* | c | | ||
Component --> | FBOpenGraphEntity | | FBDialog | | FBView | | e | | ||
*-------------------* *----------* *--------* | b | | ||
*---------* *---------* *---------------------* | o | | ||
Core --> |FBSession| |FBRequest| |Utilities (e.g. JSON)| | o | | ||
*---------* *---------* *---------------------* * k * | ||
The figure above describes three layers of functionality, with the existing | ||
Facebook on the side as a helper proxy to a subset of the overal SDK. The | ||
layers loosely organize the SDK into *Core Objects* necessary to interface | ||
with Facebook, higher-level *Framework Components* that feel like natural | ||
extensions to existing frameworks such as UIKit and Foundation, but which | ||
reuse surface broadly applicable Facebook-specific behavior, and finally the | ||
*Scenario Objects*, which provide deeper turnkey capibilities for useful | ||
mobile scenarios. | ||
Use example (low barrier use case): | ||
// log on to Facebook | ||
_fbsession = [[FBSession alloc] init]; | ||
[_fbsession loginWithCompletionBlock:^(FBSession *session, | ||
FBSessionStatus status, | ||
NSError *error) { | ||
if (session.isValid) { | ||
// request basic information for the user | ||
[FBRequest requestWithGraphPath:@"me" | ||
forSession:session | ||
completeResultToBlock:^void(FBRequest *request, | ||
FBRequestStatus status, | ||
id result) { | ||
if (status == FBRequestStatusSuccess) { | ||
// get json from result | ||
} | ||
}]; | ||
} | ||
}]; | ||
*/ |