forked from facebook/facebook-ios-sdk
-
Notifications
You must be signed in to change notification settings - Fork 0
/
FBSession.h
618 lines (494 loc) · 28.8 KB
/
FBSession.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
/*
* 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;
#define FB_SESSIONSTATETERMINALBIT (1 << 8)
#define FB_SESSIONSTATEOPENBIT (1 << 9)
/*
* Constants used by NSNotificationCenter for active session notification
*/
/*! NSNotificationCenter name indicating that a new active session was set */
extern NSString *const FBSessionDidSetActiveSessionNotification;
/*! NSNotificationCenter name indicating that an active session was unset */
extern NSString *const FBSessionDidUnsetActiveSessionNotification;
/*! NSNotificationCenter name indicating that the active session is open */
extern NSString *const FBSessionDidBecomeOpenActiveSessionNotification;
/*! NSNotificationCenter name indicating that there is no longer an open active session */
extern NSString *const FBSessionDidBecomeClosedActiveSessionNotification;
/*!
@typedef FBSessionState enum
@abstract Passed to handler block each time a session state changes
@discussion
*/
typedef enum {
/*! One of two initial states indicating that no valid cached token was found */
FBSessionStateCreated = 0,
/*! One of two initial session states indicating that a cached token was loaded;
when a session is in this state, a call to open* will result in an open session,
without UX or app-switching*/
FBSessionStateCreatedTokenLoaded = 1,
/*! One of three pre-open session states indicating that an attempt to open the session
is underway*/
FBSessionStateCreatedOpening = 2,
/*! Open session state indicating user has logged in or a cached token is available */
FBSessionStateOpen = 1 | FB_SESSIONSTATEOPENBIT,
/*! Open session state indicating token has been extended */
FBSessionStateOpenTokenExtended = 2 | FB_SESSIONSTATEOPENBIT,
/*! Closed session state indicating that a login attempt failed */
FBSessionStateClosedLoginFailed = 1 | FB_SESSIONSTATETERMINALBIT, // NSError obj w/more info
/*! Closed session state indicating that the session was closed, but the users token
remains cached on the device for later use */
FBSessionStateClosed = 2 | FB_SESSIONSTATETERMINALBIT, // "
} FBSessionState;
/*! helper macro to test for states that imply an open session */
#define FB_ISSESSIONOPENWITHSTATE(state) (0 != (state & FB_SESSIONSTATEOPENBIT))
/*! helper macro to test for states that are terminal */
#define FB_ISSESSIONSTATETERMINAL(state) (0 != (state & FB_SESSIONSTATETERMINALBIT))
/*!
@typedef FBSessionLoginBehavior enum
@abstract
Passed to open to indicate whether Facebook Login should allow for fallback to be attempted.
@discussion
Facebook Login authorizes the application to act on behalf of the user, using the user's
Facebook account. Usually a Facebook Login will rely on an account maintained outside of
the application, by the native Facebook application, the browser, or perhaps the device
itself. This avoids the need for a user to enter their username and password directly, and
provides the most secure and lowest friction way for a user to authorize the application to
interact with Facebook. If a Facebook Login is not possible, a fallback Facebook Login may be
attempted, where the user is prompted to enter their credentials in a web-view hosted directly
by the application.
The `FBSessionLoginBehavior` enum specifies whether to allow fallback, disallow fallback, or
force fallback login behavior. Most applications will use the default, which attempts a normal
Facebook Login, and only falls back if needed. In rare cases, it may be preferable to disalow
fallback Facebook Login completely, or to force a fallback login.
*/
typedef enum {
/*! Attempt Facebook Login, ask user for credentials if necessary */
FBSessionLoginBehaviorWithFallbackToWebView = 0,
/*! Attempt Facebook Login, no direct request for credentials will be made */
FBSessionLoginBehaviorWithNoFallbackToWebView = 1,
/*! Only attempt WebView Login; ask user for credentials */
FBSessionLoginBehaviorForcingWebView = 2,
/*! Attempt Facebook Login, prefering system account and falling back to fast app switch if necessary */
FBSessionLoginBehaviorUseSystemAccountIfPresent = 3,
} FBSessionLoginBehavior;
/*!
@typedef FBSessionDefaultAudience enum
@abstract
Passed to open to indicate which default audience to use for sessions that post data to Facebook.
@discussion
Certain operations such as publishing a status or publishing a photo require an audience. When the user
grants an application permission to perform a publish operation, a default audience is selected as the
publication ceiling for the application. This enumerated value allows the application to select which
audience to ask the user to grant publish permission for.
*/
typedef enum {
/*! No audience needed; this value is useful for cases where data will only be read from Facebook */
FBSessionDefaultAudienceNone = 0,
/*! Indicates that only the user is able to see posts made by the application */
FBSessionDefaultAudienceOnlyMe = 10,
/*! Indicates that the user's friends are able to see posts made by the application */
FBSessionDefaultAudienceFriends = 20,
/*! Indicates that all Facebook users are able to see posts made by the application */
FBSessionDefaultAudienceEveryone = 30,
} FBSessionDefaultAudience;
/*!
@typedef FBSessionLoginType enum
@abstract
Used as the type of the loginType property in order to specify what underlying technology was used to
login the user.
@discussion
The FBSession object is an abstraction over five distinct mechanisms. This enum allows an application
to test for the mechanism used by a particular instance of FBSession. Usually the mechanism used for a
given login does not matter, however for certain capabilities, the type of login can impact the behavior
of other Facebook functionality.
*/
typedef enum {
/*! A login type has not yet been established */
FBSessionLoginTypeNone = 0,
/*! A system integrated account was used to log the user into the application */
FBSessionLoginTypeSystemAccount = 1,
/*! The Facebook native application was used to log the user into the application */
FBSessionLoginTypeFacebookApplication = 2,
/*! Safari was used to log the user into the application */
FBSessionLoginTypeFacebookViaSafari = 3,
/*! A web view was used to log the user into the application */
FBSessionLoginTypeWebView = 4,
/*! A test user was used to create an open session */
FBSessionLoginTypeTestUser = 5,
} FBSessionLoginType;
/*!
@typedef
@abstract Block type used to define blocks called by <FBSession> for state updates
@discussion
*/
typedef void (^FBSessionStateHandler)(FBSession *session,
FBSessionState status,
NSError *error);
/*!
@typedef
@abstract Block type used to define blocks called by <[FBSession reauthorizeWithPermissions]>/.
@discussion
*/
typedef void (^FBSessionReauthorizeResultHandler)(FBSession *session,
NSError *error);
/*!
@class FBSession
@abstract
The `FBSession` object is used to authenticate a user and manage the user's session. After
initializing a `FBSession` object the Facebook App ID and desired permissions are stored.
Opening the session will initiate the authentication flow after which a valid user session
should be available and subsequently cached. Closing the session can optionally clear the
cache.
If an <FBRequest> request requires user authorization then an `FBSession` object should be used.
@discussion
Instances of the `FBSession` class provide notification of state changes in the following ways:
1. Callers of certain `FBSession` methods may provide a block that will be called
back in the course of state transitions for the session (e.g. login or session closed).
2. The object supports Key-Value Observing (KVO) for property changes.
*/
@interface FBSession : NSObject
/*!
@methodgroup Creating a session
*/
/*!
@method
@abstract
Returns a newly initialized Facebook session with default values for the parameters
to <initWithAppID:permissions:urlSchemeSuffix:tokenCacheStrategy:>.
*/
- (id)init;
/*!
@method
@abstract
Returns a newly initialized Facebook session with the specified permissions and other
default values for parameters to <initWithAppID:permissions:urlSchemeSuffix:tokenCacheStrategy:>.
@param permissions An array of strings representing the permissions to request during the
authentication flow. A value of nil indicates basic permissions. The default is nil.
@discussion
It is required that any single permission request request (including initial log in) represent read-only permissions
or publish permissions only; not both. The permissions passed here should reflect this requirement.
*/
- (id)initWithPermissions:(NSArray*)permissions;
/*!
@method
@abstract
Following are the descriptions of the arguments along with their
defaults when ommitted.
@param permissions An array of strings representing the permissions to request during the
authentication flow. A value of nil indicates basic permissions. The default is nil.
@param appID The Facebook App ID for the session. If nil is passed in the default App ID will be obtained from a call to <[FBSession defaultAppID]>. The default is nil.
@param urlSchemeSuffix The URL Scheme Suffix to be used in scenarious where multiple iOS apps use one Facebook App ID. A value of nil indicates that this information should be pulled from the plist. The default is nil.
@param tokenCachingStrategy Specifies a key name to use for cached token information in NSUserDefaults, nil
indicates a default value of @"FBAccessTokenInformationKey".
@discussion
It is required that any single permission request request (including initial log in) represent read-only permissions
or publish permissions only; not both. The permissions passed here should reflect this requirement.
*/
- (id)initWithAppID:(NSString*)appID
permissions:(NSArray*)permissions
urlSchemeSuffix:(NSString*)urlSchemeSuffix
tokenCacheStrategy:(FBSessionTokenCachingStrategy*)tokenCachingStrategy;
/*!
@method
@abstract
Following are the descriptions of the arguments along with their
defaults when ommitted.
@param permissions An array of strings representing the permissions to request during the
authentication flow. A value of nil indicates basic permissions. The default is nil.
@param defaultAudience Most applications use FBSessionDefaultAudienceNone here, only specifying an audience when using reauthorize to request publish permissions.
@param appID The Facebook App ID for the session. If nil is passed in the default App ID will be obtained from a call to <[FBSession defaultAppID]>. The default is nil.
@param urlSchemeSuffix The URL Scheme Suffix to be used in scenarious where multiple iOS apps use one Facebook App ID. A value of nil indicates that this information should be pulled from the plist. The default is nil.
@param tokenCachingStrategy Specifies a key name to use for cached token information in NSUserDefaults, nil
indicates a default value of @"FBAccessTokenInformationKey".
@discussion
It is required that any single permission request request (including initial log in) represent read-only permissions
or publish permissions only; not both. The permissions passed here should reflect this requirement. If publish permissions
are used, then the audience must also be specified.
*/
- (id)initWithAppID:(NSString*)appID
permissions:(NSArray*)permissions
defaultAudience:(FBSessionDefaultAudience)defaultAudience
urlSchemeSuffix:(NSString*)urlSchemeSuffix
tokenCacheStrategy:(FBSessionTokenCachingStrategy*)tokenCachingStrategy;
// instance readonly properties
/*! @abstract Indicates whether the session is open and ready for use. */
@property(readonly) BOOL isOpen;
/*! @abstract Detailed session state */
@property(readonly) FBSessionState state;
/*! @abstract Identifies the Facebook app which the session object represents. */
@property(readonly, copy) NSString *appID;
/*! @abstract Identifies the URL Scheme Suffix used by the session. This is used when multiple iOS apps share a single Facebook app ID. */
@property(readonly, copy) NSString *urlSchemeSuffix;
/*! @abstract The access token for the session object. */
@property(readonly, copy) NSString *accessToken;
/*! @abstract The expiration date of the access token for the session object. */
@property(readonly, copy) NSDate *expirationDate;
/*! @abstract The permissions granted to the access token during the authentication flow. */
@property(readonly, copy) NSArray *permissions;
/*! @abstract Specifies the login type used to authenticate the user. */
@property(readonly) FBSessionLoginType loginType;
/*!
@methodgroup Instance methods
*/
/*!
@method
@abstract Opens a session for the Facebook.
@discussion
A session may not be used with <FBRequest> and other classes in the SDK until it is open. If, prior
to calling open, the session is in the <FBSessionStateCreatedTokenLoaded> state, then no UX occurs, and
the session becomes available for use. If the session is in the <FBSessionStateCreated> state, prior
to calling open, then a call to open causes login UX to occur, either via the Facebook application
or via mobile Safari.
Open may be called at most once and must be called after the `FBSession` is initialized. Open must
be called before the session is closed. Calling an open method at an invalid time will result in
an exception. The open session methods may be passed a block that will be called back when the session
state changes. The block will be released when the session is closed.
@param handler A block to call with the state changes. The default is nil.
*/
- (void)openWithCompletionHandler:(FBSessionStateHandler)handler;
/*!
@method
@abstract Logs a user on to Facebook.
@discussion
A session may not be used with <FBRequest> and other classes in the SDK until it is open. If, prior
to calling open, the session is in the <FBSessionStateCreatedTokenLoaded> state, then no UX occurs, and
the session becomes available for use. If the session is in the <FBSessionStateCreated> state, prior
to calling open, then a call to open causes login UX to occur, either via the Facebook application
or via mobile Safari.
The method may be called at most once and must be called after the `FBSession` is initialized. It must
be called before the session is closed. Calling the method at an invalid time will result in
an exception. The open session methods may be passed a block that will be called back when the session
state changes. The block will be released when the session is closed.
@param behavior Controls whether to allow, force, or prohibit Facebook Login or Inline Facebook Login. The default
is to allow Facebook Login, with fallback to Inline Facebook Login.
@param handler A block to call with session state changes. The default is nil.
*/
- (void)openWithBehavior:(FBSessionLoginBehavior)behavior
completionHandler:(FBSessionStateHandler)handler;
/*!
@abstract
Closes the local in-memory session object, but does not clear the persisted token cache.
*/
- (void)close;
/*!
@abstract
Closes the in-memory session, and clears any persisted cache related to the session.
*/
- (void)closeAndClearTokenInformation;
/*!
@abstract
Reauthorizes the session, with additional permissions.
@param permissions An array of strings representing the permissions to request during the
authentication flow. A value of nil indicates basic permissions. The default is nil.
@param behavior Controls whether to allow, force, or prohibit Facebook Login. The default
is to allow Facebook Login and fall back to Inline Facebook Login if needed.
@param handler A block to call with session state changes. The default is nil.
@discussion Methods and properties that specify permissions without a read or publish
qualification are deprecated; use of a read-qualified or publish-qualified alternative is preferred
(e.g. reauthorizeWithReadPermissions or reauthorizeWithPublishPermissions)
*/
- (void)reauthorizeWithPermissions:(NSArray*)permissions
behavior:(FBSessionLoginBehavior)behavior
completionHandler:(FBSessionReauthorizeResultHandler)handler
__attribute__((deprecated));
/*!
@abstract
Reauthorizes the session, with additional permissions.
@param readPermissions An array of strings representing the permissions to request during the
authentication flow. A value of nil indicates basic permissions.
@param handler A block to call with session state changes. The default is nil.
*/
- (void)reauthorizeWithReadPermissions:(NSArray*)readPermissions
completionHandler:(FBSessionReauthorizeResultHandler)handler;
/*!
@abstract
Reauthorizes the session, with additional permissions.
@param writePermissions An array of strings representing the permissions to request during the
authentication flow.
@param defaultAudience Specifies the audience for posts.
@param handler A block to call with session state changes. The default is nil.
*/
- (void)reauthorizeWithPublishPermissions:(NSArray*)writePermissions
defaultAudience:(FBSessionDefaultAudience)defaultAudience
completionHandler:(FBSessionReauthorizeResultHandler)handler;
/*!
@abstract
A helper method that is used to provide an implementation for
[UIApplicationDelegate application:openURL:sourceApplication:annotation:]. It should be invoked during
the Facebook Login flow and will update the session information based on the incoming URL.
@param url The URL as passed to [UIApplicationDelegate application:openURL:sourceApplication:annotation:].
*/
- (BOOL)handleOpenURL:(NSURL*)url;
/*!
@abstract
A helper method that is used to provide an implementation for
[UIApplicationDelegate applicationDidBecomeActive:] to properly resolve session state for
the Facebook Login flow, specifically to support app-switch login.
*/
- (void)handleDidBecomeActive;
/*!
@methodgroup Class methods
*/
/*!
@abstract
This is the simplest method for opening a session with Facebook. Using sessionOpen logs on a user,
and sets the static activeSession which becomes the default session object for any Facebook UI widgets
used by the application. This session becomes the active session, whether open succeeds or fails.
Note, if there is not a cached token available, this method will present UI to the user in order to
open the session via explicit login by the user.
@param allowLoginUI Sometimes it is useful to attempt to open a session, but only if
no login UI will be required to accomplish the operation. For example, at application startup it may not
be disirable to transition to login UI for the user, and yet an open session is desired so long as a cached
token can be used to open the session. Passing NO to this argument, assures the method will not present UI
to the user in order to open the session.
@discussion
Returns YES if the session was opened synchronously without presenting UI to the user. This occurs
when there is a cached token available from a previous run of the application. If NO is returned, this indicates
that the session was not immediately opened, via cache. However, if YES was passed as allowLoginUI, then it is
possible that the user will login, and the session will become open asynchronously. The primary use for
this return value is to switch-on facebook capabilities in your UX upon startup, in the case were the session
is opened via cache.
*/
+ (BOOL)openActiveSessionWithAllowLoginUI:(BOOL)allowLoginUI;
/*!
@abstract
This is a simple method for opening a session with Facebook. Using sessionOpen logs on a user,
and sets the static activeSession which becomes the default session object for any Facebook UI widgets
used by the application. This session becomes the active session, whether open succeeds or fails.
@param permissions An array of strings representing the permissions to request during the
authentication flow. A value of nil indicates basic permissions. A nil value specifies
default permissions.
@param allowLoginUI Sometimes it is useful to attempt to open a session, but only if
no login UI will be required to accomplish the operation. For example, at application startup it may not
be desirable to transition to login UI for the user, and yet an open session is desired so long as a cached
token can be used to open the session. Passing NO to this argument, assures the method will not present UI
to the user in order to open the session.
@param handler Many applications will benefit from notification when a session becomes invalid
or undergoes other state transitions. If a block is provided, the FBSession
object will call the block each time the session changes state.
@discussion
Returns true if the session was opened synchronously without presenting UI to the user. This occurs
when there is a cached token available from a previous run of the application. If NO is returned, this indicates
that the session was not immediately opened, via cache. However, if YES was passed as allowLoginUI, then it is
possible that the user will login, and the session will become open asynchronously. The primary use for
this return value is to switch-on facebook capabilities in your UX upon startup, in the case were the session
is opened via cache.
It is required that initial permissions requests represent read-only permissions only. If publish
permissions are needed, you may use reauthorizeWithPermissions to specify additional permissions as
well as an audience. Use of this method will result in a legacy fast-app-switch Facebook Login due to
the requirement to seperate read and publish permissions for newer applications. Methods and properties
that specify permissions without a read or publish qualification are deprecated; use of a read-qualified
or publish-qualified alternative is preferred.
*/
+ (BOOL)openActiveSessionWithPermissions:(NSArray*)permissions
allowLoginUI:(BOOL)allowLoginUI
completionHandler:(FBSessionStateHandler)handler
__attribute__((deprecated));
/*!
@abstract
This is a simple method for opening a session with Facebook. Using sessionOpen logs on a user,
and sets the static activeSession which becomes the default session object for any Facebook UI widgets
used by the application. This session becomes the active session, whether open succeeds or fails.
@param readPermissions An array of strings representing the read permissions to request during the
authentication flow. A value of nil indicates basic permissions. It is not allowed to pass publish
permissions to this method.
@param allowLoginUI Sometimes it is useful to attempt to open a session, but only if
no login UI will be required to accomplish the operation. For example, at application startup it may not
be desirable to transition to login UI for the user, and yet an open session is desired so long as a cached
token can be used to open the session. Passing NO to this argument, assures the method will not present UI
to the user in order to open the session.
@param handler Many applications will benefit from notification when a session becomes invalid
or undergoes other state transitions. If a block is provided, the FBSession
object will call the block each time the session changes state.
@discussion
Returns true if the session was opened synchronously without presenting UI to the user. This occurs
when there is a cached token available from a previous run of the application. If NO is returned, this indicates
that the session was not immediately opened, via cache. However, if YES was passed as allowLoginUI, then it is
possible that the user will login, and the session will become open asynchronously. The primary use for
this return value is to switch-on facebook capabilities in your UX upon startup, in the case were the session
is opened via cache.
*/
+ (BOOL)openActiveSessionWithReadPermissions:(NSArray*)readPermissions
allowLoginUI:(BOOL)allowLoginUI
completionHandler:(FBSessionStateHandler)handler;
/*!
@abstract
This is a simple method for opening a session with Facebook. Using sessionOpen logs on a user,
and sets the static activeSession which becomes the default session object for any Facebook UI widgets
used by the application. This session becomes the active session, whether open succeeds or fails.
@param publishPermissions An array of strings representing the publish permissions to request during the
authentication flow.
@param defaultAudience Anytime an app publishes on behalf of a user, the post must have an audience (e.g. me, my friends, etc.)
The default audience is used to notify the user of the cieling that the user agrees to grant to the app for the provided permissions.
@param allowLoginUI Sometimes it is useful to attempt to open a session, but only if
no login UI will be required to accomplish the operation. For example, at application startup it may not
be desirable to transition to login UI for the user, and yet an open session is desired so long as a cached
token can be used to open the session. Passing NO to this argument, assures the method will not present UI
to the user in order to open the session.
@param handler Many applications will benefit from notification when a session becomes invalid
or undergoes other state transitions. If a block is provided, the FBSession
object will call the block each time the session changes state.
@discussion
Returns true if the session was opened synchronously without presenting UI to the user. This occurs
when there is a cached token available from a previous run of the application. If NO is returned, this indicates
that the session was not immediately opened, via cache. However, if YES was passed as allowLoginUI, then it is
possible that the user will login, and the session will become open asynchronously. The primary use for
this return value is to switch-on facebook capabilities in your UX upon startup, in the case were the session
is opened via cache.
*/
+ (BOOL)openActiveSessionWithPublishPermissions:(NSArray*)publishPermissions
defaultAudience:(FBSessionDefaultAudience)defaultAudience
allowLoginUI:(BOOL)allowLoginUI
completionHandler:(FBSessionStateHandler)handler;
/*!
@abstract
An appication may get or set the current active session. Certain high-level components in the SDK
will use the activeSession to set default session (e.g. `FBLoginView`, `FBFriendPickerViewController`)
@discussion
If sessionOpen* is called, the resulting `FBSession` object also becomes the activeSession. If another
session was active at the time, it is closed automatically. If activeSession is called when no session
is active, a session object is instatiated and returned; in this case open must be called on the session
in order for it to be useable for communication with Facebook.
*/
+ (FBSession*)activeSession;
/*!
@abstract
An appication may get or set the current active session. Certain high-level components in the SDK
will use the activeSession to set default session (e.g. `FBLoginView`, `FBFriendPickerViewController`)
@param session The FBSession object to become the active session
@discussion
If an application prefers the flexibilility of directly instantiating a session object, an active
session can be set directly.
*/
+ (FBSession*)setActiveSession:(FBSession*)session;
/*!
@method
@abstract Set the default Facebook App ID to use for sessions. The app ID may be
overridden on a per session basis.
@param appID The default Facebook App ID to use for <FBSession> methods.
*/
+ (void)setDefaultAppID:(NSString*)appID;
/*!
@method
@abstract Get the default Facebook App ID to use for sessions. If not explicitly
set, the default will be read from the application's plist. The app ID may be
overridden on a per session basis.
*/
+ (NSString*)defaultAppID;
@end