iOS Developer Library — Prerelease

Developer

Foundation Framework Reference NSURLSession Class Reference

Options
Deployment Target:

On This Page
Language:

NSURLSession

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):

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.

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.

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:

  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 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:

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

    For more information about writing an authentication delegate method for NSURLSession, read URL Session Programming Guide.

  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 NSInputStream object 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 (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.

  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 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.

  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 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.)

  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 do not 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 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).

  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.

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.

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.

  • 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.

  • 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.

    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.

  • 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.

  • 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.

    Availability

    Available in iOS 7.0 and later.

  • 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.

    Availability

    Available in iOS 7.0 and later.

  • 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.

    Availability

    Available in iOS 7.0 and later.

  • 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.

  • 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.

  • 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.

  • 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.

  • 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.

    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.

  • 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.

  • 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.

  • 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.

  • 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.

    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.

  • 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.

  • 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.

    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.

  • 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.

    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.

    Availability

    Available in iOS 7.0 and later.

  • 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

    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.

    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.

    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.

  • 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

    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.

    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.

    Availability

    Available in iOS 7.0 and later.

  • 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

    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.

    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.

    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.

    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.

  • 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

    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.

    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.

  • 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.

    Availability

    Available in iOS 7.0 and later.

  • 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.

  • 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.

  • 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.

    Availability

    Available in iOS 7.0 and later.

  • 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.

  • 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.

  • 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.

  • 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.