iOS NSURLSessionConfiguration Reference

Posted 2022-12-09 陌上心

ios NSURLSessionConfiguration Reference

一个NSURLSessionConfiguration对象定义的行为和策略被用于使用NSURLSession上传和下载数据，创建一个配置对象始终是你必须采取的第一步。你可以使用这个对象去配置你想要使用的NSURLSession对象的超时时间、缓存策略、连接请求以及其它类型的信息。

在你使用它初始化一个NSURLSession对象之前，适当的配置你的NSURLSessionConfiguration对象很重要。Session对象会对你提供的配置设置拷贝一个副本并且用它们去设置session的配置。一旦配置完成，session对象会忽略你读NSURLSeesionConfiguration对象的任何改变。如果你想要修改你的转让策略，你必须更新session配置对象并且用它创建一个新的NSURLSession对象。

注意：
在某些情况下，在配置中对象中定义的策略可能会被一个由提供给一个任务的NSURLRequest对象指定的策略重写。除非session对象的策略更加严格，否则request对象提起的策略都会被遵守。例如，如果session配置> 指定的蜂窝网络不应该被允许，NSURLRequest对象将不能请求蜂窝网络。

若想了解更多的关于使用配置对象创建session对象的信息，请参考NSURLSession Class Reference。

---

创建session配置对象

+ (NSURLSessionConfiguration *)defaultSessionConfiguration

返回值为使用默认选项的新的上传和下载任务的配置对象。默认session配置使用持久的给予磁盘的缓存（除了下载文件的结果）和在用户钥匙串保存的凭证。它还会在NSURLConnection和NSURLDownload类共享的cookie存储中保存cookie（默认）。

注意：如果你是基于NSURLConnection类的移植代码，使用这种方法来获得初始配置对象，然后自定义这
个对象是必要的。

修改返回的session配置对象不会影响将来任何调用这个方法返回的配置独享，并且不会改变现有的session默认行为。因此，始终使用安全的返回值作为一个额外自定义的出发点。

+ (NSURLSessionConfiguration *)ephemeralSessionConfiguration

返回值是一个对缓存、cookies或凭证的没有使用持久存储的session临时配置对象，用于优化传输数据和程序内存。

一个临时session配置对象类似于一个默认的session配置对象，除了相对于session对象不会存储缓存，凭证存储，或任何session相关的数据存储到磁盘，一个临时的session写入数据到磁盘的唯一情况是当你告诉它讲一个URL的内容写入到一个文件。

使用临时session的主要优势是隐私。如果不将潜在的敏感数据写入到磁盘，数据被拦截或以后使用将会不太可能。处于这个原因，短暂的session非常适合在私人Web浏览器和其它类似情况。

因为一个临时的session不会向磁盘写入缓存数据，缓存的大小收可用内存的限制。这个限制意味着以前获取的资源不太可能在缓存中（并且保证如果用户退出和重启应用也不会在缓存中）。此行为可能减少感知性能，这取决于你的应用。

当你的应用程序session失效，所有的临时session将会自动清除。此外，在iOS中，当你的应用程序挂起但是被清洗，当你的应用程序被终止或当你的系统出现内存压力，内存缓存不会被自动清除。

注意：自定义一个默认的session配置对象并且获得一个有临时session配置对象提供的相同的行为（或任何部分）是可能的，但是使用这种方法更方便

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

• 参数：identifier，session配置对象的唯一标示福，这个参数不能为nil或空字符串

返回值为session配置对象，允许在后台执行HTTP和HTTPS上传和下载，上传和下载任务在系统的一个单独的进程中执行。

使用这个方法来初始化配置对象适合应用在后台运行的时候传输数据文件。一个session配置了这个对象将会在系统中控制传输，在一个单独的进程中控制传输。在iOS中，即使应用被挂起或被终止，这个配置让传输变得有可能。

如果一个iOS应用被终止并且重新运行，应用能够使用相同的唯一标示去创建一个新的配置对象和session，并且检索在程序终结时的进程的传输状态。此行为只适用于有系统应用程序的正常终止。。如果用户从多任务屏幕上终止程序，系统将会取消所有session的后台传输。此外，系统不会自动重启用户自己终止的应用。用户必须明确的重新运行程序，传输才能重新开始。

你可以配置一个后台session在系统的最佳性能使用discretionay属性酌情处理传输任务。当传输大量数据的时候，我们鼓励你将这个属性的值设置为YES。

有关后台上传和下载文件的更多信息请参考URL Session Programming Guide。

---

设置常规属性

@property(readonly, copy) NSString *identifier

identifier属性是后台session配置对象的唯一标识（只读）。

这个属性的赋值只有在使用backgroundSessionConfigurationWithIdentifier:方法创建配置对象的时候。这个字符串唯一标识后台session对象。在iOS中，在应用被终止然而传输正在后台发生的情况下你才会使用这个属性。当应用被重启，使用这个字符串重新创建和转让配置对象和session。

@property(copy) NSDictionary *HTTPAdditionalHeaders

HTTPAdditionalHeaders属性是请求发送的附加否字典。

这个属性指定添加到所有任务的基础上此配置的附加头中。例如，你可以设置UserAgent头，通过使用基于这个配置的session，你的应用将会自动包含在每次请求中。

一个NSURLSession对象旨在为你处理HTTP协议的各个方面。这样一来，你不应该修改一下标题：

• Authorization

• Connection

• Host

• WWW-Authenticate

此外，如果能够自动确定上传数据体的长度，例如，如果你提供了一个NSData对象的内容体，内容长度（Content-Length）的长度由你自己设置。

@property NSURLRequestNetworkServiceType networkServiceType

networkServiceType属性提供了网络服务的类型。

这个属性决定了在此基础上配置的session的所有任务的网络服务的类型。

网络服务的类型提供了一个关于系统底层流量用途的提示。这个暗示了系统优化流量确定需要多块的速度来唤醒蜂窝会Wi-Fi无线电的能力等。通过提供准确的信息，就提高了系统最佳平衡电池寿命，性能和其他考虑的能力。

例如，如果你的应用正在执行一个不需要用户请求的下载，你应该指定NSURLNetworkServiceTypeBackground，例如预读内容，这样当用户选择查看它的时候他讲能够查看。

这个设置也能影响服务的Wi-Fi质量（QoS）优先。

默认值是NSURLNetworkServiceTypeDefault。

@property BOOL allowsCellularAccess

allowsCellularAccess属性是一个布尔值，，用来确定连接是否通过蜂窝网络。

此属性控制基于此会话配置会话任务是否允许通过无线网络进行连接。

默认值是YES。

欲了解更多信息，请阅读Restrict Cellular Networking Correctly。

@property NSTimeInterval timeoutIntervalForRequest

timeoutIntervalForRequest属性表示超时时间间隔，用于当等待更多数据是使用。

这个属性决定了基于这个配置的session的所有任务请求的超时时间间隔。请求超时间隔控制一个任务在放弃之前应该等待额外数据到达的时间长度（单位为秒）。当新数据到达时，与这个值相关联的定时器将会被复位。当请求定时器达到指定时间间隔没有收到任何新的数据，就会触发超时。

默认值为60秒。

重要：如果原始请求失败导致超时，任何后台session创建的上传或下载任务都会自动重试。要配置上传或下载任务需要多长时间被允许重试或转让，使用timeoutIntervalForResource属性。

@property NSTimeInterval timeoutIntervalForResource

timeoutIntervalForResource属性表示一个资源请求应该被允许的最长请求时间。

这个属性决定了基于这个配置的session的所有任务的资源超时间隔。资源超时间隔控制了在资源被放弃之前需要等待的时间长度（单位为秒）。当请求初始化时资源定时器开始并且计数，知道请求王城或达到超时间隔，以先到者为资源计时器开始。

默认值为7天。

@property(copy) NSString *sharedContainerIdentifier

sharedContainerIdentifier属性标识后台URL session应该被下载的文件的共享容器。

要为一个应用扩展创建爱你一个URL session，你必须为应用程序扩展和应用日你去设置一个有效的标识符。

重要：如果你尝试使用你的应用程序扩展创建一个URL session，但是不能将这个属性设置为一个有效值，URL session会在创建时失效。

关于应用扩展的更多信息，请参考App Extension Programming Guide。

---

设置cookie策略

@property NSHTTPCookieAcceptPolicy HTTPCookieAcceptPolicy

HTTPCookieAcceptPolicy属性，一个策略常量，决定何时cookies应该被接受。

这个属性决定基于这个配置的session的所有任务的cookies接受策略。

它的默认值为NSHTTPCookieAcceptPolicyOnlyFromMainDocumentDomain。你可以将它改为任何在NSHTTPCookieAcceptPolicy枚举类型上定义的常量。

如果你想更直接的控制什么样的cookies被接受，设置它的值为NSHTTPCookieAcceptPolicyNever，然后使用allHeaderFields和cookiesWithResponseHeaderFields:forURL:方法从URL响应对象自己提取cookies。

@property(retain) NSHTTPCookieStorage *HTTPCookieStorage

HTTPCookieStorage属性决定了基于这个配置的session的所有任务使用cookie存储对象。

禁用cookie存储，设置属性为nil。
对于默认的和后台的session，默认值是共享的cookie存储对象。

对于临时session，默认值是一个旨在内存中存储数据的私有cookie存储，并且当session无效时被销毁。

@property BOOL HTTPShouldSetCookies

HTTPShouldSetCookies属性是一个布尔值，用来确定请求是否应该包含cookie存储中的cookies。

这个属性控制基于这个配置的session所有任务请求时应该自动提供提供共享co存储中的cookies。

如果你想自己提供cookies，设置值为NO,并且提供一个要么通过session的HTTPAdditionalHeaders属性要么或使用自定义的NSURLRequest对象每个请求的等级的cookie头。

默认值为YES。

---

设置安全等级

@property SSLProtocol TLSMaximumSupportedProtocol

TLSMaximumSupportedProtocol，当sesssion连接时客户端应该请求的最大TLS协议版本。

这个属性决定了基于这个配置的session的所有任务的最大TLS协议版本。

默认值是系统支持的TLS最新版本（当前是TLS1.2或kTLSProtocol12）。有关SSL协议的其他值参考SSL协议的枚举常量。

@property SSLProtocol TLSMinimumSupportedProtocol

TLSMinimumSupportedProtocol属性，在协议协商过程中应该被接受的最低TLS协议.

这个属性决定了再次基础上配置的session的所有任务最低TLS协议版本。

默认值为SSL 3.0（kSSLProtocol3）。有关其他值参考SSL协议常量枚举类型。

@property(retain) NSURLCredentialStorage *URLCredentialStorage

URLCredentialStorage属性，一个凭据商店为身份验证提供的凭据。

这个属性决定在此基础上配置会话中使用任务凭据存储对象。

为不使用凭证存储，将此属性设置为nil。

对于默认和后台session，默认值是共享凭据存储对象。

对于临时session，默认值是私有凭据存储对象，只有在内存中存储数据，而当无效会话被销毁。

---

设置缓存策略

@property(retain) NSURLCache *URLCache

URLCache属性，URL缓存提供的会话中请求缓存响应。

这个属性决定在此基础上配置session中所有任务的URL缓存对象。

要禁用缓存，将此属性设置为nil。

对于默认session，默认值是共享URL缓存对象。

有关后台session，默认值是零。

对于临时session，默认值是仅在内存中存储数据的专用高速缓存的对象，当无效会话被销毁。

@property NSURLRequestCachePolicy requestCachePolicy

requestCachePolicy属性，决定何时从缓存返回响应的一个常量。

这个属性决定在此基础上配置session中使用的任务请求缓存策略。

将此属性设置为在NSURLRequestCachePolicy定义的常量之一指定缓存策略是否应取决于到期日和年龄，是否缓存应完全禁用，服务器是否应该联系，以确定是否因为它是内容已被更改最后要求。

默认值是NSURLRequestUseProtocolCachePolicy。

---

支持后台传输

@property BOOL sessionSendsLaunchEvents

sessionSendsLaunchEvents属性，一个布尔值，指示当传输结束时应用应该被回复还是在后台启动。

对于使用backgroundSessionConfigurationWithIdentifier:方法创建的配置对象，你可以使用这个属性对iOS应用控制启动行为。当使用其它方法创建的配置对象时这个属性被忽略。

这个属性的默认值是YES，当这个属性的值为YES时，但session任务完成或需要身份验证的时候系统会自动唤醒iOS应用。那时，系统调用应用程序的委托申请application:handleEventsForBackgroundURLSession:completionHandler:方法，为它提供需要注意的session标识符。如果您的应用程序必须重新启动，您可以使用该标识符来创建能够服务任务的新的配置和会话对象。

@property(getter=isDiscretionary) BOOL discretionary

discretionary属性，一个布尔值，确定是否后台任务可以在系统的最佳性能酌情安排。。

对于使用backgroundSessionConfigurationWithIdentifier:方法创建的配置对象，当传输发生的时候使用这个属性来给系统控制。使用其他方法创建的配置对象忽略这个属性。

当传输大量数据的时候，我们鼓励你设置这个属性为YES，这样最是系统调度这些传输时，对设备做到最佳。例如，传输大量数据的时候，系统可能会延迟，知道设备插入会连接到Wi-Fi。该属性默认为NO.

只有当你的应用在前台开始传输的时候，session对象请求这个属性的值。对于后台的应用传输开始，系统总是开始转塘它的自由裁量权，换句话说，系统既定此属性为YES并且忽略你指定的任何值。

---

支持自定义协议

@property(copy) NSArray <Class> *protocolClasses

protocolClasses属性，在session中处理请求的额外协议子类的数组。

此数组中的对象是对应于你定义自定义NSURLProtocol子类对象。

在此之前处理请求，一个NSURLSession对象搜索默认的协议，然后再检查你的自定义协议，直到它找到一个能够处理指定的请求。它采用的协议通过canInitWithRequest:类方法返回YES，表明类能够处理指定的请求。

注意，你不能在后台session的会议中使用自定义NSURLProtocol子类。

默认值为空数组。

---

设置HTTP策略和代理属性

@property NSInteger HTTPMaximumConnectionsPerHost

HTTPMaximumConnectionsPerHost属性，使用给定主机同时连接的最大数量。

这个属性决定了基于这个配置的session的任务每个主机所能同时连接的最大数量。

这个限制是每个session，因此，如果您使用多个session，你的应用程序作为一个整体可能会超过此限制。此外，根据您连接到互联网上，一个sess可能会使用一个比你指定的低的下限。

默认值是OS X为6， iOS为4。

@property BOOL HTTPShouldUsePipelining

HTTPShouldUsePipelining属性，一个布尔值，确定session是否应该使用HTTP传递途径。

这个属性决定在此基础上配置session中的任务是否应该使用HTTP传递途径。您还可以通过使用NSURLRequest对象在每个人物的基础上启用传递途径。

默认值是NO。

@property(copy) NSDictionary *connectionProxyDictionary

connectionProxyDictionary属性，在本次session使用的包含代理信息的字典。

当连接到远程主机时，这个属性控制了基于这个配置的session的代理任务。
默认值是NULL，，这意味着任务使用默认系统设置。

参考CFProxySupport Reference了解更多关于这个字典的信息。