NSURLSessionConfiguration Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/Foundation.framework
Availability
Available in iOS 7.0 and later.
Declared in
NSURLSession.h

Overview

This class provides a set of properties that control various policies on a sessionwide basis. These properties are set on a session at the time of its creation and cannot be changed later. If you need to change these policy properties, create a new session with a modified session configuration.

Tasks

Creating a Session Configuration Object

Setting General Properties

Setting Cookie Policies

Setting Security Policies

Setting Caching Policies

Supporting Custom Protocols

Setting HTTP Policy and Proxy Properties

New Methods

Properties

allowsCellularAccess

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

@property BOOL allowsCellularAccess
Discussion

For more information, read “Restrict Cellular Networking Correctly” in Networking Overview.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSURLSession.h

connectionProxyDictionary

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

@property(copy) NSDictionary *connectionProxyDictionary
Discussion

See CFProxySupport Reference for more information about these dictionaries.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSURLSession.h

discretionary

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

@property(getter=isDiscretionary) BOOL discretionary
Discussion

When this flag is set, transfers are more likely to occur when plugged into power and on Wi-Fi. This value is false by default.

This property is used only if a session’s configuration object was originally constructed by calling the backgroundSessionConfiguration: method, and only for tasks started while the app is in the foreground. If a task is started while the app is in the background, that task is treated as though discretionary were true, regardless of the actual value of this property. For sessions created based on other configurations, this property is ignored.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSURLSession.h

HTTPAdditionalHeaders

A dictionary of additional headers to send with requests.

@property(copy) NSDictionary *HTTPAdditionalHeaders
Availability
  • Available in iOS 7.0 and later.
Declared In
NSURLSession.h

HTTPCookieAcceptPolicy

A policy constant that determines when cookies should be accepted.

@property NSHTTPCookieAcceptPolicy HTTPCookieAcceptPolicy
Availability
  • Available in iOS 7.0 and later.
Declared In
NSURLSession.h

HTTPCookieStorage

The pool for storing cookies within this session.

@property(retain) NSHTTPCookieStorage *HTTPCookieStorage
Discussion

To disable cookie storage, set this property to NULL.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSURLSession.h

HTTPMaximumConnectionsPerHost

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

@property NSInteger HTTPMaximumConnectionsPerHost
Availability
  • Available in iOS 7.0 and later.
Declared In
NSURLSession.h

HTTPShouldSetCookies

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

@property BOOL HTTPShouldSetCookies
Availability
  • Available in iOS 7.0 and later.
Declared In
NSURLSession.h

HTTPShouldUsePipelining

A Boolean value that determines whether HTTP pipelining should be used.

@property BOOL HTTPShouldUsePipelining
Availability
  • Available in iOS 7.0 and later.
Declared In
NSURLSession.h

identifier

The background session identifier specified when creating the configuration object. (read-only)

@property(readonly, copy) NSString *identifier
Discussion

If no value was specified when the object was created, this property’s value is NULL.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSURLSession.h

networkServiceType

The type of network service.

@property NSURLRequestNetworkServiceType networkServiceType
Discussion

The network service type provides a hint to the operating system about what the underlying traffic is used for. This hint enhances the system's ability to prioritize traffic, determine how quickly it needs to wake up the cellular or Wi-Fi radio, and so on. By providing accurate information, you improve the ability of the system to optimally balance battery life, performance, and other considerations.

For example, you should specify the NSURLNetworkServiceTypeBackground type if your app is performing a download that was not requested by the user, such as prefetching content so that it will be available when the user chooses to view it.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSURLSession.h

protocolClasses

An optional array of class objects that subclass NSURLProtocol.

@property(copy) NSArray *protocolClasses
Discussion

Each object in this array is a class object obtained by calling the built-in class class method on the class itself. For example:

@interface myClass
...
@end
 
...
 
id classObject = [myClass class];

When the NSURLSession class needs to determine whether the protocol can be used for a given URL scheme, it sends each class object a canInitWithRequest: message.

Do not use the registerClass: method with NSURLSession, because that method registers your class with the default session rather than with an instance of NSURLSession.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSURLSession.h

requestCachePolicy

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

@property NSURLRequestCachePolicy requestCachePolicy
Discussion

The value stored in this property should be one of the constants defined in NSURLRequestCachePolicy. These constants let you specify whether the cache policy should depend on expiration dates and age, the cache should be disabled entirely, or the server should be contacted to determine whether the content has changed since it was last requested.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSURLSession.h

sessionSendsLaunchEvents

Whether the app should be resumed or launched in the background when needed.

@property BOOL sessionSendsLaunchEvents
Discussion

In sessions created based on this configuration object, if this property is YES, the app is automatically relaunched in the background when tasks finish or require authentication.

This property applies only to configurations created by calling backgroundSessionConfiguration:. The default value is YES.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSURLSession.h

timeoutIntervalForRequest

The timeout interval to use when waiting for additional data.

@property NSTimeInterval timeoutIntervalForRequest
Discussion

The timer associated with this value is reset whenever new data arrives. When the request timer reaches the specified interval without receiving any new data, it triggers a timeout.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSURLSession.h

timeoutIntervalForResource

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

@property NSTimeInterval timeoutIntervalForResource
Discussion

This value controls how long to wait for an entire resource to transfer before giving up. The resource timer starts when the request is initiated and counts until either the request completes or this timeout interval is reached, whichever comes first.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSURLSession.h

TLSMaximumSupportedProtocol

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

@property SSLProtocol TLSMaximumSupportedProtocol
Availability
  • Available in iOS 7.0 and later.
Declared In
NSURLSession.h

TLSMinimumSupportedProtocol

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

@property SSLProtocol TLSMinimumSupportedProtocol
Availability
  • Available in iOS 7.0 and later.
Declared In
NSURLSession.h

URLCache

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

@property(retain) NSURLCache *URLCache
Discussion

To disable caching, set this property to NULL.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSURLSession.h

URLCredentialStorage

A credential storage pool that provides stored credentials for authentication.

@property(retain) NSURLCredentialStorage *URLCredentialStorage
Discussion

To not use a credential storage pool, set this property to NULL.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSURLSession.h

Class Methods

backgroundSessionConfiguration:

Returns a preconfigured session configuration object that causes the upload or download to be performed in the background.

+ (NSURLSessionConfiguration *)backgroundSessionConfiguration:(NSString *)identifier
Parameters
identifier

An identifier for the new session configuration that is unique for your app. Your app can retrieve the download or the upload response later by creating a new background session with the same identifier.

Discussion

Sessions created with configuration objects returned by this method are called background sessions. These sessions differ from other sessions in the following ways:

  • Upload and download tasks in background sessions are performed by an external daemon instead of by the app itself. As a result, the transfers continue in the background even if the app is suspended, exits, or crashes.

  • In iOS, if your app creates a background session, the app is automatically relaunched in the background whenever tasks complete. In OS X, the results of background tasks are available when your app restarts.

  • Background transfers have a few additional constraints, such as the need to provide a delegate.

For full details, see NSURLSession Class Reference.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSURLSession.h

defaultSessionConfiguration

Returns a copy of the default session configuration.

+ (NSURLSessionConfiguration *)defaultSessionConfiguration
Discussion

The default session configuration causes the session to behave similarly to an NSURLConnection object in its standard configuration. If you are porting code from NSURLConnection, use this method to obtain an initial configuration and then customize the returned object as needed.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSURLSession.h

ephemeralSessionConfiguration

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

+ (NSURLSessionConfiguration *)ephemeralSessionConfiguration
Availability
  • Available in iOS 7.0 and later.
Declared In
NSURLSession.h