view | history | commit | commitdiff
lipengwei
2020-01-13 01b433018ffe1577fcd2684437116bac5c8ae4a3
commit | author | age
6e1425 1 // AFURLSessionManager.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
633752 22
6e1425 23 #import <Foundation/Foundation.h>
H 24
25 #import "AFURLResponseSerialization.h"
26 #import "AFURLRequestSerialization.h"
27 #import "AFSecurityPolicy.h"
633752 28 #import "AFCompatibilityMacros.h"
6e1425 29 #if !TARGET_OS_WATCH
H 30 #import "AFNetworkReachabilityManager.h"
31 #endif
32
33 /**
34  `AFURLSessionManager` creates and manages an `NSURLSession` object based on a specified `NSURLSessionConfiguration` object, which conforms to `<NSURLSessionTaskDelegate>`, `<NSURLSessionDataDelegate>`, `<NSURLSessionDownloadDelegate>`, and `<NSURLSessionDelegate>`.
35
36  ## Subclassing Notes
37
38  This is the base class for `AFHTTPSessionManager`, which adds functionality specific to making HTTP requests. If you are looking to extend `AFURLSessionManager` specifically for HTTP, consider subclassing `AFHTTPSessionManager` instead.
39
40  ## NSURLSession & NSURLSessionTask Delegate Methods
41
42  `AFURLSessionManager` implements the following delegate methods:
43
44  ### `NSURLSessionDelegate`
45
46  - `URLSession:didBecomeInvalidWithError:`
47  - `URLSession:didReceiveChallenge:completionHandler:`
48  - `URLSessionDidFinishEventsForBackgroundURLSession:`
49
50  ### `NSURLSessionTaskDelegate`
51
52  - `URLSession:willPerformHTTPRedirection:newRequest:completionHandler:`
53  - `URLSession:task:didReceiveChallenge:completionHandler:`
54  - `URLSession:task:didSendBodyData:totalBytesSent:totalBytesExpectedToSend:`
633752 55  - `URLSession:task:needNewBodyStream:`
6e1425 56  - `URLSession:task:didCompleteWithError:`
H 57
58  ### `NSURLSessionDataDelegate`
59
60  - `URLSession:dataTask:didReceiveResponse:completionHandler:`
61  - `URLSession:dataTask:didBecomeDownloadTask:`
62  - `URLSession:dataTask:didReceiveData:`
63  - `URLSession:dataTask:willCacheResponse:completionHandler:`
64
65  ### `NSURLSessionDownloadDelegate`
66
67  - `URLSession:downloadTask:didFinishDownloadingToURL:`
68  - `URLSession:downloadTask:didWriteData:totalBytesWritten:totalBytesWritten:totalBytesExpectedToWrite:`
69  - `URLSession:downloadTask:didResumeAtOffset:expectedTotalBytes:`
70
71  If any of these methods are overridden in a subclass, they _must_ call the `super` implementation first.
72
73  ## Network Reachability Monitoring
74
75  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.
76
77  ## NSCoding Caveats
78
79  - Encoded managers do not include any block properties. Be sure to set delegate callback blocks when using `-initWithCoder:` or `NSKeyedUnarchiver`.
80
81  ## NSCopying Caveats
82
83  - `-copy` and `-copyWithZone:` return a new manager with a new `NSURLSession` created from the configuration of the original.
84  - Operation copies do not include any delegate callback blocks, as they often strongly captures a reference to `self`, which would otherwise have the unintuitive side-effect of pointing to the _original_ session manager when copied.
85
86  @warning Managers for background sessions must be owned for the duration of their use. This can be accomplished by creating an application-wide or shared singleton instance.
87  */
88
89 NS_ASSUME_NONNULL_BEGIN
90
91 @interface AFURLSessionManager : NSObject <NSURLSessionDelegate, NSURLSessionTaskDelegate, NSURLSessionDataDelegate, NSURLSessionDownloadDelegate, NSSecureCoding, NSCopying>
92
93 /**
94  The managed session.
95  */
96 @property (readonly, nonatomic, strong) NSURLSession *session;
97
98 /**
99  The operation queue on which delegate callbacks are run.
100  */
101 @property (readonly, nonatomic, strong) NSOperationQueue *operationQueue;
102
103 /**
104  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 an instance of `AFJSONResponseSerializer`.
105
106  @warning `responseSerializer` must not be `nil`.
107  */
108 @property (nonatomic, strong) id <AFURLResponseSerialization> responseSerializer;
109
110 ///-------------------------------
111 /// @name Managing Security Policy
112 ///-------------------------------
113
114 /**
633752 115  The security policy used by created session to evaluate server trust for secure connections. `AFURLSessionManager` uses the `defaultPolicy` unless otherwise specified.
6e1425 116  */
H 117 @property (nonatomic, strong) AFSecurityPolicy *securityPolicy;
118
119 #if !TARGET_OS_WATCH
120 ///--------------------------------------
121 /// @name Monitoring Network Reachability
122 ///--------------------------------------
123
124 /**
125  The network reachability manager. `AFURLSessionManager` uses the `sharedManager` by default.
126  */
127 @property (readwrite, nonatomic, strong) AFNetworkReachabilityManager *reachabilityManager;
128 #endif
129
130 ///----------------------------
131 /// @name Getting Session Tasks
132 ///----------------------------
133
134 /**
135  The data, upload, and download tasks currently run by the managed session.
136  */
633752 137 @property (readonly, nonatomic, strong) NSArray <NSURLSessionTask *> *tasks;
6e1425 138
H 139 /**
140  The data tasks currently run by the managed session.
141  */
633752 142 @property (readonly, nonatomic, strong) NSArray <NSURLSessionDataTask *> *dataTasks;
6e1425 143
H 144 /**
145  The upload tasks currently run by the managed session.
146  */
633752 147 @property (readonly, nonatomic, strong) NSArray <NSURLSessionUploadTask *> *uploadTasks;
6e1425 148
H 149 /**
150  The download tasks currently run by the managed session.
151  */
633752 152 @property (readonly, nonatomic, strong) NSArray <NSURLSessionDownloadTask *> *downloadTasks;
6e1425 153
H 154 ///-------------------------------
155 /// @name Managing Callback Queues
156 ///-------------------------------
157
158 /**
159  The dispatch queue for `completionBlock`. If `NULL` (default), the main queue is used.
160  */
161 @property (nonatomic, strong, nullable) dispatch_queue_t completionQueue;
162
163 /**
164  The dispatch group for `completionBlock`. If `NULL` (default), a private dispatch group is used.
165  */
166 @property (nonatomic, strong, nullable) dispatch_group_t completionGroup;
167
168 ///---------------------------------
169 /// @name Working Around System Bugs
170 ///---------------------------------
171
172 /**
173  Whether to attempt to retry creation of upload tasks for background sessions when initial call returns `nil`. `NO` by default.
174
175  @bug As of iOS 7.0, there is a bug where upload tasks created for background tasks are sometimes `nil`. As a workaround, if this property is `YES`, AFNetworking will follow Apple's recommendation to try creating the task again.
176
177  @see https://github.com/AFNetworking/AFNetworking/issues/1675
178  */
179 @property (nonatomic, assign) BOOL attemptsToRecreateUploadTasksForBackgroundSessions;
180
181 ///---------------------
182 /// @name Initialization
183 ///---------------------
184
185 /**
186  Creates and returns a manager for a session created with the specified configuration. This is the designated initializer.
187
188  @param configuration The configuration used to create the managed session.
189
190  @return A manager for a newly-created session.
191  */
192 - (instancetype)initWithSessionConfiguration:(nullable NSURLSessionConfiguration *)configuration NS_DESIGNATED_INITIALIZER;
193
194 /**
195  Invalidates the managed session, optionally canceling pending tasks.
196
197  @param cancelPendingTasks Whether or not to cancel pending tasks.
198  */
633752 199 - (void)invalidateSessionCancelingTasks:(BOOL)cancelPendingTasks DEPRECATED_ATTRIBUTE;
L 200
201 /**
202  Invalidates the managed session, optionally canceling pending tasks and optionally resets given session.
203  
204  @param cancelPendingTasks  Whether or not to cancel pending tasks.
205  @param resetSession        Whether or not to reset the session of the manager.
206  */
207 - (void)invalidateSessionCancelingTasks:(BOOL)cancelPendingTasks resetSession:(BOOL)resetSession;
6e1425 208
H 209 ///-------------------------
210 /// @name Running Data Tasks
211 ///-------------------------
212
213 /**
214  Creates an `NSURLSessionDataTask` with the specified request.
215
216  @param request The HTTP request for the request.
217  @param completionHandler A block object to be executed when the task finishes. This block has no return value and takes three arguments: the server response, the response object created by that serializer, and the error that occurred, if any.
218  */
219 - (NSURLSessionDataTask *)dataTaskWithRequest:(NSURLRequest *)request
633752 220                             completionHandler:(nullable void (^)(NSURLResponse *response, id _Nullable responseObject,  NSError * _Nullable error))completionHandler DEPRECATED_ATTRIBUTE;
L 221
222 /**
223  Creates an `NSURLSessionDataTask` with the specified request.
224
225  @param request The HTTP request for the request.
226  @param uploadProgressBlock A block object to be executed when the upload progress is updated. Note this block is called on the session queue, not the main queue.
227  @param downloadProgressBlock A block object to be executed when the download progress is updated. Note this block is called on the session queue, not the main queue.
228  @param completionHandler A block object to be executed when the task finishes. This block has no return value and takes three arguments: the server response, the response object created by that serializer, and the error that occurred, if any.
229  */
230 - (NSURLSessionDataTask *)dataTaskWithRequest:(NSURLRequest *)request
231                                uploadProgress:(nullable void (^)(NSProgress *uploadProgress))uploadProgressBlock
232                              downloadProgress:(nullable void (^)(NSProgress *downloadProgress))downloadProgressBlock
233                             completionHandler:(nullable void (^)(NSURLResponse *response, id _Nullable responseObject,  NSError * _Nullable error))completionHandler;
6e1425 234
H 235 ///---------------------------
236 /// @name Running Upload Tasks
237 ///---------------------------
238
239 /**
240  Creates an `NSURLSessionUploadTask` with the specified request for a local file.
241
242  @param request The HTTP request for the request.
243  @param fileURL A URL to the local file to be uploaded.
633752 244  @param uploadProgressBlock A block object to be executed when the upload progress is updated. Note this block is called on the session queue, not the main queue.
6e1425 245  @param completionHandler A block object to be executed when the task finishes. This block has no return value and takes three arguments: the server response, the response object created by that serializer, and the error that occurred, if any.
H 246
247  @see `attemptsToRecreateUploadTasksForBackgroundSessions`
248  */
249 - (NSURLSessionUploadTask *)uploadTaskWithRequest:(NSURLRequest *)request
250                                          fromFile:(NSURL *)fileURL
633752 251                                          progress:(nullable void (^)(NSProgress *uploadProgress))uploadProgressBlock
L 252                                 completionHandler:(nullable void (^)(NSURLResponse *response, id _Nullable responseObject, NSError  * _Nullable error))completionHandler;
6e1425 253
H 254 /**
255  Creates an `NSURLSessionUploadTask` with the specified request for an HTTP body.
256
257  @param request The HTTP request for the request.
258  @param bodyData A data object containing the HTTP body to be uploaded.
633752 259  @param uploadProgressBlock A block object to be executed when the upload progress is updated. Note this block is called on the session queue, not the main queue.
6e1425 260  @param completionHandler A block object to be executed when the task finishes. This block has no return value and takes three arguments: the server response, the response object created by that serializer, and the error that occurred, if any.
H 261  */
262 - (NSURLSessionUploadTask *)uploadTaskWithRequest:(NSURLRequest *)request
263                                          fromData:(nullable NSData *)bodyData
633752 264                                          progress:(nullable void (^)(NSProgress *uploadProgress))uploadProgressBlock
L 265                                 completionHandler:(nullable void (^)(NSURLResponse *response, id _Nullable responseObject, NSError * _Nullable error))completionHandler;
6e1425 266
H 267 /**
268  Creates an `NSURLSessionUploadTask` with the specified streaming request.
269
270  @param request The HTTP request for the request.
633752 271  @param uploadProgressBlock A block object to be executed when the upload progress is updated. Note this block is called on the session queue, not the main queue.
6e1425 272  @param completionHandler A block object to be executed when the task finishes. This block has no return value and takes three arguments: the server response, the response object created by that serializer, and the error that occurred, if any.
H 273  */
274 - (NSURLSessionUploadTask *)uploadTaskWithStreamedRequest:(NSURLRequest *)request
633752 275                                                  progress:(nullable void (^)(NSProgress *uploadProgress))uploadProgressBlock
L 276                                         completionHandler:(nullable void (^)(NSURLResponse *response, id _Nullable responseObject, NSError * _Nullable error))completionHandler;
6e1425 277
H 278 ///-----------------------------
279 /// @name Running Download Tasks
280 ///-----------------------------
281
282 /**
283  Creates an `NSURLSessionDownloadTask` with the specified request.
284
285  @param request The HTTP request for the request.
633752 286  @param downloadProgressBlock A block object to be executed when the download progress is updated. Note this block is called on the session queue, not the main queue.
6e1425 287  @param destination A block object to be executed in order to determine the destination of the downloaded file. This block takes two arguments, the target path & the server response, and returns the desired file URL of the resulting download. The temporary file used during the download will be automatically deleted after being moved to the returned URL.
H 288  @param completionHandler A block to be executed when a task finishes. This block has no return value and takes three arguments: the server response, the path of the downloaded file, and the error describing the network or parsing error that occurred, if any.
289
290  @warning If using a background `NSURLSessionConfiguration` on iOS, these blocks will be lost when the app is terminated. Background sessions may prefer to use `-setDownloadTaskDidFinishDownloadingBlock:` to specify the URL for saving the downloaded file, rather than the destination block of this method.
291  */
292 - (NSURLSessionDownloadTask *)downloadTaskWithRequest:(NSURLRequest *)request
633752 293                                              progress:(nullable void (^)(NSProgress *downloadProgress))downloadProgressBlock
6e1425 294                                           destination:(nullable NSURL * (^)(NSURL *targetPath, NSURLResponse *response))destination
633752 295                                     completionHandler:(nullable void (^)(NSURLResponse *response, NSURL * _Nullable filePath, NSError * _Nullable error))completionHandler;
6e1425 296
H 297 /**
298  Creates an `NSURLSessionDownloadTask` with the specified resume data.
299
300  @param resumeData The data used to resume downloading.
633752 301  @param downloadProgressBlock A block object to be executed when the download progress is updated. Note this block is called on the session queue, not the main queue.
6e1425 302  @param destination A block object to be executed in order to determine the destination of the downloaded file. This block takes two arguments, the target path & the server response, and returns the desired file URL of the resulting download. The temporary file used during the download will be automatically deleted after being moved to the returned URL.
H 303  @param completionHandler A block to be executed when a task finishes. This block has no return value and takes three arguments: the server response, the path of the downloaded file, and the error describing the network or parsing error that occurred, if any.
304  */
305 - (NSURLSessionDownloadTask *)downloadTaskWithResumeData:(NSData *)resumeData
633752 306                                                 progress:(nullable void (^)(NSProgress *downloadProgress))downloadProgressBlock
6e1425 307                                              destination:(nullable NSURL * (^)(NSURL *targetPath, NSURLResponse *response))destination
633752 308                                        completionHandler:(nullable void (^)(NSURLResponse *response, NSURL * _Nullable filePath, NSError * _Nullable error))completionHandler;
6e1425 309
H 310 ///---------------------------------
311 /// @name Getting Progress for Tasks
312 ///---------------------------------
313
314 /**
315  Returns the upload progress of the specified task.
316
633752 317  @param task The session task. Must not be `nil`.
6e1425 318
H 319  @return An `NSProgress` object reporting the upload progress of a task, or `nil` if the progress is unavailable.
320  */
633752 321 - (nullable NSProgress *)uploadProgressForTask:(NSURLSessionTask *)task;
6e1425 322
H 323 /**
324  Returns the download progress of the specified task.
325
633752 326  @param task The session task. Must not be `nil`.
6e1425 327
H 328  @return An `NSProgress` object reporting the download progress of a task, or `nil` if the progress is unavailable.
329  */
633752 330 - (nullable NSProgress *)downloadProgressForTask:(NSURLSessionTask *)task;
6e1425 331
H 332 ///-----------------------------------------
333 /// @name Setting Session Delegate Callbacks
334 ///-----------------------------------------
335
336 /**
337  Sets a block to be executed when the managed session becomes invalid, as handled by the `NSURLSessionDelegate` method `URLSession:didBecomeInvalidWithError:`.
338
339  @param block A block object to be executed when the managed session becomes invalid. The block has no return value, and takes two arguments: the session, and the error related to the cause of invalidation.
340  */
341 - (void)setSessionDidBecomeInvalidBlock:(nullable void (^)(NSURLSession *session, NSError *error))block;
342
343 /**
344  Sets a block to be executed when a connection level authentication challenge has occurred, as handled by the `NSURLSessionDelegate` method `URLSession:didReceiveChallenge:completionHandler:`.
345
346  @param block A block object to be executed when a connection level authentication challenge has occurred. The block returns the disposition of the authentication challenge, and takes three arguments: the session, the authentication challenge, and a pointer to the credential that should be used to resolve the challenge.
347  */
633752 348 - (void)setSessionDidReceiveAuthenticationChallengeBlock:(nullable NSURLSessionAuthChallengeDisposition (^)(NSURLSession *session, NSURLAuthenticationChallenge *challenge, NSURLCredential * _Nullable __autoreleasing * _Nullable credential))block;
6e1425 349
H 350 ///--------------------------------------
351 /// @name Setting Task Delegate Callbacks
352 ///--------------------------------------
353
354 /**
355  Sets a block to be executed when a task requires a new request body stream to send to the remote server, as handled by the `NSURLSessionTaskDelegate` method `URLSession:task:needNewBodyStream:`.
356
357  @param block A block object to be executed when a task requires a new request body stream.
358  */
359 - (void)setTaskNeedNewBodyStreamBlock:(nullable NSInputStream * (^)(NSURLSession *session, NSURLSessionTask *task))block;
360
361 /**
362  Sets a block to be executed when an HTTP request is attempting to perform a redirection to a different URL, as handled by the `NSURLSessionTaskDelegate` method `URLSession:willPerformHTTPRedirection:newRequest:completionHandler:`.
363
364  @param block A block object to be executed when an HTTP request is attempting to perform a redirection to a different URL. The block returns the request to be made for the redirection, and takes four arguments: the session, the task, the redirection response, and the request corresponding to the redirection response.
365  */
633752 366 - (void)setTaskWillPerformHTTPRedirectionBlock:(nullable NSURLRequest * _Nullable (^)(NSURLSession *session, NSURLSessionTask *task, NSURLResponse *response, NSURLRequest *request))block;
6e1425 367
H 368 /**
369  Sets a block to be executed when a session task has received a request specific authentication challenge, as handled by the `NSURLSessionTaskDelegate` method `URLSession:task:didReceiveChallenge:completionHandler:`.
370
371  @param block A block object to be executed when a session task has received a request specific authentication challenge. The block returns the disposition of the authentication challenge, and takes four arguments: the session, the task, the authentication challenge, and a pointer to the credential that should be used to resolve the challenge.
372  */
633752 373 - (void)setTaskDidReceiveAuthenticationChallengeBlock:(nullable NSURLSessionAuthChallengeDisposition (^)(NSURLSession *session, NSURLSessionTask *task, NSURLAuthenticationChallenge *challenge, NSURLCredential * _Nullable __autoreleasing * _Nullable credential))block;
6e1425 374
H 375 /**
376  Sets a block to be executed periodically to track upload progress, as handled by the `NSURLSessionTaskDelegate` method `URLSession:task:didSendBodyData:totalBytesSent:totalBytesExpectedToSend:`.
377
378  @param block A block object to be called when an undetermined number of bytes have been uploaded to the server. This block has no return value and takes five arguments: the session, the task, the number of bytes written since the last time the upload progress block was called, the total bytes written, and the total bytes expected to be written during the request, as initially determined by the length of the HTTP body. This block may be called multiple times, and will execute on the main thread.
379  */
380 - (void)setTaskDidSendBodyDataBlock:(nullable void (^)(NSURLSession *session, NSURLSessionTask *task, int64_t bytesSent, int64_t totalBytesSent, int64_t totalBytesExpectedToSend))block;
381
382 /**
383  Sets a block to be executed as the last message related to a specific task, as handled by the `NSURLSessionTaskDelegate` method `URLSession:task:didCompleteWithError:`.
384
385  @param block A block object to be executed when a session task is completed. The block has no return value, and takes three arguments: the session, the task, and any error that occurred in the process of executing the task.
386  */
633752 387 - (void)setTaskDidCompleteBlock:(nullable void (^)(NSURLSession *session, NSURLSessionTask *task, NSError * _Nullable error))block;
6e1425 388
633752 389 /**
L 390  Sets a block to be executed when metrics are finalized related to a specific task, as handled by the `NSURLSessionTaskDelegate` method `URLSession:task:didFinishCollectingMetrics:`.
391
392  @param block A block object to be executed when a session task is completed. The block has no return value, and takes three arguments: the session, the task, and any metrics that were collected in the process of executing the task.
393  */
394 #if AF_CAN_INCLUDE_SESSION_TASK_METRICS
395 - (void)setTaskDidFinishCollectingMetricsBlock:(nullable void (^)(NSURLSession *session, NSURLSessionTask *task, NSURLSessionTaskMetrics * _Nullable metrics))block;
396 #endif
6e1425 397 ///-------------------------------------------
H 398 /// @name Setting Data Task Delegate Callbacks
399 ///-------------------------------------------
400
401 /**
402  Sets a block to be executed when a data task has received a response, as handled by the `NSURLSessionDataDelegate` method `URLSession:dataTask:didReceiveResponse:completionHandler:`.
403
404  @param block A block object to be executed when a data task has received a response. The block returns the disposition of the session response, and takes three arguments: the session, the data task, and the received response.
405  */
406 - (void)setDataTaskDidReceiveResponseBlock:(nullable NSURLSessionResponseDisposition (^)(NSURLSession *session, NSURLSessionDataTask *dataTask, NSURLResponse *response))block;
407
408 /**
409  Sets a block to be executed when a data task has become a download task, as handled by the `NSURLSessionDataDelegate` method `URLSession:dataTask:didBecomeDownloadTask:`.
410
411  @param block A block object to be executed when a data task has become a download task. The block has no return value, and takes three arguments: the session, the data task, and the download task it has become.
412  */
413 - (void)setDataTaskDidBecomeDownloadTaskBlock:(nullable void (^)(NSURLSession *session, NSURLSessionDataTask *dataTask, NSURLSessionDownloadTask *downloadTask))block;
414
415 /**
416  Sets a block to be executed when a data task receives data, as handled by the `NSURLSessionDataDelegate` method `URLSession:dataTask:didReceiveData:`.
417
418  @param block A block object to be called when an undetermined number of bytes have been downloaded from the server. This block has no return value and takes three arguments: the session, the data task, and the data received. This block may be called multiple times, and will execute on the session manager operation queue.
419  */
420 - (void)setDataTaskDidReceiveDataBlock:(nullable void (^)(NSURLSession *session, NSURLSessionDataTask *dataTask, NSData *data))block;
421
422 /**
423  Sets a block to be executed to determine the caching behavior of a data task, as handled by the `NSURLSessionDataDelegate` method `URLSession:dataTask:willCacheResponse:completionHandler:`.
424
425  @param block A block object to be executed to determine the caching behavior of a data task. The block returns the response to cache, and takes three arguments: the session, the data task, and the proposed cached URL response.
426  */
427 - (void)setDataTaskWillCacheResponseBlock:(nullable NSCachedURLResponse * (^)(NSURLSession *session, NSURLSessionDataTask *dataTask, NSCachedURLResponse *proposedResponse))block;
428
429 /**
430  Sets a block to be executed once all messages enqueued for a session have been delivered, as handled by the `NSURLSessionDataDelegate` method `URLSessionDidFinishEventsForBackgroundURLSession:`.
431
432  @param block A block object to be executed once all messages enqueued for a session have been delivered. The block has no return value and takes a single argument: the session.
433  */
633752 434 - (void)setDidFinishEventsForBackgroundURLSessionBlock:(nullable void (^)(NSURLSession *session))block AF_API_UNAVAILABLE(macos);
6e1425 435
H 436 ///-----------------------------------------------
437 /// @name Setting Download Task Delegate Callbacks
438 ///-----------------------------------------------
439
440 /**
441  Sets a block to be executed when a download task has completed a download, as handled by the `NSURLSessionDownloadDelegate` method `URLSession:downloadTask:didFinishDownloadingToURL:`.
442
443  @param block A block object to be executed when a download task has completed. The block returns the URL the download should be moved to, and takes three arguments: the session, the download task, and the temporary location of the downloaded file. If the file manager encounters an error while attempting to move the temporary file to the destination, an `AFURLSessionDownloadTaskDidFailToMoveFileNotification` will be posted, with the download task as its object, and the user info of the error.
444  */
633752 445 - (void)setDownloadTaskDidFinishDownloadingBlock:(nullable NSURL * _Nullable  (^)(NSURLSession *session, NSURLSessionDownloadTask *downloadTask, NSURL *location))block;
6e1425 446
H 447 /**
448  Sets a block to be executed periodically to track download progress, as handled by the `NSURLSessionDownloadDelegate` method `URLSession:downloadTask:didWriteData:totalBytesWritten:totalBytesWritten:totalBytesExpectedToWrite:`.
449
450  @param block A block object to be called when an undetermined number of bytes have been downloaded from the server. This block has no return value and takes five arguments: the session, the download task, the number of bytes read since the last time the download progress block was called, the total bytes read, and the total bytes expected to be read during the request, as initially determined by the expected content size of the `NSHTTPURLResponse` object. This block may be called multiple times, and will execute on the session manager operation queue.
451  */
452 - (void)setDownloadTaskDidWriteDataBlock:(nullable void (^)(NSURLSession *session, NSURLSessionDownloadTask *downloadTask, int64_t bytesWritten, int64_t totalBytesWritten, int64_t totalBytesExpectedToWrite))block;
453
454 /**
455  Sets a block to be executed when a download task has been resumed, as handled by the `NSURLSessionDownloadDelegate` method `URLSession:downloadTask:didResumeAtOffset:expectedTotalBytes:`.
456
457  @param block A block object to be executed when a download task has been resumed. The block has no return value and takes four arguments: the session, the download task, the file offset of the resumed download, and the total number of bytes expected to be downloaded.
458  */
459 - (void)setDownloadTaskDidResumeBlock:(nullable void (^)(NSURLSession *session, NSURLSessionDownloadTask *downloadTask, int64_t fileOffset, int64_t expectedTotalBytes))block;
460
461 @end
462
463 ///--------------------
464 /// @name Notifications
465 ///--------------------
466
467 /**
468  Posted when a task resumes.
469  */
633752 470 FOUNDATION_EXPORT NSString * const AFNetworkingTaskDidResumeNotification;
6e1425 471
H 472 /**
473  Posted when a task finishes executing. Includes a userInfo dictionary with additional information about the task.
474  */
633752 475 FOUNDATION_EXPORT NSString * const AFNetworkingTaskDidCompleteNotification;
6e1425 476
H 477 /**
478  Posted when a task suspends its execution.
479  */
633752 480 FOUNDATION_EXPORT NSString * const AFNetworkingTaskDidSuspendNotification;
6e1425 481
H 482 /**
483  Posted when a session is invalidated.
484  */
633752 485 FOUNDATION_EXPORT NSString * const AFURLSessionDidInvalidateNotification;
6e1425 486
H 487 /**
488  Posted when a session download task encountered an error when moving the temporary download file to a specified destination.
489  */
633752 490 FOUNDATION_EXPORT NSString * const AFURLSessionDownloadTaskDidFailToMoveFileNotification;
6e1425 491
H 492 /**
633752 493  The raw response data of the task. Included in the userInfo dictionary of the `AFNetworkingTaskDidCompleteNotification` if response data exists for the task.
6e1425 494  */
633752 495 FOUNDATION_EXPORT NSString * const AFNetworkingTaskDidCompleteResponseDataKey;
6e1425 496
H 497 /**
633752 498  The serialized response object of the task. Included in the userInfo dictionary of the `AFNetworkingTaskDidCompleteNotification` if the response was serialized.
6e1425 499  */
633752 500 FOUNDATION_EXPORT NSString * const AFNetworkingTaskDidCompleteSerializedResponseKey;
6e1425 501
H 502 /**
633752 503  The response serializer used to serialize the response. Included in the userInfo dictionary of the `AFNetworkingTaskDidCompleteNotification` if the task has an associated response serializer.
6e1425 504  */
633752 505 FOUNDATION_EXPORT NSString * const AFNetworkingTaskDidCompleteResponseSerializerKey;
6e1425 506
H 507 /**
633752 508  The file path associated with the download task. Included in the userInfo dictionary of the `AFNetworkingTaskDidCompleteNotification` if an the response data has been stored directly to disk.
6e1425 509  */
633752 510 FOUNDATION_EXPORT NSString * const AFNetworkingTaskDidCompleteAssetPathKey;
6e1425 511
H 512 /**
633752 513  Any error associated with the task, or the serialization of the response. Included in the userInfo dictionary of the `AFNetworkingTaskDidCompleteNotification` if an error exists.
6e1425 514  */
633752 515 FOUNDATION_EXPORT NSString * const AFNetworkingTaskDidCompleteErrorKey;
6e1425 516
H 517 /**
633752 518  The session task metrics taken from the download task. Included in the userInfo dictionary of the `AFNetworkingTaskDidCompleteSessionTaskMetrics`
6e1425 519  */
633752 520 FOUNDATION_EXPORT NSString * const AFNetworkingTaskDidCompleteSessionTaskMetrics;
6e1425 521
H 522 NS_ASSUME_NONNULL_END