| 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 |
