view | history | commit | commitdiff
Wuyx
2017-01-04 0ba5a82e9ec833aa36729dfbad7deffbf3ea05c6
commit | author | age
6e1425 1 // AFHTTPRequestOperationManager.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 #import <SystemConfiguration/SystemConfiguration.h>
24 #import <Availability.h>
25
26 #if __IPHONE_OS_VERSION_MIN_REQUIRED
27 #import <MobileCoreServices/MobileCoreServices.h>
28 #else
29 #import <CoreServices/CoreServices.h>
30 #endif
31
32 #import "AFHTTPRequestOperation.h"
33 #import "AFURLResponseSerialization.h"
34 #import "AFURLRequestSerialization.h"
35 #import "AFSecurityPolicy.h"
36 #import "AFNetworkReachabilityManager.h"
37
38 #ifndef NS_DESIGNATED_INITIALIZER
39 #if __has_attribute(objc_designated_initializer)
40 #define NS_DESIGNATED_INITIALIZER __attribute__((objc_designated_initializer))
41 #else
42 #define NS_DESIGNATED_INITIALIZER
43 #endif
44 #endif
45
46 NS_ASSUME_NONNULL_BEGIN
47
48 /**
49  `AFHTTPRequestOperationManager` encapsulates the common patterns of communicating with a web application over HTTP, including request creation, response serialization, network reachability monitoring, and security, as well as request operation management.
50
51  ## Subclassing Notes
52
53  Developers targeting iOS 7 or Mac OS X 10.9 or later that deal extensively with a web service are encouraged to subclass `AFHTTPSessionManager`, providing a class method that returns a shared singleton object on which authentication and other configuration can be shared across the application.
54
55  For developers targeting iOS 6 or Mac OS X 10.8 or earlier, `AFHTTPRequestOperationManager` may be used to similar effect.
56
57  ## Methods to Override
58
59  To change the behavior of all request operation construction for an `AFHTTPRequestOperationManager` subclass, override `HTTPRequestOperationWithRequest:success:failure`.
60
61  ## Serialization
62
63  Requests created by an HTTP client will contain default headers and encode parameters according to the `requestSerializer` property, which is an object conforming to `<AFURLRequestSerialization>`.
64
65  Responses received from the server are automatically validated and serialized by the `responseSerializers` property, which is an object conforming to `<AFURLResponseSerialization>`
66
67  ## URL Construction Using Relative Paths
68
69  For HTTP convenience methods, the request serializer constructs URLs from the path relative to the `-baseURL`, using `NSURL +URLWithString:relativeToURL:`, when provided. If `baseURL` is `nil`, `path` needs to resolve to a valid `NSURL` object using `NSURL +URLWithString:`.
70
71  Below are a few examples of how `baseURL` and relative paths interact:
72
73     NSURL *baseURL = [NSURL URLWithString:@"http://example.com/v1/"];
74     [NSURL URLWithString:@"foo" relativeToURL:baseURL];                  // http://example.com/v1/foo
75     [NSURL URLWithString:@"foo?bar=baz" relativeToURL:baseURL];          // http://example.com/v1/foo?bar=baz
76     [NSURL URLWithString:@"/foo" relativeToURL:baseURL];                 // http://example.com/foo
77     [NSURL URLWithString:@"foo/" relativeToURL:baseURL];                 // http://example.com/v1/foo
78     [NSURL URLWithString:@"/foo/" relativeToURL:baseURL];                // http://example.com/foo/
79     [NSURL URLWithString:@"http://example2.com/" relativeToURL:baseURL]; // http://example2.com/
80
81  Also important to note is that a trailing slash will be added to any `baseURL` without one. This would otherwise cause unexpected behavior when constructing URLs using paths without a leading slash.
82
83  ## Network Reachability Monitoring
84
85  Network reachability status and change monitoring is available through the `reachabilityManager` property. Applications may choose to monitor network reachability conditions in order to prevent or suspend any outbound requests. See `AFNetworkReachabilityManager` for more details.
86
87  ## NSSecureCoding & NSCopying Caveats
88
89  `AFHTTPRequestOperationManager` conforms to the `NSSecureCoding` and `NSCopying` protocols, allowing operations to be archived to disk, and copied in memory, respectively. There are a few minor caveats to keep in mind, however:
90
91  - Archives and copies of HTTP clients will be initialized with an empty operation queue.
92  - NSSecureCoding cannot serialize / deserialize block properties, so an archive of an HTTP client will not include any reachability callback block that may be set.
93  */
94 @interface AFHTTPRequestOperationManager : NSObject <NSSecureCoding, NSCopying>
95
96 /**
97  The URL used to monitor reachability, and construct requests from relative paths in methods like `requestWithMethod:URLString:parameters:`, and the `GET` / `POST` / et al. convenience methods.
98  */
99 @property (readonly, nonatomic, strong, nullable) NSURL *baseURL;
100
101 /**
102  Requests created with `requestWithMethod:URLString:parameters:` & `multipartFormRequestWithMethod:URLString:parameters:constructingBodyWithBlock:` are constructed with a set of default headers using a parameter serialization specified by this property. By default, this is set to an instance of `AFHTTPRequestSerializer`, which serializes query string parameters for `GET`, `HEAD`, and `DELETE` requests, or otherwise URL-form-encodes HTTP message bodies.
103
104  @warning `requestSerializer` must not be `nil`.
105  */
106 @property (nonatomic, strong) AFHTTPRequestSerializer <AFURLRequestSerialization> * requestSerializer;
107
108 /**
109  Responses sent from the server in data tasks created with `dataTaskWithRequest:success:failure:` and run using the `GET` / `POST` / et al. convenience methods are automatically validated and serialized by the response serializer. By default, this property is set to a JSON serializer, which serializes data from responses with a `application/json` MIME type, and falls back to the raw data object. The serializer validates the status code to be in the `2XX` range, denoting success. If the response serializer generates an error in `-responseObjectForResponse:data:error:`, the `failure` callback of the session task or request operation will be executed; otherwise, the `success` callback will be executed.
110
111  @warning `responseSerializer` must not be `nil`.
112  */
113 @property (nonatomic, strong) AFHTTPResponseSerializer <AFURLResponseSerialization> * responseSerializer;
114
115 /**
116  The operation queue on which request operations are scheduled and run.
117  */
118 @property (nonatomic, strong) NSOperationQueue *operationQueue;
119
120 ///-------------------------------
121 /// @name Managing URL Credentials
122 ///-------------------------------
123
124 /**
125  Whether request operations should consult the credential storage for authenticating the connection. `YES` by default.
126
127  @see AFURLConnectionOperation -shouldUseCredentialStorage
128  */
129 @property (nonatomic, assign) BOOL shouldUseCredentialStorage;
130
131 /**
132  The credential used by request operations for authentication challenges.
133
134  @see AFURLConnectionOperation -credential
135  */
136 @property (nonatomic, strong, nullable) NSURLCredential *credential;
137
138 ///-------------------------------
139 /// @name Managing Security Policy
140 ///-------------------------------
141
142 /**
143  The security policy used by created request operations to evaluate server trust for secure connections. `AFHTTPRequestOperationManager` uses the `defaultPolicy` unless otherwise specified.
144  */
145 @property (nonatomic, strong) AFSecurityPolicy *securityPolicy;
146
147 ///------------------------------------
148 /// @name Managing Network Reachability
149 ///------------------------------------
150
151 /**
152  The network reachability manager. `AFHTTPRequestOperationManager` uses the `sharedManager` by default.
153  */
154 @property (readwrite, nonatomic, strong) AFNetworkReachabilityManager *reachabilityManager;
155
156 ///-------------------------------
157 /// @name Managing Callback Queues
158 ///-------------------------------
159
160 /**
161  The dispatch queue for the `completionBlock` of request operations. If `NULL` (default), the main queue is used.
162  */
163 #if OS_OBJECT_HAVE_OBJC_SUPPORT
164 @property (nonatomic, strong, nullable) dispatch_queue_t completionQueue;
165 #else
166 @property (nonatomic, assign, nullable) dispatch_queue_t completionQueue;
167 #endif
168
169 /**
170  The dispatch group for the `completionBlock` of request operations. If `NULL` (default), a private dispatch group is used.
171  */
172 #if OS_OBJECT_HAVE_OBJC_SUPPORT
173 @property (nonatomic, strong, nullable) dispatch_group_t completionGroup;
174 #else
175 @property (nonatomic, assign, nullable) dispatch_group_t completionGroup;
176 #endif
177
178 ///---------------------------------------------
179 /// @name Creating and Initializing HTTP Clients
180 ///---------------------------------------------
181
182 /**
183  Creates and returns an `AFHTTPRequestOperationManager` object.
184  */
185 + (instancetype)manager;
186
187 /**
188  Initializes an `AFHTTPRequestOperationManager` object with the specified base URL.
189
190  This is the designated initializer.
191
192  @param url The base URL for the HTTP client.
193
194  @return The newly-initialized HTTP client
195  */
196 - (instancetype)initWithBaseURL:(nullable NSURL *)url NS_DESIGNATED_INITIALIZER;
197
198 ///---------------------------------------
199 /// @name Managing HTTP Request Operations
200 ///---------------------------------------
201
202 /**
203  Creates an `AFHTTPRequestOperation`, and sets the response serializers to that of the HTTP client.
204
205  @param request The request object to be loaded asynchronously during execution of the operation.
206  @param success A block object to be executed when the request operation finishes successfully. This block has no return value and takes two arguments: the created request operation and the object created from the response data of request.
207  @param failure A block object to be executed when the request operation finishes unsuccessfully, or that finishes successfully, but encountered an error while parsing the response data. This block has no return value and takes two arguments:, the created request operation and the `NSError` object describing the network or parsing error that occurred.
208  */
209 - (AFHTTPRequestOperation *)HTTPRequestOperationWithRequest:(NSURLRequest *)request
210                                                     success:(nullable void (^)(AFHTTPRequestOperation *operation, id responseObject))success
211                                                     failure:(nullable void (^)(AFHTTPRequestOperation *operation, NSError *error))failure;
212
213 ///---------------------------
214 /// @name Making HTTP Requests
215 ///---------------------------
216
217 /**
218  Creates and runs an `AFHTTPRequestOperation` with a `GET` request.
219
220  @param URLString The URL string used to create the request URL.
221  @param parameters The parameters to be encoded according to the client request serializer.
222  @param success A block object to be executed when the request operation finishes successfully. This block has no return value and takes two arguments: the request operation, and the response object created by the client response serializer.
223  @param failure A block object to be executed when the request operation finishes unsuccessfully, or that finishes successfully, but encountered an error while parsing the response data. This block has no return value and takes a two arguments: the request operation and the error describing the network or parsing error that occurred.
224
225  @see -HTTPRequestOperationWithRequest:success:failure:
226  */
227 - (nullable AFHTTPRequestOperation *)GET:(NSString *)URLString
228                      parameters:(nullable id)parameters
229                         success:(nullable void (^)(AFHTTPRequestOperation *operation, id responseObject))success
230                         failure:(nullable void (^)(AFHTTPRequestOperation *operation, NSError *error))failure;
231
232 /**
233  Creates and runs an `AFHTTPRequestOperation` with a `HEAD` request.
234
235  @param URLString The URL string used to create the request URL.
236  @param parameters The parameters to be encoded according to the client request serializer.
237  @param success A block object to be executed when the request operation finishes successfully. This block has no return value and takes a single arguments: the request operation.
238  @param failure A block object to be executed when the request operation finishes unsuccessfully, or that finishes successfully, but encountered an error while parsing the response data. This block has no return value and takes a two arguments: the request operation and the error describing the network or parsing error that occurred.
239
240  @see -HTTPRequestOperationWithRequest:success:failure:
241  */
242 - (nullable AFHTTPRequestOperation *)HEAD:(NSString *)URLString
243                       parameters:(nullable id)parameters
244                          success:(nullable void (^)(AFHTTPRequestOperation *operation))success
245                          failure:(nullable void (^)(AFHTTPRequestOperation *operation, NSError *error))failure;
246
247 /**
248  Creates and runs an `AFHTTPRequestOperation` with a `POST` request.
249
250  @param URLString The URL string used to create the request URL.
251  @param parameters The parameters to be encoded according to the client request serializer.
252  @param success A block object to be executed when the request operation finishes successfully. This block has no return value and takes two arguments: the request operation, and the response object created by the client response serializer.
253  @param failure A block object to be executed when the request operation finishes unsuccessfully, or that finishes successfully, but encountered an error while parsing the response data. This block has no return value and takes a two arguments: the request operation and the error describing the network or parsing error that occurred.
254
255  @see -HTTPRequestOperationWithRequest:success:failure:
256  */
257 - (nullable AFHTTPRequestOperation *)POST:(NSString *)URLString
258                       parameters:(nullable id)parameters
259                          success:(nullable void (^)(AFHTTPRequestOperation *operation, id responseObject))success
260                          failure:(nullable void (^)(AFHTTPRequestOperation *operation, NSError *error))failure;
261
262 /**
263  Creates and runs an `AFHTTPRequestOperation` with a multipart `POST` request.
264
265  @param URLString The URL string used to create the request URL.
266  @param parameters The parameters to be encoded according to the client request serializer.
267  @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.
268  @param success A block object to be executed when the request operation finishes successfully. This block has no return value and takes two arguments: the request operation, and the response object created by the client response serializer.
269  @param failure A block object to be executed when the request operation finishes unsuccessfully, or that finishes successfully, but encountered an error while parsing the response data. This block has no return value and takes a two arguments: the request operation and the error describing the network or parsing error that occurred.
270
271  @see -HTTPRequestOperationWithRequest:success:failure:
272  */
273 - (nullable AFHTTPRequestOperation *)POST:(NSString *)URLString
274                       parameters:(nullable id)parameters
275        constructingBodyWithBlock:(nullable void (^)(id <AFMultipartFormData> formData))block
276                          success:(nullable void (^)(AFHTTPRequestOperation *operation, id responseObject))success
277                          failure:(nullable void (^)(AFHTTPRequestOperation *operation, NSError *error))failure;
278
279 /**
280  Creates and runs an `AFHTTPRequestOperation` with a `PUT` request.
281
282  @param URLString The URL string used to create the request URL.
283  @param parameters The parameters to be encoded according to the client request serializer.
284  @param success A block object to be executed when the request operation finishes successfully. This block has no return value and takes two arguments: the request operation, and the response object created by the client response serializer.
285  @param failure A block object to be executed when the request operation finishes unsuccessfully, or that finishes successfully, but encountered an error while parsing the response data. This block has no return value and takes a two arguments: the request operation and the error describing the network or parsing error that occurred.
286
287  @see -HTTPRequestOperationWithRequest:success:failure:
288  */
289 - (nullable AFHTTPRequestOperation *)PUT:(NSString *)URLString
290                      parameters:(nullable id)parameters
291                         success:(nullable void (^)(AFHTTPRequestOperation *operation, id responseObject))success
292                         failure:(nullable void (^)(AFHTTPRequestOperation *operation, NSError *error))failure;
293
294 /**
295  Creates and runs an `AFHTTPRequestOperation` with a `PATCH` request.
296
297  @param URLString The URL string used to create the request URL.
298  @param parameters The parameters to be encoded according to the client request serializer.
299  @param success A block object to be executed when the request operation finishes successfully. This block has no return value and takes two arguments: the request operation, and the response object created by the client response serializer.
300  @param failure A block object to be executed when the request operation finishes unsuccessfully, or that finishes successfully, but encountered an error while parsing the response data. This block has no return value and takes a two arguments: the request operation and the error describing the network or parsing error that occurred.
301
302  @see -HTTPRequestOperationWithRequest:success:failure:
303  */
304 - (nullable AFHTTPRequestOperation *)PATCH:(NSString *)URLString
305                        parameters:(nullable id)parameters
306                           success:(nullable void (^)(AFHTTPRequestOperation *operation, id responseObject))success
307                           failure:(nullable void (^)(AFHTTPRequestOperation *operation, NSError *error))failure;
308
309 /**
310  Creates and runs an `AFHTTPRequestOperation` with a `DELETE` request.
311
312  @param URLString The URL string used to create the request URL.
313  @param parameters The parameters to be encoded according to the client request serializer.
314  @param success A block object to be executed when the request operation finishes successfully. This block has no return value and takes two arguments: the request operation, and the response object created by the client response serializer.
315  @param failure A block object to be executed when the request operation finishes unsuccessfully, or that finishes successfully, but encountered an error while parsing the response data. This block has no return value and takes a two arguments: the request operation and the error describing the network or parsing error that occurred.
316
317  @see -HTTPRequestOperationWithRequest:success:failure:
318  */
319 - (nullable AFHTTPRequestOperation *)DELETE:(NSString *)URLString
320                         parameters:(nullable id)parameters
321                            success:(nullable void (^)(AFHTTPRequestOperation *operation, id responseObject))success
322                            failure:(nullable void (^)(AFHTTPRequestOperation *operation, NSError *error))failure;
323
324 @end
325
326 NS_ASSUME_NONNULL_END