Inherits from NSObject
Conforms to NSCoding
NSCopying
NSURLSessionDataDelegate
NSURLSessionDelegate
NSURLSessionDownloadDelegate
NSURLSessionTaskDelegate
Declared in AFURLSessionManager.h
AFURLSessionManager.m

Overview

AFURLSessionManager creates and manages an NSURLSession object based on a specified NSURLSessionConfiguration object, which conforms to <NSURLSessionTaskDelegate>, <NSURLSessionDataDelegate>, <NSURLSessionDownloadDelegate>, and <NSURLSessionDelegate>.

Subclassing Notes

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.

NSURLSession & NSURLSessionTask Delegate Methods

AFURLSessionManager implements the following delegate methods:

NSURLSessionDelegate

  • URLSession:didBecomeInvalidWithError:
  • URLSession:didReceiveChallenge:completionHandler:

NSURLSessionTaskDelegate

  • URLSession:willPerformHTTPRedirection:newRequest:completionHandler:
  • URLSession:task:didReceiveChallenge:completionHandler:
  • URLSession:task:didSendBodyData:totalBytesSent:totalBytesExpectedToSend:
  • URLSession:task:didCompleteWithError:

NSURLSessionDataDelegate

  • URLSession:dataTask:didReceiveResponse:completionHandler:
  • URLSession:dataTask:didBecomeDownloadTask:
  • URLSession:dataTask:didReceiveData:
  • URLSession:dataTask:willCacheResponse:completionHandler:
  • URLSessionDidFinishEventsForBackgroundURLSession:

NSURLSessionDownloadDelegate

  • URLSession:downloadTask:didFinishDownloadingToURL:
  • URLSession:downloadTask:didWriteData:totalBytesWritten:totalBytesWritten:totalBytesExpectedToWrite:
  • URLSession:downloadTask:didResumeAtOffset:expectedTotalBytes:

If any of these methods are overridden in a subclass, they must call the super implementation first.

Network Reachability Monitoring

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.

NSCoding Caveats

  • Encoded managers do not include any block properties. Be sure to set delegate callback blocks when using -initWithCoder: or NSKeyedUnarchiver.

NSCopying Caveats

  • -copy and -copyWithZone: return a new manager with a new NSURLSession created from the configuration of the original.
  • 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.

Tasks

Other Methods

Managing Security Policy

Monitoring Network Reachability

Getting Session Tasks

Managing Callback Queues

Initialization

Running Data Tasks

Running Upload Tasks

Running Download Tasks

Setting Session Delegate Callbacks

Setting Task Delegate Callbacks

Setting Data Task Delegate Callbacks

Setting Download Task Delegate Callbacks

Properties

completionGroup

The dispatch group for completionBlock. If NULL (default), a private dispatch group is used.

@property (nonatomic, strong) dispatch_group_t completionGroup

Declared In

AFURLSessionManager.h

completionQueue

The dispatch queue for completionBlock. If NULL (default), the main queue is used.

@property (nonatomic, strong) dispatch_queue_t completionQueue

Declared In

AFURLSessionManager.h

dataTasks

The data tasks currently run by the managed session.

@property (readonly, nonatomic, strong) NSArray *dataTasks

Declared In

AFURLSessionManager.h

downloadTasks

The download tasks currently run by the managed session.

@property (readonly, nonatomic, strong) NSArray *downloadTasks

Declared In

AFURLSessionManager.h

operationQueue

The operation queue on which delegate callbacks are run.

@property (readonly, nonatomic, strong) NSOperationQueue *operationQueue

Declared In

AFURLSessionManager.h

reachabilityManager

The network reachability manager. AFURLSessionManager uses the sharedManager by default.

@property (readwrite, nonatomic, strong) AFNetworkReachabilityManager *reachabilityManager

Declared In

AFURLSessionManager.h

responseSerializer

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.

@property (nonatomic, strong) id<AFURLResponseSerialization> responseSerializer

Discussion

Warning: responseSerializer must not be nil.

Declared In

AFURLSessionManager.h

securityPolicy

The security policy used by created request operations to evaluate server trust for secure connections. AFURLSessionManager uses the defaultPolicy unless otherwise specified.

@property (nonatomic, strong) AFSecurityPolicy *securityPolicy

Declared In

AFURLSessionManager.h

session

The managed session.

@property (readonly, nonatomic, strong) NSURLSession *session

Declared In

AFURLSessionManager.h

tasks

The data, upload, and download tasks currently run by the managed session.

@property (readonly, nonatomic, strong) NSArray *tasks

Declared In

AFURLSessionManager.h

uploadTasks

The upload tasks currently run by the managed session.

@property (readonly, nonatomic, strong) NSArray *uploadTasks

Declared In

AFURLSessionManager.h

Instance Methods

dataTaskWithRequest:completionHandler:

Creates an NSURLSessionDataTask with the specified request.

- (NSURLSessionDataTask *)dataTaskWithRequest:(NSURLRequest *)request completionHandler:(void ( ^ ) ( NSURLResponse *response , id responseObject , NSError *error ))completionHandler

Parameters

request

The HTTP request for the request.

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.

Declared In

AFURLSessionManager.h

downloadTaskWithRequest:progress:destination:completionHandler:

Creates an NSURLSessionDownloadTask with the specified request.

- (NSURLSessionDownloadTask *)downloadTaskWithRequest:(NSURLRequest *)request progress:(NSProgress *__autoreleasing *)progress destination:(NSURL *( ^ ) ( NSURL *targetPath , NSURLResponse *response ))destination completionHandler:(void ( ^ ) ( NSURLResponse *response , NSURL *filePath , NSError *error ))completionHandler

Parameters

request

The HTTP request for the request.

progress

A progress object monitoring the current download progress.

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.

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.

Declared In

AFURLSessionManager.h

downloadTaskWithResumeData:progress:destination:completionHandler:

Creates an NSURLSessionDownloadTask with the specified resume data.

- (NSURLSessionDownloadTask *)downloadTaskWithResumeData:(NSData *)resumeData progress:(NSProgress *__autoreleasing *)progress destination:(NSURL *( ^ ) ( NSURL *targetPath , NSURLResponse *response ))destination completionHandler:(void ( ^ ) ( NSURLResponse *response , NSURL *filePath , NSError *error ))completionHandler

Parameters

resumeData

The data used to resume downloading.

progress

A progress object monitoring the current download progress.

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.

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.

Declared In

AFURLSessionManager.h

initWithSessionConfiguration:

Creates and returns a manager for a session created with the specified configuration. This is the designated initializer.

- (instancetype)initWithSessionConfiguration:(NSURLSessionConfiguration *)configuration

Parameters

configuration

The configuration used to create the managed session.

Return Value

A manager for a newly-created session.

Declared In

AFURLSessionManager.h

invalidateSessionCancelingTasks:

Invalidates the managed session, optionally canceling pending tasks.

- (void)invalidateSessionCancelingTasks:(BOOL)cancelPendingTasks

Parameters

cancelPendingTasks

Whether or not to cancel pending tasks.

Declared In

AFURLSessionManager.h

setDataTaskDidBecomeDownloadTaskBlock:

Sets a block to be executed when a data task has become a download task, as handled by the NSURLSessionDataDelegate method URLSession:dataTask:didBecomeDownloadTask:.

- (void)setDataTaskDidBecomeDownloadTaskBlock:(void ( ^ ) ( NSURLSession *session , NSURLSessionDataTask *dataTask , NSURLSessionDownloadTask *downloadTask ))block

Parameters

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.

Declared In

AFURLSessionManager.h

setDataTaskDidReceiveDataBlock:

Sets a block to be executed when a data task receives data, as handled by the NSURLSessionDataDelegate method URLSession:dataTask:didReceiveData:.

- (void)setDataTaskDidReceiveDataBlock:(void ( ^ ) ( NSURLSession *session , NSURLSessionDataTask *dataTask , NSData *data ))block

Parameters

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.

Declared In

AFURLSessionManager.h

setDataTaskDidReceiveResponseBlock:

Sets a block to be executed when a data task has received a response, as handled by the NSURLSessionDataDelegate method URLSession:dataTask:didReceiveResponse:completionHandler:.

- (void)setDataTaskDidReceiveResponseBlock:(NSURLSessionResponseDisposition ( ^ ) ( NSURLSession *session , NSURLSessionDataTask *dataTask , NSURLResponse *response ))block

Parameters

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.

Declared In

AFURLSessionManager.h

setDataTaskWillCacheResponseBlock:

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

- (void)setDataTaskWillCacheResponseBlock:(NSCachedURLResponse *( ^ ) ( NSURLSession *session , NSURLSessionDataTask *dataTask , NSCachedURLResponse *proposedResponse ))block

Parameters

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.

Declared In

AFURLSessionManager.h

setDidFinishEventsForBackgroundURLSessionBlock:

Sets a block to be executed once all messages enqueued for a session have been delivered, as handled by the NSURLSessionDataDelegate method URLSessionDidFinishEventsForBackgroundURLSession:.

- (void)setDidFinishEventsForBackgroundURLSessionBlock:(void ( ^ ) ( NSURLSession *session ))block

Parameters

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.

Declared In

AFURLSessionManager.h

setDownloadTaskDidFinishDownloadingBlock:

Sets a block to be executed when a download task has completed a download, as handled by the NSURLSessionDownloadDelegate method URLSession:downloadTask:didFinishDownloadingToURL:.

- (void)setDownloadTaskDidFinishDownloadingBlock:(NSURL *( ^ ) ( NSURLSession *session , NSURLSessionDownloadTask *downloadTask , NSURL *location ))block

Parameters

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.

Declared In

AFURLSessionManager.h

setDownloadTaskDidResumeBlock:

Sets a block to be executed when a download task has been resumed, as handled by the NSURLSessionDownloadDelegate method URLSession:downloadTask:didResumeAtOffset:expectedTotalBytes:.

- (void)setDownloadTaskDidResumeBlock:(void ( ^ ) ( NSURLSession *session , NSURLSessionDownloadTask *downloadTask , int64_t fileOffset , int64_t expectedTotalBytes ))block

Parameters

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.

Declared In

AFURLSessionManager.h

setDownloadTaskDidWriteDataBlock:

Sets a block to be executed periodically to track download progress, as handled by the NSURLSessionDownloadDelegate method URLSession:downloadTask:didWriteData:totalBytesWritten:totalBytesWritten:totalBytesExpectedToWrite:.

- (void)setDownloadTaskDidWriteDataBlock:(void ( ^ ) ( NSURLSession *session , NSURLSessionDownloadTask *downloadTask , int64_t bytesWritten , int64_t totalBytesWritten , int64_t totalBytesExpectedToWrite ))block

Parameters

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.

Declared In

AFURLSessionManager.h

setSessionDidBecomeInvalidBlock:

Sets a block to be executed when the managed session becomes invalid, as handled by the NSURLSessionDelegate method URLSession:didBecomeInvalidWithError:.

- (void)setSessionDidBecomeInvalidBlock:(void ( ^ ) ( NSURLSession *session , NSError *error ))block

Parameters

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.

Declared In

AFURLSessionManager.h

setSessionDidReceiveAuthenticationChallengeBlock:

Sets a block to be executed when a connection level authentication challenge has occurred, as handled by the NSURLSessionDelegate method URLSession:didReceiveChallenge:completionHandler:.

- (void)setSessionDidReceiveAuthenticationChallengeBlock:(NSURLSessionAuthChallengeDisposition ( ^ ) ( NSURLSession *session , NSURLAuthenticationChallenge *challenge , NSURLCredential *__autoreleasing *credential ))block

Parameters

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.

Declared In

AFURLSessionManager.h

setTaskDidCompleteBlock:

Sets a block to be executed as the last message related to a specific task, as handled by the NSURLSessionTaskDelegate method URLSession:task:didCompleteWithError:.

- (void)setTaskDidCompleteBlock:(void ( ^ ) ( NSURLSession *session , NSURLSessionTask *task , NSError *error ))block

Parameters

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.

Declared In

AFURLSessionManager.h

setTaskDidReceiveAuthenticationChallengeBlock:

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

- (void)setTaskDidReceiveAuthenticationChallengeBlock:(NSURLSessionAuthChallengeDisposition ( ^ ) ( NSURLSession *session , NSURLSessionTask *task , NSURLAuthenticationChallenge *challenge , NSURLCredential *__autoreleasing *credential ))block

Parameters

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.

Declared In

AFURLSessionManager.h

setTaskDidSendBodyDataBlock:

Sets a block to be executed periodically to track upload progress, as handled by the NSURLSessionTaskDelegate method URLSession:task:didSendBodyData:totalBytesSent:totalBytesExpectedToSend:.

- (void)setTaskDidSendBodyDataBlock:(void ( ^ ) ( NSURLSession *session , NSURLSessionTask *task , int64_t bytesSent , int64_t totalBytesSent , int64_t totalBytesExpectedToSend ))block

Parameters

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.

Declared In

AFURLSessionManager.h

setTaskNeedNewBodyStreamBlock:

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

- (void)setTaskNeedNewBodyStreamBlock:(NSInputStream *( ^ ) ( NSURLSession *session , NSURLSessionTask *task ))block

Parameters

block

A block object to be executed when a task requires a new request body stream.

Declared In

AFURLSessionManager.h

setTaskWillPerformHTTPRedirectionBlock:

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

- (void)setTaskWillPerformHTTPRedirectionBlock:(NSURLRequest *( ^ ) ( NSURLSession *session , NSURLSessionTask *task , NSURLResponse *response , NSURLRequest *request ))block

Parameters

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.

Declared In

AFURLSessionManager.h

uploadTaskWithRequest:fromData:progress:completionHandler:

Creates an NSURLSessionUploadTask with the specified request for an HTTP body.

- (NSURLSessionUploadTask *)uploadTaskWithRequest:(NSURLRequest *)request fromData:(NSData *)bodyData progress:(NSProgress *__autoreleasing *)progress completionHandler:(void ( ^ ) ( NSURLResponse *response , id responseObject , NSError *error ))completionHandler

Parameters

request

The HTTP request for the request.

bodyData

A data object containing the HTTP body to be uploaded.

progress

A progress object monitoring the current upload progress.

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.

Declared In

AFURLSessionManager.h

uploadTaskWithRequest:fromFile:progress:completionHandler:

Creates an NSURLSessionUploadTask with the specified request for a local file.

- (NSURLSessionUploadTask *)uploadTaskWithRequest:(NSURLRequest *)request fromFile:(NSURL *)fileURL progress:(NSProgress *__autoreleasing *)progress completionHandler:(void ( ^ ) ( NSURLResponse *response , id responseObject , NSError *error ))completionHandler

Parameters

request

The HTTP request for the request.

fileURL

A URL to the local file to be uploaded.

progress

A progress object monitoring the current upload progress.

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.

Declared In

AFURLSessionManager.h

uploadTaskWithStreamedRequest:progress:completionHandler:

Creates an NSURLSessionUploadTask with the specified streaming request.

- (NSURLSessionUploadTask *)uploadTaskWithStreamedRequest:(NSURLRequest *)request progress:(NSProgress *__autoreleasing *)progress completionHandler:(void ( ^ ) ( NSURLResponse *response , id responseObject , NSError *error ))completionHandler

Parameters

request

The HTTP request for the request.

progress

A progress object monitoring the current upload progress.

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.

Declared In

AFURLSessionManager.h