AFURLSessionManager.h 31 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554
  1. // AFURLSessionManager.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. #import <Foundation/Foundation.h>
  22. #import "AFURLResponseSerialization.h"
  23. #import "AFURLRequestSerialization.h"
  24. #import "AFSecurityPolicy.h"
  25. #if !TARGET_OS_WATCH
  26. #import "AFNetworkReachabilityManager.h"
  27. #endif
  28. #ifndef NS_DESIGNATED_INITIALIZER
  29. #if __has_attribute(objc_designated_initializer)
  30. #define NS_DESIGNATED_INITIALIZER __attribute__((objc_designated_initializer))
  31. #else
  32. #define NS_DESIGNATED_INITIALIZER
  33. #endif
  34. #endif
  35. /**
  36. `AFURLSessionManager` creates and manages an `NSURLSession` object based on a specified `NSURLSessionConfiguration` object, which conforms to `<NSURLSessionTaskDelegate>`, `<NSURLSessionDataDelegate>`, `<NSURLSessionDownloadDelegate>`, and `<NSURLSessionDelegate>`.
  37. ## Subclassing Notes
  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. ## NSURLSession & NSURLSessionTask Delegate Methods
  40. `AFURLSessionManager` implements the following delegate methods:
  41. ### `NSURLSessionDelegate`
  42. - `URLSession:didBecomeInvalidWithError:`
  43. - `URLSession:didReceiveChallenge:completionHandler:`
  44. - `URLSessionDidFinishEventsForBackgroundURLSession:`
  45. ### `NSURLSessionTaskDelegate`
  46. - `URLSession:willPerformHTTPRedirection:newRequest:completionHandler:`
  47. - `URLSession:task:didReceiveChallenge:completionHandler:`
  48. - `URLSession:task:didSendBodyData:totalBytesSent:totalBytesExpectedToSend:`
  49. - `URLSession:task:didCompleteWithError:`
  50. ### `NSURLSessionDataDelegate`
  51. - `URLSession:dataTask:didReceiveResponse:completionHandler:`
  52. - `URLSession:dataTask:didBecomeDownloadTask:`
  53. - `URLSession:dataTask:didReceiveData:`
  54. - `URLSession:dataTask:willCacheResponse:completionHandler:`
  55. ### `NSURLSessionDownloadDelegate`
  56. - `URLSession:downloadTask:didFinishDownloadingToURL:`
  57. - `URLSession:downloadTask:didWriteData:totalBytesWritten:totalBytesWritten:totalBytesExpectedToWrite:`
  58. - `URLSession:downloadTask:didResumeAtOffset:expectedTotalBytes:`
  59. If any of these methods are overridden in a subclass, they _must_ call the `super` implementation first.
  60. ## Network Reachability Monitoring
  61. 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.
  62. ## NSCoding Caveats
  63. - Encoded managers do not include any block properties. Be sure to set delegate callback blocks when using `-initWithCoder:` or `NSKeyedUnarchiver`.
  64. ## NSCopying Caveats
  65. - `-copy` and `-copyWithZone:` return a new manager with a new `NSURLSession` created from the configuration of the original.
  66. - 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.
  67. @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.
  68. */
  69. NS_ASSUME_NONNULL_BEGIN
  70. #if (defined(__IPHONE_OS_VERSION_MAX_ALLOWED) && __IPHONE_OS_VERSION_MAX_ALLOWED >= 70000) || (defined(__MAC_OS_X_VERSION_MAX_ALLOWED) && __MAC_OS_X_VERSION_MAX_ALLOWED >= 1090) || TARGET_OS_WATCH
  71. @interface AFURLSessionManager : NSObject <NSURLSessionDelegate, NSURLSessionTaskDelegate, NSURLSessionDataDelegate, NSURLSessionDownloadDelegate, NSSecureCoding, NSCopying>
  72. /**
  73. The managed session.
  74. */
  75. @property (readonly, nonatomic, strong) NSURLSession *session;
  76. /**
  77. The operation queue on which delegate callbacks are run.
  78. */
  79. @property (readonly, nonatomic, strong) NSOperationQueue *operationQueue;
  80. /**
  81. 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`.
  82. @warning `responseSerializer` must not be `nil`.
  83. */
  84. @property (nonatomic, strong) id <AFURLResponseSerialization> responseSerializer;
  85. ///-------------------------------
  86. /// @name Managing Security Policy
  87. ///-------------------------------
  88. /**
  89. The security policy used by created request operations to evaluate server trust for secure connections. `AFURLSessionManager` uses the `defaultPolicy` unless otherwise specified.
  90. */
  91. @property (nonatomic, strong) AFSecurityPolicy *securityPolicy;
  92. #if !TARGET_OS_WATCH
  93. ///--------------------------------------
  94. /// @name Monitoring Network Reachability
  95. ///--------------------------------------
  96. /**
  97. The network reachability manager. `AFURLSessionManager` uses the `sharedManager` by default.
  98. */
  99. @property (readwrite, nonatomic, strong) AFNetworkReachabilityManager *reachabilityManager;
  100. #endif
  101. ///----------------------------
  102. /// @name Getting Session Tasks
  103. ///----------------------------
  104. /**
  105. The data, upload, and download tasks currently run by the managed session.
  106. */
  107. @property (readonly, nonatomic, strong) NSArray *tasks;
  108. /**
  109. The data tasks currently run by the managed session.
  110. */
  111. @property (readonly, nonatomic, strong) NSArray *dataTasks;
  112. /**
  113. The upload tasks currently run by the managed session.
  114. */
  115. @property (readonly, nonatomic, strong) NSArray *uploadTasks;
  116. /**
  117. The download tasks currently run by the managed session.
  118. */
  119. @property (readonly, nonatomic, strong) NSArray *downloadTasks;
  120. ///-------------------------------
  121. /// @name Managing Callback Queues
  122. ///-------------------------------
  123. /**
  124. The dispatch queue for `completionBlock`. If `NULL` (default), the main queue is used.
  125. */
  126. #if OS_OBJECT_USE_OBJC
  127. @property (nonatomic, strong, nullable) dispatch_queue_t completionQueue;
  128. #else
  129. @property (nonatomic, assign, nullable) dispatch_queue_t completionQueue;
  130. #endif
  131. /**
  132. The dispatch group for `completionBlock`. If `NULL` (default), a private dispatch group is used.
  133. */
  134. #if OS_OBJECT_USE_OBJC
  135. @property (nonatomic, strong, nullable) dispatch_group_t completionGroup;
  136. #else
  137. @property (nonatomic, assign, nullable) dispatch_group_t completionGroup;
  138. #endif
  139. ///---------------------------------
  140. /// @name Working Around System Bugs
  141. ///---------------------------------
  142. /**
  143. Whether to attempt to retry creation of upload tasks for background sessions when initial call returns `nil`. `NO` by default.
  144. @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.
  145. @see https://github.com/AFNetworking/AFNetworking/issues/1675
  146. */
  147. @property (nonatomic, assign) BOOL attemptsToRecreateUploadTasksForBackgroundSessions;
  148. ///---------------------
  149. /// @name Initialization
  150. ///---------------------
  151. /**
  152. Creates and returns a manager for a session created with the specified configuration. This is the designated initializer.
  153. @param configuration The configuration used to create the managed session.
  154. @return A manager for a newly-created session.
  155. */
  156. - (instancetype)initWithSessionConfiguration:(nullable NSURLSessionConfiguration *)configuration NS_DESIGNATED_INITIALIZER;
  157. /**
  158. Invalidates the managed session, optionally canceling pending tasks.
  159. @param cancelPendingTasks Whether or not to cancel pending tasks.
  160. */
  161. - (void)invalidateSessionCancelingTasks:(BOOL)cancelPendingTasks;
  162. ///-------------------------
  163. /// @name Running Data Tasks
  164. ///-------------------------
  165. /**
  166. Creates an `NSURLSessionDataTask` with the specified request.
  167. @param request The HTTP request for the request.
  168. @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.
  169. */
  170. - (NSURLSessionDataTask *)dataTaskWithRequest:(NSURLRequest *)request
  171. completionHandler:(nullable void (^)(NSURLResponse *response, id __nullable responseObject, NSError * __nullable error))completionHandler;
  172. ///---------------------------
  173. /// @name Running Upload Tasks
  174. ///---------------------------
  175. /**
  176. Creates an `NSURLSessionUploadTask` with the specified request for a local file.
  177. @param request The HTTP request for the request.
  178. @param fileURL A URL to the local file to be uploaded.
  179. @param progress A progress object monitoring the current upload progress.
  180. @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.
  181. @see `attemptsToRecreateUploadTasksForBackgroundSessions`
  182. */
  183. - (NSURLSessionUploadTask *)uploadTaskWithRequest:(NSURLRequest *)request
  184. fromFile:(NSURL *)fileURL
  185. progress:(NSProgress * __nullable __autoreleasing * __nullable)progress
  186. completionHandler:(nullable void (^)(NSURLResponse *response, id __nullable responseObject, NSError * __nullable error))completionHandler;
  187. /**
  188. Creates an `NSURLSessionUploadTask` with the specified request for an HTTP body.
  189. @param request The HTTP request for the request.
  190. @param bodyData A data object containing the HTTP body to be uploaded.
  191. @param progress A progress object monitoring the current upload progress.
  192. @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.
  193. */
  194. - (NSURLSessionUploadTask *)uploadTaskWithRequest:(NSURLRequest *)request
  195. fromData:(nullable NSData *)bodyData
  196. progress:(NSProgress * __nullable __autoreleasing * __nullable)progress
  197. completionHandler:(nullable void (^)(NSURLResponse *response, id __nullable responseObject, NSError * __nullable error))completionHandler;
  198. /**
  199. Creates an `NSURLSessionUploadTask` with the specified streaming request.
  200. @param request The HTTP request for the request.
  201. @param progress A progress object monitoring the current upload progress.
  202. @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.
  203. */
  204. - (NSURLSessionUploadTask *)uploadTaskWithStreamedRequest:(NSURLRequest *)request
  205. progress:(NSProgress * __nullable __autoreleasing * __nullable)progress
  206. completionHandler:(nullable void (^)(NSURLResponse *response, id __nullable responseObject, NSError * __nullable error))completionHandler;
  207. ///-----------------------------
  208. /// @name Running Download Tasks
  209. ///-----------------------------
  210. /**
  211. Creates an `NSURLSessionDownloadTask` with the specified request.
  212. @param request The HTTP request for the request.
  213. @param progress A progress object monitoring the current download progress.
  214. @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.
  215. @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.
  216. @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.
  217. */
  218. - (NSURLSessionDownloadTask *)downloadTaskWithRequest:(NSURLRequest *)request
  219. progress:(NSProgress * __nullable __autoreleasing * __nullable)progress
  220. destination:(nullable NSURL * (^)(NSURL *targetPath, NSURLResponse *response))destination
  221. completionHandler:(nullable void (^)(NSURLResponse *response, NSURL * __nullable filePath, NSError * __nullable error))completionHandler;
  222. /**
  223. Creates an `NSURLSessionDownloadTask` with the specified resume data.
  224. @param resumeData The data used to resume downloading.
  225. @param progress A progress object monitoring the current download progress.
  226. @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.
  227. @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.
  228. */
  229. - (NSURLSessionDownloadTask *)downloadTaskWithResumeData:(NSData *)resumeData
  230. progress:(NSProgress * __nullable __autoreleasing * __nullable)progress
  231. destination:(nullable NSURL * (^)(NSURL *targetPath, NSURLResponse *response))destination
  232. completionHandler:(nullable void (^)(NSURLResponse *response, NSURL * __nullable filePath, NSError * __nullable error))completionHandler;
  233. ///---------------------------------
  234. /// @name Getting Progress for Tasks
  235. ///---------------------------------
  236. /**
  237. Returns the upload progress of the specified task.
  238. @param uploadTask The session upload task. Must not be `nil`.
  239. @return An `NSProgress` object reporting the upload progress of a task, or `nil` if the progress is unavailable.
  240. */
  241. - (nullable NSProgress *)uploadProgressForTask:(NSURLSessionUploadTask *)uploadTask;
  242. /**
  243. Returns the download progress of the specified task.
  244. @param downloadTask The session download task. Must not be `nil`.
  245. @return An `NSProgress` object reporting the download progress of a task, or `nil` if the progress is unavailable.
  246. */
  247. - (nullable NSProgress *)downloadProgressForTask:(NSURLSessionDownloadTask *)downloadTask;
  248. ///-----------------------------------------
  249. /// @name Setting Session Delegate Callbacks
  250. ///-----------------------------------------
  251. /**
  252. Sets a block to be executed when the managed session becomes invalid, as handled by the `NSURLSessionDelegate` method `URLSession:didBecomeInvalidWithError:`.
  253. @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.
  254. */
  255. - (void)setSessionDidBecomeInvalidBlock:(nullable void (^)(NSURLSession *session, NSError *error))block;
  256. /**
  257. Sets a block to be executed when a connection level authentication challenge has occurred, as handled by the `NSURLSessionDelegate` method `URLSession:didReceiveChallenge:completionHandler:`.
  258. @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.
  259. */
  260. - (void)setSessionDidReceiveAuthenticationChallengeBlock:(nullable NSURLSessionAuthChallengeDisposition (^)(NSURLSession *session, NSURLAuthenticationChallenge *challenge, NSURLCredential * __nullable __autoreleasing * __nullable credential))block;
  261. ///--------------------------------------
  262. /// @name Setting Task Delegate Callbacks
  263. ///--------------------------------------
  264. /**
  265. 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:`.
  266. @param block A block object to be executed when a task requires a new request body stream.
  267. */
  268. - (void)setTaskNeedNewBodyStreamBlock:(nullable NSInputStream * (^)(NSURLSession *session, NSURLSessionTask *task))block;
  269. /**
  270. 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:`.
  271. @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.
  272. */
  273. - (void)setTaskWillPerformHTTPRedirectionBlock:(nullable NSURLRequest * (^)(NSURLSession *session, NSURLSessionTask *task, NSURLResponse *response, NSURLRequest *request))block;
  274. /**
  275. 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:`.
  276. @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.
  277. */
  278. - (void)setTaskDidReceiveAuthenticationChallengeBlock:(nullable NSURLSessionAuthChallengeDisposition (^)(NSURLSession *session, NSURLSessionTask *task, NSURLAuthenticationChallenge *challenge, NSURLCredential * __nullable __autoreleasing * __nullable credential))block;
  279. /**
  280. Sets a block to be executed periodically to track upload progress, as handled by the `NSURLSessionTaskDelegate` method `URLSession:task:didSendBodyData:totalBytesSent:totalBytesExpectedToSend:`.
  281. @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.
  282. */
  283. - (void)setTaskDidSendBodyDataBlock:(nullable void (^)(NSURLSession *session, NSURLSessionTask *task, int64_t bytesSent, int64_t totalBytesSent, int64_t totalBytesExpectedToSend))block;
  284. /**
  285. Sets a block to be executed as the last message related to a specific task, as handled by the `NSURLSessionTaskDelegate` method `URLSession:task:didCompleteWithError:`.
  286. @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.
  287. */
  288. - (void)setTaskDidCompleteBlock:(nullable void (^)(NSURLSession *session, NSURLSessionTask *task, NSError * __nullable error))block;
  289. ///-------------------------------------------
  290. /// @name Setting Data Task Delegate Callbacks
  291. ///-------------------------------------------
  292. /**
  293. Sets a block to be executed when a data task has received a response, as handled by the `NSURLSessionDataDelegate` method `URLSession:dataTask:didReceiveResponse:completionHandler:`.
  294. @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.
  295. */
  296. - (void)setDataTaskDidReceiveResponseBlock:(nullable NSURLSessionResponseDisposition (^)(NSURLSession *session, NSURLSessionDataTask *dataTask, NSURLResponse *response))block;
  297. /**
  298. Sets a block to be executed when a data task has become a download task, as handled by the `NSURLSessionDataDelegate` method `URLSession:dataTask:didBecomeDownloadTask:`.
  299. @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.
  300. */
  301. - (void)setDataTaskDidBecomeDownloadTaskBlock:(nullable void (^)(NSURLSession *session, NSURLSessionDataTask *dataTask, NSURLSessionDownloadTask *downloadTask))block;
  302. /**
  303. Sets a block to be executed when a data task receives data, as handled by the `NSURLSessionDataDelegate` method `URLSession:dataTask:didReceiveData:`.
  304. @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.
  305. */
  306. - (void)setDataTaskDidReceiveDataBlock:(nullable void (^)(NSURLSession *session, NSURLSessionDataTask *dataTask, NSData *data))block;
  307. /**
  308. 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:`.
  309. @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.
  310. */
  311. - (void)setDataTaskWillCacheResponseBlock:(nullable NSCachedURLResponse * (^)(NSURLSession *session, NSURLSessionDataTask *dataTask, NSCachedURLResponse *proposedResponse))block;
  312. /**
  313. Sets a block to be executed once all messages enqueued for a session have been delivered, as handled by the `NSURLSessionDataDelegate` method `URLSessionDidFinishEventsForBackgroundURLSession:`.
  314. @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.
  315. */
  316. - (void)setDidFinishEventsForBackgroundURLSessionBlock:(nullable void (^)(NSURLSession *session))block;
  317. ///-----------------------------------------------
  318. /// @name Setting Download Task Delegate Callbacks
  319. ///-----------------------------------------------
  320. /**
  321. Sets a block to be executed when a download task has completed a download, as handled by the `NSURLSessionDownloadDelegate` method `URLSession:downloadTask:didFinishDownloadingToURL:`.
  322. @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.
  323. */
  324. - (void)setDownloadTaskDidFinishDownloadingBlock:(nullable NSURL * (^)(NSURLSession *session, NSURLSessionDownloadTask *downloadTask, NSURL *location))block;
  325. /**
  326. Sets a block to be executed periodically to track download progress, as handled by the `NSURLSessionDownloadDelegate` method `URLSession:downloadTask:didWriteData:totalBytesWritten:totalBytesWritten:totalBytesExpectedToWrite:`.
  327. @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.
  328. */
  329. - (void)setDownloadTaskDidWriteDataBlock:(nullable void (^)(NSURLSession *session, NSURLSessionDownloadTask *downloadTask, int64_t bytesWritten, int64_t totalBytesWritten, int64_t totalBytesExpectedToWrite))block;
  330. /**
  331. Sets a block to be executed when a download task has been resumed, as handled by the `NSURLSessionDownloadDelegate` method `URLSession:downloadTask:didResumeAtOffset:expectedTotalBytes:`.
  332. @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.
  333. */
  334. - (void)setDownloadTaskDidResumeBlock:(nullable void (^)(NSURLSession *session, NSURLSessionDownloadTask *downloadTask, int64_t fileOffset, int64_t expectedTotalBytes))block;
  335. @end
  336. #endif
  337. ///--------------------
  338. /// @name Notifications
  339. ///--------------------
  340. /**
  341. Posted when a task begins executing.
  342. @deprecated Use `AFNetworkingTaskDidResumeNotification` instead.
  343. */
  344. FOUNDATION_EXPORT NSString * const AFNetworkingTaskDidStartNotification DEPRECATED_ATTRIBUTE;
  345. /**
  346. Posted when a task resumes.
  347. */
  348. FOUNDATION_EXPORT NSString * const AFNetworkingTaskDidResumeNotification;
  349. /**
  350. Posted when a task finishes executing. Includes a userInfo dictionary with additional information about the task.
  351. @deprecated Use `AFNetworkingTaskDidCompleteNotification` instead.
  352. */
  353. FOUNDATION_EXPORT NSString * const AFNetworkingTaskDidFinishNotification DEPRECATED_ATTRIBUTE;
  354. /**
  355. Posted when a task finishes executing. Includes a userInfo dictionary with additional information about the task.
  356. */
  357. FOUNDATION_EXPORT NSString * const AFNetworkingTaskDidCompleteNotification;
  358. /**
  359. Posted when a task suspends its execution.
  360. */
  361. FOUNDATION_EXPORT NSString * const AFNetworkingTaskDidSuspendNotification;
  362. /**
  363. Posted when a session is invalidated.
  364. */
  365. FOUNDATION_EXPORT NSString * const AFURLSessionDidInvalidateNotification;
  366. /**
  367. Posted when a session download task encountered an error when moving the temporary download file to a specified destination.
  368. */
  369. FOUNDATION_EXPORT NSString * const AFURLSessionDownloadTaskDidFailToMoveFileNotification;
  370. /**
  371. The raw response data of the task. Included in the userInfo dictionary of the `AFNetworkingTaskDidFinishNotification` if response data exists for the task.
  372. @deprecated Use `AFNetworkingTaskDidCompleteResponseDataKey` instead.
  373. */
  374. FOUNDATION_EXPORT NSString * const AFNetworkingTaskDidFinishResponseDataKey DEPRECATED_ATTRIBUTE;
  375. /**
  376. The raw response data of the task. Included in the userInfo dictionary of the `AFNetworkingTaskDidFinishNotification` if response data exists for the task.
  377. */
  378. FOUNDATION_EXPORT NSString * const AFNetworkingTaskDidCompleteResponseDataKey;
  379. /**
  380. The serialized response object of the task. Included in the userInfo dictionary of the `AFNetworkingTaskDidFinishNotification` if the response was serialized.
  381. @deprecated Use `AFNetworkingTaskDidCompleteSerializedResponseKey` instead.
  382. */
  383. FOUNDATION_EXPORT NSString * const AFNetworkingTaskDidFinishSerializedResponseKey DEPRECATED_ATTRIBUTE;
  384. /**
  385. The serialized response object of the task. Included in the userInfo dictionary of the `AFNetworkingTaskDidFinishNotification` if the response was serialized.
  386. */
  387. FOUNDATION_EXPORT NSString * const AFNetworkingTaskDidCompleteSerializedResponseKey;
  388. /**
  389. The response serializer used to serialize the response. Included in the userInfo dictionary of the `AFNetworkingTaskDidFinishNotification` if the task has an associated response serializer.
  390. @deprecated Use `AFNetworkingTaskDidCompleteResponseSerializerKey` instead.
  391. */
  392. FOUNDATION_EXPORT NSString * const AFNetworkingTaskDidFinishResponseSerializerKey DEPRECATED_ATTRIBUTE;
  393. /**
  394. The response serializer used to serialize the response. Included in the userInfo dictionary of the `AFNetworkingTaskDidFinishNotification` if the task has an associated response serializer.
  395. */
  396. FOUNDATION_EXPORT NSString * const AFNetworkingTaskDidCompleteResponseSerializerKey;
  397. /**
  398. The file path associated with the download task. Included in the userInfo dictionary of the `AFNetworkingTaskDidFinishNotification` if an the response data has been stored directly to disk.
  399. @deprecated Use `AFNetworkingTaskDidCompleteAssetPathKey` instead.
  400. */
  401. FOUNDATION_EXPORT NSString * const AFNetworkingTaskDidFinishAssetPathKey DEPRECATED_ATTRIBUTE;
  402. /**
  403. The file path associated with the download task. Included in the userInfo dictionary of the `AFNetworkingTaskDidFinishNotification` if an the response data has been stored directly to disk.
  404. */
  405. FOUNDATION_EXPORT NSString * const AFNetworkingTaskDidCompleteAssetPathKey;
  406. /**
  407. Any error associated with the task, or the serialization of the response. Included in the userInfo dictionary of the `AFNetworkingTaskDidFinishNotification` if an error exists.
  408. @deprecated Use `AFNetworkingTaskDidCompleteErrorKey` instead.
  409. */
  410. FOUNDATION_EXPORT NSString * const AFNetworkingTaskDidFinishErrorKey DEPRECATED_ATTRIBUTE;
  411. /**
  412. Any error associated with the task, or the serialization of the response. Included in the userInfo dictionary of the `AFNetworkingTaskDidFinishNotification` if an error exists.
  413. */
  414. FOUNDATION_EXPORT NSString * const AFNetworkingTaskDidCompleteErrorKey;
  415. NS_ASSUME_NONNULL_END