Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 310 lines (256 sloc) 8.801 kb
167eaa6 @jverkoey Use // instead of /** for license headers.
jverkoey authored
1 //
23b3258 @jwang Massive Copyright Notice Update
jwang authored
2 // Copyright 2009-2011 Facebook
167eaa6 @jverkoey Use // instead of /** for license headers.
jverkoey authored
3 //
4 // Licensed under the Apache License, Version 2.0 (the "License");
5 // you may not use this file except in compliance with the License.
6 // You may obtain a copy of the License at
7 //
8 // http://www.apache.org/licenses/LICENSE-2.0
9 //
10 // Unless required by applicable law or agreed to in writing, software
11 // distributed under the License is distributed on an "AS IS" BASIS,
12 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 // See the License for the specific language governing permissions and
14 // limitations under the License.
15 //
58ebed0 @jverkoey Prepend the Apache license to every file.
jverkoey authored
16
800bc03 @jverkoey [Network] Move TTURLRequestCachePolicy to a separate file.
jverkoey authored
17 #import <Foundation/Foundation.h>
18
6471488 @jverkoey [Dox] General cleanup of Network. Consistent include groups.
jverkoey authored
19 // Network
27eefd1 @jverkoey Update header paths and add the Three20Network project configuration.
jverkoey authored
20 #import "Three20Network/TTURLRequestCachePolicy.h"
9c6d6a2 @joehewitt First commit
joehewitt authored
21
6471488 @jverkoey [Dox] General cleanup of Network. Consistent include groups.
jverkoey authored
22 // Core
27eefd1 @jverkoey Update header paths and add the Three20Network project configuration.
jverkoey authored
23 #import "Three20Core/TTCorePreprocessorMacros.h" // For __TTDEPRECATED_METHOD
f762dc7 @jverkoey [Dox] Clean up TTURLRequest.
jverkoey authored
24
fff1d14 @jwang Squashed commit of the following:
jwang authored
25 /**
26 * A constant to improve code readabillity, when using negative numbers for
27 * timeoutInterval.
28 *
29 * @see timeoutInterval
30 */
31 extern const NSTimeInterval TTURLRequestUseQueueTimeout;
32
efb0236 @jverkoey [Dox] Document TTURLRequest.
jverkoey authored
33 @protocol TTURLRequestDelegate;
34 @protocol TTURLResponse;
9c6d6a2 @joehewitt First commit
joehewitt authored
35
efb0236 @jverkoey [Dox] Document TTURLRequest.
jverkoey authored
36 /**
37 * The Three20 network request object, built to work with the Three20 cache and co.
38 *
39 * Allows customization of the http method, body, and parameters, as well as natural response
40 * processing using TTURLResponse objects.
41 */
6394c48 @joehewitt * Fixed bug @1026: Rename T3* to TT*
joehewitt authored
42 @interface TTURLRequest : NSObject {
f762dc7 @jverkoey [Dox] Clean up TTURLRequest.
jverkoey authored
43 NSString* _urlPath;
efb0236 @jverkoey [Dox] Document TTURLRequest.
jverkoey authored
44
45 NSString* _httpMethod;
46 NSData* _httpBody;
47 NSMutableDictionary* _parameters;
48 NSMutableDictionary* _headers;
49
50 NSString* _contentType;
51 NSStringEncoding _charsetForMultipart;
52
53 NSMutableArray* _files;
54
55 id<TTURLResponse> _response;
56
6394c48 @joehewitt * Fixed bug @1026: Rename T3* to TT*
joehewitt authored
57 TTURLRequestCachePolicy _cachePolicy;
efb0236 @jverkoey [Dox] Document TTURLRequest.
jverkoey authored
58 NSTimeInterval _cacheExpirationAge;
59 NSString* _cacheKey;
9c6d6a2 @joehewitt First commit
joehewitt authored
60
efb0236 @jverkoey [Dox] Document TTURLRequest.
jverkoey authored
61 NSDate* _timestamp;
5a05691 @joehewitt Functionality of T3URLCache expanded and stabilized greatly
joehewitt authored
62
efb0236 @jverkoey [Dox] Document TTURLRequest.
jverkoey authored
63 NSInteger _totalBytesLoaded;
64 NSInteger _totalBytesExpected;
fff1d14 @jwang Squashed commit of the following:
jwang authored
65
66 NSTimeInterval _timeoutInterval;
efb0236 @jverkoey [Dox] Document TTURLRequest.
jverkoey authored
67
0f95d8d @cemaleker [Network] Download tracking implemented
cemaleker authored
68 NSInteger _totalBytesDownloaded;
69 NSInteger _totalContentLength;
efb0236 @jverkoey [Dox] Document TTURLRequest.
jverkoey authored
70
71 id _userInfo;
72
73 BOOL _isLoading;
74 BOOL _shouldHandleCookies;
75 BOOL _respondedFromCache;
76 BOOL _filterPasswordLogging;
3d10d48 @dewind support sending application/x-www-form-urlencoded forms
dewind authored
77 BOOL _multiPartForm;
efb0236 @jverkoey [Dox] Document TTURLRequest.
jverkoey authored
78
79 NSMutableArray* _delegates;
80 }
5a05691 @joehewitt Functionality of T3URLCache expanded and stabilized greatly
joehewitt authored
81
82 /**
f762dc7 @jverkoey [Dox] Clean up TTURLRequest.
jverkoey authored
83 * The URL path to be loaded by the request.
84 */
85 @property (nonatomic, copy) NSString* urlPath;
86
87 /**
88 * The URL path to be loaded by the request.
89 *
90 * Deprecated due to name ambiguity. Use urlPath instead.
91 * Remove after May 6, 2010.
6eb7ec5 @joehewitt * Fixed bug @1047: Simply the request delegate model
joehewitt authored
92 */
f762dc7 @jverkoey [Dox] Clean up TTURLRequest.
jverkoey authored
93 @property (nonatomic, copy) NSString* URL __TTDEPRECATED_METHOD;
8ecc4b4 @joehewitt Improve robustness of photo viewer
joehewitt authored
94
6eb7ec5 @joehewitt * Fixed bug @1047: Simply the request delegate model
joehewitt authored
95 /**
96 * The HTTP method to send with the request.
efb0236 @jverkoey [Dox] Document TTURLRequest.
jverkoey authored
97 *
98 * @example @"POST"
99 * @example @"GET"
c05a31d @jverkoey [Dox] Document and clean up the PUT logic.
jverkoey authored
100 * @example @"PUT"
efb0236 @jverkoey [Dox] Document TTURLRequest.
jverkoey authored
101 * @default nil (equivalent to @"GET")
6eb7ec5 @joehewitt * Fixed bug @1047: Simply the request delegate model
joehewitt authored
102 */
d456049 @jverkoey [Dox] Clean up TTURLRequest.
jverkoey authored
103 @property (nonatomic, copy) NSString* httpMethod;
8ecc4b4 @joehewitt Improve robustness of photo viewer
joehewitt authored
104
6eb7ec5 @joehewitt * Fixed bug @1047: Simply the request delegate model
joehewitt authored
105 /**
efb0236 @jverkoey [Dox] Document TTURLRequest.
jverkoey authored
106 * An object that handles the response data and may parse and validate it.
107 *
108 * @see TTURLDataResponse
109 * @see TTURLImageResponse
878913e @jverkoey [Network] Document TTURLRequest further.
jverkoey authored
110 * @see TTURLXMLResponse
efb0236 @jverkoey [Dox] Document TTURLRequest.
jverkoey authored
111 */
d456049 @jverkoey [Dox] Clean up TTURLRequest.
jverkoey authored
112 @property (nonatomic, retain) id<TTURLResponse> response;
efb0236 @jverkoey [Dox] Document TTURLRequest.
jverkoey authored
113
114 /**
6eb7ec5 @joehewitt * Fixed bug @1047: Simply the request delegate model
joehewitt authored
115 * The HTTP body to send with the request.
efb0236 @jverkoey [Dox] Document TTURLRequest.
jverkoey authored
116 *
c05a31d @jverkoey [Dox] Document and clean up the PUT logic.
jverkoey authored
117 * If provided, will always be used. Please consider this when using POST/PUT methods: if
118 * httpBody is provided, then the POST/PUT data generated from the parameters property will not
119 * be used.
6eb7ec5 @joehewitt * Fixed bug @1047: Simply the request delegate model
joehewitt authored
120 */
d456049 @jverkoey [Dox] Clean up TTURLRequest.
jverkoey authored
121 @property (nonatomic, retain) NSData* httpBody;
8ecc4b4 @joehewitt Improve robustness of photo viewer
joehewitt authored
122
6eb7ec5 @joehewitt * Fixed bug @1047: Simply the request delegate model
joehewitt authored
123 /**
124 * The content type of the data in the request.
efb0236 @jverkoey [Dox] Document TTURLRequest.
jverkoey authored
125 *
878913e @jverkoey [Network] Document TTURLRequest further.
jverkoey authored
126 * If not provided and httpMethod is POST/PUT, then contentType is @"multipart/form-data".
6eb7ec5 @joehewitt * Fixed bug @1047: Simply the request delegate model
joehewitt authored
127 */
d456049 @jverkoey [Dox] Clean up TTURLRequest.
jverkoey authored
128 @property (nonatomic, copy) NSString* contentType;
8ecc4b4 @joehewitt Improve robustness of photo viewer
joehewitt authored
129
130 /**
c05a31d @jverkoey [Dox] Document and clean up the PUT logic.
jverkoey authored
131 * Parameters to use for an HTTP POST/PUT.
6eb7ec5 @joehewitt * Fixed bug @1047: Simply the request delegate model
joehewitt authored
132 */
d456049 @jverkoey [Dox] Clean up TTURLRequest.
jverkoey authored
133 @property (nonatomic, readonly) NSMutableDictionary* parameters;
6eb7ec5 @joehewitt * Fixed bug @1047: Simply the request delegate model
joehewitt authored
134
135 /**
bcea055 @joehewitt * Merged patch from vergeguy to support custom HTTP headers in TTURLR…
joehewitt authored
136 * Custom HTTP headers.
137 */
d456049 @jverkoey [Dox] Clean up TTURLRequest.
jverkoey authored
138 @property (nonatomic, readonly) NSMutableDictionary* headers;
bcea055 @joehewitt * Merged patch from vergeguy to support custom HTTP headers in TTURLR…
joehewitt authored
139
140 /**
efb0236 @jverkoey [Dox] Document TTURLRequest.
jverkoey authored
141 * @default TTURLRequestCachePolicyDefault
8ecc4b4 @joehewitt Improve robustness of photo viewer
joehewitt authored
142 */
d456049 @jverkoey [Dox] Clean up TTURLRequest.
jverkoey authored
143 @property (nonatomic) TTURLRequestCachePolicy cachePolicy;
8ecc4b4 @joehewitt Improve robustness of photo viewer
joehewitt authored
144
6eb7ec5 @joehewitt * Fixed bug @1047: Simply the request delegate model
joehewitt authored
145 /**
146 * The maximum age of cached data that can be used as a response.
efb0236 @jverkoey [Dox] Document TTURLRequest.
jverkoey authored
147 *
148 * @default TT_DEFAULT_CACHE_EXPIRATION_AGE (1 week)
6eb7ec5 @joehewitt * Fixed bug @1047: Simply the request delegate model
joehewitt authored
149 */
d456049 @jverkoey [Dox] Clean up TTURLRequest.
jverkoey authored
150 @property (nonatomic) NSTimeInterval cacheExpirationAge;
8ecc4b4 @joehewitt Improve robustness of photo viewer
joehewitt authored
151
efb0236 @jverkoey [Dox] Document TTURLRequest.
jverkoey authored
152 /**
153 * If no cache key is provided, a unique key is generated from the request data. If the request
c05a31d @jverkoey [Dox] Document and clean up the PUT logic.
jverkoey authored
154 * is a POST/PUT request, then the POST/PUT parameters are also used to generate the cache key.
efb0236 @jverkoey [Dox] Document TTURLRequest.
jverkoey authored
155 *
156 * By setting the cacheKey, you may override the default cache key generator with your own.
157 */
8464e20 @jverkoey [delint] Delint the entire project.
jverkoey authored
158 @property (nonatomic, copy) NSString* cacheKey;
8ecc4b4 @joehewitt Improve robustness of photo viewer
joehewitt authored
159
efb0236 @jverkoey [Dox] Document TTURLRequest.
jverkoey authored
160 /**
161 * A dummy object used to uniquely identify this request object once it's been sent into the fray.
162 * Generally TTUserInfo objects are used here.
163 *
164 * @see TTUserInfo
165 */
d456049 @jverkoey [Dox] Clean up TTURLRequest.
jverkoey authored
166 @property (nonatomic, retain) id userInfo;
ff236ef @joehewitt * Expose cache method to get path of a cache key
joehewitt authored
167
d456049 @jverkoey [Dox] Clean up TTURLRequest.
jverkoey authored
168 @property (nonatomic, retain) NSDate* timestamp;
6eb7ec5 @joehewitt * Fixed bug @1047: Simply the request delegate model
joehewitt authored
169
efb0236 @jverkoey [Dox] Document TTURLRequest.
jverkoey authored
170 /**
171 * Whether or not the request is currently active.
172 */
d456049 @jverkoey [Dox] Clean up TTURLRequest.
jverkoey authored
173 @property (nonatomic) BOOL isLoading;
8ecc4b4 @joehewitt Improve robustness of photo viewer
joehewitt authored
174
efb0236 @jverkoey [Dox] Document TTURLRequest.
jverkoey authored
175 /**
176 * Decide whether default cookie handling will happen for this request.
177 *
178 * @param YES if cookies should be sent with and set for this request;
179 * otherwise NO.
180 * @discussion The default is YES - in other words, cookies are sent from and
181 * stored to the cookie manager by default.
182 *
183 * @default YES
184 */
d456049 @jverkoey [Dox] Clean up TTURLRequest.
jverkoey authored
185 @property (nonatomic) BOOL shouldHandleCookies;
8ecc4b4 @joehewitt Improve robustness of photo viewer
joehewitt authored
186
efb0236 @jverkoey [Dox] Document TTURLRequest.
jverkoey authored
187 /**
641856e @tonklon [Dox] small clearification
tonklon authored
188 * The number of request body bytes already uploaded by this request.
efb0236 @jverkoey [Dox] Document TTURLRequest.
jverkoey authored
189 */
d456049 @jverkoey [Dox] Clean up TTURLRequest.
jverkoey authored
190 @property (nonatomic) NSInteger totalBytesLoaded;
9a99214 * Dispatch upload progress messages to TTURLRequest delegates (new fe…
Joe Hewitt authored
191
efb0236 @jverkoey [Dox] Document TTURLRequest.
jverkoey authored
192 /**
641856e @tonklon [Dox] small clearification
tonklon authored
193 * The total number of request body bytes expected to be uploaded for this request.
efb0236 @jverkoey [Dox] Document TTURLRequest.
jverkoey authored
194 */
d456049 @jverkoey [Dox] Clean up TTURLRequest.
jverkoey authored
195 @property (nonatomic) NSInteger totalBytesExpected;
9a99214 * Dispatch upload progress messages to TTURLRequest delegates (new fe…
Joe Hewitt authored
196
efb0236 @jverkoey [Dox] Document TTURLRequest.
jverkoey authored
197 /**
0f95d8d @cemaleker [Network] Download tracking implemented
cemaleker authored
198 * The number of downloaded bytes from server.
199 */
200 @property (nonatomic) NSInteger totalBytesDownloaded;
201
202 /**
203 * The number of content length of request.
204 */
205 @property (nonatomic) NSInteger totalContentLength;
206
207 /**
fff1d14 @jwang Squashed commit of the following:
jwang authored
208 * The timeout to use for the request.
209 *
210 * If a negative value is set the request uses
211 * the defaultTimeout of the TTURLRequestQueue. <b>This differs from behaviour of
212 * NSURLRequest.</b> Given a negative timeoutInterval NSURLRequest always fails.
213 *
214 * You should use the TTURLRequestUseQueueTimeout constant to improve
215 * code readabillity, instead of negative numbers.
216 *
217 * The default value is TTURLRequestUseQueueTimeout
218 *
219 * @par from NSURLRequest.h:
220 *
221 * The timeout interval specifies the limit on the idle
222 * interval alloted to a request in the process of loading. The "idle
223 * interval" is defined as the period of time that has passed since the
224 * last instance of load activity occurred for a request that is in the
225 * process of loading. Hence, when an instance of load activity occurs
226 * (e.g. bytes are received from the network for a request), the idle
227 * interval for a request is reset to 0. If the idle interval ever
228 * becomes greater than or equal to the timeout interval, the request
229 * is considered to have timed out. This timeout interval is measured
230 * in seconds.
231 *
232 * @see TTURLRequestQueue::defaultTimeout
233 */
234 @property (nonatomic) NSTimeInterval timeoutInterval;
235
236 /**
efb0236 @jverkoey [Dox] Document TTURLRequest.
jverkoey authored
237 * Whether or not the request was loaded from the cache.
238 *
239 * This is only valid after the request has completed.
240 */
d456049 @jverkoey [Dox] Clean up TTURLRequest.
jverkoey authored
241 @property (nonatomic) BOOL respondedFromCache;
9c6d6a2 @joehewitt First commit
joehewitt authored
242
203ef35 * Add option to TTURLRequest to suppress logging of passwords
Owen Yamauchi authored
243 /**
244 * Whether parameters named "password" should be suppressed in log messages.
245 */
6c004f3 @jverkoey [Dox] Property style cleanup.
jverkoey authored
246 @property (nonatomic, assign) BOOL filterPasswordLogging;
203ef35 * Add option to TTURLRequest to suppress logging of passwords
Owen Yamauchi authored
247
d8a6787 Implement a way to set the character set for a multiform post.
Tobias Rundström authored
248 /**
249 * Charset to use when creating multipart/form-data data.
efb0236 @jverkoey [Dox] Document TTURLRequest.
jverkoey authored
250 *
251 * @default NSUTF8StringEncoding to remain backwards compatible.
d8a6787 Implement a way to set the character set for a multiform post.
Tobias Rundström authored
252 */
d456049 @jverkoey [Dox] Clean up TTURLRequest.
jverkoey authored
253 @property (nonatomic) NSStringEncoding charsetForMultipart;
d8a6787 Implement a way to set the character set for a multiform post.
Tobias Rundström authored
254
efb0236 @jverkoey [Dox] Document TTURLRequest.
jverkoey authored
255 /**
256 * An array of non-retained objects that receive messages about the progress of the request.
257 */
d456049 @jverkoey [Dox] Clean up TTURLRequest.
jverkoey authored
258 @property (nonatomic, readonly) NSMutableArray* delegates;
259
3d10d48 @dewind support sending application/x-www-form-urlencoded forms
dewind authored
260 /**
261 * Determine whether to construct a multipart form or to instead encode the http body as the W3C default
262 * of application/x-www-form-urlencoded
263 */
264 @property (nonatomic, assign) BOOL multiPartForm;
efb0236 @jverkoey [Dox] Document TTURLRequest.
jverkoey authored
265
6394c48 @joehewitt * Fixed bug @1026: Rename T3* to TT*
joehewitt authored
266 + (TTURLRequest*)request;
8ecc4b4 @joehewitt Improve robustness of photo viewer
joehewitt authored
267
cf8d192 @jverkoey TTURLRequestDelegate is now a recommended delegate of TTURLRequest.
jverkoey authored
268 + (TTURLRequest*)requestWithURL:(NSString*)URL delegate:(id /*<TTURLRequestDelegate>*/)delegate;
9c6d6a2 @joehewitt First commit
joehewitt authored
269
cf8d192 @jverkoey TTURLRequestDelegate is now a recommended delegate of TTURLRequest.
jverkoey authored
270 - (id)initWithURL:(NSString*)URL delegate:(id /*<TTURLRequestDelegate>*/)delegate;
9c6d6a2 @joehewitt First commit
joehewitt authored
271
bcea055 @joehewitt * Merged patch from vergeguy to support custom HTTP headers in TTURLR…
joehewitt authored
272 - (void)setValue:(NSString *)value forHTTPHeaderField:(NSString *)field;
273
9c6d6a2 @joehewitt First commit
joehewitt authored
274 /**
efb0236 @jverkoey [Dox] Document TTURLRequest.
jverkoey authored
275 * Add a file whose data will be posted.
b9f99c0 @joehewitt * Support for including files to post with TTURLRequest (useful for u…
joehewitt authored
276 */
277 - (void)addFile:(NSData*)data mimeType:(NSString*)mimeType fileName:(NSString*)fileName;
278
279 /**
efb0236 @jverkoey [Dox] Document TTURLRequest.
jverkoey authored
280 * Attempt to send a request.
37a2ad2 @joehewitt Some re-factoring to support migrating to T3ImageView in Facebook
joehewitt authored
281 *
282 * If the request can be resolved by the cache, it will happen synchronously. Otherwise,
283 * the request will respond to its delegate asynchronously.
284 *
9c6d6a2 @joehewitt First commit
joehewitt authored
285 * @return YES if the request was loaded synchronously from the cache.
286 */
287 - (BOOL)send;
288
37a2ad2 @joehewitt Some re-factoring to support migrating to T3ImageView in Facebook
joehewitt authored
289 /**
efb0236 @jverkoey [Dox] Document TTURLRequest.
jverkoey authored
290 * Attempt to send a synchronous request.
1404c7b @jverkoey Add a synchronous request implementation to TTURLRequest.
jverkoey authored
291 *
efb0236 @jverkoey [Dox] Document TTURLRequest.
jverkoey authored
292 * The request will happen synchronously, regardless of whether the data is being grabbed from
1404c7b @jverkoey Add a synchronous request implementation to TTURLRequest.
jverkoey authored
293 * the network or from the cache.
294 *
295 * @return YES if the request was loaded from the cache.
296 */
297 - (BOOL)sendSynchronously;
298
299 /**
efb0236 @jverkoey [Dox] Document TTURLRequest.
jverkoey authored
300 * Cancel the request.
37a2ad2 @joehewitt Some re-factoring to support migrating to T3ImageView in Facebook
joehewitt authored
301 *
302 * If there are multiple requests going to the same URL as this request, the others will
303 * not be cancelled.
304 */
9c6d6a2 @joehewitt First commit
joehewitt authored
305 - (void)cancel;
306
b5e86f3 @joehewitt * Method to create an NSURLRequest from a TTURLRequest
joehewitt authored
307 - (NSURLRequest*)createNSURLRequest;
308
9c6d6a2 @joehewitt First commit
joehewitt authored
309 @end
Something went wrong with that request. Please try again.