The FBRequestConnection
represents a single connection to Facebook to service a request.
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 |
delegate
The delegate object that receives updates.
@property (nonatomic,
assign) id<FBRequestConnectionDelegate> delegate;
FBRequestConnection.h
errorBehavior
Set the automatic error handling behaviors.
@property (nonatomic,
assign) FBRequestConnectionErrorBehavior errorBehavior;
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.
FBRequestConnection.h
urlRequest
The request that will be sent to the server.
@property (nonatomic,
retain,
readwrite) NSMutableURLRequest *urlRequest;
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
.
FBRequestConnection.h
urlResponse
The raw response that was returned from the server. (readonly)
@property (nonatomic,
retain,
readonly) NSHTTPURLResponse *urlResponse;
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.
FBRequestConnection.h
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.
Parameter | Description |
---|---|
session | The FBSession to use to establish the user's identity for users logged into Facebook through this app.
If |
handler | The handler block to call when the request completes with a success, error, or cancel action. |
+ (FBRequestConnection *)
startForCustomAudienceThirdPartyID: | (FBSession *)session |
completionHandler: | (FBRequestHandler)handler; |
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.
FBRequestConnection.h
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]
.
Parameter | Description |
---|---|
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; |
FBRequestConnection.h
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;
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;
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; |
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.
FBRequestConnection.h
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]
.
Parameter | Description |
---|---|
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; |
FBRequestConnection.h
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]
.
Parameter | Description |
---|---|
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; |
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; |
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; |
FBRequestConnection.h
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]
.
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; |
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:
FBRequestConnection.h
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]
.
Parameter | Description |
---|---|
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; |
FBRequestConnection.h
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]
.
Parameter | Description |
---|---|
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; |
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 |
handler | The handler block to call when the request completes with a success, error, or cancel action. |
+ (FBRequestConnection *)
startForUploadPhoto: | (UIImage *)photo |
completionHandler: | (FBRequestHandler)handler; |
FBRequestConnection.h
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.
Parameter | Description |
---|---|
image | A |
handler | The handler block to call when the request completes. |
+ (FBRequestConnection *)
startForUploadStagingResourceWithImage: | (UIImage *)image |
completionHandler: | (FBRequestHandler)handler; |
This method simplifies the preparation of a Graph API call be creating the FBRequest object and starting the request connection with a single method
FBRequestConnection.h
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]
.
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; |
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; |
FBRequestConnection.h
addRequest:completionHandler:
This method adds an FBRequest object to this 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. The handler will be invoked on the main thread. |
- (void)
addRequest: | (FBRequest *)request |
completionHandler: | (FBRequestHandler)handler; |
The completion handler is retained until the block is called upon the completion or cancellation of the connection.
FBRequestConnection.h
addRequest:completionHandler:batchEntryName:
This method adds an FBRequest object to this 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. 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
|
- (void)
addRequest: | (FBRequest *)request |
completionHandler: | (FBRequestHandler)handler |
batchEntryName: | (NSString *)name; |
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.
FBRequestConnection.h
addRequest:completionHandler:batchParameters:
This method adds an FBRequest object to this 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. |
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; |
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.
FBRequestConnection.h
cancel
Signals that a connection should be logically terminated as the application is no longer interested in a response.
- (void)
cancel;
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.
FBRequestConnection.h
init
- (instancetype)
init;
Calls initWithTimeout:
with a default timeout of 180 seconds.
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 |
- (instancetype)
initWithTimeout:(NSTimeInterval)timeout;
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]
.
FBRequestConnection.h
overrideVersionPartWith:
Overrides the default version for a batch request
Parameter | Description |
---|---|
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;
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.
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;
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.
FBRequestConnection.h
FBNonJSONResponseProperty
FBSDK_EXTER N NSString *const FBNonJSONResponseProperty;
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.
FBRequestConnection.h
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);
Pass a block of this type when calling addRequest. This will be called once the request completes. The call occurs on the UI thread.
FBRequestConnection.h
NS_ENUM enum
Describes what automatic error handling behaviors to provide (if any).
typedef NS_ENUM(NSUInteger, FBRequestConnectionErrorBehavior) { FBRequestConnectionErrorBehaviorNone = 0, FBRequestConnectionErrorBehaviorRetry = 1, FBRequestConnectionErrorBehaviorAlertUser = 2, FBRequestConnectionErrorBehaviorReconnectSession = 4, };
Constant | Description |
---|---|
FBRequestConnectionErrorBehaviorNone | The default behavior of none |
FBRequestConnectionErrorBehaviorRetry | This will retry any requests whose error category is classified as |
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. |
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.
FBRequestConnection.h