Class

NSURLSessionConfiguration

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

Overview

An NSURLSessionConfiguration object defines the behavior and policies to use when uploading and downloading data using an NSURLSession object. When uploading or downloading data, creating a configuration object is always the first step you must take. You use this object to configure the timeout values, caching policies, connection requirements, and other types of information that you intend to use with your NSURLSession object.

It is important to configure your NSURLSessionConfiguration object appropriately before using it to initialize a session object. Session objects make a copy of the configuration settings you provide and use those settings to configure the session. Once configured, the session object ignores any changes you make to the NSURLSessionConfiguration object. If you need to modify your transfer policies, you must update the session configuration object and use it to create a new NSURLSession object.

For more information about using configuration objects to create sessions, see NSURLSession.

Topics

Creating a Session Configuration Object

defaultSessionConfiguration

Returns a newly created default session configuration object.

ephemeralSessionConfiguration

Returns a session configuration that uses no persistent storage for caches, cookies, or credentials.

+ backgroundSessionConfigurationWithIdentifier:

Returns a session configuration object that allows HTTP and HTTPS uploads or downloads to be performed in the background.

Setting General Properties

identifier

The background session identifier of the configuration object.

HTTPAdditionalHeaders

A dictionary of additional headers to send with requests.

networkServiceType

The type of network service.

allowsCellularAccess

A Boolean value that determines whether connections should be made over a cellular network.

timeoutIntervalForRequest

The timeout interval to use when waiting for additional data.

timeoutIntervalForResource

The maximum amount of time that a resource request should be allowed to take.

sharedContainerIdentifier

The identifier for the shared container into which files in background URL sessions should be downloaded.

waitsForConnectivity

A Boolean value that indicates whether the session should wait for connectivity to become available, or fail immediately.

Setting Cookie Policies

HTTPCookieAcceptPolicy

A policy constant that determines when cookies should be accepted.

HTTPShouldSetCookies

A Boolean value that determines whether requests should contain cookies from the cookie store.

HTTPCookieStorage

The cookie store for storing cookies within this session.

NSHTTPCookieStorage

A singleton object (shared instance) that manages storage of cookies.

NSHTTPCookie

An object that represents an HTTP cookie. It is an immutable object, initialized from a dictionary containing the cookie attributes.

Setting Security Policies

TLSMaximumSupportedProtocol

The maximum TLS protocol version that the client should request when making connections in this session.

TLSMinimumSupportedProtocol

The minimum TLS protocol that should be accepted during protocol negotiation.

URLCredentialStorage

A credential store that provides credentials for authentication.

Setting Caching Policies

URLCache

The URL cache for providing cached responses to requests within the session.

requestCachePolicy

A predefined constant that determines when to return a response from the cache.

Supporting Background Transfers

sessionSendsLaunchEvents

A Boolean value that indicates whether the app should be resumed or launched in the background when transfers finish.

discretionary

A Boolean value that determines whether background tasks can be scheduled at the discretion of the system for optimal performance.

shouldUseExtendedBackgroundIdleMode

Supporting Custom Protocols

protocolClasses

An array of extra protocol subclasses that handle requests in a session.

NSURLProtocol

An NSURLProtocol object handles the loading of protocol-specific URL data. The NSURLProtocol class itself is an abstract class that provides the infrastructure for processing URLs with a specific URL scheme. You create subclasses for any custom protocols or URL schemes that your app supports.

Supporting Multipath TCP

Improving Network Reliability Using Multipath TCP

Use the available radios in iOS devices to improve your app’s network reliability and performance.

multipathServiceType

A service type that specifies the Multipath TCP connection policy for transmitting data over Wi-Fi and cellular interfaces.

NSURLSessionMultipathServiceType

Constants that specify the type of service that Multipath TCP uses.

Setting HTTP Policy and Proxy Properties

HTTPMaximumConnectionsPerHost

The maximum number of simultaneous connections to make to a given host.

HTTPShouldUsePipelining

A Boolean value that determines whether the session should use HTTP pipelining.

connectionProxyDictionary

A dictionary containing information about the proxy to use within this session.

Supporting Connectivity Changes

waitsForConnectivity

A Boolean value that indicates whether the session should wait for connectivity to become available, or fail immediately.

Deprecated Methods

+ backgroundSessionConfiguration: