FBRequestConnection
This class is no longer available in the most recent version of the SDK.

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
delegate

The delegate object that receives updates.

@property (nonatomic, assign) id<FBRequestConnectionDelegate> delegate;
errorBehavior

Set the automatic error handling behaviors.

@property (nonatomic, assign) FBRequestConnectionErrorBehavior errorBehavior;
Discussion:

This must be set before any requests are added.

When using retry behaviors, note the FBRequestConnection instance passed to the FBRequestHandler may be a different instance that the one the requests were originally started on.

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.

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.

Class Methods
startForCustomAudienceThirdPartyID:completionHandler:

Starts a request representing the Graph API call to retrieve a Custom Audience "third party ID" for the app's Facebook user. Callers will send this ID back to their own servers, collect up a set to create a Facebook Custom Audience with, and then use the resultant Custom Audience to target ads.

ParameterDescription
session

The FBSession to use to establish the user's identity for users logged into Facebook through this app. If nil, then the activeSession is used.

handler

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

+ (FBRequestConnection *)
startForCustomAudienceThirdPartyID: (FBSession *)session
completionHandler: (FBRequestHandler)handler;
Discussion:

This method will throw an exception if [FBSettings defaultAppID] is nil. The appID won't be nil when the pList includes the appID, or if it's explicitly set.

The JSON in the request's response will include an "custom_audience_third_party_id" key/value pair, with the value being the ID retrieved. This ID is an encrypted encoding of the Facebook user's ID and the invoking Facebook app ID. Multiple calls with the same user will return different IDs, thus these IDs cannot be used to correlate behavior across devices or applications, and are only meaningful when sent back to Facebook for creating Custom Audiences.

The ID retrieved represents the Facebook user identified in the following way: if the specified session (or activeSession if the specified session is nil) is open, the ID will represent the user associated with the activeSession; otherwise the ID will represent the user logged into the native Facebook app on the device. If there is no native Facebook app, no one is logged into it, or the user has opted out at the iOS level from ad tracking, then a nil ID will be returned.

This method returns nil if either the user has opted-out (via iOS) from Ad Tracking, the app itself has limited event usage via the [FBAppEvents setLimitEventUsage] flag, or a specific Facebook user cannot be identified.

startForDeleteObject:completionHandler:

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

ParameterDescription
object

The object to delete, may be an NSString or NSNumber representing an fbid or an NSDictionary with an id property

handler

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

+ (FBRequestConnection *)
startForDeleteObject: (id)object
completionHandler: (FBRequestHandler)handler;
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].

See connectionWithSession:graphPath:parameters:HTTPMethod:completionHandler:

ParameterDescription
handler

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

+ (FBRequestConnection *) startForMeWithCompletionHandler:(FBRequestHandler)handler;
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].

See connectionWithSession:graphPath:parameters:HTTPMethod:completionHandler:

ParameterDescription
handler

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

+ (FBRequestConnection *) startForMyFriendsWithCompletionHandler:(FBRequestHandler)handler;
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.

ParameterDescription
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.

startForPostOpenGraphObject:completionHandler:

Creates an FBRequest for creating a user owned Open Graph object, instantiate a FBRequestConnection object, add the request to the newly created connection and finally start the connection. The request uses the active session represented by [FBSession activeSession].

ParameterDescription
object

The Open Graph object to create. Some common expected fields include "title", "image", "url", etc.

handler

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

+ (FBRequestConnection *)
startForPostOpenGraphObject: (id<FBOpenGraphObject>)object
completionHandler: (FBRequestHandler)handler;
startForPostOpenGraphObjectWithType:title:image:url:description:objectProperties:completionHandler:

Creates an FBRequest for creating a user owned Open Graph object, instantiate a FBRequestConnection object, add the request to the newly created connection and finally start the connection. The request uses the active session represented by [FBSession activeSession].

ParameterDescription
type

The fully-specified Open Graph object type (e.g., my_app_namespace:my_object_name)

title

The title of the Open Graph object.

image

The link to an image to be associated with the Open Graph object.

url

The url to be associated with the Open Graph object.

description

The description for the object.

objectProperties

Any additional properties for the Open Graph object.

handler

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

+ (FBRequestConnection *)
startForPostOpenGraphObjectWithType: (NSString *)type
title: (NSString *)title
image: (id)image
url: (id)url
description: (NSString *)description
objectProperties: (NSDictionary *)objectProperties
completionHandler: (FBRequestHandler)handler;
startForPostStatusUpdate:completionHandler:

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

ParameterDescription
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;
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].

ParameterDescription
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;
startForPostWithGraphPath:graphObject:completionHandler:

Simple method to 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].

ParameterDescription
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;
Discussion:

This method is typically used for posting an open graph action. If you are only posting an open graph object (without an action), consider using startForPostOpenGraphObject:completionHandler:

startForUpdateOpenGraphObject:completionHandler:

Creates an FBRequest for updating a user owned Open Graph object, instantiate a FBRequestConnection object, add the request to the newly created connection and finally start the connection. The request uses the active session represented by [FBSession activeSession].

ParameterDescription
object

The Open Graph object to update the existing object with.

handler

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

+ (FBRequestConnection *)
startForUpdateOpenGraphObject: (id<FBOpenGraphObject>)object
completionHandler: (FBRequestHandler)handler;
startForUpdateOpenGraphObjectWithId:title:image:url:description:objectProperties:completionHandler:

Creates an FBRequest for updating a user owned Open Graph object, instantiate a FBRequestConnection object, add the request to the newly created connection and finally start the connection. The request uses the active session represented by [FBSession activeSession].

ParameterDescription
objectId

The id of the Open Graph object to update.

title

The updated title of the Open Graph object.

image

The updated link to an image to be associated with the Open Graph object.

url

The updated url to be associated with the Open Graph object.

description

The object's description.

objectProperties

Any additional properties to update for the Open Graph object.

handler

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

+ (FBRequestConnection *)
startForUpdateOpenGraphObjectWithId: (id)objectId
title: (NSString *)title
image: (id)image
url: (id)url
description: (NSString *)description
objectProperties: (NSDictionary *)objectProperties
completionHandler: (FBRequestHandler)handler;
startForUploadPhoto:completionHandler:

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

ParameterDescription
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;
startForUploadStagingResourceWithImage:completionHandler:

Starts a request connection to upload an image to create a staging resource. Staging resources allow you to post binary data such as images, in preparation for a post of an open graph object or action which references the image. The URI returned when uploading a staging resource may be passed as the value for the image property of an open graph object or action.

ParameterDescription
image

A UIImage for the image to upload.

handler

The handler block to call when the request completes.

+ (FBRequestConnection *)
startForUploadStagingResourceWithImage: (UIImage *)image
completionHandler: (FBRequestHandler)handler;
Discussion:

This method simplifies the preparation of a Graph API call be creating the FBRequest object and starting the request connection with a single method

startWithGraphPath:completionHandler:

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

See connectionWithSession:graphPath:parameters:HTTPMethod:completionHandler:

ParameterDescription
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;
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].

ParameterDescription
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;
Instance Methods
addRequest:completionHandler:

This method adds an FBRequest object to this connection.

ParameterDescription
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. The handler will be invoked on the main thread.

- (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.

addRequest:completionHandler:batchEntryName:

This method adds an FBRequest object to this connection.

ParameterDescription
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. The handler will be invoked on the main thread.

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.

addRequest:completionHandler:batchParameters:

This method adds an FBRequest object to this connection.

ParameterDescription
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.

batchParameters

The optional dictionary of parameters to include for this request as described in Graph API Batch Requests. Examples include "depends_on", "name", or "omit_response_on_success".

- (void)
addRequest: (FBRequest *)request
completionHandler: (FBRequestHandler)handler
batchParameters: (NSDictionary *)batchParameters;
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.

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.

init
- (instancetype) init;
Discussion:

Calls initWithTimeout: with a default timeout of 180 seconds.

initWithTimeout:

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

ParameterDescription
timeout

The NSTimeInterval (seconds) to wait for a response before giving up.

- (instancetype) 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].

overrideVersionPartWith:

Overrides the default version for a batch request

ParameterDescription
version

This is a string in the form @"v2.0" which will be used for the version part of an API path

- (void) overrideVersionPartWith:(NSString *)version;
Discussion:

The SDK automatically prepends a version part, such as "v2.0" to API paths in order to simplify API versioning for applications. If you want to override the version part while using batch requests on the connection, call this method to set the version for the batch request.

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.

Constants
FBNonJSONResponseProperty
FBSDK_EXTER N 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.

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.

NS_OPTIONS enum

Describes what automatic error handling behaviors to provide (if any).

typedef NS_OPTIONS(NSUInteger, FBRequestConnectionErrorBehavior) {
FBRequestConnectionErrorBehaviorNone = 0,
FBRequestConnectionErrorBehaviorRetry = 1,
FBRequestConnectionErrorBehaviorAlertUser = 2,
FBRequestConnectionErrorBehaviorReconnectSession = 4,
};
ConstantDescription
FBRequestConnectionErrorBehaviorNone

The default behavior of none

FBRequestConnectionErrorBehaviorRetry

This will retry any requests whose error category is classified as FBErrorCategoryRetry. If the retry fails, the normal handler is invoked.

FBRequestConnectionErrorBehaviorAlertUser

This will automatically surface any SDK provided userMessage (at most one), after retry attempts, but before any reconnects are tried. The alert will have one button whose text can be localized with the key "FBE:AlertMessageButton".

You should not display your own alert views in your request handler when specifying this behavior.

FBRequestConnectionErrorBehaviorReconnectSession

This will automatically reconnect a session if the request failed due to an invalid token that would otherwise close the session (such as an expired token or password change). Note this will NOT reconnect a session if the user had uninstalled the app, or if the user had disabled the app's slider in their privacy settings (in cases of iOS 6 system auth). If the session is reconnected, this will transition the session state to FBSessionStateTokenExtended which will invoke any state change handlers. Otherwise, the session is closed as normal.

This behavior should not be used if the FBRequestConnection contains multiple session instances. Further, when this behavior is used, you must not request new permissions for the session until the connection is completed.

Lastly, you should avoid using additional FBRequestConnections with the same session because that will be subject to race conditions.

Discussion:

This is a bitflag enum that can be composed of different values.

See FBError.h and FBErrorUtility.h for error category and user message details.