sharedSession
NSURLSession
@interface NSURLSession : NSObject
Overview
The NSURLSession
class and related classes provide an API for downloading data from and uploading data to endpoints indicated by URLs. Your app can also use this API to perform background downloads when your app isn’t running or, in iOS, while your app is suspended. You can use the related NSURLSession
and NSURLSession
to support authentication and receive events like redirection and task completion.
Note
The NSURLSession
API involves many different classes that work together in a fairly complex way which may not be obvious if you read the reference documentation by itself. Before using the API, read the overview in the URL Loading System topic. The articles in the Essentials, Uploading, and Downloading sections offer examples of performing common tasks with NSURLSession
.
Your app creates one or more NSURLSession
instances, 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).
Types of URL sessions
The tasks within a given URL session share a common session configuration object, which defines connection behavior, like the maximum number of simultaneous connections to make to a single host, whether connections can use the cellular network, and so on.
NSURLSession
has a singleton shared
session (which doesn’t have a configuration object) for basic requests. It’s not as customizable as sessions you create, but it serves as a good starting point if you have very limited requirements. You access this session by calling the shared class method. For other kinds of sessions, you create a NSURLSession
with one of three kinds of configurations:
A default session behaves much like the shared session, but lets you configure it. You can also assign a delegate to the default session to obtain data incrementally.
Ephemeral sessions are similar to shared sessions, but don’t write caches, cookies, or credentials to disk.
Background sessions let you perform uploads and downloads of content in the background while your app isn’t running.
See Creating a session configuration object in the NSURLSession
class for details on creating each type of configuration.
Types of URL session tasks
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 four 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.
WebSocket tasks exchange messages over TCP and TLS, using the WebSocket protocol defined in RFC 6455.
Using a session delegate
Tasks in a session also share a common delegate object. You implement this delegate to provide and obtain information when various events occur, including when:
Authentication fails.
Data arrives from the server.
Data becomes available for caching.
If you don’t need the features provided by a delegate, you can use this API without providing one by passing nil
when you create a session.
Important
The session object keeps a strong reference to the delegate until your app exits or explicitly invalidates the session. If you don’t invalidate the session, your app leaks memory until the app terminates.
Each task you create with the session calls back to the session’s delegate, using the methods defined in NSURLSession
. You can also intercept these callbacks before they reach the session delegate by populating a separate delegate
that’s specific to the task.
Asynchronicity and URL sessions
Like most networking APIs, the NSURLSession
API is highly asynchronous. It returns data to your app in one of three ways, depending on the methods you call:
If you’re using Swift, you can use the methods marked with the
async
keyword to perform common tasks. For example,data(from:
fetches data, whiledelegate:) download(from:
downloads files. Your call point uses thedelegate:) await
keyword to suspend running until the transfer completes. You can also use thebytes(from:
method to receive data as andelegate:) Async
. With this approach, you use theSequence for
-await
-in
syntax to iterate over the data as your app receives it. TheURL
type also offers covenience methods to fetch bytes or lines from the shared URL session.In Swift or Objective-C, you can provide a completion handler block, which runs when the transfer completes.
In Swift or Objective-C, you can receive callbacks to a delegate method as the transfer progresses and immediately after it completes.
In addition to delivering this information to delegates, the NSURLSession
provides status and progress properties. Query these properties 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).
Protocol support
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, HTTP/2, and HTTP/3 protocols. HTTP/2 support, as described by RFC 7540, requires a server that supports Application-Layer Protocol Negotiation (ALPN).
You can also add support for your own custom networking protocols and URL schemes (for your app’s private use) by subclassing NSURLProtocol
.
App Transport Security (ATS)
iOS 9.0 and macOS 10.11 and later use App Transport Security (ATS) for all HTTP connections made with NSURLSession
. ATS requires that HTTP connections use HTTPS (RFC 2818).
For more information, see NSApp
.
Foundation copying 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 you can independently modify.
Thread safety
The URL session API is thread-safe. You can freely create sessions and tasks in any thread context. When your delegate methods call the provided completion handlers, the work is automatically scheduled on the correct delegate queue.
Topics
+ sessionWithConfiguration:
+ sessionWithConfiguration:delegate:delegateQueue:
NSURLSessionConfiguration
configuration
delegate
NSURLSessionDelegate
NSURLSessionTaskDelegate
delegateQueue
NSURLSessionTaskDelegate
- dataTaskWithURL:
- dataTaskWithURL:completionHandler:
- dataTaskWithRequest:
- dataTaskWithRequest:completionHandler:
NSURLSessionDataTask
NSURLSessionDataDelegate
- downloadTaskWithURL:
- downloadTaskWithURL:completionHandler:
- downloadTaskWithRequest:
- downloadTaskWithRequest:completionHandler:
- downloadTaskWithResumeData:
- downloadTaskWithResumeData:completionHandler:
NSURLSessionDownloadTask
NSURLSessionDownloadDelegate
- uploadTaskWithRequest:fromData:
- uploadTaskWithRequest:fromData:completionHandler:
- uploadTaskWithRequest:fromFile:
- uploadTaskWithRequest:fromFile:completionHandler:
- uploadTaskWithStreamedRequest:
NSURLSessionUploadTask
NSURLSessionDataDelegate
- streamTaskWithHostName:port:
- streamTaskWithNetService:
NSURLSessionStreamTask
NSURLSessionStreamDelegate
- webSocketTaskWithURL:
- webSocketTaskWithRequest:
- webSocketTaskWithURL:protocols:
NSURLSessionWebSocketTask
NSURLSessionWebSocketDelegate
- finishTasksAndInvalidate
- flushWithCompletionHandler:
- getTasksWithCompletionHandler:
- getAllTasksWithCompletionHandler:
- invalidateAndCancel
- resetWithCompletionHandler:
sessionDescription
Background task cancellation
- init
Deprecated+ new
DeprecatedSee Also
NSURLSessionTask