view | history | commit | commitdiff
Wuyx
2017-01-04 0ba5a82e9ec833aa36729dfbad7deffbf3ea05c6
commit | author | age
6e1425 1 // AFURLRequestSerialization.h
H 2 // Copyright (c) 2011–2015 Alamofire Software Foundation (http://alamofire.org/)
3 //
4 // Permission is hereby granted, free of charge, to any person obtaining a copy
5 // of this software and associated documentation files (the "Software"), to deal
6 // in the Software without restriction, including without limitation the rights
7 // to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
8 // copies of the Software, and to permit persons to whom the Software is
9 // furnished to do so, subject to the following conditions:
10 //
11 // The above copyright notice and this permission notice shall be included in
12 // all copies or substantial portions of the Software.
13 //
14 // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
15 // IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
16 // FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
17 // AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
18 // LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
19 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
20 // THE SOFTWARE.
21
22 #import <Foundation/Foundation.h>
23 #if TARGET_OS_IOS
24 #import <UIKit/UIKit.h>
25 #elif TARGET_OS_WATCH
26 #import <WatchKit/WatchKit.h>
27 #endif
28
29 NS_ASSUME_NONNULL_BEGIN
30
31 /**
32  The `AFURLRequestSerialization` protocol is adopted by an object that encodes parameters for a specified HTTP requests. Request serializers may encode parameters as query strings, HTTP bodies, setting the appropriate HTTP header fields as necessary.
33
34  For example, a JSON request serializer may set the HTTP body of the request to a JSON representation, and set the `Content-Type` HTTP header field value to `application/json`.
35  */
36 @protocol AFURLRequestSerialization <NSObject, NSSecureCoding, NSCopying>
37
38 /**
39  Returns a request with the specified parameters encoded into a copy of the original request.
40
41  @param request The original request.
42  @param parameters The parameters to be encoded.
43  @param error The error that occurred while attempting to encode the request parameters.
44
45  @return A serialized request.
46  */
47 - (nullable NSURLRequest *)requestBySerializingRequest:(NSURLRequest *)request
48                                withParameters:(nullable id)parameters
49                                         error:(NSError * __nullable __autoreleasing *)error;
50
51 @end
52
53 #pragma mark -
54
55 /**
56
57  */
58 typedef NS_ENUM(NSUInteger, AFHTTPRequestQueryStringSerializationStyle) {
59     AFHTTPRequestQueryStringDefaultStyle = 0,
60 };
61
62 @protocol AFMultipartFormData;
63
64 /**
65  `AFHTTPRequestSerializer` conforms to the `AFURLRequestSerialization` & `AFURLResponseSerialization` protocols, offering a concrete base implementation of query string / URL form-encoded parameter serialization and default request headers, as well as response status code and content type validation.
66
67  Any request or response serializer dealing with HTTP is encouraged to subclass `AFHTTPRequestSerializer` in order to ensure consistent default behavior.
68  */
69 @interface AFHTTPRequestSerializer : NSObject <AFURLRequestSerialization>
70
71 /**
72  The string encoding used to serialize parameters. `NSUTF8StringEncoding` by default.
73  */
74 @property (nonatomic, assign) NSStringEncoding stringEncoding;
75
76 /**
77  Whether created requests can use the device’s cellular radio (if present). `YES` by default.
78
79  @see NSMutableURLRequest -setAllowsCellularAccess:
80  */
81 @property (nonatomic, assign) BOOL allowsCellularAccess;
82
83 /**
84  The cache policy of created requests. `NSURLRequestUseProtocolCachePolicy` by default.
85
86  @see NSMutableURLRequest -setCachePolicy:
87  */
88 @property (nonatomic, assign) NSURLRequestCachePolicy cachePolicy;
89
90 /**
91  Whether created requests should use the default cookie handling. `YES` by default.
92
93  @see NSMutableURLRequest -setHTTPShouldHandleCookies:
94  */
95 @property (nonatomic, assign) BOOL HTTPShouldHandleCookies;
96
97 /**
98  Whether created requests can continue transmitting data before receiving a response from an earlier transmission. `NO` by default
99
100  @see NSMutableURLRequest -setHTTPShouldUsePipelining:
101  */
102 @property (nonatomic, assign) BOOL HTTPShouldUsePipelining;
103
104 /**
105  The network service type for created requests. `NSURLNetworkServiceTypeDefault` by default.
106
107  @see NSMutableURLRequest -setNetworkServiceType:
108  */
109 @property (nonatomic, assign) NSURLRequestNetworkServiceType networkServiceType;
110
111 /**
112  The timeout interval, in seconds, for created requests. The default timeout interval is 60 seconds.
113
114  @see NSMutableURLRequest -setTimeoutInterval:
115  */
116 @property (nonatomic, assign) NSTimeInterval timeoutInterval;
117
118 ///---------------------------------------
119 /// @name Configuring HTTP Request Headers
120 ///---------------------------------------
121
122 /**
123  Default HTTP header field values to be applied to serialized requests. By default, these include the following:
124
125  - `Accept-Language` with the contents of `NSLocale +preferredLanguages`
126  - `User-Agent` with the contents of various bundle identifiers and OS designations
127
128  @discussion To add or remove default request headers, use `setValue:forHTTPHeaderField:`.
129  */
130 @property (readonly, nonatomic, strong) NSDictionary *HTTPRequestHeaders;
131
132 /**
133  Creates and returns a serializer with default configuration.
134  */
135 + (instancetype)serializer;
136
137 /**
138  Sets the value for the HTTP headers set in request objects made by the HTTP client. If `nil`, removes the existing value for that header.
139
140  @param field The HTTP header to set a default value for
141  @param value The value set as default for the specified header, or `nil`
142  */
143 - (void)setValue:(nullable NSString *)value
144 forHTTPHeaderField:(NSString *)field;
145
146 /**
147  Returns the value for the HTTP headers set in the request serializer.
148
149  @param field The HTTP header to retrieve the default value for
150
151  @return The value set as default for the specified header, or `nil`
152  */
153 - (nullable NSString *)valueForHTTPHeaderField:(NSString *)field;
154
155 /**
156  Sets the "Authorization" HTTP header set in request objects made by the HTTP client to a basic authentication value with Base64-encoded username and password. This overwrites any existing value for this header.
157
158  @param username The HTTP basic auth username
159  @param password The HTTP basic auth password
160  */
161 - (void)setAuthorizationHeaderFieldWithUsername:(NSString *)username
162                                        password:(NSString *)password;
163
164 /**
165  @deprecated This method has been deprecated. Use -setValue:forHTTPHeaderField: instead.
166  */
167 - (void)setAuthorizationHeaderFieldWithToken:(NSString *)token DEPRECATED_ATTRIBUTE;
168
169
170 /**
171  Clears any existing value for the "Authorization" HTTP header.
172  */
173 - (void)clearAuthorizationHeader;
174
175 ///-------------------------------------------------------
176 /// @name Configuring Query String Parameter Serialization
177 ///-------------------------------------------------------
178
179 /**
180  HTTP methods for which serialized requests will encode parameters as a query string. `GET`, `HEAD`, and `DELETE` by default.
181  */
182 @property (nonatomic, strong) NSSet *HTTPMethodsEncodingParametersInURI;
183
184 /**
185  Set the method of query string serialization according to one of the pre-defined styles.
186
187  @param style The serialization style.
188
189  @see AFHTTPRequestQueryStringSerializationStyle
190  */
191 - (void)setQueryStringSerializationWithStyle:(AFHTTPRequestQueryStringSerializationStyle)style;
192
193 /**
194  Set the a custom method of query string serialization according to the specified block.
195
196  @param block A block that defines a process of encoding parameters into a query string. This block returns the query string and takes three arguments: the request, the parameters to encode, and the error that occurred when attempting to encode parameters for the given request.
197  */
198 - (void)setQueryStringSerializationWithBlock:(nullable NSString * (^)(NSURLRequest *request, id parameters, NSError * __autoreleasing *error))block;
199
200 ///-------------------------------
201 /// @name Creating Request Objects
202 ///-------------------------------
203
204 /**
205  @deprecated This method has been deprecated. Use -requestWithMethod:URLString:parameters:error: instead.
206  */
207 - (NSMutableURLRequest *)requestWithMethod:(NSString *)method
208                                  URLString:(NSString *)URLString
209                                 parameters:(id)parameters DEPRECATED_ATTRIBUTE;
210
211 /**
212  Creates an `NSMutableURLRequest` object with the specified HTTP method and URL string.
213
214  If the HTTP method is `GET`, `HEAD`, or `DELETE`, the parameters will be used to construct a url-encoded query string that is appended to the request's URL. Otherwise, the parameters will be encoded according to the value of the `parameterEncoding` property, and set as the request body.
215
216  @param method The HTTP method for the request, such as `GET`, `POST`, `PUT`, or `DELETE`. This parameter must not be `nil`.
217  @param URLString The URL string used to create the request URL.
218  @param parameters The parameters to be either set as a query string for `GET` requests, or the request HTTP body.
219  @param error The error that occurred while constructing the request.
220
221  @return An `NSMutableURLRequest` object.
222  */
223 - (NSMutableURLRequest *)requestWithMethod:(NSString *)method
224                                  URLString:(NSString *)URLString
225                                 parameters:(nullable id)parameters
226                                      error:(NSError * __nullable __autoreleasing *)error;
227
228 /**
229  @deprecated This method has been deprecated. Use -multipartFormRequestWithMethod:URLString:parameters:constructingBodyWithBlock:error: instead.
230  */
231 - (NSMutableURLRequest *)multipartFormRequestWithMethod:(NSString *)method
232                                               URLString:(NSString *)URLString
233                                              parameters:(NSDictionary *)parameters
234                               constructingBodyWithBlock:(void (^)(id <AFMultipartFormData> formData))block DEPRECATED_ATTRIBUTE;
235
236 /**
237  Creates an `NSMutableURLRequest` object with the specified HTTP method and URLString, and constructs a `multipart/form-data` HTTP body, using the specified parameters and multipart form data block. See http://www.w3.org/TR/html4/interact/forms.html#h-17.13.4.2
238
239  Multipart form requests are automatically streamed, reading files directly from disk along with in-memory data in a single HTTP body. The resulting `NSMutableURLRequest` object has an `HTTPBodyStream` property, so refrain from setting `HTTPBodyStream` or `HTTPBody` on this request object, as it will clear out the multipart form body stream.
240
241  @param method The HTTP method for the request. This parameter must not be `GET` or `HEAD`, or `nil`.
242  @param URLString The URL string used to create the request URL.
243  @param parameters The parameters to be encoded and set in the request HTTP body.
244  @param block A block that takes a single argument and appends data to the HTTP body. The block argument is an object adopting the `AFMultipartFormData` protocol.
245  @param error The error that occurred while constructing the request.
246
247  @return An `NSMutableURLRequest` object
248  */
249 - (NSMutableURLRequest *)multipartFormRequestWithMethod:(NSString *)method
250                                               URLString:(NSString *)URLString
251                                              parameters:(nullable NSDictionary *)parameters
252                               constructingBodyWithBlock:(nullable void (^)(id <AFMultipartFormData> formData))block
253                                                   error:(NSError * __nullable __autoreleasing *)error;
254
255 /**
256  Creates an `NSMutableURLRequest` by removing the `HTTPBodyStream` from a request, and asynchronously writing its contents into the specified file, invoking the completion handler when finished.
257
258  @param request The multipart form request. The `HTTPBodyStream` property of `request` must not be `nil`.
259  @param fileURL The file URL to write multipart form contents to.
260  @param handler A handler block to execute.
261
262  @discussion There is a bug in `NSURLSessionTask` that causes requests to not send a `Content-Length` header when streaming contents from an HTTP body, which is notably problematic when interacting with the Amazon S3 webservice. As a workaround, this method takes a request constructed with `multipartFormRequestWithMethod:URLString:parameters:constructingBodyWithBlock:error:`, or any other request with an `HTTPBodyStream`, writes the contents to the specified file and returns a copy of the original request with the `HTTPBodyStream` property set to `nil`. From here, the file can either be passed to `AFURLSessionManager -uploadTaskWithRequest:fromFile:progress:completionHandler:`, or have its contents read into an `NSData` that's assigned to the `HTTPBody` property of the request.
263
264  @see https://github.com/AFNetworking/AFNetworking/issues/1398
265  */
266 - (NSMutableURLRequest *)requestWithMultipartFormRequest:(NSURLRequest *)request
267                              writingStreamContentsToFile:(NSURL *)fileURL
268                                        completionHandler:(nullable void (^)(NSError * __nullable error))handler;
269
270 @end
271
272 #pragma mark -
273
274 /**
275  The `AFMultipartFormData` protocol defines the methods supported by the parameter in the block argument of `AFHTTPRequestSerializer -multipartFormRequestWithMethod:URLString:parameters:constructingBodyWithBlock:`.
276  */
277 @protocol AFMultipartFormData
278
279 /**
280  Appends the HTTP header `Content-Disposition: file; filename=#{generated filename}; name=#{name}"` and `Content-Type: #{generated mimeType}`, followed by the encoded file data and the multipart form boundary.
281
282  The filename and MIME type for this data in the form will be automatically generated, using the last path component of the `fileURL` and system associated MIME type for the `fileURL` extension, respectively.
283
284  @param fileURL The URL corresponding to the file whose content will be appended to the form. This parameter must not be `nil`.
285  @param name The name to be associated with the specified data. This parameter must not be `nil`.
286  @param error If an error occurs, upon return contains an `NSError` object that describes the problem.
287
288  @return `YES` if the file data was successfully appended, otherwise `NO`.
289  */
290 - (BOOL)appendPartWithFileURL:(NSURL *)fileURL
291                          name:(NSString *)name
292                         error:(NSError * __nullable __autoreleasing *)error;
293
294 /**
295  Appends the HTTP header `Content-Disposition: file; filename=#{filename}; name=#{name}"` and `Content-Type: #{mimeType}`, followed by the encoded file data and the multipart form boundary.
296
297  @param fileURL The URL corresponding to the file whose content will be appended to the form. This parameter must not be `nil`.
298  @param name The name to be associated with the specified data. This parameter must not be `nil`.
299  @param fileName The file name to be used in the `Content-Disposition` header. This parameter must not be `nil`.
300  @param mimeType The declared MIME type of the file data. This parameter must not be `nil`.
301  @param error If an error occurs, upon return contains an `NSError` object that describes the problem.
302
303  @return `YES` if the file data was successfully appended otherwise `NO`.
304  */
305 - (BOOL)appendPartWithFileURL:(NSURL *)fileURL
306                          name:(NSString *)name
307                      fileName:(NSString *)fileName
308                      mimeType:(NSString *)mimeType
309                         error:(NSError * __nullable __autoreleasing *)error;
310
311 /**
312  Appends the HTTP header `Content-Disposition: file; filename=#{filename}; name=#{name}"` and `Content-Type: #{mimeType}`, followed by the data from the input stream and the multipart form boundary.
313
314  @param inputStream The input stream to be appended to the form data
315  @param name The name to be associated with the specified input stream. This parameter must not be `nil`.
316  @param fileName The filename to be associated with the specified input stream. This parameter must not be `nil`.
317  @param length The length of the specified input stream in bytes.
318  @param mimeType The MIME type of the specified data. (For example, the MIME type for a JPEG image is image/jpeg.) For a list of valid MIME types, see http://www.iana.org/assignments/media-types/. This parameter must not be `nil`.
319  */
320 - (void)appendPartWithInputStream:(nullable NSInputStream *)inputStream
321                              name:(NSString *)name
322                          fileName:(NSString *)fileName
323                            length:(int64_t)length
324                          mimeType:(NSString *)mimeType;
325
326 /**
327  Appends the HTTP header `Content-Disposition: file; filename=#{filename}; name=#{name}"` and `Content-Type: #{mimeType}`, followed by the encoded file data and the multipart form boundary.
328
329  @param data The data to be encoded and appended to the form data.
330  @param name The name to be associated with the specified data. This parameter must not be `nil`.
331  @param fileName The filename to be associated with the specified data. This parameter must not be `nil`.
332  @param mimeType The MIME type of the specified data. (For example, the MIME type for a JPEG image is image/jpeg.) For a list of valid MIME types, see http://www.iana.org/assignments/media-types/. This parameter must not be `nil`.
333  */
334 - (void)appendPartWithFileData:(NSData *)data
335                           name:(NSString *)name
336                       fileName:(NSString *)fileName
337                       mimeType:(NSString *)mimeType;
338
339 /**
340  Appends the HTTP headers `Content-Disposition: form-data; name=#{name}"`, followed by the encoded data and the multipart form boundary.
341
342  @param data The data to be encoded and appended to the form data.
343  @param name The name to be associated with the specified data. This parameter must not be `nil`.
344  */
345
346 - (void)appendPartWithFormData:(NSData *)data
347                           name:(NSString *)name;
348
349
350 /**
351  Appends HTTP headers, followed by the encoded data and the multipart form boundary.
352
353  @param headers The HTTP headers to be appended to the form data.
354  @param body The data to be encoded and appended to the form data. This parameter must not be `nil`.
355  */
356 - (void)appendPartWithHeaders:(nullable NSDictionary *)headers
357                          body:(NSData *)body;
358
359 /**
360  Throttles request bandwidth by limiting the packet size and adding a delay for each chunk read from the upload stream.
361
362  When uploading over a 3G or EDGE connection, requests may fail with "request body stream exhausted". Setting a maximum packet size and delay according to the recommended values (`kAFUploadStream3GSuggestedPacketSize` and `kAFUploadStream3GSuggestedDelay`) lowers the risk of the input stream exceeding its allocated bandwidth. Unfortunately, there is no definite way to distinguish between a 3G, EDGE, or LTE connection over `NSURLConnection`. As such, it is not recommended that you throttle bandwidth based solely on network reachability. Instead, you should consider checking for the "request body stream exhausted" in a failure block, and then retrying the request with throttled bandwidth.
363
364  @param numberOfBytes Maximum packet size, in number of bytes. The default packet size for an input stream is 16kb.
365  @param delay Duration of delay each time a packet is read. By default, no delay is set.
366  */
367 - (void)throttleBandwidthWithPacketSize:(NSUInteger)numberOfBytes
368                                   delay:(NSTimeInterval)delay;
369
370 @end
371
372 #pragma mark -
373
374 /**
375  `AFJSONRequestSerializer` is a subclass of `AFHTTPRequestSerializer` that encodes parameters as JSON using `NSJSONSerialization`, setting the `Content-Type` of the encoded request to `application/json`.
376  */
377 @interface AFJSONRequestSerializer : AFHTTPRequestSerializer
378
379 /**
380  Options for writing the request JSON data from Foundation objects. For possible values, see the `NSJSONSerialization` documentation section "NSJSONWritingOptions". `0` by default.
381  */
382 @property (nonatomic, assign) NSJSONWritingOptions writingOptions;
383
384 /**
385  Creates and returns a JSON serializer with specified reading and writing options.
386
387  @param writingOptions The specified JSON writing options.
388  */
389 + (instancetype)serializerWithWritingOptions:(NSJSONWritingOptions)writingOptions;
390
391 @end
392
393 #pragma mark -
394
395 /**
396  `AFPropertyListRequestSerializer` is a subclass of `AFHTTPRequestSerializer` that encodes parameters as JSON using `NSPropertyListSerializer`, setting the `Content-Type` of the encoded request to `application/x-plist`.
397  */
398 @interface AFPropertyListRequestSerializer : AFHTTPRequestSerializer
399
400 /**
401  The property list format. Possible values are described in "NSPropertyListFormat".
402  */
403 @property (nonatomic, assign) NSPropertyListFormat format;
404
405 /**
406  @warning The `writeOptions` property is currently unused.
407  */
408 @property (nonatomic, assign) NSPropertyListWriteOptions writeOptions;
409
410 /**
411  Creates and returns a property list serializer with a specified format, read options, and write options.
412
413  @param format The property list format.
414  @param writeOptions The property list write options.
415
416  @warning The `writeOptions` property is currently unused.
417  */
418 + (instancetype)serializerWithFormat:(NSPropertyListFormat)format
419                         writeOptions:(NSPropertyListWriteOptions)writeOptions;
420
421 @end
422
423 #pragma mark -
424
425 ///----------------
426 /// @name Constants
427 ///----------------
428
429 /**
430  ## Error Domains
431
432  The following error domain is predefined.
433
434  - `NSString * const AFURLRequestSerializationErrorDomain`
435
436  ### Constants
437
438  `AFURLRequestSerializationErrorDomain`
439  AFURLRequestSerializer errors. Error codes for `AFURLRequestSerializationErrorDomain` correspond to codes in `NSURLErrorDomain`.
440  */
441 extern NSString * const AFURLRequestSerializationErrorDomain;
442
443 /**
444  ## User info dictionary keys
445
446  These keys may exist in the user info dictionary, in addition to those defined for NSError.
447
448  - `NSString * const AFNetworkingOperationFailingURLRequestErrorKey`
449
450  ### Constants
451
452  `AFNetworkingOperationFailingURLRequestErrorKey`
453  The corresponding value is an `NSURLRequest` containing the request of the operation associated with an error. This key is only present in the `AFURLRequestSerializationErrorDomain`.
454  */
455 extern NSString * const AFNetworkingOperationFailingURLRequestErrorKey;
456
457 /**
458  ## Throttling Bandwidth for HTTP Request Input Streams
459
460  @see -throttleBandwidthWithPacketSize:delay:
461
462  ### Constants
463
464  `kAFUploadStream3GSuggestedPacketSize`
465  Maximum packet size, in number of bytes. Equal to 16kb.
466
467  `kAFUploadStream3GSuggestedDelay`
468  Duration of delay each time a packet is read. Equal to 0.2 seconds.
469  */
470 extern NSUInteger const kAFUploadStream3GSuggestedPacketSize;
471 extern NSTimeInterval const kAFUploadStream3GSuggestedDelay;
472
473 NS_ASSUME_NONNULL_END