Platforms to show: All Mac Windows Linux Cross-Platform

Back to NSURLSessionConfigurationMBS class.

NSURLSessionConfigurationMBS.allowsCellularAccess as Boolean

Type Topic Plugin Version macOS Windows Linux iOS Targets
property Cocoa Networking MBS MacFrameworks Plugin 20.2 ✅ Yes ❌ No ❌ No ✅ Yes All
A Boolean value that determines whether connections should be made over a cellular network.

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

For more information, read Restrict Cellular Networking Correctly on Apple website.
(Read and Write property)

NSURLSessionConfigurationMBS.allowsConstrainedNetworkAccess as Boolean

Type Topic Plugin Version macOS Windows Linux iOS Targets
property Cocoa Networking MBS MacFrameworks Plugin 20.2 ✅ Yes ❌ No ❌ No ✅ Yes All
A Boolean value that indicates whether connections may use the network when the user has specified Low Data Mode.

In iOS 13 and later, users can set their device to use Low Data Mode as one of the Cellular Data Options in the Settings app. Users can turn on Low Data Mode to reduce your app’s network data usage. This property controls a URL session’s behavior when the user turns on Low Data Mode. If there are no nonconstrained network interfaces available and the session’s allowsConstrainedNetworkAccess property is false, any task created from the session fails. In this case, the error provided when the task fails has a networkUnavailableReason property whose value is NSURLErrorNetworkUnavailableReasonConstrained.
Limit your app’s of use of constrained network access to user-initiated tasks, and put off discretionary tasks until a nonconstrained interface becomes available. To do this, set allowsConstrainedNetworkAccess (and allowsExpensiveNetworkAccess) to false and waitsForConnectivity to true. This way, your NSURLSessionTaskMBS waits for a suitable interface to become available before sending or receiving data.

Available in MacOS 10.15 or newer.
(Read and Write property)

NSURLSessionConfigurationMBS.allowsExpensiveNetworkAccess as Boolean

Type Topic Plugin Version macOS Windows Linux iOS Targets
property Cocoa Networking MBS MacFrameworks Plugin 20.2 ✅ Yes ❌ No ❌ No ✅ Yes All
A Boolean value that indicates whether connections may use a network interface that the system considers expensive.

The system determines what constitutes “expensive” based on the nature of the network interface and other factors. iOS 13 considers most cellular networks and personal hotspots expensive. If there are no nonexpensive network interfaces available and the session’s allowsExpensiveNetworkAccess property is false, any task created from the session fails. In this case, the error provided when the task fails has a networkUnavailableReason property whose value is NSURLErrorNetworkUnavailableReasonExpensive.

Limit your app’s of use of expensive network access to user-initiated tasks, and put off discretionary tasks until an nonexpensive interface becomes available. To do this, set allowsExpensiveNetworkAccess (and allowsConstrainedNetworkAccess) to false and waitsForConnectivity to true. This way, your NSURLSessionTaskMBS waits for a suitable interface to become available before sending or receiving data.

Available in MacOS 10.15 or newer.
(Read and Write property)

NSURLSessionConfigurationMBS.connectionProxyDictionary as Dictionary

Type Topic Plugin Version macOS Windows Linux iOS Targets
property Cocoa Networking MBS MacFrameworks Plugin 20.2 ✅ Yes ❌ No ❌ No ✅ Yes All
A dictionary containing information about the proxy to use within this session.

This property controls which proxy tasks within sessions based on this configuration use when connecting to remote hosts.
The default value is nil, which means that tasks use the default system settings.
See Global Proxy Configuration for more information about these dictionaries.
(Read and Write property)

NSURLSessionConfigurationMBS.discretionary as Boolean

Type Topic Plugin Version macOS Windows Linux iOS Targets
property Cocoa Networking MBS MacFrameworks Plugin 20.2 ✅ Yes ❌ No ❌ No ✅ Yes All
A Boolean value that determines whether background tasks can be scheduled at the discretion of the system for optimal performance.

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 true. 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 false.
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 true and ignores any value you specified.

Available in MacOS 10.10 or newer.
(Read and Write property)

NSURLSessionConfigurationMBS.Handle as Integer

Type Topic Plugin Version macOS Windows Linux iOS Targets
property Cocoa Networking MBS MacFrameworks Plugin 20.2 ✅ Yes ❌ No ❌ No ✅ Yes All
The internal object reference.

(Read and Write property)

NSURLSessionConfigurationMBS.HTTPAdditionalHeaders as Dictionary

Type Topic Plugin Version macOS Windows Linux iOS Targets
property Cocoa Networking MBS MacFrameworks Plugin 20.2 ✅ Yes ❌ No ❌ No ✅ Yes All
A dictionary of additional headers to send with requests.

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 NSURLSessionMBS 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
  • Proxy-Authenticate
  • Proxy-Authorization
  • 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 MemoryBlock 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.
(Read and Write property)

NSURLSessionConfigurationMBS.HTTPCookieAcceptPolicy as Integer

Type Topic Plugin Version macOS Windows Linux iOS Targets
property Cocoa Networking MBS MacFrameworks Plugin 20.2 ✅ Yes ❌ No ❌ No ✅ Yes All
A policy constant that determines when cookies should be accepted.

This property determines the cookie accept policy for all tasks within sessions based on this configuration.
The default value is CookieAcceptPolicyOnlyFromMainDocumentDomain. You can change it to any of the constants defined in the CookieAcceptPolicy enumerated type.
If you want more direct control over what cookies are accepted, set this value to CookieAcceptPolicyNever and then use the allHeaderFields and cookiesWithResponseHeaderFields methods to extract cookies from the URL response object yourself.
(Read and Write property)

NSURLSessionConfigurationMBS.HTTPCookieStorage as NSHTTPCookieStorageMBS

Type Topic Plugin Version macOS Windows Linux iOS Targets
property Cocoa Networking MBS MacFrameworks Plugin 20.2 ✅ Yes ❌ No ❌ No ❌ No Desktop, Console & Web
The cookie store for storing cookies within this session.

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 sharedHTTPCookieStorage cookie storage object.
For ephemeralSessionConfiguration sessions, the default value is a private cookie storage object that stores data in memory only, and is destroyed when you invalidate the session.
(Read and Write property)

NSURLSessionConfigurationMBS.HTTPMaximumConnectionsPerHost as Integer

Type Topic Plugin Version macOS Windows Linux iOS Targets
property Cocoa Networking MBS MacFrameworks Plugin 20.2 ✅ Yes ❌ No ❌ No ✅ Yes All
The maximum number of simultaneous connections to make to a given host.

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 macOS, or 4 in iOS.
(Read and Write property)

NSURLSessionConfigurationMBS.HTTPShouldSetCookies as Boolean

Type Topic Plugin Version macOS Windows Linux iOS Targets
property Cocoa Networking MBS MacFrameworks Plugin 20.2 ✅ Yes ❌ No ❌ No ✅ Yes All
A Boolean value that determines whether requests should contain cookies from the cookie store.

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 false and provide a Cookie header either through the session’s HTTPAdditionalHeaders property or on a per-request level using a custom NSURLRequestMBS object.
The default value is true.
(Read and Write property)

NSURLSessionConfigurationMBS.HTTPShouldUsePipelining as Boolean

Type Topic Plugin Version macOS Windows Linux iOS Targets
property Cocoa Networking MBS MacFrameworks Plugin 20.2 ✅ Yes ❌ No ❌ No ✅ Yes All
A Boolean value that determines whether the session should use HTTP pipelining.

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 NSURLRequestMBS object.
The default value is false.
(Read and Write property)

NSURLSessionConfigurationMBS.identifier as String

Type Topic Plugin Version macOS Windows Linux iOS Targets
property Cocoa Networking MBS MacFrameworks Plugin 20.2 ✅ Yes ❌ No ❌ No ✅ Yes All
The background session identifier of the configuration object.

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.
(Read only property)

NSURLSessionConfigurationMBS.NetworkServiceType as Integer

Type Topic Plugin Version macOS Windows Linux iOS Targets
property Cocoa Networking MBS MacFrameworks Plugin 20.2 ✅ Yes ❌ No ❌ No ✅ Yes All
The type of network service 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, specify the NetworkServiceTypeBackground type if your app is performing a download that wasn’t requested by the user, like prefetching content so that it’s 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 NetworkServiceTypeDefault.
(Read and Write property)

NSURLSessionConfigurationMBS.RequestCachePolicy as Integer

Type Topic Plugin Version macOS Windows Linux iOS Targets
property Cocoa Networking MBS MacFrameworks Plugin 20.2 ✅ Yes ❌ No ❌ No ✅ Yes All
A predefined constant that determines when to return a response from the cache.

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 CachePolicy constants 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 CachePolicyUseProtocolCachePolicy.
(Read and Write property)

NSURLSessionConfigurationMBS.sharedContainerIdentifier as String

Type Topic Plugin Version macOS Windows Linux iOS Targets
property Cocoa Networking MBS MacFrameworks Plugin 20.2 ✅ Yes ❌ No ❌ No ✅ Yes All
The identifier for the shared container into which files in background URL sessions should be downloaded.

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

Available in MacOS 10.10 or newer.
(Read and Write property)

NSURLSessionConfigurationMBS.shouldUseExtendedBackgroundIdleMode as Boolean

Type Topic Plugin Version macOS Windows Linux iOS Targets
property Cocoa Networking MBS MacFrameworks Plugin 20.2 ✅ Yes ❌ No ❌ No ✅ Yes All
A Boolean value that indicates whether TCP connections should be kept open when the app moves to the background.

In addition to requesting that the connection be kept open, setting this value to true asks the system to delay reclaiming the connection when the app moves to the background.

Available in MacOS 10.11 or newer.
(Read and Write property)

NSURLSessionConfigurationMBS.timeoutIntervalForRequest as Double

Type Topic Plugin Version macOS Windows Linux iOS Targets
property Cocoa Networking MBS MacFrameworks Plugin 20.2 ✅ Yes ❌ No ❌ No ✅ Yes All
The timeout interval to use when waiting for additional data.

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.

Important
Any upload or download tasks created by a background session are automatically retried if the original request fails due to a timeout. To configure how long an upload or download task should be allowed to be retried or transferred, use the timeoutIntervalForResource property.
(Read and Write property)

NSURLSessionConfigurationMBS.timeoutIntervalForResource as Double

Type Topic Plugin Version macOS Windows Linux iOS Targets
property Cocoa Networking MBS MacFrameworks Plugin 20.2 ✅ Yes ❌ No ❌ No ✅ Yes All
The maximum amount of time that a resource request should be allowed to take.

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.
(Read and Write property)

NSURLSessionConfigurationMBS.URLCache as NSURLCacheMBS

Type Topic Plugin Version macOS Windows Linux iOS Targets
property Cocoa Networking MBS MacFrameworks Plugin 20.2 ✅ Yes ❌ No ❌ No ✅ Yes All
The URL cache for providing cached responses to requests within the session.

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.
(Read and Write property)

NSURLSessionConfigurationMBS.URLCredentialStorage as NSURLCredentialStorageMBS

Type Topic Plugin Version macOS Windows Linux iOS Targets
property Cocoa Networking MBS MacFrameworks Plugin 20.2 ✅ Yes ❌ No ❌ No ✅ Yes All
A credential store that provides credentials for authentication.

This property determines the credential storage object used by tasks within sessions based on this configuration.
If you don’t want to use a credential store, set this property to nil.
For default and background sessions, the default value is the sharedCredentialStorage credential store object.
For ephemeralSessionConfiguration sessions, the default value is a private credential store object that stores data in memory only, and is destroyed when you invalidate the session.
(Read and Write property)

NSURLSessionConfigurationMBS.waitsForConnectivity as Boolean

Type Topic Plugin Version macOS Windows Linux iOS Targets
property Cocoa Networking MBS MacFrameworks Plugin 20.2 ✅ Yes ❌ No ❌ No ✅ Yes All
A Boolean value that indicates whether the session should wait for connectivity to become available, or fail immediately.

Connectivity might be temporarily unavailable for several reasons. For example, a device might only have a cellular connection when allowsCellularAccess is set to false, or the device might require a VPN connection but none is available. If the value of this property is true and sufficient connectivity is unavailable, the session calls the taskIsWaitingForConnectivity: method of NSURLSessionTaskDelegate and waits for connectivity. When connectivity becomes available, the task begins its work and ultimately calls the delegate or completion handler as usual.
If the value of the property is false and connectivity is unavailable, the connection fails immediately with an error, such as NSURLErrorNotConnectedToInternet.
This property is relevant only during the establishment of a connection. If a connection is established and then drops, the completion handler or delegate receives an error, such as NSURLErrorNetworkConnectionLost. For help dealing with dropped connections, see Handling “The network connection was lost” Errors.
This property is ignored by background sessions, which always wait for connectivity.

Available in MacOS 10.13 or newer.
(Read and Write property)

The items on this page are in the following plugins: MBS MacFrameworks Plugin.


The biggest plugin in space...