NSURLSession

Inherits From

NSObject
NSURLSession
AVAssetDownloadURLSession

NSObject
NSURLSession
AVAssetDownloadURLSession

Conforms To

Import Statement

Objective-C

@import Foundation;

Swift

import Foundation

Availability

Available in iOS 7.0 and later

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.

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. You can also add support for your own custom networking protocols and URL schemes (for your app’s private use).

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 are writing a web browser, your app might create one session per tab or window, or one session for interactive use and another session 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 is 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 do not 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 is not 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. For all background downloads and uploads, you must provide a delegate that conforms to the NSURLSessionDownloadDelegate Objective-C protocol. Otherwise, if you don’t need any of the features provided by a delegate, you can use this API without providing a delegate by passing nil when you create a session.

Within a session, you create tasks that optionally upload data to a server, 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 is not running.
Download tasks retrieve data in the form of a file, and support background downloads and uploads while the app is not 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:

To a completion handler block that is called 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.

URL Session Class Hierarchy

The NSURLSession API consists of the following classes (nested to show subclass relationships):

NSURLSession—A session object.
NSURLSessionConfiguration—A configuration object used when initializing the session.
NSURLSessionTask—The base class for tasks within a session.
- NSURLSessionDataTask—A task for retrieving the contents of a URL as an NSData object
  - NSURLSessionUploadTask—A task for uploading a file, then retrieving the contents of a URL as an NSData object
- NSURLSessionDownloadTask—A task for retrieving the contents of a URL as a temporary file on disk
- NSURLSessionStreamTask—A task for establishing a TCP/IP connection

In addition, the NSURLSession API provides four protocols that define delegate methods your app can implement to provide more fine-grained control over session and task behavior.

NSURLSessionDelegate—Defines delegate methods to handle session-level events
NSURLSessionTaskDelegate—Defines delegate methods to handle task-level events common to all task types
NSURLSessionDataDelegate—Defines delegate methods to handle task-level events specific to data and upload tasks
NSURLSessionDownloadDelegate—Defines delegate methods to handle task-level events specific to download tasks
NSURLSessionStreamDelegate—Defines delegate methods to handle task-level events specific to stream tasks

Finally, 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 additional metadata specific to HTTP requests, such as response headers.
NSCachedURLResponse—Encapsulates an NSURLResponse object, along with the actual body data of the server’s response, for caching purposes.

Authentication and TLS Customization

When a server requests authentication or provides credentials during TLS negotiation, the URL session calls methods on its delegate, allowing you to handle the authentication or certificate validation in a custom manner. The method it calls depends on whether you are handling a task-specific challenge or a session-wide challenge. Table 1 shows the difference between the two.

**Table 1**Session-level and connection-level challenges
Session-wide challenges	Task-specific challenges
`NSURLAuthenticationMethodNTLM`	`NSURLAuthenticationMethodDefault`
`NSURLAuthenticationMethodNegotiate`	`NSURLAuthenticationMethodHTTPBasic`
`NSURLAuthenticationMethodClientCertificate`	`NSURLAuthenticationMethodHTTPDigest`
`NSURLAuthenticationMethodServerTrust`

For task-specific challenges, the session calls its delegate’s URLSession:task:didReceiveChallenge:completionHandler: method.

For session-wide authentication challenges, the session calls its delegate’s URLSession:didReceiveChallenge:completionHandler: method if that method exists. Otherwise, it calls the delegate’s URLSession:task:didReceiveChallenge:completionHandler: method.

If you do not implement these methods, when a request requires client authentication, the URL session attempts to authenticate as follows:

Using the authentication information provided as part of the requested URL, if available
By looking up Internet passwords and certificates in the user’s keychain (in OS X) or the app’s keychain (in iOS)

Then, if credentials are not available, or if the server rejects the credentials, the connection continues without authenticating. For HTTP and HTTPS requests, the connection attempt fails with an appropriate HTTP status code, and may provide alternative content (such as the public version of a private site). For other URL types (such as FTP),the connection fails with a connection failure.

App Transport Security (ATS)

Starting in iOS 9.0 and OS X v10.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 an URL Session

To make a request using the NSURLSession class:

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.
Create a session, specifying a configuration object and, optionally, a delegate.
Create task objects within a session that each represent a resource request. These task objects are subclasses of NSURLSessionTask—NSURLSessionDataTask, NSURLSessionUploadTask, or NSURLSessionDownloadTask, depending on the behavior you are trying to achieve.

Each task starts out 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:

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, as previously described in Authentication and TLS Customization.

For more information about writing an authentication delegate method for NSURLSession, read URL Session Programming Guide.
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 NSInputStream object that provides the body data for the new request.
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.
The server sends a response.
If the response indicates that authentication is required, the session calls its delegate’s URLSession:task:didReceiveChallenge:completionHandler: method. Go back to step 2.
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.
For a (re-)download task created by calling downloadTaskWithResumeData: or downloadTaskWithResumeData:completionHandler:, NSURLSession calls the delegate’s URLSession:downloadTask:didResumeAtOffset:expectedTotalBytes: method with the new task object.
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 callback to continue receiving data or downloading data.

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.
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 are 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.)
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 do not implement this method, the default behavior is to use the caching policy specified in the session’s configuration object.
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).
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.
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 cannot 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).

Note

NSURLSession does not report server errors through the error parameter. The only errors your delegate 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.
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.

Background Transfer Considerations

Because restarting your app (or waiting for the user to relaunch it) is relatively expensive, some features are unavailable in background sessions. As a result:

The session must provide a delegate for event delivery. Because your app might quit and be relaunched while the transfer is in progress, completion handler blocks are not supported. (For uploads and downloads, these delegates behave the same as for in-process transfers.)
Only HTTP and HTTPS protocols are supported. Other built-in networking protocols are not supported, and neither are custom networking protocols.
Only upload and download tasks are supported (no data tasks).
Redirects are always followed.
The number of system-wide concurrent background transfers is limited.
A background task may be cancelled if it fails to meet a system-specified throughput limit. That is to say, if a long-running task is not sending or receiving enough data over a period of time, it may be cancelled to be resumed later. Therefore, it is important to make a transfer resumable, if possible.
If the background transfer is initiated while the app is in the background, the task is treated as discretionary. In other words, it behaves like a task in a session whose configuration object’s discretionary property is true.

If these limitations are incompatible with your app’s needs, you can also download remote resources to a file in non-background sessions. If you do, then when the user puts your iOS app into the background or quits your OS X app, pause any active downloads by calling the cancelByProducingResumeData: method. Resume the downloads when the user brings your app to the foreground again. If your app is terminated before you have obtained resume data, you’ll be unable to resume the download.

Note

Background sessions are optimized for transferring a small number of large resources that can be resumed as necessary. If possible, you may want to investigate methods of optimizing server-side behavior to facilitate this kind of usage, such as:

Making requests to endpoints that send or receive zip or tar archives instead of making several individual calls.
Making requests to endpoints that send or receive incremental diffs for replication between the client and server.
Making requests to endpoints that return an upload identifier, which can then be used to track and resume the transfer of data to the server.
Adding an intermediary web service that proxies requests to a canonical web service in order to facilitate any of the aforementioned optimizations.

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.

Creating a Session


    
      
           init(configuration:)
      
      
           + sessionWithConfiguration:

Creates a session with the specified session configuration.

Declaration

Swift

init(configuration configuration: NSURLSessionConfiguration)

Objective-C

+ (NSURLSession *)sessionWithConfiguration:(NSURLSessionConfiguration *)configuration

Parameters


  configuration

A configuration object that specifies certain behaviors, such as caching policies, timeouts, proxies, pipelining, TLS versions to support, cookie policies, credential storage, and so on. If nil, the session uses a newly created default configuration object.

See NSURLSessionConfiguration Class Reference for more information.

Discussion

Calling this method is equivalent to calling sessionWithConfiguration:delegate:delegateQueue: with a nil delegate and queue.

Availability

Available in iOS 7.0 and later.


    
      
           init(configuration:delegate:delegateQueue:)
      
      
           + sessionWithConfiguration:delegate:delegateQueue:

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

Declaration

Swift

init(configuration configuration: NSURLSessionConfiguration, delegate delegate: NSURLSessionDelegate?, delegateQueue queue: NSOperationQueue?)

Objective-C

+ (NSURLSession *)sessionWithConfiguration:(NSURLSessionConfiguration *)configuration delegate:(id<NSURLSessionDelegate>)delegate delegateQueue:(NSOperationQueue *)queue

Parameters

`configuration`	A configuration object that specifies certain behaviors, such as caching policies, timeouts, proxies, pipelining, TLS versions to support, cookie policies, and credential storage. If `nil`, the session uses a newly created default configuration object. See NSURLSessionConfiguration Class Reference for more information.
`delegate`	A session delegate object that handles requests for authentication and other session-related events. This delegate object is responsible for handling authentication challenges, for making caching decisions, and for handling other session-related events. If `nil`, the class should be used only with methods that take completion handlers. Important The session object keeps a strong reference to the delegate until your app exits or explicitly invalidates the session. If you do not invalidate the session by calling the `invalidateAndCancel` or `finishTasksAndInvalidate` method, your app leaks memory until it exits.
`queue`	An operation queue for scheduling the delegate calls and completion handlers. The queue need not be a serial queue. If `nil`, the session creates a serial operation queue for performing all delegate method calls and completion handler calls.

Availability

Available in iOS 7.0 and later.

sharedSession() + sharedSession
Returns a shared singleton session object.

Declaration

Swift

class func sharedSession() -> NSURLSession

Objective-C

+ (NSURLSession *)sharedSession
Discussion

For basic requests, the URL session class provides a shared singleton session object that gives you a reasonable default behavior. By using the shared session, you can fetch the contents of a URL to memory with just a few lines of code.

Unlike the other session types, you do not create the shared session; you merely request it by calling [NSURLSession sharedSession]. As a result, you don’t provide a delegate or a configuration object. Therefore, with the shared session:
- You cannot obtain data incrementally as it arrives from the server.
- You cannot significantly customize the default connection behavior.
- Your ability to perform authentication is limited.
- You cannot perform background downloads or uploads while your app is not running.
The shared session uses the shared NSURLCache, NSHTTPCookieStorage, and NSURLCredentialStorage objects, uses a shared custom networking protocol list (configured with registerClass: and unregisterClass:), and is based on a default configuration.

When working with a shared session, you should generally avoid customizing the cache, cookie storage, or credential storage (unless you are already doing so with NSURLConnection), because there’s a very good chance that you’ll eventually outgrow the capabilities of the default session, at which point you’ll have to rewrite all of those customizations in a manner that works with your custom URL sessions.

In other words, if you’re doing anything with caches, cookies, authentication, or custom networking protocols, you should probably be using a default session instead of the shared session.
Availability

Available in iOS 7.0 and later.

Configuring a Session

configuration configuration Property

A copy of the configuration object for this session. (read-only)

Declaration

Swift

@NSCopying var configuration: NSURLSessionConfiguration { get }

Objective-C

@property(readonly, copy) NSURLSessionConfiguration *configuration

Discussion

Changing mutable values within the configuration object has no effect on the current session, but you can create a new session with the modified configuration object.

Note

On iOS 9 and OS X 10.11, NSURLSession objects store a copy of the NSURLSessionConfiguration object passed to their initializers, such that a session’s configuration is immutable after initialization. Any further changes to mutable properties on the configuration object passed to a session’s initializer or the value returned from a session’s configuration property do not affect the behavior of that session.

On previous versions of iOS and OS X, there is a bug in the implementation, whereby NSURLSession objects instead store a reference to configuration objects passed to their initializers. This allows the behavior of a session to be further configured after initialization by modifying the configuration object passed to a session’s initializer or the value returned from a session’s configuration property. You can ensure consistent behavior across different platform versions by explicitly calling copy on configuration objects passed to an NSURLSession initializer or returned from the configuration property.

Availability

Available in iOS 7.0 and later.
delegate delegate Property

The delegate assigned when this object was created. (read-only)

Declaration

Swift

var delegate: NSURLSessionDelegate? { get }

Objective-C

@property(readonly, retain) id< NSURLSessionDelegate > delegate

Discussion

This delegate object is responsible for handling authentication challenges, for making caching decisions, and for handling other session-related events. The session object keeps a strong reference to this delegate until your app exits or explicitly invalidates the session. If you do not invalidate the session, your app leaks memory until it exits.

Note

This delegate object must be set at object creation time and may not be changed.

Availability

Available in iOS 7.0 and later.
delegateQueue delegateQueue Property

The operation queue provided when this object was created. (read-only)

Declaration

Swift

var delegateQueue: NSOperationQueue { get }

Objective-C

@property(readonly, retain) NSOperationQueue *delegateQueue

Discussion

All delegate method calls and completion handlers related to the session are performed on this queue. The session object keeps a strong reference to this queue until your app exits or the session object is deallocated. If you do not invalidate the session, your app leaks memory until it exits.

Note

This queue must be set at object creation time and may not be changed.

Availability

Available in iOS 7.0 and later.
sessionDescription sessionDescription Property

An app-defined descriptive label for the session.

Declaration

Swift

var sessionDescription: String?

Objective-C

@property(copy) NSString *sessionDescription

Discussion

This property contains a human-readable string that you can use for debugging purposes. This value may be nil and defaults to nil. The value is ignored by the session.

Availability

Available in iOS 7.0 and later.

Adding Data Tasks to a Session

dataTaskWithURL(_:) - dataTaskWithURL:

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

Declaration

Swift

func dataTaskWithURL(_ url: NSURL) -> NSURLSessionDataTask

Objective-C

- (NSURLSessionDataTask *)dataTaskWithURL:(NSURL *)url

Parameters

url

The URL to be retrieved.

Return Value

The new session data task.

Discussion

After you create the task, you must start it by calling its resume method. The task calls methods on the session’s delegate to provide you with the response metadata, response data, and so on.

Availability

Available in iOS 7.0 and later.


    
      
           dataTaskWithURL(_:completionHandler:)
      
      
           - dataTaskWithURL:completionHandler:

Creates a task that retrieves the contents of the specified URL, then calls a handler upon completion. The task bypasses calls to delegate methods for response and data delivery, and instead provides any resulting NSData, NSURLResponse, and NSError objects inside the completion handler. Delegate methods for handling authentication challenges, however, are still called.

Declaration

Swift

func dataTaskWithURL(_ url: NSURL, completionHandler completionHandler: (NSData?, NSURLResponse?, NSError?) -> Void) -> NSURLSessionDataTask

Objective-C

- (NSURLSessionDataTask *)dataTaskWithURL:(NSURL *)url completionHandler:(void (^)(NSData *data, NSURLResponse *response, NSError *error))completionHandler

Parameters

url

The URL to be retrieved.


  completionHandler

The completion handler to call when the load request is complete. This handler is executed on the delegate queue.

If you pass nil, only the session delegate methods are called when the task completes, making this method equivalent to the dataTaskWithRequest: method.

This completion handler takes the following parameters:

`data`	The data returned by the server.
`response`	An object that provides response metadata, such as HTTP headers and status code. If you are making an HTTP or HTTPS request, the returned object is actually an `NSHTTPURLResponse` object.
`error`	An error object that indicates why the request failed, or `nil` if the request was successful.

Return Value

The new session data task.

Discussion

After you create the task, you must start it by calling its resume method.

You should pass a nil completion handler only when creating tasks in sessions whose delegates include a URLSession:dataTask:didReceiveData: method.

If the request completes successfully, the data parameter of the completion handler block contains the resource data, and the error parameter is nil. If the request fails, the data parameter is nil and the error parameter contain information about the failure. If a response from the server is received, regardless of whether the request completes successfully or fails, the response parameter contains that information.

Availability

Available in iOS 7.0 and later.

dataTaskWithRequest(_:) - dataTaskWithRequest:

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

Declaration

Swift

func dataTaskWithRequest(_ request: NSURLRequest) -> NSURLSessionDataTask

Objective-C

- (NSURLSessionDataTask *)dataTaskWithRequest:(NSURLRequest *)request

Parameters

request

An object that provides request-specific information such as the URL, cache policy, request type, and body data or body stream.

Return Value

The new session data task.

Discussion

By creating a task based on a request object, you can tune various aspects of the task’s behavior, including the cache policy and timeout interval.

After you create the task, you must start it by calling its resume method.

Availability

Available in iOS 7.0 and later.


    
      
           dataTaskWithRequest(_:completionHandler:)
      
      
           - 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. The task bypasses calls to delegate methods for response and data delivery, and instead provides any resulting NSData, NSURLResponse, and NSError objects inside the completion handler. Delegate methods for handling authentication challenges, however, are still called.

Declaration

Swift

func dataTaskWithRequest(_ request: NSURLRequest, completionHandler completionHandler: (NSData?, NSURLResponse?, NSError?) -> Void) -> NSURLSessionDataTask

Objective-C

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

Parameters


  request

An NSURLRequest object that provides the URL, cache policy, request type, body data or body stream, and so on.


  completionHandler

The completion handler to call when the load request is complete. This handler is executed on the delegate queue.

If you pass nil, only the session delegate methods are called when the task completes, making this method equivalent to the dataTaskWithRequest: method.

This completion handler takes the following parameters:

`data`	The data returned by the server.
`response`	An object that provides response metadata, such as HTTP headers and status code. If you are making an HTTP or HTTPS request, the returned object is actually an `NSHTTPURLResponse` object.
`error`	An error object that indicates why the request failed, or `nil` if the request was successful.

Return Value

The new session data task.

Discussion

By creating a task based on a request object, you can tune various aspects of the task’s behavior, including the cache policy and timeout interval.

After you create the task, you must start it by calling its resume method.

You should pass a nil completion handler only when creating tasks in sessions whose delegates include a URLSession:dataTask:didReceiveData: method.

Availability

Available in iOS 7.0 and later.

Adding Download Tasks to a Session

downloadTaskWithURL(_:) - downloadTaskWithURL:

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

Declaration

Swift

func downloadTaskWithURL(_ url: NSURL) -> NSURLSessionDownloadTask

Objective-C

- (NSURLSessionDownloadTask *)downloadTaskWithURL:(NSURL *)url

Parameters

url

An NSURL object that provides the URL to download.

Return Value

The new session download task.

Discussion

After you create the task, you must start it by calling its resume method.

Availability

Available in iOS 7.0 and later.


    
      
           downloadTaskWithURL(_:completionHandler:)
      
      
           - 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. The task bypasses calls to delegate methods for response and data delivery, and instead provides any resulting NSData, NSURLResponse, and NSError objects inside the completion handler. Delegate methods for handling authentication challenges, however, are still called.

Declaration

Swift

func downloadTaskWithURL(_ url: NSURL, completionHandler completionHandler: (NSURL?, NSURLResponse?, NSError?) -> Void) -> NSURLSessionDownloadTask

Objective-C

- (NSURLSessionDownloadTask *)downloadTaskWithURL:(NSURL *)url completionHandler:(void (^)(NSURL *location, NSURLResponse *response, NSError *error))completionHandler

Parameters

url

An NSURL object that provides the URL to download.


  completionHandler

The completion handler to call when the load request is complete. This handler is executed on the delegate queue.

If you pass nil, only the session delegate methods are called when the task completes, making this method equivalent to the downloadTaskWithURL: method.

This completion handler takes the following parameters:

`location`	The location of a temporary file where the server’s response is stored. You must move this file or open it for reading before your completion handler returns. Otherwise, the file is deleted, and the data is lost.
`response`	An object that provides response metadata, such as HTTP headers and status code. If you are making an HTTP or HTTPS request, the returned object is actually an `NSHTTPURLResponse` object.
`error`	An error object that indicates why the request failed, or `nil` if the request was successful.

Return Value

The new session download task.

Discussion

After you create the task, you must start it by calling its resume method.

You should pass a nil completion handler only when creating tasks in sessions whose delegates include a URLSession:downloadTask:didFinishDownloadingToURL: method.

If the request completes successfully, the location parameter of the completion handler block contains the location of the temporary file, and the error parameter is nil. If the request fails, the location parameter is nil and the error parameter contain information about the failure. If a response from the server is received, regardless of whether the request completes successfully or fails, the response parameter contains that information.

Availability

Available in iOS 7.0 and later.

downloadTaskWithRequest(_:) - 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.

Declaration

Swift

func downloadTaskWithRequest(_ request: NSURLRequest) -> NSURLSessionDownloadTask

Objective-C

- (NSURLSessionDownloadTask *)downloadTaskWithRequest:(NSURLRequest *)request

Parameters

request

An NSURLRequest object that provides the URL, cache policy, request type, body data or body stream, and so on.

Return Value

The new session download task.

Discussion

By creating a task based on a request object, you can tune various aspects of the task’s behavior, including the cache policy and timeout interval.

After you create the task, you must start it by calling its resume method. The task calls methods on the session’s delegate to provide you with progress notifications, the location of the resulting temporary file, and so on.

Availability

Available in iOS 7.0 and later.


    
      
           downloadTaskWithRequest(_:completionHandler:)
      
      
           - 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. The task bypasses calls to delegate methods for response and data delivery, and instead provides any resulting NSURL, NSURLResponse, and NSError objects inside the completion handler. Delegate methods for handling authentication challenges, however, are still called.

Declaration

Swift

func downloadTaskWithRequest(_ request: NSURLRequest, completionHandler completionHandler: (NSURL?, NSURLResponse?, NSError?) -> Void) -> NSURLSessionDownloadTask

Objective-C

- (NSURLSessionDownloadTask *)downloadTaskWithRequest:(NSURLRequest *)request completionHandler:(void (^)(NSURL *location, NSURLResponse *response, NSError *error))completionHandler

Parameters


  request

An NSURLRequest object that provides the URL, cache policy, request type, body data or body stream, and so on.


  completionHandler

The completion handler to call when the load request is complete. This handler is executed on the delegate queue.

If you pass nil, only the session delegate methods are called when the task completes, making this method equivalent to the downloadTaskWithRequest: method.

`location`	The location of a temporary file where the server’s response is stored. You must move this file or open it for reading before your completion handler returns. Otherwise, the file is deleted, and the data is lost.
`response`	An object that provides response metadata, such as HTTP headers and status code. If you are making an HTTP or HTTPS request, the returned object is actually an `NSHTTPURLResponse` object.
`error`	An error object that indicates why the request failed, or `nil` if the request was successful.

Return Value

The new session download task.

Discussion

By creating a task based on a request object, you can tune various aspects of the task’s behavior, including the cache policy and timeout interval.

After you create the task, you must start it by calling its resume method.

You should pass a nil completion handler only when creating tasks in sessions whose delegates include a URLSession:downloadTask:didFinishDownloadingToURL: method.

Availability

Available in iOS 7.0 and later.

downloadTaskWithResumeData(_:) - downloadTaskWithResumeData:

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

Declaration

Swift

func downloadTaskWithResumeData(_ resumeData: NSData) -> NSURLSessionDownloadTask

Objective-C

- (NSURLSessionDownloadTask *)downloadTaskWithResumeData:(NSData *)resumeData

Parameters

resumeData

A data object that provides the data necessary to resume a download.

Return Value

The new session download task.

Discussion

After you create the task, you must start it by calling its resume method.

This method is equivalent to the downloadTaskWithResumeData:completionHandler: with a nil completion handler. For detailed usage information, including ways to obtain a resume data object, see that method.

Availability

Available in iOS 7.0 and later.


    
      
           downloadTaskWithResumeData(_:completionHandler:)
      
      
           - downloadTaskWithResumeData:completionHandler:

Creates a download task to resume a previously canceled or failed download and calls a handler upon completion. The task bypasses calls to delegate methods for response and data delivery, and instead provides any resulting NSURL, NSURLResponse, and NSError objects inside the completion handler. Delegate methods for handling authentication challenges, however, are still called.

Declaration

Swift

func downloadTaskWithResumeData(_ resumeData: NSData, completionHandler completionHandler: (NSURL?, NSURLResponse?, NSError?) -> Void) -> NSURLSessionDownloadTask

Objective-C

- (NSURLSessionDownloadTask *)downloadTaskWithResumeData:(NSData *)resumeData completionHandler:(void (^)(NSURL *location, NSURLResponse *response, NSError *error))completionHandler

Parameters


  resumeData

A data object that provides the data necessary to resume the download.


  completionHandler

The completion handler to call when the load request is complete. This handler is executed on the delegate queue.

If you pass nil, only the session delegate methods are called when the task completes, making this method equivalent to the downloadTaskWithResumeData: method.

`location`	The location of a temporary file where the server’s response is stored. You must move this file or open it for reading before your completion handler returns. Otherwise, the file is deleted, and the data is lost.
`response`	An object that provides response metadata, such as HTTP headers and status code. If you are making an HTTP or HTTPS request, the returned object is actually an `NSHTTPURLResponse` object.
`error`	An error object that indicates why the request failed, or `nil` if the request was successful.

Return Value

The new session download task.

Discussion

You should pass a nil completion handler only when creating tasks in sessions whose delegates include a URLSession:downloadTask:didFinishDownloadingToURL: method.

Your app can obtain a resumeData object in two ways:

If your app cancels an existing transfer by calling cancelByProducingResumeData:, the session object passes a resumeData object to the completion handler that you provided in that call.
If a transfer fails, the session object provides an NSError object either to its delegate or to the task’s completion handler. In that object, the NSURLSessionDownloadTaskResumeData key in the userInfo dictionary contains a resumeData object.

After you create the task, you must start it by calling its resume method.

Availability

Available in iOS 7.0 and later.

Adding Upload Tasks to a Session


    
      
           uploadTaskWithRequest(_:fromData:)
      
      
           - uploadTaskWithRequest:fromData:

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

Declaration

Swift

func uploadTaskWithRequest(_ request: NSURLRequest, fromData bodyData: NSData) -> NSURLSessionUploadTask

Objective-C

- (NSURLSessionUploadTask *)uploadTaskWithRequest:(NSURLRequest *)request fromData:(NSData *)bodyData

Parameters

`request`	An `NSURLRequest` object that provides the URL, cache policy, request type, and so on. The body stream and body data in this request object are ignored.
`bodyData`	The body data for the request.

Return Value

The new session upload task.

Discussion

An HTTP upload request is any request that contains a request body, such as a POST or PUT request. Upload tasks require you to provide a request object so that you can provide metadata for the upload, such as HTTP request headers.

Availability

Available in iOS 7.0 and later.


    
      
           uploadTaskWithRequest(_:fromData:completionHandler:)
      
      
           - 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. The task bypasses calls to delegate methods for response and data delivery, and instead provides any resulting NSData, NSURLResponse, and NSError objects inside the completion handler. Delegate methods for handling authentication challenges, however, are still called.

Declaration

Swift

func uploadTaskWithRequest(_ request: NSURLRequest, fromData bodyData: NSData?, completionHandler completionHandler: (NSData?, NSURLResponse?, NSError?) -> Void) -> NSURLSessionUploadTask

Objective-C

- (NSURLSessionUploadTask *)uploadTaskWithRequest:(NSURLRequest *)request fromData:(NSData *)bodyData completionHandler:(void (^)(NSData *data, NSURLResponse *response, NSError *error))completionHandler

Parameters


  request

An NSURLRequest object that provides the URL, cache policy, request type, and so on. The body stream and body data in this request object are ignored.


  bodyData

The body data for the request.


  completionHandler

The completion handler to call when the load request is complete. This handler is executed on the delegate queue.

If you pass nil, only the session delegate methods are called when the task completes, making this method equivalent to the uploadTaskWithRequest:fromData: method.

This completion handler takes the following parameters:

`data`	The data returned by the server.
`response`	An object that provides response metadata, such as HTTP headers and status code. If you are making an HTTP or HTTPS request, the returned object is actually an `NSHTTPURLResponse` object.
`error`	An error object that indicates why the request failed, or `nil` if the request was successful.

Return Value

The new session upload task.

Discussion

Unlike uploadTaskWithRequest:fromData:, this method returns the response body after it has been received in full, and does not require you to write a custom delegate to obtain the response body.

After you create the task, you must start it by calling its resume method.

You should usually pass a nil completion handler only when creating tasks in sessions whose delegates include a URLSession:dataTask:didReceiveData: method. However, if you do not need the response data, use key-value observing to watch for changes to the task’s status to determine when it completes.

Availability

Available in iOS 7.0 and later.


    
      
           uploadTaskWithRequest(_:fromFile:)
      
      
           - uploadTaskWithRequest:fromFile:

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

Declaration

Swift

func uploadTaskWithRequest(_ request: NSURLRequest, fromFile fileURL: NSURL) -> NSURLSessionUploadTask

Objective-C

- (NSURLSessionUploadTask *)uploadTaskWithRequest:(NSURLRequest *)request fromFile:(NSURL *)fileURL

Parameters

`request`	An `NSURLRequest` object that provides the URL, cache policy, request type, and so on. The body stream and body data in this request object are ignored.
`fileURL`	The URL of the file to upload.

Return Value

The new session upload task.

Discussion

Availability

Available in iOS 7.0 and later.


    
      
           uploadTaskWithRequest(_:fromFile:completionHandler:)
      
      
           - uploadTaskWithRequest:fromFile:completionHandler:

Creates a task that performs an HTTP request for uploading the specified file, then calls a handler upon completion. The task bypasses calls to delegate methods for response and data delivery, and instead provides any resulting NSData, NSURLResponse, and NSError objects inside the completion handler. Delegate methods for handling authentication challenges, however, are still called.

Declaration

Swift

func uploadTaskWithRequest(_ request: NSURLRequest, fromFile fileURL: NSURL, completionHandler completionHandler: (NSData?, NSURLResponse?, NSError?) -> Void) -> NSURLSessionUploadTask

Objective-C

- (NSURLSessionUploadTask *)uploadTaskWithRequest:(NSURLRequest *)request fromFile:(NSURL *)fileURL completionHandler:(void (^)(NSData *data, NSURLResponse *response, NSError *error))completionHandler

Parameters


  request

An NSURLRequest object that provides the URL, cache policy, request type, and so on. The body stream and body data in this request object are ignored.


  fileURL

The URL of the file to upload.


  completionHandler

The completion handler to call when the load request is complete. This handler is executed on the delegate queue.

If you pass nil, only the session delegate methods are called when the task completes, making this method equivalent to the uploadTaskWithRequest:fromFile: method.

This completion handler takes the following parameters:

`data`	The data returned by the server.
`response`	An object that provides response metadata, such as HTTP headers and status code. If you are making an HTTP or HTTPS request, the returned object is actually an `NSHTTPURLResponse` object.
`error`	An error object that indicates why the request failed, or `nil` if the request was successful.

Return Value

The new session upload task.

Discussion

Unlike uploadTaskWithRequest:fromFile:, this method returns the response body after it has been received in full, and does not require you to write a custom delegate to obtain the response body.

After you create the task, you must start it by calling its resume method.

Availability

Available in iOS 7.0 and later.


    
      
           uploadTaskWithStreamedRequest(_:)
      
      
           - uploadTaskWithStreamedRequest:

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

Declaration

Swift

func uploadTaskWithStreamedRequest(_ request: NSURLRequest) -> NSURLSessionUploadTask

Objective-C

- (NSURLSessionUploadTask *)uploadTaskWithStreamedRequest:(NSURLRequest *)request

Parameters


  request

An NSURLRequest object that provides the URL, cache policy, request type, and so on. The body stream and body data in this request object are ignored, and NSURLSession calls its delegate’s URLSession:task:needNewBodyStream: method to provide the body data.

Return Value

The new session upload task.

Discussion

After you create the task, you must start it by calling its resume method. The task calls methods on the session’s delegate to provide you with the upload’s progress, response metadata, response data, and so on. The session’s delegate must have a URLSession:task:needNewBodyStream: method that provides the body data to upload.

Availability

Available in iOS 7.0 and later.

Adding Stream Tasks to a Session

streamTaskWithHostName(_:port:) - streamTaskWithHostName:port:

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

Declaration

Swift

func streamTaskWithHostName(_ hostname: String, port port: Int) -> NSURLSessionStreamTask

Objective-C

- (NSURLSessionStreamTask *)streamTaskWithHostName:(NSString *)hostname port:(NSInteger)port

Parameters

hostname

The hostname of the connection endpoint.

port

The port of the connection endpoint.

Return Value

The new session stream task.

Discussion

After you create the task, you must start it by calling its resume method.

Availability

Available in iOS 9.0 and later.


    
      
           streamTaskWithNetService(_:)
      
      
           - streamTaskWithNetService:

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

Declaration

Swift

func streamTaskWithNetService(_ service: NSNetService) -> NSURLSessionStreamTask

Objective-C

- (NSURLSessionStreamTask *)streamTaskWithNetService:(NSNetService *)service

Parameters


  service

An NSNetService object used to determine the endpoint of the TCP/IP connection. This network service is resolved before any data is read or written to the resulting stream task.

Return Value

The new session stream task.

Discussion

After you create the task, you must start it by calling its resume method.

Availability

Available in iOS 9.0 and later.

Managing the Session

finishTasksAndInvalidate() - finishTasksAndInvalidate

Invalidates the session, allowing any outstanding tasks to finish.

Declaration

Swift

func finishTasksAndInvalidate()

Objective-C

- (void)finishTasksAndInvalidate

Discussion

This method returns immediately without waiting for tasks to finish. Once a session is invalidated, new tasks cannot be created in the session, but existing tasks continue until completion. After the last task finishes and the session makes the last delegate call related to those tasks, the session calls the URLSession:didBecomeInvalidWithError: method on its delegate, then breaks references to the delegate and callback objects. After invalidation, session objects cannot be reused.

To cancel all outstanding tasks, call invalidateAndCancel instead.

Important

Calling this method on the session returned by the sharedSession method has no effect.

Availability

Available in iOS 7.0 and later.
flushWithCompletionHandler(_:) - flushWithCompletionHandler:

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

Declaration

Swift

func flushWithCompletionHandler(_ completionHandler: () -> Void)

Objective-C

- (void)flushWithCompletionHandler:(void (^)(void))completionHandler

Parameters

completionHandler

The completion handler to call when the flush operation is complete. This handler is executed on the delegate queue.

Availability

Available in iOS 7.0 and later.
getTasksWithCompletionHandler(_:) - getTasksWithCompletionHandler:

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

Declaration

Swift

func getTasksWithCompletionHandler(_ completionHandler: ([NSURLSessionDataTask], [NSURLSessionUploadTask], [NSURLSessionDownloadTask]) -> Void)

Objective-C

- (void)getTasksWithCompletionHandler:(void (^)(NSArray<NSURLSessionDataTask *> *dataTasks, NSArray<NSURLSessionUploadTask *> *uploadTasks, NSArray<NSURLSessionDownloadTask *> *downloadTasks))completionHandler

Parameters

completionHandler

The completion handler to call with the list of tasks. This handler is executed on the delegate queue.

Discussion

The returned arrays contain any tasks that you have created within the session, not including any tasks that have been invalidated after completing, failing, or being cancelled.

Availability

Available in iOS 7.0 and later.
invalidateAndCancel() - invalidateAndCancel

Cancels all outstanding tasks and then invalidates the session.

Declaration

Swift

func invalidateAndCancel()

Objective-C

- (void)invalidateAndCancel

Discussion

Once invalidated, references to the delegate and callback objects are broken. After invalidation, session objects cannot be reused.

To allow outstanding tasks to run until completion, call finishTasksAndInvalidate instead.

Important

Calling this method on the session returned by the sharedSession method has no effect.

Availability

Available in iOS 7.0 and later.
resetWithCompletionHandler(_:) - 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.

Declaration

Swift

func resetWithCompletionHandler(_ completionHandler: () -> Void)

Objective-C

- (void)resetWithCompletionHandler:(void (^)(void))completionHandler

Parameters

completionHandler

The completion handler to call when the reset operation is complete. This handler is executed on the delegate queue.

Availability

Available in iOS 7.0 and later.

Constants

NSURLSession-Specific NSError userInfo Dictionary Keys
Keys used in conjunction with NSError objects returned by the NSURLSession API.

Declaration

Swift

let NSURLSessionDownloadTaskResumeData: String let NSURLErrorBackgroundTaskCancelledReasonKey: String

Objective-C

NSString * const NSURLSessionDownloadTaskResumeData; NSString * const NSURLErrorBackgroundTaskCancelledReasonKey;

Constants
- NSURLSessionDownloadTaskResumeData
  
  NSURLSessionDownloadTaskResumeData
  
  A key in the error dictionary that provides resume data.
  
  When a transfer error occurs or when you call the cancelByProducingResumeData: method, the delegate object or completion handler gets an NSError object. If the transfer is resumable, that error object’s userInfo dictionary contains a value for this key. To resume the transfer, your app can pass that value to the downloadTaskWithResumeData: or downloadTaskWithResumeData:completionHandler: method.
  
  Available in iOS 7.0 and later.
- NSURLErrorBackgroundTaskCancelledReasonKey
  
  NSURLErrorBackgroundTaskCancelledReasonKey
  
  An NSNumber value indicating why a background task was cancelled. For a list of possible values, see NSURLSession-Specific NSError userInfo Dictionary Keys.
  
  Available in iOS 8.0 and later.
Background Task Cancellation reasons
Constants that indicate why a background task was cancelled.

Declaration

Swift

var NSURLErrorCancelledReasonUserForceQuitApplication: Int { get } var NSURLErrorCancelledReasonBackgroundUpdatesDisabled: Int { get }

Objective-C

enum { NSURLErrorCancelledReasonUserForceQuitApplication = 0, NSURLErrorCancelledReasonBackgroundUpdatesDisabled = 1, };

Constants
- NSURLErrorCancelledReasonUserForceQuitApplication
  
  NSURLErrorCancelledReasonUserForceQuitApplication
  
  The operation was canceled because the user forced the app to quit.
  
  Available in iOS 7.0 and later.
- NSURLErrorCancelledReasonBackgroundUpdatesDisabled
  
  NSURLErrorCancelledReasonBackgroundUpdatesDisabled
  
  The operation was canceled because background updates are disabled. See Background Execution for more information.
  
  Available in iOS 7.0 and later.
Discussion

These values are used in conjunction with the NSURLErrorBackgroundTaskCancelledReasonKey key in an NSError object’s userInfo dictionary.
Transfer Size Constant
A constant denoting an unknown transfer size.

Declaration

Swift

let NSURLSessionTransferSizeUnknown: Int64

Objective-C

const int64_t NSURLSessionTransferSizeUnknown ; /* -1LL */

Constants
- NSURLSessionTransferSizeUnknown
  
  NSURLSessionTransferSizeUnknown
  
  The total size of the transfer cannot be determined.
  
  Available in iOS 7.0 and later.

`hostname`	The hostname of the connection endpoint.
`port`	The port of the connection endpoint.