FBRequest - Documentation - Meta for Developers

FBRequest

This class is no longer available in the most recent version of the SDK.
A more recent version of this class is available. Check out the latest version.

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.

Inherits from:	`NSObject`
Declared in:	`FBRequest.h`

Properties

graphObject

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

graphPath

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

HTTPMethod

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

parameters

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

restMethod

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

session

The FBSession session object to use for the request.

@property (nonatomic,
    retain) FBSession *session;

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.

Declared In: FBRequest.h

Class Methods

requestForGraphPath:

Returns a newly initialized request object that can be used to make a Graph API call for the active session.

Parameter	Description
`graphPath`	The Graph API endpoint to use for the request, for example "me".

+ (FBRequest*) requestForGraphPath:(NSString*)graphPath;

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

requestForMe

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.

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

requestForMyFriends

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.

A successful Graph API call will return an array of FBGraphUser objects representing the user's friends.

Declared In: FBRequest.h

requestForPlacesSearchAtCoordinate:radiusInMeters:resultsLimit:searchText:

Creates a request representing a Graph API call to the "search" endpoint for a given location using the active session.

Parameter	Description
`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.

+ (FBRequest*)

	`requestForPlacesSearchAtCoordinate`
	`CLLocationCoordinate`
	`D`
	`coordinate`
`radiusInMeters:`	`(NSInteger)radius`
`resultsLimit:`	`(NSInteger)limit`
`searchText:`	`(NSString*)searchText;`

Discussion:

Simplifies preparing a request to search for places near a coordinate.

A successful Graph API call will return an array of FBGraphPlace objects representing the nearby locations.

Declared In: FBRequest.h

requestForPostStatusUpdate:

Creates a request representing a status update.

Parameter	Description
`message`	The message to post.

+ (FBRequest *) requestForPostStatusUpdate:(NSString *)message;

Discussion:

Simplifies preparing a request to post a status update.

Declared In: FBRequest.h

requestForPostStatusUpdate:place:tags:

Creates a request representing a status update.

Parameter	Description
`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.

+ (FBRequest *)

`requestForPostStatusUpdate:`	`(NSString *)message`
`place:`	`(id)place`
`tags:`	`(id<NSFastEnumeration>)tags;`

Discussion:

Simplifies preparing a request to post a status update.

Declared In: FBRequest.h

requestForPostWithGraphPath:graphObject:

Creates a request representing a POST for a graph object.

Parameter	Description
`graphPath`	The Graph API endpoint to use for the request, for example "me".
`graphObject`	An object or open graph action to post.

+ (FBRequest*)

`requestForPostWithGraphPath:`	`(NSString*)graphPath`
`graphObject:`	`(id<FBGraphObject>)graphObject;`

Declared In: FBRequest.h

requestForUploadPhoto:

Creates a request representing a Graph API call to upload a photo to the app's album using the active session.

Parameter	Description
`photo`	A `UIImage` for the photo to upload.

+ (FBRequest*) requestForUploadPhoto:(UIImage *)photo;

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.

Declared In: FBRequest.h

requestWithGraphPath:parameters:HTTPMethod:

Returns a newly initialized request object that can be used to make a Graph API call for the active session.

Parameter	Description
`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.

+ (FBRequest*)

`requestWithGraphPath:`	`(NSString*)graphPath`
`parameters:`	`(NSDictionary*)parameters`
`HTTPMethod:`	`(NSString*)HTTPMethod;`

Discussion:

This method simplifies the preparation of a Graph API call.

Declared In: FBRequest.h

Instance Methods

initForPostWithSession:graphPath:graphObject:

Initialize a FBRequest object that will do a graph request.

Parameter	Description
`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.

- (id)

`initForPostWithSession:`	`(FBSession*)session`
`graphPath:`	`(NSString *)graphPath`
`graphObject:`	`(id<FBGraphObject>)graphObject;`

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

initWithSession:graphPath:

Parameter	Description
`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".

- (id)

`initWithSession:`	`(FBSession*)session`
`graphPath:`	`(NSString *)graphPath;`

Discussion:

Calls initWithSession:graphPath:parameters:HTTPMethod: with default parameters except for the ones provided to this method.

Declared In: FBRequest.h

initWithSession:graphPath:parameters:HTTPMethod:

Initializes an FBRequest object for a Graph API request call.

Parameter	Description
`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.

- (id)

`initWithSession:`	`(FBSession*)session`
`graphPath:`	`(NSString *)graphPath`
`parameters:`	`(NSDictionary *)parameters`
`HTTPMethod:`	`(NSString *)HTTPMethod;`

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

initWithSession:restMethod:parameters:HTTPMethod:

Initialize a FBRequest object that will do a rest API request.

Parameter	Description
`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.

- (id)

`initWithSession:`	`(FBSession*)session`
`restMethod:`	`(NSString *)restMethod`
`parameters:`	`(NSDictionary *)parameters`
`HTTPMethod:`	`(NSString *)HTTPMethod;`

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

startWithCompletionHandler:

Starts a connection to the Facebook API.

Parameter	Description
`handler`	The handler block to call when the request completes with a success, error, or cancel action.

- (FBRequestConnection*) startWithCompletionHandler:(FBRequestHandler)handler;

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

FBGraphBasePath

extern NSString* const FBGraphBasePath;

Discussion:

The base URL used for graph requests

Declared In: FBRequest.h

Typedefs

FBRequestState

Deprecated - do not use in new code.

typedef NSUInteger FBRequestState __attribute__((deprecated));

Discussion:

FBRequestState is retained from earlier versions of the SDK to give existing apps time to remove dependency on this.

Declared In: FBRequest.h