In iOS 7, Apple introduced
NSURLSession, which is a suite of classes that replaces
NSURLConnection as the preferred method of networking. In this article, we cover the benefits of using
NSURLSession, and when and how to use it.
What are the benefits of using NSURLSession?
There are a number of new advantages and benefits of using NSURLSession:
- Uploads and Downloads can be done in the Background
- When the NSURLSession is created, a configuration option can be selected to allow background networking. This helps to save battery life, supports multitasking and allows developers to use the same delegate model as in-process transfers.
- Allows the pause and resume for network operations
- When the NSURLSession API is utilized, any networking task can be paused, stopped and restarted. There is no NSOperation subclassing required.
- Configurable container for storing network request configuration
- Each NSURLSession provides a configurable container for storing network requests. For instance, for setting an HTTP header option, we will need to only do this once and each subsequent request will utilize the same configuration
- Allows a private storage which is subclassable.
- Each NSURLSession is subclassable and one can configure a session to use private storage on a per session basis. This allows one to have private storage objects outside of the global state.
- Improved authentication handling
- When using NSURLConnection, if an authentication challenge was issued, the challenge would come back for an arbitrary request, so one would not know exactly what request was getting the challenge. However, with NSURLSession, the delegate handles the authentication.
- Rich delegate model
- NSURLConnection does have some asynchronous block based methods. However, a delegate cannot be used with them.
- Uploads and downloads allowed through the file system.
- This encourages a separation of the data (i.e. file contents) from the metadata (i.e. URL and settings)
NSURLSession
NSURLSession is designed as a replacement API for NSURLConnection. An NSURLSession is made using an NSURLSessionConfiguration with an optional delegate. After the session is established, the network requirements are satisfied by creating NSURLSessionTask.
According to Apple's URL Loading Programming Guide, you can use the NSURLSession API in two ways: with a system-provided delegate or with your own delegate. In general, you must use your own delegate if your app does any of the following:
Uses background sessions to download or upload content while your app is not running.
Performs custom authentication.
Performs custom SSL certificate verification.
Decides whether a transfer should be downloaded to disk or displayed based on the MIME type returned by the server or other similar criteria.
Uploads data from a body stream (as opposed to an NSData object).
Limits caching programmatically.
Limits HTTP redirects programmatically.
If your app does not need to do any of these things, your app can use the system-provided delegates.
Basic sequence of method calls that your app needs to make and completion handler calls that your app receives when using NSURLSession with the system-provided delegate :
- Create the NSURLSessionConfiguration
- Create a session specifying a configuration object and a nil delegate.
- Create task objects within a session that each represent a resource request. The task objects are subclasses of
NSURLSessionTask—NSURLSessionDataTask, NSURLSessionUploadTask, or NSURLSessionDownloadTask, depending on the behavior you are trying to achieve. These objects are analogous to NSURLConnection objects, but give you more control and a unified delegate model.
- We need to have our delegate implement the required methods from the NSURLSessionDownloadDelegate protocol.
- When a task completes, the NSURLSession object calls the task's completion handler.
- When your app no longer needs a session, invalidate it by calling either either
invalidateAndCancel (to cancel outstanding tasks) or finishTasksAndInvalidate (to allow outstanding tasks to finish before invalidating the object).
Important: If you are using the NSURLSession class without providing delegates, your app must create tasks using a call that takes a completionHandler parameter, because otherwise it cannot obtain data from the class.
Note: NSURLSession does not report server errors through the error parameter. The only errors your app receives through the error parameter are client-side errors, such as being unable to resolve the hostname or connect to the host. The error codes are described in
URL Loading System Error Codes. Server-side errors are reported through the HTTP status code in the
NSHTTPURLResponse object. For more information, read the documentation for the
NSHTTPURLResponse and
NSURLResponse classes.
Step #1: Creating the NSURLSessionConfiguration
There are three ways to create an NSURLSessionConfiguration:
- defaultSessionConfiguration
- creates a configuration object that uses the global cache, cookie and credential storage objects. This configuration provides a session to look very much like the NSURLConnection.
- ephemeralSessionConfiguration
- This configuration is for "private" sessions and has no persistent storage for cache, cookie or credential storage objects
- backgroundSessionConfiguration
- This configuration is used for making networking calls from remote push notifications or while the app is suspended.
Once the NSURLSessionConfiguration is created, then the setting of various properties on it can be done as follows:
NSURLSessionConfiguration *sessionConfig =
[NSURLSessionConfiguration defaultSessionConfiguration];
// restricts network operations to Wifi
sessionConfig.allowsCellularAccess = NO;
// sets all requests to only accept JSON responses
[sessionConfig setHTTPAdditionalHeaders:
@{@"Accept": @"application/json"}];
// configures timeouts & restricts app to only have one network connection to a host
sessionConfig.timeoutIntervalForRequest = 30.0;
sessionConfig.timeoutIntervalForResource = 60.0;
sessionConfig.HTTPMaximumConnectionsPerHost = 1;
|
Step #2: Creating the Session
With NSURLSession, you can create the tasks using the block based convenience methods, set up a delegate or both. For instance, if you want to download an image, then you will need to create an NSURLSessionDownloadTask.
// set the image URL
NSString *imageUrl = @"http://someImage.png";
// create the default session configuration
NSURLSessionConfiguration *sessionConfig =
[NSURLSessionConfiguration defaultSessionConfiguration];
// create a session using the current class as a delegate
NSURLSession *session =
[NSURLSession sessionWithConfiguration:sessionConfig
delegate:self
delegateQueue:nil];
Step #3: Download the image by creating a task with a completion handler
// the task is created from a session
NSURLSessionDownloadTask *getImageTask =
[session downloadTaskWithURL:[NSURL URLWithString:imageUrl]
completionHandler:^(NSURL *location,
NSURLResponse *response,
NSError *error) {
// the image is uploaded as NSData
UIImage *downloadedImage =
[UIImage imageWithData:
[NSData dataWithContentsOfURL:location]];
// update UIImageView image to show the new file
dispatch_async(dispatch_get_main_queue(), ^{
// do stuff with image
_imageWithBlock.image = downloadedImage;
});
}];
// start up the task
[getImageTask resume];
|
Step #4 Implementing the delegate methods
We need to have our delegate implement some methods from the NSURLSessionDownloadDelegate protocol. For instance,
we need to get notified when the download is complete:
-(void)URLSession:(NSURLSession *)session
downloadTask:(NSURLSessionDownloadTask *)downloadTask
didFinishDownloadingToURL:(NSURL *)location
{
// see code above from completion handler
}
|
Here we are provided with the location that the file is downloaded to so you can use it to work with the image.
Tracking Download Progress.
To track the download progress for either task creation method, do the following:
-(void)URLSession:(NSURLSession *)session
downloadTask:(NSURLSessionDownloadTask *)downloadTask
didWriteData:(int64_t)bytesWritten
totalBytesWritten:(int64_t)totalBytesWritten
totalBytesExpectedToWrite:(int64_t)totalBytesExpectedToWrite
{
NSLog(@"%f / %f", (double)totalBytesWritten,
(double)totalBytesExpectedToWrite);
}
|
Step #5: When the task is finished, URLSession:downloadTask:didFinishDownloadingToURL: is called.
In the case of a file download, this is when you can save the file from the temporary location to a permanent one.
NSURLSessionTask
Both NSURLSessionDataTask and NSURLSessionDownloadTask are derived from NSURLSessionTask, which is the
base class as illustrated below.
 |
| Image: Courtesy of Ray Wenderlick's NSURLSession Tutorial |
NSURLSessionTask
This is the base class for creating session tasks, which are generally one of the following subclasses.
NSURLSessionDataTask
This task is used for issuing HTTP GET requests to pull down data from servers.
The data is returned in the form of NSData, which needs to be converted to the appropriate
XML, JSON, etc. format.
NSURLSessionDataTask *jsonData = [session dataTaskWithURL:yourNSURL
completionHandler:^(NSData *data,
NSURLResponse *response,
NSError *error) {
// handle NSData
}];
|
NSURLSessionUploadTask
This class is used to upload something to a web service using HTTP POST or PUT commands.
The delegate for the tasks also allows you to watch the network traffic while it is being
transmitted.
Upload an image:
NSData *imageData = UIImageJPEGRepresentation(image, 0.6);
NSURLSessionUploadTask *uploadTask =
[upLoadSession uploadTaskWithRequest:request
fromData:imageData];
|
The task above is created from a session and the image is uploaded as NSData. Separate methods are available for uploading using files or a stream.
NSURLSessionDownloadTask
NSURLSessionDownloadTask makes it super-easy to download files from remote service and/or pause and resume the download at will. This subclass is a little different than the other two.
- This type of task writes directly to a temporary file.
- During the download the session will call NSURLSessionDownload URLSession:downloadTask:didWriteData:totalBytesWritten:totalBytesExpectedToWrite: to update status information
- When the task is finished, URLSession:downloadTask:didFinishDownloadingToURL: is called. This is when you can save the file from the temp location to a permanent one.
- When the download fails or is cancelled you can get the data to resume the download.
- This feature can be useful for downloading photos to your device's camera roll.
We have covered the essential sequence of method calls required for NSURLSession when using a system provided delegate. For further thorough documentation and detailed information on the NSURLSession and associated APIs, please refer to the Apple's URL Loading System Programming Guide or Ray Wenderlick's NSURLSession Tutorial .
If you find this post helpful or want to share your experiences, feel free to send me comments here or follow me on Twitter @tasneemsayeed. Have fun with NSURLSession Coding!
|
