iOS NSURLSession
Remarks
The NSURLSession class and related classes provide an API for downloading content. This API provides a rich set of delegate methods for supporting authentication and gives your app the ability to perform background downloads when your app is not running or, in iOS, while your app is suspended.
At a high level, NSURLSession is based around the concept of sessions and tasks. A task represents a single request for a single URL (or a single upload to a single URL). A session is a group of related requests.
The operating system provides a single preexisting session—the shared session, which basically works like NSURLConnection. Additionally, you can create your own sessions in your app as needed.
Different apps use sessions in different ways. Many apps create a single session on launch and just keep reusing it. Other apps benefit from being able to cancel a group of related tasks (e.g. a web browser canceling all outstanding requests when you close a tab), and thus create one session to hold each group of related requests.
The first step when using NSURLSession is to create a session configuration object. The (usually) reusable object contains various session settings that you can tweak for your particular needs, such as maximum concurrency, extra headers to send with each request, whether to allow requests to be sent over the cellular radio (iOS only), timeouts, credential storage, minimum TLS version, and even proxy settings.
There are three types of session configurations, depending on how you want the resulting session to behave:
- Default configurations create sessions that work much like NSURLConnection.
- Background configurations create sessions in which requests happen out-of-process, allowing downloads to continue even when the app is no longer running.
- Ephemeral configurations create sessions that do not cache anything to disk, do not store cookies to disk, etc. and thus are suitable for backing things like incognito browser windows.
When you create a background configuration, you must provide a session identifier that allows you to reassociate the background session later (if your app exits or is suspended or terminated by the OS). You must not have more than one instance of a session with the same identifier active in your app, so as a rule, these configurations are not reusable. All other session configurations can be reused to create as many sessions as you want. So if you need to create multiple sessions with similar settings, you can create the configuration once and reuse it every time you create a new session.
After you create a session, you can create tasks in that session. There are three types of tasks:
- Data tasks return data as an NSData object. These are suitable for general use, but are not supported in background sessions.
- Download tasks return data as a file on disk. These are suitable for larger requests, or for use in background sessions.
- Upload tasks upload data from an NSData object or from a file on disk. You provide a data object or file that provides the POST body. The body data/file that you provide on the task overrides any body data/file provided in the NSURLRequest object (if applicable).
Each of these types lets you obtain the response data in a couple of different ways—either by using block-based callbacks or by providing a delegate on the session and implementing delegate methods.
Additionally NSURLSession lets you provide delegate methods for handling authentication, performing custom TLS certificate handling (both for client certificates and server validation), changing the caching behavior, and so on.
