FBRequest
FBRequest
| Inherits from: | NSObject |
| Declared in: | FBRequest.h |
Overview
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.
Tasks
graphObject property
graphPath property
HTTPMethod property
parameters property
restMethod property
session property
FBGraphBasePath constant
FBRequestState typedef
Properties
The graph object to post with the request.
@property(nonatomic,
retain) id<FBGraphObject> graphObject;
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.
Declared In
FBRequest.h
The Graph API endpoint to use for the request, for example "me".
@property(nonatomic,
copy) NSString *graphPath;
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.
Declared In
FBRequest.h
The HTTPMethod to use for the request, for example "GET" or "POST".
@property(nonatomic,
copy) NSString *HTTPMethod;
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.
Declared In
FBRequest.h
The parameters for the request.
@property(nonatomic,
retain,
readonly) NSMutableDictionary *parameters;
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.
Declared In
FBRequest.h
A valid REST API method.
@property(nonatomic,
copy) NSString *restMethod;
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.
Declared In
FBRequest.h
Class Methods
Returns a newly initialized request object that can be used to make a Graph API call for the active session.
+ (FBRequest*)requestForGraphPath:(NSString*)graphPath;
Parameter
graphPath
The Graph API endpoint to use for the request, for example "me".
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.
Declared In
FBRequest.h
Creates a request representing a Graph API call to the "me" endpoint, using the active session.
+ (FBRequest*)requestForMe;
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.
Declared In
FBRequest.h
Creates a request representing a Graph API call to the "me/friends" endpoint using the active session.
+ (FBRequest*)requestForMyFriends;
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.
Declared In
FBRequest.h
Creates a request representing a Graph API call to the "search" endpoint for a given location using the active session.
+ (FBRequest*)requestForPlacesSearchAtCoordinate:(CLLocationCoordinate2D)coordinate radiusInMeters:(NSInteger)radius resultsLimit:(NSInteger)limit searchText:(NSString*)searchText;
Parameter
coordinate
The search coordinates.
radius
The search radius in meters.
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.
searchText
The text to use in the query to narrow the set of places returned.
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.
Declared In
FBRequest.h
Creates a request representing a status update.
+ (FBRequest *)requestForPostStatusUpdate:(NSString *)message;
Parameter
message
The message to post.
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.
Declared In
FBRequest.h
Creates a request representing a status update.
+ (FBRequest *)requestForPostStatusUpdate:(NSString *)message place:(id)place tags:(id<NSFastEnumeration>)tags;
Parameter
message
The message to post.
place
The place to checkin with, or nil. Place may be an fbid or a graph object representing a place.
tags
Array of friends to tag in the status update, each element may be an fbid or a graph object representing a user.
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.
Declared In
FBRequest.h
Creates a request representing a POST for a graph object.
+ (FBRequest*)requestForPostWithGraphPath:(NSString*)graphPath graphObject:(id<FBGraphObject>)graphObject;
Parameter
graphPath
The Graph API endpoint to use for the request, for example "me".
graphObject
An object or open graph action to post.
Declared In
FBRequest.h
Creates a request representing a Graph API call to upload a photo to the app's album using the active session.
+ (FBRequest*)requestForUploadPhoto:(UIImage *)photo;
Parameter
photo
A UIImage for the photo to upload.
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.
Declared In
FBRequest.h
Returns a newly initialized request object that can be used to make a Graph API call for the active session.
+ (FBRequest*)requestWithGraphPath:(NSString*)graphPath parameters:(NSDictionary*)parameters HTTPMethod:(NSString*)HTTPMethod;
Parameter
graphPath
The Graph API endpoint to use for the request, for example "me".
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.
HTTPMethod
The HTTP method to use for the request. A nil value implies a GET.
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.
Declared In
FBRequest.h
Instance Methods
Initialize a FBRequest object that will do a graph request.
- (id)initForPostWithSession:(FBSession*)session graphPath:(NSString *)graphPath graphObject:(id<FBGraphObject>)graphObject;
Parameter
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].
graphPath
The Graph API endpoint to use for the request, for example "me".
graphObject
An object or open graph action to post.
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.
Declared In
FBRequest.h
Array
- (id)initWithSession:(FBSession*)session graphPath:(NSString *)graphPath;
Parameter
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].
graphPath
The Graph API endpoint to use for the request, for example "me".
Discussion
Calls initWithSession:graphPath:parameters:HTTPMethod: with default parameters
except for the ones provided to this method.
Declared In
FBRequest.h
Initializes an FBRequest object for a Graph API request call.
- (id)initWithSession:(FBSession*)session graphPath:(NSString *)graphPath parameters:(NSDictionary *)parameters HTTPMethod:(NSString *)HTTPMethod;
Parameter
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].
graphPath
The Graph API endpoint to use for the request, for example "me".
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.
HTTPMethod
The HTTP method to use for the request. The default is value of nil implies a GET.
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.
Declared In
FBRequest.h
Initialize a FBRequest object that will do a rest API request.
- (id)initWithSession:(FBSession*)session restMethod:(NSString *)restMethod parameters:(NSDictionary *)parameters HTTPMethod:(NSString *)HTTPMethod;
Parameter
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].
restMethod
A valid REST API method.
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.
HTTPMethod
The HTTP method to use for the request. The default is value of nil implies a GET.
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.
Declared In
FBRequest.h
Starts a connection to the Facebook API.
- (FBRequestConnection*)startWithCompletionHandler:(FBRequestHandler)handler;
Parameter
handler
The handler block to call when the request completes with a success, error, or cancel action.
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.
Declared In
FBRequest.h
Constants
Last Updated: November 19, 2012