国内WASDK WA实现层
view | history | commit | commitdiff
lpw
2022-06-21 4aeed2fc76be6749888e9982d8902b520c650d71
commit | author | age
6e1425 1 // AFURLRequestSerialization.h
633752 2 // Copyright (c) 2011–2016 Alamofire Software Foundation ( http://alamofire.org/ )
6e1425 3 //
H 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>
633752 23 #import <TargetConditionals.h>
L 24
25 #if TARGET_OS_IOS || TARGET_OS_TV
6e1425 26 #import <UIKit/UIKit.h>
H 27 #elif TARGET_OS_WATCH
28 #import <WatchKit/WatchKit.h>
29 #endif
30
31 NS_ASSUME_NONNULL_BEGIN
633752 32
L 33 /**
34  Returns a percent-escaped string following RFC 3986 for a query string key or value.
35  RFC 3986 states that the following characters are "reserved" characters.
36  - General Delimiters: ":", "#", "[", "]", "@", "?", "/"
37  - Sub-Delimiters: "!", "$", "&", "'", "(", ")", "*", "+", ",", ";", "="
38
39  In RFC 3986 - Section 3.4, it states that the "?" and "/" characters should not be escaped to allow
40  query strings to include a URL. Therefore, all "reserved" characters with the exception of "?" and "/"
41  should be percent-escaped in the query string.
42  
43  @param string The string to be percent-escaped.
44  
45  @return The percent-escaped string.
46  */
47 FOUNDATION_EXPORT NSString * AFPercentEscapedStringFromString(NSString *string);
48
49 /**
50  A helper method to generate encoded url query parameters for appending to the end of a URL.
51
52  @param parameters A dictionary of key/values to be encoded.
53
54  @return A url encoded query string
55  */
56 FOUNDATION_EXPORT NSString * AFQueryStringFromParameters(NSDictionary *parameters);
6e1425 57
H 58 /**
59  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.
60
61  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`.
62  */
63 @protocol AFURLRequestSerialization <NSObject, NSSecureCoding, NSCopying>
64
65 /**
66  Returns a request with the specified parameters encoded into a copy of the original request.
67
68  @param request The original request.
69  @param parameters The parameters to be encoded.
70  @param error The error that occurred while attempting to encode the request parameters.
71
72  @return A serialized request.
73  */
74 - (nullable NSURLRequest *)requestBySerializingRequest:(NSURLRequest *)request
75                                withParameters:(nullable id)parameters
633752 76                                         error:(NSError * _Nullable __autoreleasing *)error NS_SWIFT_NOTHROW;
6e1425 77
H 78 @end
79
80 #pragma mark -
81
82 /**
83
84  */
85 typedef NS_ENUM(NSUInteger, AFHTTPRequestQueryStringSerializationStyle) {
86     AFHTTPRequestQueryStringDefaultStyle = 0,
87 };
88
89 @protocol AFMultipartFormData;
90
91 /**
92  `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.
93
94  Any request or response serializer dealing with HTTP is encouraged to subclass `AFHTTPRequestSerializer` in order to ensure consistent default behavior.
95  */
96 @interface AFHTTPRequestSerializer : NSObject <AFURLRequestSerialization>
97
98 /**
99  The string encoding used to serialize parameters. `NSUTF8StringEncoding` by default.
100  */
101 @property (nonatomic, assign) NSStringEncoding stringEncoding;
102
103 /**
104  Whether created requests can use the device’s cellular radio (if present). `YES` by default.
105
106  @see NSMutableURLRequest -setAllowsCellularAccess:
107  */
108 @property (nonatomic, assign) BOOL allowsCellularAccess;
109
110 /**
111  The cache policy of created requests. `NSURLRequestUseProtocolCachePolicy` by default.
112
113  @see NSMutableURLRequest -setCachePolicy:
114  */
115 @property (nonatomic, assign) NSURLRequestCachePolicy cachePolicy;
116
117 /**
118  Whether created requests should use the default cookie handling. `YES` by default.
119
120  @see NSMutableURLRequest -setHTTPShouldHandleCookies:
121  */
122 @property (nonatomic, assign) BOOL HTTPShouldHandleCookies;
123
124 /**
125  Whether created requests can continue transmitting data before receiving a response from an earlier transmission. `NO` by default
126
127  @see NSMutableURLRequest -setHTTPShouldUsePipelining:
128  */
129 @property (nonatomic, assign) BOOL HTTPShouldUsePipelining;
130
131 /**
132  The network service type for created requests. `NSURLNetworkServiceTypeDefault` by default.
133
134  @see NSMutableURLRequest -setNetworkServiceType:
135  */
136 @property (nonatomic, assign) NSURLRequestNetworkServiceType networkServiceType;
137
138 /**
139  The timeout interval, in seconds, for created requests. The default timeout interval is 60 seconds.
140
141  @see NSMutableURLRequest -setTimeoutInterval:
142  */
143 @property (nonatomic, assign) NSTimeInterval timeoutInterval;
144
145 ///---------------------------------------
146 /// @name Configuring HTTP Request Headers
147 ///---------------------------------------
148
149 /**
150  Default HTTP header field values to be applied to serialized requests. By default, these include the following:
151
152  - `Accept-Language` with the contents of `NSLocale +preferredLanguages`
153  - `User-Agent` with the contents of various bundle identifiers and OS designations
154
155  @discussion To add or remove default request headers, use `setValue:forHTTPHeaderField:`.
156  */
633752 157 @property (readonly, nonatomic, strong) NSDictionary <NSString *, NSString *> *HTTPRequestHeaders;
6e1425 158
H 159 /**
160  Creates and returns a serializer with default configuration.
161  */
162 + (instancetype)serializer;
163
164 /**
165  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.
166
167  @param field The HTTP header to set a default value for
168  @param value The value set as default for the specified header, or `nil`
169  */
170 - (void)setValue:(nullable NSString *)value
171 forHTTPHeaderField:(NSString *)field;
172
173 /**
174  Returns the value for the HTTP headers set in the request serializer.
175
176  @param field The HTTP header to retrieve the default value for
177
178  @return The value set as default for the specified header, or `nil`
179  */
180 - (nullable NSString *)valueForHTTPHeaderField:(NSString *)field;
181
182 /**
183  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.
184
185  @param username The HTTP basic auth username
186  @param password The HTTP basic auth password
187  */
188 - (void)setAuthorizationHeaderFieldWithUsername:(NSString *)username
189                                        password:(NSString *)password;
190
191 /**
192  Clears any existing value for the "Authorization" HTTP header.
193  */
194 - (void)clearAuthorizationHeader;
195
196 ///-------------------------------------------------------
197 /// @name Configuring Query String Parameter Serialization
198 ///-------------------------------------------------------
199
200 /**
201  HTTP methods for which serialized requests will encode parameters as a query string. `GET`, `HEAD`, and `DELETE` by default.
202  */
633752 203 @property (nonatomic, strong) NSSet <NSString *> *HTTPMethodsEncodingParametersInURI;
6e1425 204
H 205 /**
206  Set the method of query string serialization according to one of the pre-defined styles.
207
208  @param style The serialization style.
209
210  @see AFHTTPRequestQueryStringSerializationStyle
211  */
212 - (void)setQueryStringSerializationWithStyle:(AFHTTPRequestQueryStringSerializationStyle)style;
213
214 /**
215  Set the a custom method of query string serialization according to the specified block.
216
217  @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.
218  */
bf3f86 219 - (void)setQueryStringSerializationWithBlock:(nullable NSString * _Nullable (^)(NSURLRequest *request, id parameters, NSError * __autoreleasing *error))block;
6e1425 220
H 221 ///-------------------------------
222 /// @name Creating Request Objects
223 ///-------------------------------
224
225 /**
226  Creates an `NSMutableURLRequest` object with the specified HTTP method and URL string.
227
228  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.
229
230  @param method The HTTP method for the request, such as `GET`, `POST`, `PUT`, or `DELETE`. This parameter must not be `nil`.
231  @param URLString The URL string used to create the request URL.
232  @param parameters The parameters to be either set as a query string for `GET` requests, or the request HTTP body.
233  @param error The error that occurred while constructing the request.
234
235  @return An `NSMutableURLRequest` object.
236  */
bf3f86 237 - (nullable NSMutableURLRequest *)requestWithMethod:(NSString *)method
L 238                                           URLString:(NSString *)URLString
239                                          parameters:(nullable id)parameters
240                                               error:(NSError * _Nullable __autoreleasing *)error;
6e1425 241
H 242 /**
243  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
244
245  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.
246
247  @param method The HTTP method for the request. This parameter must not be `GET` or `HEAD`, or `nil`.
248  @param URLString The URL string used to create the request URL.
249  @param parameters The parameters to be encoded and set in the request HTTP body.
250  @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.
251  @param error The error that occurred while constructing the request.
252
253  @return An `NSMutableURLRequest` object
254  */
255 - (NSMutableURLRequest *)multipartFormRequestWithMethod:(NSString *)method
256                                               URLString:(NSString *)URLString
633752 257                                              parameters:(nullable NSDictionary <NSString *, id> *)parameters
6e1425 258                               constructingBodyWithBlock:(nullable void (^)(id <AFMultipartFormData> formData))block
633752 259                                                   error:(NSError * _Nullable __autoreleasing *)error;
6e1425 260
H 261 /**
262  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.
263
264  @param request The multipart form request. The `HTTPBodyStream` property of `request` must not be `nil`.
265  @param fileURL The file URL to write multipart form contents to.
266  @param handler A handler block to execute.
267
268  @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.
269
270  @see https://github.com/AFNetworking/AFNetworking/issues/1398
271  */
272 - (NSMutableURLRequest *)requestWithMultipartFormRequest:(NSURLRequest *)request
273                              writingStreamContentsToFile:(NSURL *)fileURL
633752 274                                        completionHandler:(nullable void (^)(NSError * _Nullable error))handler;
6e1425 275
H 276 @end
277
278 #pragma mark -
279
280 /**
281  The `AFMultipartFormData` protocol defines the methods supported by the parameter in the block argument of `AFHTTPRequestSerializer -multipartFormRequestWithMethod:URLString:parameters:constructingBodyWithBlock:`.
282  */
283 @protocol AFMultipartFormData
284
285 /**
286  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.
287
288  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.
289
290  @param fileURL The URL corresponding to the file whose content will be appended to the form. This parameter must not be `nil`.
291  @param name The name to be associated with the specified data. This parameter must not be `nil`.
292  @param error If an error occurs, upon return contains an `NSError` object that describes the problem.
293
294  @return `YES` if the file data was successfully appended, otherwise `NO`.
295  */
296 - (BOOL)appendPartWithFileURL:(NSURL *)fileURL
297                          name:(NSString *)name
633752 298                         error:(NSError * _Nullable __autoreleasing *)error;
6e1425 299
H 300 /**
301  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.
302
303  @param fileURL The URL corresponding to the file whose content will be appended to the form. This parameter must not be `nil`.
304  @param name The name to be associated with the specified data. This parameter must not be `nil`.
305  @param fileName The file name to be used in the `Content-Disposition` header. This parameter must not be `nil`.
306  @param mimeType The declared MIME type of the file data. This parameter must not be `nil`.
307  @param error If an error occurs, upon return contains an `NSError` object that describes the problem.
308
309  @return `YES` if the file data was successfully appended otherwise `NO`.
310  */
311 - (BOOL)appendPartWithFileURL:(NSURL *)fileURL
312                          name:(NSString *)name
313                      fileName:(NSString *)fileName
314                      mimeType:(NSString *)mimeType
633752 315                         error:(NSError * _Nullable __autoreleasing *)error;
6e1425 316
H 317 /**
318  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.
319
320  @param inputStream The input stream to be appended to the form data
321  @param name The name to be associated with the specified input stream. This parameter must not be `nil`.
322  @param fileName The filename to be associated with the specified input stream. This parameter must not be `nil`.
323  @param length The length of the specified input stream in bytes.
324  @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`.
325  */
326 - (void)appendPartWithInputStream:(nullable NSInputStream *)inputStream
327                              name:(NSString *)name
328                          fileName:(NSString *)fileName
329                            length:(int64_t)length
330                          mimeType:(NSString *)mimeType;
331
332 /**
333  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.
334
335  @param data The data to be encoded and appended to the form data.
336  @param name The name to be associated with the specified data. This parameter must not be `nil`.
337  @param fileName The filename to be associated with the specified data. This parameter must not be `nil`.
338  @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`.
339  */
340 - (void)appendPartWithFileData:(NSData *)data
341                           name:(NSString *)name
342                       fileName:(NSString *)fileName
343                       mimeType:(NSString *)mimeType;
344
345 /**
346  Appends the HTTP headers `Content-Disposition: form-data; name=#{name}"`, followed by the encoded data and the multipart form boundary.
347
348  @param data The data to be encoded and appended to the form data.
349  @param name The name to be associated with the specified data. This parameter must not be `nil`.
350  */
351
352 - (void)appendPartWithFormData:(NSData *)data
353                           name:(NSString *)name;
354
355
356 /**
357  Appends HTTP headers, followed by the encoded data and the multipart form boundary.
358
359  @param headers The HTTP headers to be appended to the form data.
360  @param body The data to be encoded and appended to the form data. This parameter must not be `nil`.
361  */
633752 362 - (void)appendPartWithHeaders:(nullable NSDictionary <NSString *, NSString *> *)headers
6e1425 363                          body:(NSData *)body;
H 364
365 /**
366  Throttles request bandwidth by limiting the packet size and adding a delay for each chunk read from the upload stream.
367
368  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.
369
370  @param numberOfBytes Maximum packet size, in number of bytes. The default packet size for an input stream is 16kb.
371  @param delay Duration of delay each time a packet is read. By default, no delay is set.
372  */
373 - (void)throttleBandwidthWithPacketSize:(NSUInteger)numberOfBytes
374                                   delay:(NSTimeInterval)delay;
375
376 @end
377
378 #pragma mark -
379
380 /**
381  `AFJSONRequestSerializer` is a subclass of `AFHTTPRequestSerializer` that encodes parameters as JSON using `NSJSONSerialization`, setting the `Content-Type` of the encoded request to `application/json`.
382  */
383 @interface AFJSONRequestSerializer : AFHTTPRequestSerializer
384
385 /**
386  Options for writing the request JSON data from Foundation objects. For possible values, see the `NSJSONSerialization` documentation section "NSJSONWritingOptions". `0` by default.
387  */
388 @property (nonatomic, assign) NSJSONWritingOptions writingOptions;
389
390 /**
391  Creates and returns a JSON serializer with specified reading and writing options.
392
393  @param writingOptions The specified JSON writing options.
394  */
395 + (instancetype)serializerWithWritingOptions:(NSJSONWritingOptions)writingOptions;
396
397 @end
398
399 #pragma mark -
400
401 /**
402  `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`.
403  */
404 @interface AFPropertyListRequestSerializer : AFHTTPRequestSerializer
405
406 /**
407  The property list format. Possible values are described in "NSPropertyListFormat".
408  */
409 @property (nonatomic, assign) NSPropertyListFormat format;
410
411 /**
412  @warning The `writeOptions` property is currently unused.
413  */
414 @property (nonatomic, assign) NSPropertyListWriteOptions writeOptions;
415
416 /**
417  Creates and returns a property list serializer with a specified format, read options, and write options.
418
419  @param format The property list format.
420  @param writeOptions The property list write options.
421
422  @warning The `writeOptions` property is currently unused.
423  */
424 + (instancetype)serializerWithFormat:(NSPropertyListFormat)format
425                         writeOptions:(NSPropertyListWriteOptions)writeOptions;
426
427 @end
428
429 #pragma mark -
430
431 ///----------------
432 /// @name Constants
433 ///----------------
434
435 /**
436  ## Error Domains
437
438  The following error domain is predefined.
439
440  - `NSString * const AFURLRequestSerializationErrorDomain`
441
442  ### Constants
443
444  `AFURLRequestSerializationErrorDomain`
445  AFURLRequestSerializer errors. Error codes for `AFURLRequestSerializationErrorDomain` correspond to codes in `NSURLErrorDomain`.
446  */
633752 447 FOUNDATION_EXPORT NSString * const AFURLRequestSerializationErrorDomain;
6e1425 448
H 449 /**
450  ## User info dictionary keys
451
452  These keys may exist in the user info dictionary, in addition to those defined for NSError.
453
454  - `NSString * const AFNetworkingOperationFailingURLRequestErrorKey`
455
456  ### Constants
457
458  `AFNetworkingOperationFailingURLRequestErrorKey`
459  The corresponding value is an `NSURLRequest` containing the request of the operation associated with an error. This key is only present in the `AFURLRequestSerializationErrorDomain`.
460  */
633752 461 FOUNDATION_EXPORT NSString * const AFNetworkingOperationFailingURLRequestErrorKey;
6e1425 462
H 463 /**
464  ## Throttling Bandwidth for HTTP Request Input Streams
465
466  @see -throttleBandwidthWithPacketSize:delay:
467
468  ### Constants
469
470  `kAFUploadStream3GSuggestedPacketSize`
471  Maximum packet size, in number of bytes. Equal to 16kb.
472
473  `kAFUploadStream3GSuggestedDelay`
474  Duration of delay each time a packet is read. Equal to 0.2 seconds.
475  */
633752 476 FOUNDATION_EXPORT NSUInteger const kAFUploadStream3GSuggestedPacketSize;
L 477 FOUNDATION_EXPORT NSTimeInterval const kAFUploadStream3GSuggestedDelay;
6e1425 478
H 479 NS_ASSUME_NONNULL_END