NSURLSessionConfiguration - URL会话配置
定义URL会话的行为和策略的配置对象。NSURLSessionConfiguration对象定义使用NSURLSession对象上传和下载数据时要使用的行为和策略。上传或下载数据时，创建NSURLSessionConfiguration对象始终是必须采取的第一步。可以使用此对象来配置超时值、缓存策略、连接要求以及要与NSURLSession对象一起使用的其他类型的信息。
在使用NSURLSessionConfiguration对象初始化会话对象之前，必须对其进行适当配置。NSURLSession对象复制提供的配置设置，并使用这些设置配置到会话中。配置后，NSURLSession对象将忽略对NSURLSessionConfiguration对象所做的任何更改。如果需要修改传输策略，则必须更新NSURLSessionConfiguration对象并使用它创建新的NSURLSession对象。
在某些情况下，此配置中定义的策略可能会被为任务提供的NSURLRequest对象指定的策略覆盖。除非会话的策略更具限制性，例如如果会话配置指定不允许蜂窝网络，则NSURLRequest对象无法请求蜂窝网络。否则将遵守NSURLRequest对象上指定的任何策略。
NSURLSessionConfiguration常用属性
@property (class, readonly, strong) NSURLSessionConfiguration *defaultSessionConfiguration;
属性描述：类属性，默认会话配置对象。默认会话配置使用基于磁盘的持久缓存(结果下载到文件时除外)，并将凭据存储在用户的密钥链中。它还将cookie(默认情况下)存储在与NSURLConnection和NSURLDownload类相同的共享cookie存储中。修改返回的会话配置对象不会影响将来调用此方法返回的任何配置对象，也不会更改现有会话的默认行为。因此，使用返回的对象作为额外定制的起点总是安全的。
@property (class, readonly, strong) NSURLSessionConfiguration *ephemeralSessionConfiguration;
属性描述：类属性，临时会话配置对象。临时会话配置对象类似于默认会话配置，只是对应的会话对象不将缓存、凭据存储或任何与会话相关的数据存储到磁盘上。相反，与会话相关的数据存储在RAM中。临时会话将数据写入磁盘的唯一时间是当您告诉它将URL的内容写入文件时。
@property (nullable, readonly, copy) NSString *identifier;
属性描述：配置对象的后台会话标识符。此属性的值仅在使用backgroundSessionConfigurationWithIdentifier:方法创建配置对象时设置。字符串唯一标识一个后台会话对象。在iOS中，可以在应用程序后台传输终止的情况下使用这个字符串。当应用程序重新启动时，它使用该字符串重新创建与传输相关的配置和会话对象。
@property NSURLRequestCachePolicy requestCachePolicy;
属性描述：一个预定义的常量，用于确定何时从缓存中返回响应。配置对象根据此属性确定会话内任务使用的请求缓存策略。此属性的值为NSURLRequestCachePolicy中定义的常量之一，以指定缓存策略是否应依赖于过期日期和有效期，缓存是否应完全禁用，以及是否应联系服务器以确定自上次请求以来内容是否已更改。默认值为NSURLRequestUseProtocolCachePolicy。
@property NSTimeInterval timeoutIntervalForRequest;
属性描述：配置对象根据此属性确定会话内所有任务的请求超时间隔，默认值为60。请求超时间隔控制任务在放弃之前等待额外数据到达的时间(以秒为单位)。每当有新数据到达时，与此值关联的计时器将被重置。当请求计时器到达指定的时间间隔而没有收到任何新数据时，它将触发超时。
任何由后台会话创建的上传或下载任务，如果原始请求由于超时而失败，将自动重试。若要配置上传或下载任务允许重试超时时间，则使用timeoutIntervalForResource属性。
@property NSTimeInterval timeoutIntervalForResource;
属性描述：允许资源请求所花费的最大时间，默认值为7天。配置对象根据此属性确定会话内所有任务的资源超时间隔。资源超时间隔控制在放弃之前等待整个资源传输的时间(以秒为单位)。资源计时器在请求启动时开始计数，直到请求完成或达到该超时间隔(以先到者为准)。
@property NSURLRequestNetworkServiceType networkServiceType;
属性描述：配置对象使用此属性设置会话中所有任务的网络服务类型。默认值为NSURLNetworkServiceTypeDefault。此设置还会影响Wi-Fi服务质量(QoS)优先级。网络服务类型向操作系统提供关于底层流量用于做什么的提示。此提示增强了系统对流量进行优先级排序、确定唤醒蜂窝或Wi-Fi无线电所需的速度等的能力。通过提供准确的信息，可以提高系统在电池寿命、性能和其他考虑因素之间进行最佳平衡的能力。
例如，如果您的应用程序正在执行用户未请求的下载（如预取内容），则指定NSURLNetworkServiceTypeBackground类型，以便在用户选择查看时可用。
- NSURLRequestNetworkServiceType提供的枚举值：
typedef NS_ENUM(NSUInteger, NSURLRequestNetworkServiceType)
{
//标准互联网流量
NSURLNetworkServiceTypeDefault = 0,
//IP语音控制流量
NSURLNetworkServiceTypeVoIP API_DEPRECATED("Use PushKit for VoIP control purposes", macos(10.7,10.15), ios(4.0,13.0), watchos(2.0,6.0), tvos(9.0,13.0)) = 1,
//视频流量
NSURLNetworkServiceTypeVideo = 2,
//后台流量
NSURLNetworkServiceTypeBackground = 3,
//语音数据
NSURLNetworkServiceTypeVoice = 4,
//响应性数据
NSURLNetworkServiceTypeResponsiveData = 6,
//多媒体音频/视频流
NSURLNetworkServiceTypeAVStreaming API_AVAILABLE(macosx(10.9), ios(7.0), watchos(2.0), tvos(9.0)) = 8 ,
//响应式多媒体音频/视频
NSURLNetworkServiceTypeResponsiveAV API_AVAILABLE(macosx(10.9), ios(7.0), watchos(2.0), tvos(9.0)) = 9,
//呼叫信令
NSURLNetworkServiceTypeCallSignaling API_AVAILABLE(macosx(10.12), ios(10.0), watchos(3.0), tvos(10.0)) = 11,
};
@property BOOL allowsCellularAccess;
属性描述：一个布尔值，用于确定是否应通过蜂窝网络进行连接。默认值为YES。此属性控制基于此会话配置的会话中的任务是否允许通过蜂窝网络进行连接。
@property BOOL allowsExpensiveNetworkAccess API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0));
属性描述：一个布尔值，指示连接是否可以使用系统认为昂贵的网络接口。系统根据网络接口的性质和其他因素来决定什么是“昂贵”。iOS 13认为大多数蜂窝网络和个人热点都很昂贵。如果没有可用的非昂贵网络接口，并且会话的allowsExpensiveNetworkAccess属性为NO，则从会话创建的任何任务都会失败。在这种情况下，当任务失败时提供的错误具有networkUnavailableReason属性，其值为NSURLErrorNetworkUnavailableReasonExpensive。
可以限制应用程序使用昂贵的网络访问用户发起的任务，并推迟可自由支配的任务，直到一个不昂贵的接口可用。为此，设置allowsExpensiveNetworkAccess (和 allowsConstrainedNetworkAccess) 为NO，waitsForConnectivity为YES。这样，NSURLSessionTask在发送或接收数据之前等待一个合适的接口变得可用。
要测试此属性的行为，您可以在设备中选择设置>开发人员>网络，覆盖设备的蜂窝和Wi-Fi成本的当前值。
建议你的应用程序的策略逻辑围绕allowsConstrainedNetworkAccess属性，而不是这个。使用应用程序的用户可以使用“低数据模式”设置来设置受限状态，从而选择使用可能是昂贵的网络。
@property BOOL allowsConstrainedNetworkAccess API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0));
属性描述：一个布尔值，指示当用户指定低数据模式时连接是否可以使用网络。在iOS 13及更高版本中，用户可以将他们的设备设置为使用低数据模式作为设置应用程序中的蜂窝数据选项之一。用户可以打开低数据模式来减少应用程序的网络数据使用量。当用户打开低数据模式时，此属性控制URL会话的行为。如果没有可用的非受限网络接口，并且会话的allowsConstrainedNetworkAccess属性为NO，则从会话创建的任何任务都会失败。在这种情况下，当任务失败时提供的错误具有networkUnavailableReason属性，其值为NSURLErrorNetworkUnavailableReasonConstrained。
限制应用程序使用受限网络访问用户发起的任务，并推迟可自由支配的任务，直到一个非受限接口可用。为此，设置allowsConstrainedNetworkAccess (和 allowsExpensiveNetworkAccess)为YES。这样，NSURLSessionTask在发送或接收数据之前等待一个合适的接口变得可用。
@property BOOL requiresDNSSECValidation API_AVAILABLE(macos(13.0), ios(16.0), watchos(9.0), tvos(16.0));
属性描述：要求在启用DNSSEC验证的情况下发出会话请求。默认为NO。
@property BOOL waitsForConnectivity API_AVAILABLE(macos(10.13), ios(11.0), watchos(4.0), tvos(11.0));
属性描述：一个布尔值，指示会话是否应该等待连接变得可用，还是立即失败。由于某些原因，连接可能暂时不可用。例如当allowsCellularAccess设置为false时，设备可能只有蜂窝连接，或者设备可能需要VPN连接，但没有可用的VPN连接。如果这个属性的值为true并且没有足够的连接，会话调用NSURLSessionTaskDelegate的URLSession:taskIsWaitingForConnectivity: 方法并等待连接。当连接性可用时，任务开始其工作，并最终像往常一样调用代理或完成处理程序。如果该属性的值为false且连接不可用，则连接将立即失败，并出现错误，例如NSURLErrorNotConnectedToInternet错误。
此属性仅在建立连接期间相关。如果连接建立后又断开，完成处理程序或委托会接收一个错误，例如NSURLErrorNetworkConnectionLost错误。
后台会话将忽略此属性，后台会话始终等待连接。
@property (getter=isDiscretionary) BOOL discretionary API_AVAILABLE(macos(10.10), ios(7.0), watchos(2.0), tvos(9.0));
属性描述：一个布尔值，它决定是否可以根据系统的判断来调度后台任务以获得最佳性能。对于使用backgroundSessionConfigurationWithIdentifier:方法创建的配置对象，使用此属性让系统控制何时应该发生传输。使用其他方法创建的配置对象将忽略此属性。
当传输大量数据时，建议将此属性的值设置为YES。这样做可以让系统在对设备更优的时间安排这些传输。例如，系统可能会延迟传输大文件，直到设备插入并通过Wi-Fi连接到网络。该属性的默认值为NO。
会话对象仅将此属性的值应用于应用程序在前台启动时的传输。对于在应用程序处于后台时启动的传输，系统总是根据自己的判断启动传输——换句话说，系统假设此属性为YES并忽略您指定的任何值。
@property (nullable, copy) NSString *sharedContainerIdentifier API_AVAILABLE(macos(10.10), ios(8.0), watchos(2.0), tvos(9.0));
属性描述：共享容器的标识符，后台URL会话中的文件应该下载到其中。创建一个URL会话供应用程序扩展使用，请将此属性设置为应用程序扩展及其包含应用程序之间共享的容器的有效标识符。如果尝试从应用程序扩展创建URL会话，但未能将此属性设置为有效值，则URL会话将在创建时无效。
@property BOOL sessionSendsLaunchEvents API_AVAILABLE(macos(11.0), ios(7.0), watchos(2.0), tvos(9.0));
属性描述：一个布尔值，指示传输完成时应用程序是否应在后台启动或唤醒。对于使用backgroundSessionConfigurationWithIdentifier:方法创建的配置对象，可以使用此属性来控制iOS应用程序的启动行为。对于使用其他方法创建的配置对象，此属性将被忽略。该属性的默认值为YES。当该属性值为YES时，当会话任务完成或需要身份验证时，系统会自动在后台唤醒或启动iOS应用程序。这时，系统调用应用程序代理的application:handleEventsForBackgroundURLSession:completionHandler: 方法，为它提供需要注意的会话标识符。如果应用程序必须重新启动，可以使用该标识符创建一个新的配置和会话对象，该对象能够为任务提供服务。
@property tls_protocol_version_t TLSMinimumSupportedProtocolVersion API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0));
属性描述：客户端在此会话中进行连接时应接受的最低TLS协议版本。
@property tls_protocol_version_t TLSMaximumSupportedProtocolVersion API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0));
属性描述：客户端在此会话中进行连接时应请求的最高TLS协议版本。
@property BOOL HTTPShouldUsePipelining;
属性描述：一个布尔值，用于确定会话是否应使用HTTP通道。此属性确定基于此配置的会话中的任务是否应使用HTTP通道。
@property BOOL HTTPShouldSetCookies;
属性描述：一个布尔值，用于确定请求是否应包含来自Cookie存储区的Cookie。此属性控制基于此配置的会话中的任务在发出请求时是否应自动提供来自共享Cookie存储区的Cookie。如果需要自己提供Cookie，将此值设置为NO，并通过会话的HTTPAdditionalHeaders属性或使用自定义NSURLRequest对象在每个请求级别上提供Cookie报头。此属性默认值为YES。
@property NSHTTPCookieAcceptPolicy HTTPCookieAcceptPolicy;
属性描述：一个策略常数，用于确定何时应该接受Cookie的策略。此属性控制基于此配置的会话中的所有任务的Cookie接受策略。默认值为NSHTTPCookieAcceptPolicyOnlyFromMainDocumentDomain。如果想更直接地控制哪些Cookie被接受，设置这个值为NSHTTPCookieAcceptPolicyNever，然后使用allHeaderFields属性和cookiesWithResponseHeaderFields:forURL: 方法自己从URL响应对象中提取Cookie。
@property (nullable, copy) NSDictionary *HTTPAdditionalHeaders;
属性描述：与请求一起发送的附加头的字典。此属性控制基于此配置的会话中的所有任务的附加头。例如可以设置User-Agent头，这样它就会自动包含在应用程序通过基于此配置的会话发出的每个请求中。
NSURLSession对象旨在为您处理HTTP协议的各个方面。因此，您不应修改以下标头：
- Authorization
- Connection
- Host
- Proxy-Authenticate
- Proxy-Authorization
- WWW-Authenticate
此外，如果可以自动确定上传正文数据的长度，例如如果为正文内容提供NSData对象，则会设置Content-Length的值。
如果在这个字典和请求对象(如果适用)中都出现了相同的头，则请求对象的值优先。默认值为空字典。
@property (nullable, retain) NSHTTPCookieStorage *HTTPCookieStorage;
属性描述：Cookie存储，用于存储此会话中的Cookie。此属性控制基于此配置的会话中的所有任务使用的Cookie存储对象。要禁用Cookie存储，请将此属性设置为nil。
对于默认会话和后台会话，默认值为sharedHTTPCookieStorage的cookie存储对象。对于临时会话，默认值是一个私有cookie存储对象，仅在内存中存储数据，并在会话无效时销毁。
@property (nullable, retain) NSURLCredentialStorage *URLCredentialStorage;
属性描述：为身份验证提供凭据的凭据存储。此属性控制基于此配置的会话中的所有任务使用的凭据存储对象。如果不想使用凭据存储，请将此属性设置为nil。
对于默认会话和后台会话，默认值是sharedCredentialStorage凭据存储对象。对于临时会话，默认值是一个私有凭据存储对象，仅在内存中存储数据，并且在使会话无效时销毁该值。
@property (nullable, retain) NSURLCache *URLCache;
属性描述：URL缓存，用于为会话中的请求提供缓存响应。此属性控制基于此配置的会话中的任务使用的URL缓存对象。要禁用缓存，请将此属性设置为nil。
对于默认会话，默认值为sharedURLCache对象。对于后台会话，默认值为nil。对于临时会话，默认值是仅在内存中存储数据的私有缓存对象，并且在使会话无效时销毁该值。
@property BOOL shouldUseExtendedBackgroundIdleMode API_AVAILABLE(macos(10.11), ios(9.0), watchos(2.0), tvos(9.0));
属性描述：一个布尔值，指示当应用程序移动到后台时，TCP连接是否应保持打开。除了请求连接保持打开之外，将这个值设置为YES会要求系统在应用程序移动到后台时延迟回收连接。
@property (nullable, copy) NSArray<Class> *protocolClasses;
属性描述：在会话中处理请求的一组额外的协议子类，默认值为空数组。。这个数组中的对象是Class对象，对应于你定义的自定义NSURLProtocol子类。URL会话对象默认支持许多常见的网络协议。此数组可包含自定义的一个或多个协议，用于扩展会话使用的通用网络协议的默认集。在处理请求之前，NSURLSession对象首先搜索默认协议，然后检查自定义协议，直到找到一个能够处理指定请求的协议。 它使用canInitWithRequest: 类方法返回值为YES的协议，表示该类能够处理指定的请求。不能将自定义NSURLProtocol子类与后台会话一起使用。
@property NSURLSessionMultipathServiceType multipathServiceType API_AVAILABLE(ios(11.0)) API_UNAVAILABLE(macos, watchos, tvos);
属性描述：一种服务类型，用于指定通过Wi-Fi和蜂窝接口传输数据的多路径TCP连接策略。多路径TCP，由RFC 6824中的IETF定义，是TCP的扩展，允许多个接口传输单个数据流。该功能允许从Wi-Fi到蜂窝网络的无缝切换，旨在提高两种界面的效率，并改善用户体验。
multipathServiceType属性定义了多路径TCP堆栈使用哪个策略来调度跨Wi-Fi和蜂窝接口的流量。默认值为none，即关闭多路径TCP。还可以选择切换模式，实现Wi-Fi和蜂窝网络的无缝切换。多路径TCP需要服务器支持。
+ (NSURLSessionConfiguration *)backgroundSessionConfigurationWithIdentifier:(NSString *)identifier API_AVAILABLE(macos(10.10), ios(8.0), watchos(2.0), tvos(9.0));
函数描述：创建允许在后台执行HTTP和HTTPS上传或下载的会话配置对象。当应用程序在后台运行时，使用此方法初始化一个适合传输数据文件的配置对象。配置了此对象的会话将传输的控制权移交给系统，系统在单独的进程中处理传输。在iOS中，这种配置使得即使应用本身被暂停或终止，传输也可以继续进行。
如果一个iOS应用程序被系统终止并重新启动，该应用程序可以使用相同的标识符创建一个新的配置对象和会话，并检索在终止时正在进行的传输状态。此行为仅适用于系统正常终止应用程序。如果用户在多任务屏幕上终止了应用程序，系统会取消所有会话的后台传输。此外，系统不会自动重新启动被用户强制退出的应用程序。用户必须显式地重新启动应用程序才能再次开始传输。
可以使用discretionary属性配置后台会话，当传输大量数据时，建议将此属性的值设置为YES。
参数 ：
identifier ：配置对象的唯一标识符。此参数不能为nil或空字符串。
返回值 ：一个配置对象，它使系统在单独的进程中执行上传和下载任务。
网友评论