SLRequest Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/Social.framework
Availability
Available in OS X v10.8 and later.
Declared in
SLRequest.h
SLServiceTypes.h

Overview

The SLRequest object encapsulates the properties of an HTTP request, providing a convenient template for you to make requests. You send a request to a social networking service to perform some operation on behalf of the user or to retrieve user information.

HTTP requests have these common components: an HTTP request method (GET, POST, PUT, or DELETE), a URL identifying the operation to perform, a set of query parameters, and an optional multipart POST body containing additional data. The values for these properties depend on the request you are sending and the target service provider. Refer to each supported social networking site’s documentation for possible values. Links to documentation are provided in Table 1.

Use the requestForServiceType:requestMethod:URL:parameters: method to initialize a newly created SLRequest object passing the required property values. Use the addMultipartData:withName:type: to optionally specify a multipart POST body. After you create your request, use the performRequestWithHandler: method to send the request, specifying the handler to call when the request is done.

If you already have a sending mechanism, you can use the preparedURLRequest method to create the request that you send using an NSURLConnection object. If the request requires user authorization, set the account property to an ACAccount object.

Table 1   Social Services Individual Documentation Sites

Facebook

https://developers.facebook.com/docs/

Sina Weibo

http://open.weibo.com/wiki/

Twitter

https://dev.twitter.com/docs

LinkedIn

https://developer.linkedin.com/rest

Tasks

Initializing Requests

Accessing Properties

Sending Requests

Properties

account

Account information used to authenticate the request.

@property (nonatomic, retain) ACAccount *account
Discussion

The account is used to sign a request with OAuth1 services or to add an access token for OAuth2 services. By associating the account with the request, the necessary tokens are added automatically. The default value is nil.

Availability
  • Available in OS X v10.8 and later.
Declared In
SLRequest.h

parameters

The parameters for this request. (read-only)

@property (nonatomic, readonly) NSDictionary *parameters
Discussion

Use this property to look up the query parameters of the HTTP request that was set in requestForServiceType:requestMethod:URL:parameters:. Possible values are dependent on the target service and are documented by the service provider. For links to documentation for the supported services, see Table 1.

Availability
  • Available in OS X v10.8 and later.
Declared In
SLRequest.h

requestMethod

The method to use for this request. (read-only)

@property (nonatomic, readonly) SLRequestMethod requestMethod
Discussion

Use this property to look up the method of the HTTP request that was set in requestForServiceType:requestMethod:URL:parameters:. Possible values are described in “SLRequestMethod.”

Availability
  • Available in OS X v10.8 and later.
Declared In
SLRequest.h

URL

The destination URL for this request. (read-only)

@property (nonatomic, readonly) NSURL *URL
Discussion

Use this property to look up the URL of the HTTP request that was set in requestForServiceType:requestMethod:URL:parameters:. Possible values are dependent on the target service and are documented by the service provider. For links to documentation for the supported services, see Table 1.

Availability
  • Available in OS X v10.8 and later.
Declared In
SLRequest.h

Class Methods

requestForServiceType:requestMethod:URL:parameters:

Initializes a newly created request object with the specified properties.

+ (SLRequest *)requestForServiceType:(NSString *)serviceType requestMethod:(SLRequestMethod)requestMethod URL:(NSURL *)url parameters:(NSDictionary *)parameters
Parameters
serviceType

The social networking service type. For possible values, see “Service Type Constants.”

requestMethod

The method to use for this HTTP request. For possible values, see “SLRequestMethod.”

url

The destination URL for this HTTP request. The values and formatting for the URL are dependent on the target service and are documented by the service provider. For links to documentation for the supported services, see Table 1.

parameters

The parameters for this HTTP request. The values and formatting are dependent on the target service and are documented by the service provider. For links to documentation for the supported services, see Table 1.

Return Value

The newly initialized request object.

Discussion

Use this method to initialize an SLRequest. The value and formatting of each parameter is dependent on the target service.

Availability
  • Available in OS X v10.8 and later.
Declared In
SLRequest.h

Instance Methods

addMultipartData:withName:type:filename:

Specifies a named multipart POST body for this request.

- (void)addMultipartData:(NSData *)data withName:(NSString *)name type:(NSString*)type filename:(NSString *)filename
Parameters
data

The data for the multipart POST body, such as an image or text.

name

The name of the multipart POST body. This is the name that a specific social service expects.

type

The type of the multipart POST body. This is the MIME content type of the multipart data.

filename

The filename of the attachment that you want to POST. Many social services require a filename in order to accept certain POST requests, such as uploading an image or video. If your multipart data does not require a filename, pass in nil.

Discussion

Possible parameter values are dependent on the target service. This information, as well as guidance on when to use a multipart POST body, is documented by the service provider. For links to documentation for the supported services, see Table 1.

Availability
  • Available in OS X v10.8 and later.
Declared In
SLRequest.h

performRequestWithHandler:

Performs an asynchronous request and calls the specified handler when done.

- (void)performRequestWithHandler:(SLRequestHandler)handler
Parameters
handler

The handler to call when the request is done. The parameters for this handler are described in SLRequestHandler. This handler is not guaranteed to be called on any particular thread and should not be nil.

Availability
  • Available in OS X v10.8 and later.
Declared In
SLRequest.h

preparedURLRequest

Returns an authorized URL request that can be sent using an NSURLConnection object.

- (NSURLRequest *)preparedURLRequest
Return Value

An OAuth-compatible NSURLRequest object that allows an app to act on behalf of the user while keeping the user’s password private. The NSURLRequest is signed as OAuth1 by default, or OAuth2 by adding the appropriate token based on the user’s account.

Discussion

Use this method to modify your request before sending. By setting the account correctly, this method will automatically add any necessary tokens.

Availability
  • Available in OS X v10.8 and later.
Declared In
SLRequest.h

Constants

Service Type Constants

Possible values for the serviceType parameter.

NSString *const SLServiceTypeFacebook;
NSString *const SLServiceTypeTwitter;
NSString *const SLServiceTypeSinaWeibo;
NSString *const SLServiceTypeLinkedIn;
NSString *const SLServiceTypeTencentWeibo;
Constants
SLServiceTypeFacebook

A string constant that identifies the social networking site, Facebook.

Available in OS X v10.8 and later.

Declared in SLServiceTypes.h.

SLServiceTypeTwitter

A string constant that identifies the social networking site, Twitter.

Available in OS X v10.8 and later.

Declared in SLServiceTypes.h.

SLServiceTypeSinaWeibo

A string constant that identifies the social networking site, Sina Weibo.

Available in OS X v10.8 and later.

Declared in SLServiceTypes.h.

SLServiceTypeLinkedIn

A string constant that identifies the social networking site, LinkedIn.

Available in OS X v10.9 and later.

Declared in SLServiceTypes.h.

SLServiceTypeTencentWeibo

A string constant that identifies the social networking site, Tencent Weibo.

Available in OS X v10.9 and later.

Declared in SLServiceTypes.h.

SLRequestMethod

Indicates the request method used in the request.

typedef NS_ENUM(NSInteger,
   SLRequestMethod)  {
   SLRequestMethodGET,
   SLRequestMethodPOST,
   SLRequestMethodDELETE,
   SLRequestMethodPUT;
};
Constants
SLRequestMethodGET

Requests information from the specified resource. Use a GET request to fetch information from the specified server such as character limits or a user’s timeline.

Available in OS X v10.8 and later.

Declared in SLRequest.h.

SLRequestMethodPOST

Submits data to be processed. Use a POST request to submit information to the specified server such as a status update or an image.

Available in OS X v10.8 and later.

Declared in SLRequest.h.

SLRequestMethodDELETE

Deletes the specified resource.

Available in OS X v10.8 and later.

Declared in SLRequest.h.

SLRequestMethodPUT

Uses a PUT request to submit the data.

Available in OS X v10.9 and later.

Declared in SLRequest.h.

Discussion

Use this constant to set the requestMethod property. The type of request to use depends on the target service. For links to documentation for the supported services, see Table 1.

SLRequestHandler

The callback handler for a request.

typedef void(^SLRequestHandler)(NSData *responseData, NSHTTPURLResponse *urlResponse, NSError *error);
Discussion

The parameters for this handler are:

responseData

The data returned by the request. The format of this data is dependent on the target service.

urlResponse

The URL response returned by the request that includes the HTTP response codes.

error

An error identifier.

Possible values are dependent on the target service and are documented by the service provider. For links to documentation for the supported services, see Table 1.

Availability
  • Available in OS X v10.8 and later.
Declared In
SLRequest.h