Class

NSURLSession

An object that coordinates a group of related network data transfer tasks.

Overview

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 isn’t running or, in iOS, while your app is suspended.

The NSURLSession class natively supports the data, file, ftp, http, and https URL schemes, with transparent support for proxy servers and SOCKS gateways, as configured in the user’s system preferences.

NSURLSession supports the HTTP/1.1, SPDY, and HTTP/2 protocols. HTTP/2 support is described by RFC 7540, and requires a server supporting either ALPN or NPN for protocol negotiation.

You can also add support for your own custom networking protocols and URL schemes (for your app’s private use) using NSURLProtocol.

With the NSURLSession API, your app creates one or more sessions, each of which coordinates a group of related data transfer tasks. For example, if you’re creating a web browser, your app might create one session per tab or window, or one session for interactive use and another for background downloads. Within each session, your app adds a series of tasks, each of which represents a request for a specific URL (following HTTP redirects, if necessary).

The tasks within a given URL session share a common session configuration object, which defines connection behavior, such as the maximum number of simultaneous connections to make to a single host, whether to allow connections over a cellular network, and so on. The behavior of a session is determined in part by which method you call when creating its configuration object:

  • The singleton shared session (which has no configuration object) is for basic requests. It’s not as customizable as sessions that you create, but it serves as a good starting point if you have very limited requirements. You access this session by calling the sharedSession class method. See that method’s discussion for more information about its limitations.

  • Default sessions behave much like the shared session (unless you customize them further), but let you obtain data incrementally using a delegate. You can create a default session configuration by calling the defaultSessionConfiguration method on the NSURLSessionConfiguration class.

  • Ephemeral sessions are similar to default sessions, but they don’t write caches, cookies, or credentials to disk. You can create an ephemeral session configuration by calling the ephemeralSessionConfiguration method on the NSURLSessionConfiguration class.

  • Background sessions let you perform uploads and downloads of content in the background while your app isn’t running. You can create a background session configuration by calling the backgroundSessionConfiguration: method on the NSURLSessionConfiguration class.

The session configuration object also contains a reference to URL cache and cookie storage objects that may be used when making requests and handling the responses, depending on the configuration and request type.

The tasks in a session also share a common delegate that lets you provide and obtain information when various events occur—when authentication fails, when data arrives from the server, when data is ready to be cached, and so on. Using a URL Session has a step-by-step list of events that occur when a session is performing a task, and which delegate methods are called as a result.

On the other hand, if you don’t need any of the features provided by a delegate, you can use this API without providing one by passing nil when you create a session.

Within a session, you create tasks that optionally upload data to a server and then retrieve data from the server either as a file on disk or as one or more NSData objects in memory. The NSURLSession API provides three types of tasks:

  • Data tasks send and receive data using NSData objects. Data tasks are intended for short, often interactive requests to a server.

  • Upload tasks are similar to data tasks, but they also send data (often in the form of a file), and support background uploads while the app isn’t running.

  • Download tasks retrieve data in the form of a file, and support background downloads and uploads while the app isn’t running.

Like most networking APIs, the NSURLSession API is highly asynchronous. It returns data to your app in one of two ways, depending on the methods you call:

  • By calling a completion handler block when a transfer finishes successfully or with an error.

  • By calling methods on the session’s delegate as data is received and when the transfer is complete.

In addition to delivering this information to delegates, the NSURLSession API provides status and progress properties that you can query if you need to make programmatic decisions based on the current state of the task (with the caveat that its state can change at any time).

URL sessions also support canceling, restarting or resuming, and suspending tasks, and provide the ability to resume suspended, canceled, or failed downloads where they left off.

Related Classes

The NSURLSession API uses a number of classes that are also commonly used with other APIs, such as NSURLConnection and NSURLDownload. Some of these shared classes include:

  • NSURL—An object that contains a URL.

  • NSURLRequest—Encapsulates metadata related to a URL request, including the URL, request method, and so on.

  • NSURLResponse—Encapsulates metadata related to a server’s response to a request, such as the content MIME type and length.

  • NSHTTPURLResponse—Adds metadata specific to HTTP requests, such as response headers.

  • NSCachedURLResponse—Encapsulates a URL response object, along with the actual body data of the server’s response, for caching purposes.

App Transport Security (ATS)

Starting in iOS 9.0 and OS X 10.11, a new security feature called App Transport Security (ATS) is enabled by default for all HTTP connections made with NSURLSession. ATS requires that HTTP connections use HTTPS (RFC 2818).

For more information, see NSAppTransportSecurity in the Information Property List Key Reference.

Using a URL Session

To make a request using the NSURLSession class:

  1. Create a session configuration. For background sessions, this configuration must contain a unique identifier. Store that identifier, and use it to reassociate with the session if your app crashes or is terminated or suspended.

  2. Create a session, specifying a configuration object and, optionally, a delegate.

  3. Create task objects within a session that each represent a resource request. These task objects are subclasses of NSURLSessionTaskNSURLSessionDataTask, NSURLSessionUploadTask, or NSURLSessionDownloadTask, depending on the behavior you’re trying to achieve. Each task starts in a suspended state. After your app calls resume on the task, it begins downloading the specified resource.

After you start a task, the session calls methods on its delegate, as follows:

  1. If the initial handshake with the server requires a connection-level challenge (such as an SSL client certificate), NSURLSession calls either the URLSession:task:didReceiveChallenge:completionHandler: or URLSession:didReceiveChallenge:completionHandler: delegate method.

  2. If the task’s data is provided from a stream, the NSURLSession object calls the delegate’s URLSession:task:needNewBodyStream: delegate method to obtain an instance of NSInputStream that provides the body data for the new request.

  3. During the initial upload of body content to the server (if applicable), the delegate periodically receives URLSession:task:didSendBodyData:totalBytesSent:totalBytesExpectedToSend: callbacks that report the progress of the upload.

  4. The server sends a response.

  5. If the response indicates that authentication is required, the session calls its delegate’s URLSession:task:didReceiveChallenge:completionHandler: method. Go back to step 2.

  6. If the response is an HTTP redirect response, the NSURLSession object calls the delegate’s URLSession:task:willPerformHTTPRedirection:newRequest:completionHandler: method. That delegate method calls the provided completion handler with either the provided NSURLRequest object (to follow the redirect), a new NSURLRequest object (to redirect to a different URL), or nil (to treat the redirect’s response body as a valid response and return it as the result).

    • If you decide to follow the redirect, go back to step 2.

    • If the delegate doesn’t implement this method, the redirect is followed up to the maximum number of redirects.

  7. For a download (or redownload) task created by calling downloadTaskWithResumeData: or downloadTaskWithResumeData:completionHandler:, NSURLSession calls the delegate’s URLSession:downloadTask:didResumeAtOffset:expectedTotalBytes: method with the new task object.

  8. For a data task, the NSURLSession object calls the delegate’s URLSession:dataTask:didReceiveResponse:completionHandler: method. Decide whether to convert the data task into a download task, and then call the completion handler to convert, continue, or cancel the task. If your app chooses to convert the data task to a download task, NSURLSession calls the delegate’s URLSession:dataTask:didBecomeDownloadTask: method with the new download task as a parameter. After this call, the delegate receives no further callbacks from the data task, and begins receiving callbacks from the download task.

  9. During the transfer from the server, the delegate periodically receives a task-level callback to report the progress of the transfer. For a data task, the session calls the delegate’s URLSession:dataTask:didReceiveData:method with the actual pieces of data as they’re received. For a download task, the session calls the delegate’s URLSession:downloadTask:didWriteData:totalBytesWritten:totalBytesExpectedToWrite: method with the number of bytes successfully written to disk. If the user tells your app to pause the download, cancel the task by calling the cancelByProducingResumeData: method. Later, if the user asks your app to resume the download, pass the returned resume data to either the downloadTaskWithResumeData: or downloadTaskWithResumeData:completionHandler: method to create a new download task that continues the download. (Go to step 1.)

  10. For a data task, the NSURLSession object may call the delegate’s URLSession:dataTask:willCacheResponse:completionHandler: method. Your app should then decide whether to allow caching. If you don’t implement this method, the default behavior is to use the caching policy specified in the session’s configuration object.

  11. If the response is multipart encoded, the session may call the delegate’s didReceiveResponse method again, followed by zero or more additional didReceiveData calls. If this happens, go to step 8 (handling the didReceiveResponse call).

  12. If a download task completes successfully, then the NSURLSession object calls the task’s URLSession:downloadTask:didFinishDownloadingToURL: method with the location of a temporary file. Your app must either read the response data from this file or move it to a permanent location before this delegate method returns.

  13. When any task completes, the NSURLSession object calls the delegate’s URLSession:task:didCompleteWithError: method with either an error object or nil (if the task completed successfully). If the download task can be resumed, the NSError object’s userInfo dictionary contains a value for the NSURLSessionDownloadTaskResumeData key. Your app should pass this value to call downloadTaskWithResumeData: or downloadTaskWithResumeData:completionHandler: to create a new download task that continues the existing download. If the task can’t be resumed, your app should create a new download task and restart the transaction from the beginning. In either case, if the transfer failed for any reason other than a server error, go to step 3 (creating and resuming task objects).

  14. If you no longer need a session, you can invalidate it by calling either invalidateAndCancel (to cancel outstanding tasks) or finishTasksAndInvalidate (to allow outstanding tasks to finish before invalidating the object). If you don’t invalidate the session, it automatically goes away when your app is terminated (unless it’s a background session with active tasks). After invalidating the session, when all outstanding tasks have been canceled or have finished, the session calls the delegate’s URLSession:didBecomeInvalidWithError: method. When that delegate method returns, the session disposes of its strong reference to the delegate.

If your app cancels an in-progress download, the NSURLSession object calls the delegate’s URLSession:task:didCompleteWithError: method as though an error occurred.

NSCopying Behavior

Session and task objects conform to the NSCopying protocol as follows:

  • When your app copies a session or task object, you get the same object back.

  • When your app copies a configuration object, you get a new copy that you can independently modify.

Thread Safety

The URL session API itself is fully thread-safe. You can freely create sessions and tasks in any thread context, and when your delegate methods call the provided completion handlers, the work is automatically scheduled on the correct delegate queue.

Topics

Creating a Session

sessionWithConfiguration:

Creates a session with the specified session configuration.

sessionWithConfiguration:delegate:delegateQueue:

Creates a session with the specified session configuration, delegate, and operation queue.

sharedSession

Returns a shared singleton session object.

Configuring a Session

configuration

A copy of the configuration object for this session.

delegate

The delegate assigned when this object was created.

NSURLSessionDelegate

The NSURLSessionDelegate protocol describes the methods that NSURLSession objects call on their delegates to handle session-level events.

NSURLSessionTaskDelegate

The NSURLSessionTaskDelegate protocol defines the task-specific delegate methods that you should implement when working with any type of NSURLSession task.

delegateQueue

The operation queue provided when this object was created.

sessionDescription

An app-defined descriptive label for the session.

Adding Data Tasks to a Session

dataTaskWithURL:

Creates a task that retrieves the contents of the specified URL.

dataTaskWithURL:completionHandler:

Creates a task that retrieves the contents of the specified URL, then calls a handler upon completion.

dataTaskWithRequest:

Creates a task that retrieves the contents of a URL based on the specified URL request object.

dataTaskWithRequest:completionHandler:

Creates a task that retrieves the contents of a URL based on the specified URL request object, and calls a handler upon completion.

NSURLSessionDataTask

A URL session task that returns downloaded data directly to the app in memory.

NSURLSessionDataDelegate

The NSURLSessionDataDelegate protocol defines the methods that a delegate of an NSURLSession object can implement to handle task-level events specific to data tasks and upload tasks.

Adding Download Tasks to a Session

downloadTaskWithURL:

Creates a download task that retrieves the contents of the specified URL and saves the results to a file.

downloadTaskWithURL:completionHandler:

Creates a download task that retrieves the contents of the specified URL, saves the results to a file, and calls a handler upon completion.

downloadTaskWithRequest:

Creates a download task that retrieves the contents of a URL based on the specified URL request object and saves the results to a file.

downloadTaskWithRequest:completionHandler:

Creates a download task that retrieves the contents of a URL based on the specified URL request object, saves the results to a file, and calls a handler upon completion.

downloadTaskWithResumeData:

Creates a download task to resume a previously canceled or failed download.

downloadTaskWithResumeData:completionHandler:

Creates a download task to resume a previously canceled or failed download and calls a handler upon completion.

NSURLSessionDownloadTask

A URL session task that stores downloaded data to file.

NSURLSessionDownloadDelegate

The NSURLSessionDownloadDelegate protocol defines delegate methods that you should implement when using NSURLSession download tasks.

Adding Upload Tasks to a Session

uploadTaskWithRequest:fromData:

Creates a task that performs an HTTP request for the specified URL request object and uploads the provided data.

uploadTaskWithRequest:fromData:completionHandler:

Creates a task that performs an HTTP request for the specified URL request object, uploads the provided data, and calls a handler upon completion.

uploadTaskWithRequest:fromFile:

Creates a task that performs an HTTP request for uploading the specified file.

uploadTaskWithRequest:fromFile:completionHandler:

Creates a task that performs an HTTP request for uploading the specified file, then calls a handler upon completion.

uploadTaskWithStreamedRequest:

Creates a task that performs an HTTP request for uploading data based on the specified URL request.

NSURLSessionUploadTask

A URL session task that uploads data to the network in a request body.

NSURLSessionDataDelegate

The NSURLSessionDataDelegate protocol defines the methods that a delegate of an NSURLSession object can implement to handle task-level events specific to data tasks and upload tasks.

Adding Stream Tasks to a Session

streamTaskWithHostName:port:

Creates a task that establishes a bidirectional TCP/IP connection to a specified hostname and port.

streamTaskWithNetService:

Creates a task that establishes a bidirectional TCP/IP connection using a specified network service.

NSURLSessionStreamTask

A URL session task that is stream-based.

NSURLSessionStreamDelegate

The NSURLSessionStreamDelegate protocol defines delegate methods that you should implement when using NSURLSession stream tasks.

Managing the Session

finishTasksAndInvalidate

Invalidates the session, allowing any outstanding tasks to finish.

flushWithCompletionHandler:

Flushes cookies and credentials to disk, clears transient caches, and ensures that future requests occur on a new TCP connection.

getTasksWithCompletionHandler:

Asynchronously calls a completion callback with all data, upload, and download tasks in a session.

getAllTasksWithCompletionHandler:

Asynchronously calls a completion callback with all tasks in a session

invalidateAndCancel

Cancels all outstanding tasks and then invalidates the session.

resetWithCompletionHandler:

Empties all cookies, caches and credential stores, removes disk files, flushes in-progress downloads to disk, and ensures that future requests occur on a new socket.

Constants

NSURLSession-Specific NSError userInfo Dictionary Keys

Keys used in conjunction with NSError objects returned by the NSURLSession API.

Background Task Cancellation reasons

Constants that indicate why a background task was cancelled.

NSURLSessionDelayedRequestDisposition

The action to take on a delayed URL session task.

Transfer Size Constant

A constant denoting an unknown transfer size.

Relationships

Inherits From

See Also

First Steps

Fetching Website Data into Memory

Receive data directly into memory by creating a data task from a URL session.

Posting Data to a Website

Use upload tasks to post data to servers.

Downloading Files in the Background

Create tasks that download files while your app is inactive.

NSURLSessionConfiguration

A configuration object that defines behavior and policies for a URL session.

NSURLSessionTask

A task, such as downloading a specific resource, to be undertaken by a URL session.