URL Loading System

Interact with URLs and communicate with servers using standard Internet protocols.

Overview

The URL Loading System provides access to resources identified by URLs, using standard protocols like https or custom protocols you create. Loading is performed asynchronously, so your app can remain responsive and handle incoming data or errors as they arrive.

You use a NSURLSession instance to create one or more NSURLSessionTask instances, which can fetch and return data to your app, download files, or upload data and files to remote locations. To configure a session, you use a NSURLSessionConfiguration object, which controls behavior like how to use caches and cookies, or whether to allow connections on a cellular network.

You can use one session repeatedly to create tasks. For example, a web browser might have separate sessions for regular and private browsing use, where the private session doesn’t cache its data. Figure 1 shows how two sessions with these configurations can then create multiple tasks.

Figure 1

Creating tasks from URL sessions

Figure showing two scenarios, default browsing and private browsing, each with a URL Session creating multiple URL Session Tasks. In the default browsing case, the URL Session contains a default configuration. In the private browsing case, it contains an ephemeral configuration.

Each session is associated with a delegate to receive periodic updates (or errors). The default delegate calls a completion handler block that you provide; if you choose to provide your own custom delegate, this block is not called.

You can configure a session to run in the background, so that while the app is suspended, the system can download data on its behalf and wake up the app to deliver the results.

Topics

First Steps

Configure and create sessions, then use them to create tasks that interact with URLs.

Fetching Website Data into Memory

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

NSURLSession

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

NSURLSessionTask

A task, like downloading a specific resource, performed in a URL session.

Requests and Responses

NSURLRequest

A URL load request that is independent of protocol or URL scheme.

NSMutableURLRequest

A mutable URL load request that is independent of protocol or URL scheme.

NSURLResponse

The metadata associated with the response to a URL load request, independent of protocol and URL scheme.

NSHTTPURLResponse

The metadata associated with the response to an HTTP protocol URL load request.

Uploading

Uploading Data to a Website

Post data from your app to servers.

Uploading Streams of Data

Send a stream of data to a server.

Downloading

Downloading Files from Websites

Download files directly to the filesystem.

Pausing and Resuming Downloads

Allow the user to resume a download without starting over.

Downloading Files in the Background

Create tasks that download files while your app is inactive.

Cache Behavior

Accessing Cached Data

Control how URL requests make use of previously cached data.

NSCachedURLResponse

A cached response to a URL request.

NSURLCache

An object that maps URL requests to cached response objects.

Authentication and Credentials

Handling an Authentication Challenge

Respond appropriately when a server demands authentication for a URL request.

NSURLAuthenticationChallenge

A challenge from a server requiring authentication from the client.

NSURLCredential

An authentication credential consisting of information specific to the type of credential and the type of persistent storage to use, if any.

NSURLCredentialStorage

The manager of a shared credentials cache.

NSURLProtectionSpace

A server or an area on a server, commonly referred to as a realm, that requires authentication.

Cookies

NSHTTPCookie

A representation of an HTTP cookie.

NSHTTPCookieStorage

A container that manages the storage of cookies.

Errors

URL Loading System Error Codes

Error codes returned by URL loading APIs.

URL Loading System Error Info Keys

Recognize these keys from the user info dictionary of error objects produced by URL Loading APIs.

Legacy

Legacy URL Loading Systems

Migrate your code away from using these legacy objects.

See Also

Networking

Bonjour

Advertise services for easy discovery on local networks, or discover services advertised by others.