iOS Developer Library

Developer

Foundation Framework Reference NSURLSessionConfiguration Class Reference

Options
Deployment Target:

On This Page
Language:

NSURLSessionConfiguration

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

Inheritance


Conforms To


Import Statement


import Foundation @import Foundation;

Availability


Available in iOS 7.0 and later.
  • Returns a newly created default session configuration object.

    Declaration

    Swift

    class func defaultSessionConfiguration() -> NSURLSessionConfiguration

    Objective-C

    + (NSURLSessionConfiguration *)defaultSessionConfiguration

    Return Value

    A new configuration object for managing upload and download tasks using the default options.

    Discussion

    The default session configuration uses a persistent disk-based cache (except when the result is downloaded to a file) and stores credentials in the user’s keychain. It also stores cookies (by default) in the same shared cookie store as the NSURLConnection and NSURLDownload classes.

    Modifying the returned session configuration object does not affect any configuration objects returned by future calls to this method, and does not change the default behavior for existing sessions. It is therefore always safe to use the returned object as a starting point for additional customization.

    Import Statement

    import Foundation

    Availability

    Available in iOS 7.0 and later.

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

    Declaration

    Swift

    class func ephemeralSessionConfiguration() -> NSURLSessionConfiguration

    Objective-C

    + (NSURLSessionConfiguration *)ephemeralSessionConfiguration

    Return Value

    A configuration object optimized for transferring data to and from your app’s memory.

    Discussion

    An ephemeral session configuration object is similar to a default session configuration object except that the corresponding session object does not store caches, credential stores, or any session-related data to disk. Instead, session-related data is stored in RAM. The only time an ephemeral session writes data to disk is when you tell it to write the contents of a URL to a file.

    The main advantage to using ephemeral sessions is privacy. By not writing potentially sensitive data to disk, you make it less likely that the data will be intercepted and used later. For this reason, ephemeral sessions are ideal for private browsing modes in web browsers and other similar situations.

    Because an ephemeral session does not write cached data to disk, the size of the cache is limited by available RAM. This limitation means that previously fetched resources are less likely to be in the cache (and are guaranteed to not be there if the user quits and relaunches your app). This behavior may reduce perceived performance, depending on your app.

    When your app invalidates the session, all ephemeral session data is purged automatically. Additionally, in iOS, the in-memory cache is not purged automatically when your app is suspended but may be purged when your app is terminated or when the system experiences memory pressure.

    Import Statement

    import Foundation

    Availability

    Available in iOS 7.0 and later.

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

    Declaration

    Swift

    class func backgroundSessionConfigurationWithIdentifier(_ identifier: String) -> NSURLSessionConfiguration

    Objective-C

    + (NSURLSessionConfiguration *)backgroundSessionConfigurationWithIdentifier:(NSString *)identifier

    Parameters

    identifier

    The unique identifier for the configuration object. This parameter must not be nil or an empty string.

    Return Value

    A configuration object that causes upload and download tasks to be performed by the system in a separate process.

    Discussion

    Use this method to initialize a configuration object suitable for transferring data files while the app runs in the background. A session configured with this object hands control of the transfers over to the system, which handles the transfers in a separate process. In iOS, this configuration makes it possible for transfers to continue even when the app itself is suspended or terminated.

    If an iOS app is terminated by the system and relaunched, the app can use the same identifier to create a new configuration object and session and retrieve the status of transfers that were in progress at the time of termination. This behavior applies only for normal termination of the app by the system. If the user terminates the app from the multitasking screen, the system cancels all of the session’s background transfers. In addition, the system does not automatically relaunch apps that were force quit by the user. The user must explicitly relaunch the app before transfers can begin again.

    For more information about uploading and downloading files in the background, see URL Loading System Programming Guide.

    Import Statement

    import Foundation

    Availability

    Available in iOS 8.0 and later.

  • The background session identifier of the configuration object. (read-only)

    Declaration

    Swift

    var identifier: String { get }

    Objective-C

    @property(readonly, copy) NSString *identifier

    Discussion

    The value of this property is set only when you use the backgroundSessionConfigurationWithIdentifier: method to create the configuration object. The string uniquely identifies a background session object. In iOS, you use this string in cases where the app was terminated while transfers were occurring in the background. When the app relaunches, it uses the string to recreate the configuration and session objects associated with the transfers.

    Import Statement

    import Foundation

    Availability

    Available in iOS 7.0 and later.

  • A dictionary of additional headers to send with requests.

    Declaration

    Swift

    var HTTPAdditionalHeaders: [NSObject : AnyObject]?

    Objective-C

    @property(copy) NSDictionary *HTTPAdditionalHeaders

    Discussion

    This property specifies additional headers that are added to all tasks within sessions based on this configuration. For example, you might set the User-Agent header so that it is automatically included in every request your app makes through sessions based on this configuration.

    An NSURLSession object is designed to handle various aspects of the HTTP protocol for you. As a result, you should not modify the following headers:

    • Authorization

    • Connection

    • Host

    • WWW-Authenticate

    Additionally, if the length of your upload body data can be determined automatically—for example, if you provide the body content with an NSData object—the value of Content-Length is set for you.

    If the same header appears in both this array and the request object (where applicable), the request object’s value takes precedence.

    The default value is an empty array.

    Import Statement

    import Foundation

    Availability

    Available in iOS 7.0 and later.

  • The type of network service.

    Declaration

    Swift

    var networkServiceType: NSURLRequestNetworkServiceType

    Objective-C

    @property NSURLRequestNetworkServiceType networkServiceType

    Discussion

    This property determines the network service type for all tasks within sessions based on this configuration.

    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.

    This setting can also affect the Wi-Fi Quality of Service (QoS) Priority.

    The default value is NSURLNetworkServiceTypeDefault.

    Import Statement

    import Foundation

    Availability

    Available in iOS 7.0 and later.

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

    Declaration

    Swift

    var allowsCellularAccess: Bool

    Objective-C

    @property BOOL allowsCellularAccess

    Discussion

    This property controls whether tasks in sessions based on this session configuration are allowed to make connections over a cellular network.

    The default value is YEStrue.

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

    Import Statement

    import Foundation

    Availability

    Available in iOS 7.0 and later.

  • The timeout interval to use when waiting for additional data.

    Declaration

    Swift

    var timeoutIntervalForRequest: NSTimeInterval

    Objective-C

    @property NSTimeInterval timeoutIntervalForRequest

    Discussion

    This property determines the request timeout interval for all tasks within sessions based on this configuration. The request timeout interval controls how long (in seconds) a task should wait for additional data to arrive before giving up. 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.

    The default value is 60.

    Import Statement

    import Foundation

    Availability

    Available in iOS 7.0 and later.

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

    Declaration

    Swift

    var timeoutIntervalForResource: NSTimeInterval

    Objective-C

    @property NSTimeInterval timeoutIntervalForResource

    Discussion

    This property determines the resource timeout interval for all tasks within sessions based on this configuration. The resource timeout interval controls how long (in seconds) 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.

    The default value is 7 days.

    Import Statement

    import Foundation

    Availability

    Available in iOS 7.0 and later.

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

    Declaration

    Swift

    var sharedContainerIdentifier: String?

    Objective-C

    @property(copy) NSString *sharedContainerIdentifier

    Discussion

    To create a URL session for use by an app extension, you must set this property to a valid identifier for a container shared between the app extension and its containing app.

    For information about app extensions, see App Extension Programming Guide.

    Import Statement

    import Foundation

    Availability

    Available in iOS 8.0 and later.

  • A policy constant that determines when cookies should be accepted.

    Declaration

    Swift

    var HTTPCookieAcceptPolicy: NSHTTPCookieAcceptPolicy

    Objective-C

    @property NSHTTPCookieAcceptPolicy HTTPCookieAcceptPolicy

    Discussion

    This property determines the cookie accept policy for all tasks within sessions based on this configuration.

    The default value is NSHTTPCookieAcceptPolicyOnlyFromMainDocumentDomain. You can change it to any of the constants defined in the NSHTTPCookieAcceptPolicy enumerated type.

    If you want more direct control over what cookies are accepted, set this value to NSHTTPCookieAcceptPolicyNever and then use the allHeaderFields and cookiesWithResponseHeaderFields:forURL: methods to extract cookies from the URL response object yourself.

    Import Statement

    import Foundation

    Availability

    Available in iOS 7.0 and later.

  • The cookie store for storing cookies within this session.

    Declaration

    Swift

    var HTTPCookieStorage: NSHTTPCookieStorage?

    Objective-C

    @property(retain) NSHTTPCookieStorage *HTTPCookieStorage

    Discussion

    This property determines the cookie storage object used by all tasks within sessions based on this configuration.

    To disable cookie storage, set this property to nil.

    For default and background sessions, the default value is the shared cookie storage object.

    For ephemeral sessions, the default value is a private cookie storage object that stores data in memory only, and is destroyed when you invalidate the session.

    Import Statement

    import Foundation

    Availability

    Available in iOS 7.0 and later.

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

    Declaration

    Swift

    var HTTPShouldSetCookies: Bool

    Objective-C

    @property BOOL HTTPShouldSetCookies

    Discussion

    This property controls whether tasks within sessions based on this configuration should automatically provide cookies from the shared cookie store when making requests.

    If you want to provide cookies yourself, set this value to NOfalse and provide a Cookie header either through the session’s HTTPAdditionalHeaders property or on a per-request level using a custom NSURLRequest object.

    The default value is YEStrue.

    Import Statement

    import Foundation

    Availability

    Available in iOS 7.0 and later.

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

    Declaration

    Swift

    var TLSMaximumSupportedProtocol: SSLProtocol

    Objective-C

    @property SSLProtocol TLSMaximumSupportedProtocol

    Discussion

    This property determines the maximum supported TLS protocol version for tasks within sessions based on this configuration.

    The default value is the latest version of TLS supported by the system (currently TLS 1.2, or kTLSProtocol12). See the SSL Protocol Constants enumerated type for additional values.

    Import Statement

    import Foundation

    Availability

    Available in iOS 7.0 and later.

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

    Declaration

    Swift

    var TLSMinimumSupportedProtocol: SSLProtocol

    Objective-C

    @property SSLProtocol TLSMinimumSupportedProtocol

    Discussion

    This property determines the minimum supported TLS protocol version for tasks within sessions based on this configuration.

    The default value is SSL 3.0 (kSSLProtocol3). See the SSL Protocol Constants enumerated type for additional values.

    Import Statement

    import Foundation

    Availability

    Available in iOS 7.0 and later.

  • A credential store that provides credentials for authentication.

    Declaration

    Swift

    var URLCredentialStorage: NSURLCredentialStorage?

    Objective-C

    @property(retain) NSURLCredentialStorage *URLCredentialStorage

    Discussion

    This property determines the credential storage object used by tasks within sessions based on this configuration.

    To not use a credential store, set this property to nil.

    For default and background sessions, the default value is the shared credential store object.

    For ephemeral sessions, the default value is a private credential store object that stores data in memory only, and is destroyed when you invalidate the session.

    Import Statement

    import Foundation

    Availability

    Available in iOS 7.0 and later.

  • URLCache URLCache Property

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

    Declaration

    Swift

    var URLCache: NSURLCache?

    Objective-C

    @property(retain) NSURLCache *URLCache

    Discussion

    This property determines the URL cache object used by tasks within sessions based on this configuration.

    To disable caching, set this property to nil.

    For default sessions, the default value is the shared URL cache object.

    For background sessions, the default value is nil.

    For ephemeral sessions, the default value is a private cache object that stores data in memory only, and is destroyed when you invalidate the session.

    Import Statement

    import Foundation

    Availability

    Available in iOS 7.0 and later.

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

    Declaration

    Swift

    var requestCachePolicy: NSURLRequestCachePolicy

    Objective-C

    @property NSURLRequestCachePolicy requestCachePolicy

    Discussion

    This property determines the request caching policy used by tasks within sessions based on this configuration.

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

    The default value is NSURLRequestUseProtocolCachePolicy.

    Import Statement

    import Foundation

    Availability

    Available in iOS 7.0 and later.

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

    Declaration

    Swift

    var sessionSendsLaunchEvents: Bool

    Objective-C

    @property BOOL sessionSendsLaunchEvents

    Discussion

    For configuration objects created using the backgroundSessionConfigurationWithIdentifier: method, you can use this property to control the launching behavior for an iOS app. This property is ignored for configuration objects created using other methods.

    The default value of this property is YEStrue. When the value of this property is YEStrue, the system automatically wakes up or launches the iOS app in the background when the session’s tasks finish or require authentication. At that time, the system calls the app delegate’s application:handleEventsForBackgroundURLSession:completionHandler: method, providing it with the identifier of the session that needs attention. If your app had to be relaunched, you can use that identifier to create a new configuration and session object capable of servicing the tasks.

    Import Statement

    import Foundation

    Availability

    Available in iOS 7.0 and later.

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

    Declaration

    Swift

    var discretionary: Bool

    Objective-C

    @property(getter=isDiscretionary) BOOL discretionary

    Discussion

    For configuration objects created using the backgroundSessionConfigurationWithIdentifier: method, use this property to give the system control over when transfers should occur. This property is ignored for configuration objects created using other methods.

    When transferring large amounts of data, you are encouraged to set the value of this property to YEStrue. Doing so lets the system schedule those transfers at times that are more optimal for the device. For example, the system might delay transferring large files until the device is plugged in and connected to the network via Wi-Fi. The default value of this property is NOfalse.

    The session object applies the value of this property only to transfers that your app starts while it is in the foreground. For transfers started while your app is in the background, the system always starts transfers at its discretion—in other words, the system assumes this property is YEStrue and ignores any value you specified.

    Import Statement

    import Foundation

    Availability

    Available in iOS 7.0 and later.

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

    Declaration

    Swift

    var protocolClasses: [AnyObject]?

    Objective-C

    @property(copy) NSArray *protocolClasses

    Discussion

    The objects in this array are Class objects corresponding to custom NSURLProtocol subclasses that you define. URL session objects support a number of common networking protocols by default. Use this array to extend the default set of common networking protocols available for use by a session with one or more custom protocols that you define.

    Prior to handling a request, an NSURLSession object searches the default protocols first and then checks your custom protocols until it finds one capable of handling the specified request. It uses the protocol whose canInitWithRequest: class method returns YEStrue, indicating that the class is capable of handling the specified request.

    The default value is an empty array.

    Import Statement

    import Foundation

    Availability

    Available in iOS 7.0 and later.

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

    Declaration

    Swift

    var HTTPMaximumConnectionsPerHost: Int

    Objective-C

    @property NSInteger HTTPMaximumConnectionsPerHost

    Discussion

    This property determines the maximum number of simultaneous connections made to each host by tasks within sessions based on this configuration.

    This limit is per session, so if you use multiple sessions, your app as a whole may exceed this limit. Additionally, depending on your connection to the Internet, a session may use a lower limit than the one you specify.

    The default value is 6 in OS X, or 4 in iOS.

    Import Statement

    import Foundation

    Availability

    Available in iOS 7.0 and later.

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

    Declaration

    Swift

    var HTTPShouldUsePipelining: Bool

    Objective-C

    @property BOOL HTTPShouldUsePipelining

    Discussion

    This property determines whether tasks within sessions based on this configuration should use HTTP pipelining. You can also enable pipelining on a per-task basis by creating the task with an NSURLRequest object.

    The default value is NOfalse.

    Import Statement

    import Foundation

    Availability

    Available in iOS 7.0 and later.

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

    Declaration

    Swift

    var connectionProxyDictionary: [NSObject : AnyObject]?

    Objective-C

    @property(copy) NSDictionary *connectionProxyDictionary

    Discussion

    This property controls which proxy tasks within sessions based on this configuration use when connecting to remote hosts.

    The default value is NULL, which means that tasks use the default system settings.

    See CFProxySupport Reference for more information about these dictionaries.

    Import Statement

    import Foundation

    Availability

    Available in iOS 7.0 and later.

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

    Deprecation Statement

    Use backgroundSessionConfigurationWithIdentifier: instead.

    Declaration

    Swift

    class func backgroundSessionConfiguration(_ identifier: String) -> NSURLSessionConfiguration

    Objective-C

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

    Parameters

    identifier

    The unique identifier for the configuration object. This parameter must not be nil or an empty string.

    Return Value

    A URL session configuration object that causes upload and download tasks to be performed by the system in a separate process.

    Import Statement

    import Foundation

    Availability

    Available in iOS 7.0 and later.

    Deprecated in iOS 8.0.