-
Notifications
You must be signed in to change notification settings - Fork 3.5k
/
FBRequest.h
504 lines (383 loc) · 16.8 KB
/
FBRequest.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
/*
* 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>
#import <CoreLocation/CoreLocation.h>
#import "FBRequestConnection.h"
#import "FBGraphObject.h"
/*! The base URL used for graph requests */
extern NSString* const FBGraphBasePath;
// up-front decl's
@protocol FBRequestDelegate;
@class FBSession;
@class UIImage;
/*!
@typedef FBRequestState
@abstract
Deprecated - do not use in new code.
@discussion
FBRequestState is retained from earlier versions of the SDK to give existing
apps time to remove dependency on this.
@deprecated
*/
typedef NSUInteger FBRequestState __attribute__((deprecated));
/*!
@class FBRequest
@abstract
The `FBRequest` object is used to setup and manage requests to Facebook Graph
and REST APIs. This class provides helper methods that simplify the connection
and response handling.
@discussion
An <FBSession> object is required for all authenticated uses of `FBRequest`.
Requests that do not require an unauthenticated user are also supported and
do not require an <FBSession> object to be passed in.
An instance of `FBRequest` represents the arguments and setup for a connection
to Facebook. After creating an `FBRequest` object it can be used to setup a
connection to Facebook through the <FBRequestConnection> object. The
<FBRequestConnection> object is created to manage a single connection. To
cancel a connection use the instance method in the <FBRequestConnection> class.
An `FBRequest` object may be reused to issue multiple connections to Facebook.
However each <FBRequestConnection> instance will manage one connection.
Class and instance methods prefixed with **start* ** can be used to perform the
request setup and initiate the connection in a single call.
*/
@interface FBRequest : NSObject {
@private
id<FBRequestDelegate> _delegate;
NSString* _url;
NSURLConnection* _connection;
NSMutableData* _responseText;
#pragma GCC diagnostic push
#pragma GCC diagnostic ignored "-Wdeprecated-declarations"
FBRequestState _state;
#pragma GCC diagnostic pop
NSError* _error;
BOOL _sessionDidExpire;
id<FBGraphObject> _graphObject;
}
/*!
@methodgroup Creating a request
@method
Calls <initWithSession:graphPath:parameters:HTTPMethod:> with the default parameters.
*/
- (id)init;
/*!
@method
Calls <initWithSession:graphPath:parameters:HTTPMethod:> with default parameters
except for the ones provided to this method.
@param session The session object representing the identity of the Facebook user making
the request. A nil value indicates a request that requires no token; to
use the active session pass `[FBSession activeSession]`.
@param graphPath The Graph API endpoint to use for the request, for example "me".
*/
- (id)initWithSession:(FBSession*)session
graphPath:(NSString *)graphPath;
/*!
@method
@abstract
Initializes an `FBRequest` object for a Graph API request call.
@discussion
Note that this only sets properties on the `FBRequest` object.
To send the request, initialize an <FBRequestConnection> object, add this request,
and send <[FBRequestConnection start]>. See other methods on this
class for shortcuts to simplify this process.
@param session The session object representing the identity of the Facebook user making
the request. A nil value indicates a request that requires no token; to
use the active session pass `[FBSession activeSession]`.
@param graphPath The Graph API endpoint to use for the request, for example "me".
@param parameters The parameters for the request. A value of nil sends only the automatically handled
parameters, for example, the access token. The default is nil.
@param HTTPMethod The HTTP method to use for the request. The default is value of nil implies a GET.
*/
- (id)initWithSession:(FBSession*)session
graphPath:(NSString *)graphPath
parameters:(NSDictionary *)parameters
HTTPMethod:(NSString *)HTTPMethod;
/*!
@method
@abstract
Initialize a `FBRequest` object that will do a graph request.
@discussion
Note that this only sets properties on the `FBRequest`.
To send the request, initialize a <FBRequestConnection>, add this request,
and send <[FBRequestConnection start]>. See other methods on this
class for shortcuts to simplify this process.
@param session The session object representing the identity of the Facebook user making
the request. A nil value indicates a request that requires no token; to
use the active session pass `[FBSession activeSession]`.
@param graphPath The Graph API endpoint to use for the request, for example "me".
@param graphObject An object or open graph action to post.
*/
- (id)initForPostWithSession:(FBSession*)session
graphPath:(NSString *)graphPath
graphObject:(id<FBGraphObject>)graphObject;
/*!
@method
@abstract
Initialize a `FBRequest` object that will do a rest API request.
@discussion
Prefer to use graph requests instead of this where possible.
Note that this only sets properties on the `FBRequest`.
To send the request, initialize a <FBRequestConnection>, add this request,
and send <[FBRequestConnection start]>. See other methods on this
class for shortcuts to simplify this process.
@param session The session object representing the identity of the Facebook user making
the request. A nil value indicates a request that requires no token; to
use the active session pass `[FBSession activeSession]`.
@param restMethod A valid REST API method.
@param parameters The parameters for the request. A value of nil sends only the automatically handled
parameters, for example, the access token. The default is nil.
@param HTTPMethod The HTTP method to use for the request. The default is value of nil implies a GET.
*/
- (id)initWithSession:(FBSession*)session
restMethod:(NSString *)restMethod
parameters:(NSDictionary *)parameters
HTTPMethod:(NSString *)HTTPMethod;
/*!
@abstract
The parameters for the request.
@discussion
May be used to read the parameters that were automatically set during
the object initiliazation. Make any required modifications prior to
sending the request.
`NSString` parameters are used to generate URL parameter values or JSON
parameters. `NSData` and `UIImage` parameters are added as attachments
to the HTTP body and referenced by name in the URL and/or JSON.
*/
@property(nonatomic, retain, readonly) NSMutableDictionary *parameters;
/*!
@abstract
The <FBSession> session object to use for the request.
@discussion
May be used to read the session that was automatically set during
the object initiliazation. Make any required modifications prior to
sending the request.
*/
@property(nonatomic, retain) FBSession *session;
/*!
@abstract
The Graph API endpoint to use for the request, for example "me".
@discussion
May be used to read the Graph API endpoint that was automatically set during
the object initiliazation. Make any required modifications prior to
sending the request.
*/
@property(nonatomic, copy) NSString *graphPath;
/*!
@abstract
A valid REST API method.
@discussion
May be used to read the REST method that was automatically set during
the object initiliazation. Make any required modifications prior to
sending the request.
Use the Graph API equivalent of the API if it exists as the REST API
method is deprecated if there is a Graph API equivalent.
*/
@property(nonatomic, copy) NSString *restMethod;
/*!
@abstract
The HTTPMethod to use for the request, for example "GET" or "POST".
@discussion
May be used to read the HTTP method that was automatically set during
the object initiliazation. Make any required modifications prior to
sending the request.
*/
@property(nonatomic, copy) NSString *HTTPMethod;
/*!
@abstract
The graph object to post with the request.
@discussion
May be used to read the graph object that was automatically set during
the object initiliazation. Make any required modifications prior to
sending the request.
*/
@property(nonatomic, retain) id<FBGraphObject> graphObject;
/*!
@methodgroup Instance methods
*/
/*!
@method
@abstract
Starts a connection to the Facebook API.
@discussion
This is used to start an API call to Facebook and call the block when the
request completes with a success, error, or cancel.
@param handler The handler block to call when the request completes with a success, error, or cancel action.
*/
- (FBRequestConnection*)startWithCompletionHandler:(FBRequestHandler)handler;
/*!
@methodgroup FBRequestConnection start methods
@abstract
These methods start an <FBRequestConnection>.
@discussion
These methods simplify the process of preparing a request and starting
the connection. The methods handle initializing an `FBRequest` object,
initializing a <FBRequestConnection> object, adding the `FBRequest`
object to the to the <FBRequestConnection>, and finally starting the
connection.
*/
/*!
@methodgroup FBRequest factory methods
@abstract
These methods initialize a `FBRequest` for common scenarios.
@discussion
These simplify the process of preparing a request to send. These
initialize a `FBRequest` based on strongly typed parameters that are
specific to the scenario.
These method do not initialize an <FBRequestConnection> object. To initiate the API
call first instantiate an <FBRequestConnection> object, add the request to this object,
then call the `start` method on the connection instance.
*/
// request*
//
// Summary:
// Helper methods used to create common request objects which can be used to create single or batch connections
//
// session: - the session object representing the identity of the
// Facebook user making the request; nil implies an
// unauthenticated request; default=nil
/*!
@method
@abstract
Creates a request representing a Graph API call to the "me" endpoint, using the active session.
@discussion
Simplifies preparing a request to retrieve the user's identity.
This method does not initialize an <FBRequestConnection> object. To initiate the API
call first instantiate an <FBRequestConnection> object, add the request to this object,
then call the `start` method on the connection instance.
A successful Graph API call will return an <FBGraphUser> object representing the
user's identity.
Note you may change the session property after construction if a session other than
the active session is preferred.
*/
+ (FBRequest*)requestForMe;
/*!
@method
@abstract
Creates a request representing a Graph API call to the "me/friends" endpoint using the active session.
@discussion
Simplifies preparing a request to retrieve the user's friends.
This method does not initialize an <FBRequestConnection> object. To initiate the API
call first instantiate an <FBRequestConnection> object, add the request to this object,
then call the `start` method on the connection instance.
A successful Graph API call will return an array of <FBGraphUser> objects representing the
user's friends.
*/
+ (FBRequest*)requestForMyFriends;
/*!
@method
@abstract
Creates a request representing a Graph API call to upload a photo to the app's album using the active session.
@discussion
Simplifies preparing a request to post a photo.
To post a photo to a specific album, get the `FBRequest` returned from this method
call, then modify the request parameters by adding the album ID to an "album" key.
This method does not initialize an <FBRequestConnection> object. To initiate the API
call first instantiate an <FBRequestConnection> object, add the request to this object,
then call the `start` method on the connection instance.
@param photo A `UIImage` for the photo to upload.
*/
+ (FBRequest*)requestForUploadPhoto:(UIImage *)photo;
/*!
@method
@abstract
Creates a request representing a status update.
@discussion
Simplifies preparing a request to post a status update.
This method does not initialize an <FBRequestConnection> object. To initiate the API
call first instantiate an <FBRequestConnection> object, add the request to this object,
then call the `start` method on the connection instance.
@param message The message to post.
*/
+ (FBRequest *)requestForPostStatusUpdate:(NSString *)message;
/*!
@method
@abstract
Creates a request representing a status update.
@discussion
Simplifies preparing a request to post a status update.
This method does not initialize an <FBRequestConnection> object. To initiate the API
call first instantiate an <FBRequestConnection> object, add the request to this object,
then call the `start` method on the connection instance.
@param message The message to post.
@param place The place to checkin with, or nil. Place may be an fbid or a
graph object representing a place.
@param tags Array of friends to tag in the status update, each element
may be an fbid or a graph object representing a user.
*/
+ (FBRequest *)requestForPostStatusUpdate:(NSString *)message
place:(id)place
tags:(id<NSFastEnumeration>)tags;
/*!
@method
@abstract
Creates a request representing a Graph API call to the "search" endpoint
for a given location using the active session.
@discussion
Simplifies preparing a request to search for places near a coordinate.
This method does not initialize an <FBRequestConnection> object. To initiate the API
call first instantiate an <FBRequestConnection> object, add the request to this object,
then call the `start` method on the connection instance.
A successful Graph API call will return an array of <FBGraphPlace> objects representing
the nearby locations.
@param coordinate The search coordinates.
@param radius The search radius in meters.
@param limit The maxiumum number of results to return. It is
possible to receive fewer than this because of the radius and because of server limits.
@param searchText The text to use in the query to narrow the set of places
returned.
*/
+ (FBRequest*)requestForPlacesSearchAtCoordinate:(CLLocationCoordinate2D)coordinate
radiusInMeters:(NSInteger)radius
resultsLimit:(NSInteger)limit
searchText:(NSString*)searchText;
/*!
@method
@abstract
Returns a newly initialized request object that can be used to make a Graph API call for the active session.
@discussion
This method simplifies the preparation of a Graph API call.
This method does not initialize an <FBRequestConnection> object. To initiate the API
call first instantiate an <FBRequestConnection> object, add the request to this object,
then call the `start` method on the connection instance.
@param graphPath The Graph API endpoint to use for the request, for example "me".
*/
+ (FBRequest*)requestForGraphPath:(NSString*)graphPath;
/*!
@method
@abstract
Creates a request representing a POST for a graph object.
@param graphPath The Graph API endpoint to use for the request, for example "me".
@param graphObject An object or open graph action to post.
*/
+ (FBRequest*)requestForPostWithGraphPath:(NSString*)graphPath
graphObject:(id<FBGraphObject>)graphObject;
/*!
@method
@abstract
Returns a newly initialized request object that can be used to make a Graph API call for the active session.
@discussion
This method simplifies the preparation of a Graph API call.
This method does not initialize an <FBRequestConnection> object. To initiate the API
call first instantiate an <FBRequestConnection> object, add the request to this object,
then call the `start` method on the connection instance.
@param graphPath The Graph API endpoint to use for the request, for example "me".
@param parameters The parameters for the request. A value of nil sends only the automatically handled parameters, for example, the access token. The default is nil.
@param HTTPMethod The HTTP method to use for the request. A nil value implies a GET.
*/
+ (FBRequest*)requestWithGraphPath:(NSString*)graphPath
parameters:(NSDictionary*)parameters
HTTPMethod:(NSString*)HTTPMethod;
@end