twitter framework reference

Twitter Framework Reference

Contents

Introduction 3About the Twitter Framework 3

Classes 4

TWRequest Class Reference 5Overview 5

Tasks 6

Properties 6

Instance Methods 8

Constants 10

TWTweetComposeViewController Class Reference 13Overview 13

Tasks 14

Properties 15

Class Methods 15

Instance Methods 15

Constants 18

Document Revision History 20

2012-02-16 | 2012 Apple Inc. All Rights Reserved.

2

Framework /System/Library/Frameworks/Twitter.framework

Header file directories System/Library/Frameworks/Twitter.framework/Headers

Declared in TWRequest.h

TWTweetComposeViewController.h

About the Twitter FrameworkThe Twitter framework allows your application to send Twitter requests on behalf of the user. The framework

takes care of user authentication for you and provides a template for creating HTTP requests. Refer to the

Twitter API for populating the content of the request. The Twitter framework also provides a sheet for composing

tweets. In Twitter's Settings, users control whether an application is allowed to communicate with Twitter on

their behalf.


3

Introduction


4

Classes

Inherits from NSObject

Conforms to NSObject (NSObject)


Availability Available in iOS 5.0 and later.

Declared in TWRequest.h

OverviewThe TWRequest object encapsulates the properties of an HTTP request that you send to Twitter to perform

some operation on behalf of the user. The TWRequest class provides a convenient template for you to make

Twitter requests, and handles user authentication.

Twitter HTTP requests have these common components: a URL identifying the operation to perform, the HTTP

method (GET, POST, or DELETE), a set of query parameters that depends on the operation, and an optional

multipart POST body containing additional data. The values for these properties depend on the request you

are sending. Refer to Twitters documentation at https://dev.twitter.com/docs for details on the possible values.

Use the initWithURL:parameters:requestMethod: (page 9) method to initialize a newly created TWRequest

object passing the required property values. Use the addMultiPartData:withName:type: (page 8) to optionally

specify a multipart POST body. Use the performRequestWithHandler: (page 9) method to perform the actual

request specifying the handler to call when the request is done. Alternatively, you can use the

signedURLRequest (page 10) method to create a request that you send using an NSURLConnection object.

If the Twitter request requires user authorization, set the account (page 6) property to an ACAccount object.


5

TWRequest Class Reference

Tasks

Initializing Requests

initWithURL:parameters:requestMethod: (page 9)

Initializes a newly created request object with the specified properties.

Accessing Properties

account (page 6) property

Optional account information used to authenticate the request.

requestMethod (page 7) property

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

URL (page 8) property

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

parameters (page 7) property

The parameters for this request. (read-only)

addMultiPartData:withName:type: (page 8)

Specifies a named multipart POST body for this request.

Sending Requests

performRequestWithHandler: (page 9)

Performs the request and calls the specified handler when done.

signedURLRequest (page 10)

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

Properties

account

Optional account information used to authenticate the request.

TWRequest Class ReferenceTasks


6

@property(nonatomic, retain) ACAccount *account

DiscussionNot all Twitter requests require authorization. The default value is nil.

AvailabilityAvailable in iOS 5.0 and later.

Declared inTWRequest.h

parameters

The parameters for this request. (read-only)

@property(nonatomic, readonly) NSDictionary *parameters

DiscussionThese are the query parameters for this HTTP request. Possible values are described in Twitters documentation

at https://dev.twitter.com/docs.



requestMethod

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

@property(nonatomic, readonly) TWRequestMethod requestMethod

DiscussionThis property specifies the method of the HTTP request. Possible values are described in

TWRequestMethod (page 10).



TWRequest Class ReferenceProperties


7

URL

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

@property(nonatomic, readonly) NSURL *URL

DiscussionThis is the URL for the HTTP request. Possible values are described in Twitters documentation at

https://dev.twitter.com/docs.



Instance Methods

addMultiPartData:withName:type:

Specifies a named multipart POST body for this request.

- (void)addMultiPartData:(NSData *)data withName:(NSString *)name type:(NSString*)type

Parametersdata

The data for the multipart POST body.

name

The name of the multipart POST body.

type

The type of the multipart POST body.

DiscussionRefer to Twitters documentation at https://dev.twitter.com/docs for when a multipart POST body is needed

and what parameters to pass to this method.


TWRequest Class ReferenceInstance Methods


8


initWithURL:parameters:requestMethod:

Initializes a newly created request object with the specified properties.

- (id)initWithURL:(NSURL *)url parameters:(NSDictionary *)parametersrequestMethod:(TWRequestMethod)requestMethod

Parametersurl

The destination URL for this HTTP request.

parameters

The parameters for this HTTP request.

requestMethod

The method to use for this HTTP request.

Return ValueThe newly initialized request object.

DiscussionPossible values for these parameters are described in Twitters documentation at https://dev.twitter.com/docs.



performRequestWithHandler:

Performs the request and calls the specified handler when done.

- (void)performRequestWithHandler:(TWRequestHandler)handler

Parametershandler

The handler to call when the request is done. The parameters for this handler are described in

TWRequestHandler (page 11). This handler is not guaranteed to be called on any particular thread.

TWRequest Class ReferenceInstance Methods


9



signedURLRequest

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

- (NSURLRequest *)signedURLRequest

Return ValueAn OAuth-compatible NSURLRequest object that allows an application to act on behalf of the user while

keeping the users password private.



Constants

TWRequestMethod

Indicates the method used in the request.

enum TWRequestMethod {TWRequestMethodGET,TWRequestMethodPOST,TWRequestMethodDELETE

};typedef enum TWRequestMethod TWRequestMethod;

ConstantsTWRequestMethodGET

Requests a representation of the specified resource.

Available in iOS 5.0 and later.

Declared in TWRequest.h.

TWRequest Class ReferenceConstants


10

TWRequestMethodPOST

Submits data to be processed.



TWRequestMethodDELETE

Deletes the specified resource.



DiscussionUse this constant to set the requestMethod (page 7) property.



TWRequestHandler

The callback handler for a Twitter request.

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

DiscussionThe parameters for this handler are:

responseData

The data returned by the Twitter request.

urlResponse

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

error

An error identifier.

Refer to Twitters documentation at https://dev.twitter.com/docs for possible values of these parameters.




11




12

Inherits from UIViewController : UIResponder : NSObject

Conforms to NSCoding (UIViewController)

UIAppearanceContainer (UIViewController)

NSObject (NSObject)


Availability Available in iOS 5.0 and later.

Declared in TWTweetComposeViewController.h

OverviewThe TWTweetComposeViewController class presents a view to the user to compose a tweet.

Although you may perform Twitter requests on behalf of the user, you cannot append text, images, or URLs

to tweets without the users knowledge. Hence, you can set the initial text and other content before presenting

the tweet to the user but cannot change the tweet after the user views it. All of the methods used to set the

content of the tweet return a Boolean value. The methods return NO if the content doesnt fit in the tweet or

if the view was already presented to the user and the tweet can no longer be changed.

Optionally, use the canSendTweet (page 15) class method to check if Twitter is set up and reachable before

presenting this view to the user.

You can also set a handler using the completionHandler (page 15) property to be notified when the user is

done composing the tweet. Note that completion handlers are not called on any particular thread.


13

TWTweetComposeViewController Class Reference

Note: You cannot use a UIPopoverController object to present a TWTweetComposeViewControllerobject.

Tasks

Checking Status

+ canSendTweet (page 15)

Returns whether you can send a Twitter request.

Composing Tweets

setInitialText: (page 17)

Sets the initial text for a tweet.

addImage: (page 15)

Adds an image to the tweet.

addURL: (page 16)

Adds a URL to the tweet.

removeAllImages (page 16)

Removes all images from the tweet.

removeAllURLs (page 17)

Removes all URLs from the tweet.

Handling Results

completionHandler (page 15) property

The handler to call when the user is done composing the tweet.

TWTweetComposeViewController Class ReferenceTasks


14

Properties

completionHandler

The handler to call when the user is done composing the tweet.

@property(nonatomic, copy) TWTweetComposeViewControllerCompletionHandler completionHandler

DiscussionThe handler has a single parameter that indicates whether the user finished or cancelled composing the tweet.


Declared inTWTweetComposeViewController.h

Class Methods

canSendTweet

Returns whether you can send a Twitter request.

+ (BOOL)canSendTweet

Return ValueYES if Twitter is accessible and at least one account is set up; otherwise NO.



Instance Methods

addImage:

Adds an image to the tweet.

- (BOOL)addImage:(UIImage *)image

TWTweetComposeViewController Class ReferenceProperties


15

Parametersimage

The image to add to the tweet.

Return ValueYES if successful. NO if image does not fit in the currently available character space or the view was presented

to the user.



addURL:

Adds a URL to the tweet.

- (BOOL)addURL:(NSURL *)url

Parametersurl

The URL to add to the tweet.

Return ValueYES if successful. NO if url does not fit in the currently available character space or the view was presented

to the user.



removeAllImages

Removes all images from the tweet.

- (BOOL)removeAllImages

Return ValueYES if successful. NO if the images were not removed because the view was presented to the user.

TWTweetComposeViewController Class ReferenceInstance Methods


16



removeAllURLs

Removes all URLs from the tweet.

- (BOOL)removeAllURLs

Return ValueYES if successful. NO if the URLs were not removed because the view was presented to the user.



setInitialText:

Sets the initial text for a tweet.

- (BOOL)setInitialText:(NSString *)text

Parameterstext

The text to add to the tweet.

Return ValueYES if successful. NO if text does not fit in the currently available character space or the view was presented

to the user.



TWTweetComposeViewController Class ReferenceInstance Methods


17

Constants

TWTweetComposeViewControllerCompletionHandler

Defines a handler to call when the user finishes composing the tweet.

typedef void(^TWTweetComposeViewControllerCompletionHandler)(TWTweetComposeViewControllerResult result);

DiscussionSee TWTweetComposeViewControllerResult (page 18) for possible values of the result parameter. Use the

completionHandler (page 15) property to set this handler.



TWTweetComposeViewControllerResult

Possible values for the result parameter of the completionHandler (page 15) property.

enum TWTweetComposeViewControllerResult {TWTweetComposeViewControllerResultCancelled,TWTweetComposeViewControllerResultDone

};typedef enum TWTweetComposeViewControllerResult TWTweetComposeViewControllerResult;

ConstantsTWTweetComposeViewControllerResultCancelled

The user cancelled composing a tweet.


Declared in TWTweetComposeViewController.h.

TWTweetComposeViewControllerResultDone

The user finished composing a tweet.


Declared in TWTweetComposeViewController.h.

TWTweetComposeViewController Class ReferenceConstants


18



TWTweetComposeViewController Class ReferenceConstants


19

This table describes the changes to Twitter Framework Reference .

NotesDate

Minor editorial fixes.2012-02-16

First revision of this book that describes the classes for sending Twitter

requests on behalf of the user.

2011-10-12


20

Document Revision History

Apple Inc. 2012 Apple Inc.All rights reserved.

No part of this publication may be reproduced,stored in a retrieval system, or transmitted, in anyform or by any means, mechanical, electronic,photocopying, recording, or otherwise, withoutprior written permission of Apple Inc., with thefollowing exceptions: Any person is herebyauthorized to store documentation on a singlecomputer for personal use only and to printcopies of documentation for personal useprovided that the documentation containsApples copyright notice.

No licenses, express or implied, are granted withrespect to any of the technology described in thisdocument. Apple retains all intellectual propertyrights associated with the technology describedin this document. This document is intended toassist application developers to developapplications only for Apple-labeled computers.

Apple Inc.1 Infinite LoopCupertino, CA 95014408-996-1010

Apple and the Apple logo are trademarks ofApple Inc., registered in the U.S. and othercountries.

iOS is a trademark or registered trademark ofCisco in the U.S. and other countries and is usedunder license.

Even though Apple has reviewed this document,APPLE MAKES NO WARRANTY OR REPRESENTATION,EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THISDOCUMENT, ITS QUALITY, ACCURACY,MERCHANTABILITY, OR FITNESS FOR A PARTICULARPURPOSE. AS A RESULT, THIS DOCUMENT IS PROVIDEDAS IS, AND YOU, THE READER, ARE ASSUMING THEENTIRE RISK AS TO ITS QUALITY AND ACCURACY.

IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT,INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIALDAMAGES RESULTING FROM ANY DEFECT ORINACCURACY IN THIS DOCUMENT, even if advised ofthe possibility of such damages.

THE WARRANTY AND REMEDIES SET FORTH ABOVEARE EXCLUSIVE AND IN LIEU OF ALL OTHERS, ORALOR WRITTEN, EXPRESS OR IMPLIED. No Apple dealer,agent, or employee is authorized to make anymodification, extension, or addition to this warranty.

Some states do not allow the exclusion or limitationof implied warranties or liability for incidental orconsequential damages, so the above limitation orexclusion may not apply to you. This warranty givesyou specific legal rights, and you may also have otherrights which vary from state to state.

Twitter Framework ReferenceContentsIntroductionAbout the Twitter Framework

Part I: ClassesTWRequest Class ReferenceOverviewTasksInitializing RequestsAccessing PropertiesSending Requests

PropertiesaccountparametersrequestMethodURL

Instance MethodsaddMultiPartData:withName:type:initWithURL:parameters:requestMethod:performRequestWithHandler:signedURLRequest

ConstantsTWRequestMethodTWRequestHandler

TWTweetComposeViewController Class ReferenceOverviewTasksChecking StatusComposing TweetsHandling Results

PropertiescompletionHandler

Class MethodscanSendTweet

Instance MethodsaddImage:addURL:removeAllImagesremoveAllURLssetInitialText:

ConstantsTWTweetComposeViewControllerCompletionHandlerTWTweetComposeViewControllerResult

Revision History

twitter framework reference

Documents