FBRequestConnection

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 FBRequestConnection represents a single connection to Facebook to service a request.

Discussion:

The request settings are encapsulated in a reusable FBRequest object. The FBRequestConnection object encapsulates the concerns of a single communication e.g. starting a connection, canceling a connection, or batching requests.

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

Properties

urlRequest

The request that will be sent to the server.

@property (nonatomic,
    retain,
    readwrite) NSMutableURLRequest *urlRequest;

Discussion:

This property can be used to create a NSURLRequest without using FBRequestConnection to send that request. It is legal to set this property in which case the provided NSMutableURLRequest will be used instead. However, the NSMutableURLRequest must result in an appropriate response. Furthermore, once this property has been set, no more FBRequest objects can be added to this FBRequestConnection.

Declared In: FBRequestConnection.h

urlResponse

The raw response that was returned from the server. (readonly)

@property (nonatomic,
    retain,
    readonly) NSHTTPURLResponse *urlResponse;

Discussion:

This property can be used to inspect HTTP headers that were returned from the server.

The property is nil until the request completes. If there was a response then this property will be non-nil during the FBRequestHandler callback.

Declared In: FBRequestConnection.h

Class Methods

startForMeWithCompletionHandler:

Simple method to make a graph API request for user info (/me), creates an FBRequest then uses an FBRequestConnection object to start the connection with Facebook. The request uses the active session represented by [FBSession activeSession].

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

+ (FBRequestConnection*) startForMeWithCompletionHandler:(FBRequestHandler)handler;

Declared In: FBRequestConnection.h

startForMyFriendsWithCompletionHandler:

Simple method to make a graph API request for user friends (/me/friends), creates an FBRequest then uses an FBRequestConnection object to start the connection with Facebook. The request uses the active session represented by [FBSession activeSession].

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

+ (FBRequestConnection*) startForMyFriendsWithCompletionHandler:(FBRequestHandler)handler;

Declared In: FBRequestConnection.h

startForPlacesSearchAtCoordinate:radiusInMeters:resultsLimit:searchText:completionHandler:

Starts 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.
`handler`	The handler block to call when the request completes with a success, error, or cancel action.

+ (FBRequestConnection*)

	`startForPlacesSearchAtCoordinate`
	`CLLocationCoordinate`
	`D`
	`coordinate`
`radiusInMeters:`	`(NSInteger)radius`
`resultsLimit:`	`(NSInteger)limit`
`searchText:`	`(NSString*)searchText`
`completionHandler:`	`(FBRequestHandler)handler;`

Discussion:

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

This method creates the necessary FBRequest object and initializes and starts an FBRequestConnection object. A successful Graph API call will return an array of FBGraphPlace objects representing the nearby locations.

Declared In: FBRequestConnection.h

startForPostStatusUpdate:completionHandler:

Simple method to make a graph API post of a status update. The request
uses the active session represented by [FBSession activeSession].

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

+ (FBRequestConnection *)

`startForPostStatusUpdate:`	`(NSString *)message`
`completionHandler:`	`(FBRequestHandler)handler;`

Declared In: FBRequestConnection.h

startForPostStatusUpdate:place:tags:completionHandler:

Simple method to make a graph API post of a status update. The request
uses the active session represented by [FBSession activeSession].

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.
`handler`	The handler block to call when the request completes with a success, error, or cancel action.

+ (FBRequestConnection *)

`startForPostStatusUpdate:`	`(NSString *)message`
`place:`	`(id)place`
`tags:`	`(id<NSFastEnumeration>)tags`
`completionHandler:`	`(FBRequestHandler)handler;`

Declared In: FBRequestConnection.h

startForPostWithGraphPath:graphObject:completionHandler:

Simple method to make post an object using the graph API, creates an FBRequest object for HTTP POST, then uses FBRequestConnection to start a connection with Facebook. The request uses the active session represented by [FBSession activeSession].

Parameter	Description
`graphPath`	The Graph API endpoint to use for the request, for example "me".
`graphObject`	An object or open graph action to post.
`handler`	The handler block to call when the request completes with a success, error, or cancel action.

+ (FBRequestConnection*)

`startForPostWithGraphPath:`	`(NSString*)graphPath`
`graphObject:`	`(id<FBGraphObject>)graphObject`
`completionHandler:`	`(FBRequestHandler)handler;`

Declared In: FBRequestConnection.h

startForUploadPhoto:completionHandler:

Simple method to make a graph API post of a photo. The request
uses the active session represented by [FBSession activeSession].

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

+ (FBRequestConnection*)

`startForUploadPhoto:`	`(UIImage *)photo`
`completionHandler:`	`(FBRequestHandler)handler;`

Declared In: FBRequestConnection.h

startWithGraphPath:completionHandler:

Simple method to make a graph API request, creates an FBRequest object for then uses an FBRequestConnection object to start the connection with Facebook. The request uses the active session represented by [FBSession activeSession].

Parameter	Description
`graphPath`	The Graph API endpoint to use for the request, for example "me".
`handler`	The handler block to call when the request completes with a success, error, or cancel action.

+ (FBRequestConnection*)

`startWithGraphPath:`	`(NSString*)graphPath`
`completionHandler:`	`(FBRequestHandler)handler;`

Declared In: FBRequestConnection.h

startWithGraphPath:parameters:HTTPMethod:completionHandler:

Creates an FBRequest object for a Graph API call, instantiate an FBRequestConnection object, add the request to the newly created connection and finally start the connection. Use this method for specifying the request parameters and HTTP Method. The request uses the active session represented by [FBSession activeSession].

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.
`handler`	The handler block to call when the request completes with a success, error, or cancel action.

+ (FBRequestConnection*)

`startWithGraphPath:`	`(NSString*)graphPath`
`parameters:`	`(NSDictionary*)parameters`
`HTTPMethod:`	`(NSString*)HTTPMethod`
`completionHandler:`	`(FBRequestHandler)handler;`

Declared In: FBRequestConnection.h

Instance Methods

addRequest:completionHandler:

This method adds an FBRequest object to this connection and then calls start on the connection.

Parameter	Description
`request`	A request to be included in the round-trip when start is called.
`handler`	A handler to call back when the round-trip completes or times out.

- (void)

`addRequest:`	`(FBRequest*)request`
`completionHandler:`	`(FBRequestHandler)handler;`

Discussion:

The completion handler is retained until the block is called upon the completion or cancellation of the connection.

Declared In: FBRequestConnection.h

addRequest:completionHandler:batchEntryName:

This method adds an FBRequest object to this connection and then calls start on the connection.

Parameter	Description
`request`	A request to be included in the round-trip when start is called.
`handler`	A handler to call back when the round-trip completes or times out.
`name`	An optional name for this request. This can be used to feed the results of one request to the input of another in the same `FBRequestConnection` as described in Graph API Batch Requests.

- (void)

`addRequest:`	`(FBRequest*)request`
`completionHandler:`	`(FBRequestHandler)handler`
`batchEntryName:`	`(NSString*)name;`

Discussion:

The completion handler is retained until the block is called upon the completion or cancellation of the connection. This request can be named to allow for using the request's response in a subsequent request.

Declared In: FBRequestConnection.h

cancel

Signals that a connection should be logically terminated as the application is no longer interested in a response.

- (void) cancel;

Discussion:

Synchronously calls any handlers indicating the request was cancelled. Cancel does not guarantee that the request-related processing will cease. It does promise that all handlers will complete before the cancel returns. A call to cancel prior to a start implies a cancellation of all requests associated with the connection.

Declared In: FBRequestConnection.h

init

- (id) init;

Discussion:

Calls initWithTimeout: with a default timeout of 180 seconds.

Declared In: FBRequestConnection.h

initWithTimeout:

FBRequestConnection objects are used to issue one or more requests as a single request/response connection with Facebook.

Parameter	Description
`timeout`	The `NSTimeInterval` (seconds) to wait for a response before giving up.

- (id) initWithTimeout:(NSTimeInterval)timeout;

Discussion:

For a single request, the usual method for creating an FBRequestConnection object is to call one of the **start* ** methods on FBRequest. However, it is allowable to init an FBRequestConnection object directly, and call addRequest:completionHandler: to add one or more request objects to the connection, before calling start.

Note that if requests are part of a batch, they must have an open FBSession that has an access token associated with it. Alternatively a default App ID must be set either in the plist or through an explicit call to [FBSession defaultAppID].

Declared In: FBRequestConnection.h

start

This method starts a connection with the server and is capable of handling all of the requests that were added to the connection.

- (void) start;

Discussion:

Errors are reported via the handler callback, even in cases where no communication is attempted by the implementation of FBRequestConnection. In such cases multiple error conditions may apply, and if so the following priority (highest to lowest) is used:

FBRequestConnectionInvalidRequestKey -- this error is reported when an FBRequest cannot be encoded for transmission.
FBRequestConnectionInvalidBatchKey -- this error is reported when any request in the connection cannot be encoded for transmission with the batch. In this scenario all requests fail.

This method cannot be called twice for an FBRequestConnection instance.

Declared In: FBRequestConnection.h

Constants

FBNonJSONResponseProperty

extern NSString *const FBNonJSONResponseProperty;

Discussion:

Normally requests return JSON data that is parsed into a set of NSDictionary and NSArray objects.

When a request returns a non-JSON response, that response is packaged in a NSDictionary using FBNonJSONResponseProperty as the key and the literal response as the value.

Declared In: FBRequestConnection.h

Typedefs

FBRequestHandler

A block that is passed to addRequest to register for a callback with the results of that request once the connection completes.

typedef void (^FBRequestHandler)(
    FBRequestConnection *connection, 
    id result, 
    NSError *error);

Discussion:

Pass a block of this type when calling addRequest. This will be called once the request completes. The call occurs on the UI thread.

Declared In: FBRequestConnection.h