FBRequestConnection
FBRequestConnection
| Inherits from: | NSObject |
| Declared in: | FBRequestConnection.h |
Overview
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.
Tasks
urlRequest property
urlResponse property
FBNonJSONResponseProperty constant
FBRequestHandler typedef
Properties
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
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
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:
+ (FBRequestConnection*)startForMeWithCompletionHandler:(FBRequestHandler)handler;
Parameter
handler
The handler block to call when the request completes with a success, error, or cancel action.
Declared In
FBRequestConnection.h
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:
+ (FBRequestConnection*)
startForMyFriendsWithCompletionHandler:(FBRequestHandler)handler;
Parameter
handler
The handler block to call when the request completes with a success, error, or cancel action.
Declared In
FBRequestConnection.h
Starts a request representing a Graph API call to the "search" endpoint for a given location using the active session.
+ (FBRequestConnection*)startForPlacesSearchAtCoordinate:(CLLocationCoordinate2D)coordinate radiusInMeters:(NSInteger)radius resultsLimit:(NSInteger)limit searchText:(NSString*)searchText completionHandler:(FBRequestHandler)handler;
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 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
Simple method to make a graph API post of a status update. The request
uses the active session represented by [FBSession activeSession].
+ (FBRequestConnection *)startForPostStatusUpdate:(NSString *)message completionHandler:(FBRequestHandler)handler;
Parameter
message
The message to post.
Declared In
FBRequestConnection.h
Simple method to make a graph API post of a status update. The request
uses the active session represented by [FBSession activeSession].
+ (FBRequestConnection *)startForPostStatusUpdate:(NSString *)message place:(id)place tags:(id<NSFastEnumeration>)tags completionHandler:(FBRequestHandler)handler;
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.
Declared In
FBRequestConnection.h
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].
+ (FBRequestConnection*)startForPostWithGraphPath:(NSString*)graphPath graphObject:(id<FBGraphObject>)graphObject completionHandler:(FBRequestHandler)handler;
Parameter
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.
Declared In
FBRequestConnection.h
Simple method to make a graph API post of a photo. The request
uses the active session represented by [FBSession activeSession].
+ (FBRequestConnection*)startForUploadPhoto:(UIImage *)photo completionHandler:(FBRequestHandler)handler;
Parameter
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.
Declared In
FBRequestConnection.h
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].
See connectionWithSession:graphPath:parameters:HTTPMethod:completionHandler:
+ (FBRequestConnection*)startWithGraphPath:(NSString*)graphPath completionHandler:(FBRequestHandler)handler;
Parameter
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.
Declared In
FBRequestConnection.h
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].
+ (FBRequestConnection*)startWithGraphPath:(NSString*)graphPath parameters:(NSDictionary*)parameters HTTPMethod:(NSString*)HTTPMethod completionHandler:(FBRequestHandler)handler;
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.
handler
The handler block to call when the request completes with a success, error, or cancel action.
Declared In
FBRequestConnection.h
Instance Methods
This method adds an FBRequest object to this connection and then calls
start on the connection.
- (void)addRequest:(FBRequest*)request completionHandler:(FBRequestHandler)handler;
Parameter
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.
Discussion
The completion handler is retained until the block is called upon the completion or cancellation of the connection.
Declared In
FBRequestConnection.h
This method adds an FBRequest object to this connection and then calls
start on the connection.
- (void)addRequest:(FBRequest*)request completionHandler:(FBRequestHandler)handler batchEntryName:(NSString*)name;
Parameter
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 FBRequestConnection as described in
Graph API Batch Requests.
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
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
Array
- (id)init;
Discussion
Calls initWithTimeout: with a default timeout of 180 seconds.
Declared In
FBRequestConnection.h
FBRequestConnection objects are used to issue one or more requests as a single
request/response connection with Facebook.
- (id)initWithTimeout:(NSTimeInterval)timeout;
Parameter
timeout
The NSTimeInterval (seconds) to wait for a response before giving up.
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
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
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
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
Last Updated: November 19, 2012