SDWebImage探究（十三） —— 深入研究图片下载流程（七）之NSURLSession中几个代理的基本用法和关系

版本记录

版本号	时间
V1.0	2018.02.24

前言

我们做APP，文字和图片是绝对不可缺少的元素，特别是图片一般存储在图床里面，一般公司可以委托第三方保存，NB的公司也可以自己存储图片，ios有很多图片加载的第三方框架，其中最优秀的莫过于SDWebImage，它几乎可以满足你所有的需求，用了好几年这个框架，今天想总结一下。感兴趣的可以看其他几篇。
1. SDWebImage探究（一）
2. SDWebImage探究（二）
3. SDWebImage探究（三）
4. SDWebImage探究（四）
5. SDWebImage探究（五）
6. SDWebImage探究（六） —— 图片类型判断深入研究
 7. SDWebImage探究（七） —— 深入研究图片下载流程（一）之有关option的位移枚举的说明
 8. SDWebImage探究（八） —— 深入研究图片下载流程（二）之开始下载并返回下载结果的总的方法
 9. SDWebImage探究（九） —— 深入研究图片下载流程（三）之下载之前的缓存查询操作
 10. SDWebImage探究（十） —— 深入研究图片下载流程（四）之查询缓存后的block回调处理
 11. SDWebImage探究（十一） —— 深入研究图片下载流程（五）之SDWebImageDownloadToken和操作对象的生成和返回
 12. SDWebImage探究（十二） —— 深入研究图片下载流程（六）之下载器到具体下载操作的代理分发实现

NSURLSession中的几种代理

这些代理方法都在NSURLSession中，我们先简单的看一下该类的功能。

通过URL将数据下载到内存
通过URL将数据下载到文件系统
将数据上传到指定URL
在后台完成上述功能

NSURLSession是下载的上下文，其中包含了很多下载相关的代理分发，包括NSURLSessionDelegate、NSURLSessionTaskDelegate <NSURLSessionDelegate>、NSURLSessionDataDelegate <NSURLSessionTaskDelegate>、NSURLSessionDownloadDelegate <NSURLSessionTaskDelegate>、NSURLSessionStreamDelegate <NSURLSessionTaskDelegate>，它们之间的关系看继承就已经很清楚了。

它们之间的关系可以参考下图：

NSURLSessionDelegate

先看一下API文档

/*
 * Messages related to the URL session as a whole
   与整个URL session相关的消息
 */
@protocol NSURLSessionDelegate <NSObject>
@optional

/* The last message a session receives.  A session will only become
 * invalid because of a systemic error or when it has been
 * explicitly invalidated, in which case the error parameter will be nil.
 */
  会话收到的最后一条消息。 一个会话只会因为系统错误或者当它明确地失效而失效，
  在这种情况下，错误参数将为nil。
- (void)URLSession:(NSURLSession *)session didBecomeInvalidWithError:(nullable NSError *)error;

/* If implemented, when a connection level authentication challenge
 * has occurred, this delegate will be given the opportunity to
 * provide authentication credentials to the underlying
 * connection. Some types of authentication will apply to more than
 * one request on a given connection to a server (SSL Server Trust
 * challenges).  If this delegate message is not implemented, the 
 * behavior will be to use the default handling, which may involve user
 * interaction. 
 */
  如果已实现，则在发生连接级别身份验证质询时，此代理将有机会向底层连接提供身份验证凭据。 
  某些类型的身份验证将适用于给定服务器连接上的多个请求（SSL服务器信任SSL Server Trust挑战）。 
  如果此代理消息未实现，则行为将使用默认处理，这可能涉及用户交互。
- (void)URLSession:(NSURLSession *)session didReceiveChallenge:(NSURLAuthenticationChallenge *)challenge
                                             completionHandler:(void (^)(NSURLSessionAuthChallengeDisposition disposition, NSURLCredential * _Nullable credential))completionHandler;

/* If an application has received an
 * -application:handleEventsForBackgroundURLSession:completionHandler:
 * message, the session delegate will receive this message to indicate
 * that all messages previously enqueued for this session have been
 * delivered.  At this time it is safe to invoke the previously stored
 * completion handler, or to begin any internal updates that will
 * result in invoking the completion handler.
 */
  如果应用程序收到了-application：handleEventsForBackgroundURLSession：completionHandler：
  消息，则会话代理将收到此消息，指示之前已为此会话入队的所有消息已传递。 此时，调用先前存储的
  完成处理程序或开始任何内部更新将导致调用完成处理程序，这一过程是安全的。
- (void)URLSessionDidFinishEventsForBackgroundURLSession:(NSURLSession *)session API_AVAILABLE(ios(7.0), watchos(2.0), tvos(9.0)) API_UNAVAILABLE(macos);

@end

NSURLSessionTaskDelegate

下面看一下API

/*
 * Messages related to the operation of a specific task.
   与特定任务的操作有关的消息
 */
@protocol NSURLSessionTaskDelegate <NSURLSessionDelegate>
@optional

/*
 * Sent when the system is ready to begin work for a task with a delayed start
 * time set (using the earliestBeginDate property). The completionHandler must
 * be invoked in order for loading to proceed. The disposition provided to the
 * completion handler continues the load with the original request provided to
 * the task, replaces the request with the specified task, or cancels the task.
 * If this delegate is not implemented, loading will proceed with the original
 * request.
 *
 * Recommendation: only implement this delegate if tasks that have the
 * earliestBeginDate property set may become stale and require alteration prior
 * to starting the network load.
 *
 * If a new request is specified, the allowsCellularAccess property from the
 * new request will not be used; the allowsCellularAccess property from the
 * original request will continue to be used.
 *
 * Canceling the task is equivalent to calling the task's cancel method; the
 * URLSession:task:didCompleteWithError: task delegate will be called with error
 * NSURLErrorCancelled.
 */
当系统准备好开始工作时设置延迟的开始时间（使用earliestBeginDate属性）时发送。必须调用
completionHandler才能继续加载。提供给完成处理程序的处置将继续使用提供给该任务的原始请求的
负载，用指定的任务替换该请求或取消该任务。如果这个委托没有实现，加载将继续处理原始请求。

建议：如果具有设置earliestBeginDate属性的任务可能会过时并且需要在开始网络加载
之前进行更改，那么仅实现此代理。

如果指定了新请求，则不会使用来自新请求的allowsCellularAccess
属性；来自原始请求的allowsCellularAccess属性将继续使用。

取消任务等同于调用任务的cancel方法； URLSession：task：didCompleteWithError：任务代理将被调用，error为NSURLErrorCancelled。
- (void)URLSession:(NSURLSession *)session task:(NSURLSessionTask *)task
                        willBeginDelayedRequest:(NSURLRequest *)request
                              completionHandler:(void (^)(NSURLSessionDelayedRequestDisposition disposition, NSURLRequest * _Nullable newRequest))completionHandler
    API_AVAILABLE(macos(10.13), ios(11.0), watchos(4.0), tvos(11.0));

/*
 * Sent when a task cannot start the network loading process because the current
 * network connectivity is not available or sufficient for the task's request.
 *
 * This delegate will be called at most one time per task, and is only called if
 * the waitsForConnectivity property in the NSURLSessionConfiguration has been
 * set to YES.
 *
 * This delegate callback will never be called for background sessions, because
 * the waitForConnectivity property is ignored by those sessions.
 */
当任务无法启动网络加载过程时发送，因为当前网络连接不可用或不足以满足任务请求。

每个任务最多只能调用一次该委托，并且只有在NSURLSessionConfiguration中
的waitsForConnectivity属性设置为YES时才会调用该代理。

此代理回调将永远不会被后台会话调用，因为这些会话会忽略waitForConnectivity属性。
- (void)URLSession:(NSURLSession *)session taskIsWaitingForConnectivity:(NSURLSessionTask *)task
    API_AVAILABLE(macos(10.13), ios(11.0), watchos(4.0), tvos(11.0));

/* An HTTP request is attempting to perform a redirection to a different
 * URL. You must invoke the completion routine to allow the
 * redirection, allow the redirection with a modified request, or
 * pass nil to the completionHandler to cause the body of the redirection 
 * response to be delivered as the payload of this request. The default
 * is to follow redirections. 
 *
 * For tasks in background sessions, redirections will always be followed and this method will not be called.
 */
一个HTTP请求正试图执行重定向到一个不同的URL。 您必须调用完成例程以允许重定向，允许使用修改后
的请求进行重定向，或将nil传递给completionHandler以使重定向响应的主体作为此请求的有效内容传递。 
默认是遵循重定向。

对于后台会话中的任务，将始终遵循重定向，并且不会调用此方法。
- (void)URLSession:(NSURLSession *)session task:(NSURLSessionTask *)task
                     willPerformHTTPRedirection:(NSHTTPURLResponse *)response
                                     newRequest:(NSURLRequest *)request
                              completionHandler:(void (^)(NSURLRequest * _Nullable))completionHandler;

/* The task has received a request specific authentication challenge.
 * If this delegate is not implemented, the session specific authentication challenge
 * will *NOT* be called and the behavior will be the same as using the default handling
 * disposition. 
 */
该任务已收到请求特定的身份验证质询。 如果这个代理没有被实现，会话特定的认证挑战不会被调用，
并且行为将与使用默认处理处置相同。
- (void)URLSession:(NSURLSession *)session task:(NSURLSessionTask *)task
                            didReceiveChallenge:(NSURLAuthenticationChallenge *)challenge 
                              completionHandler:(void (^)(NSURLSessionAuthChallengeDisposition disposition, NSURLCredential * _Nullable credential))completionHandler;

/* Sent if a task requires a new, unopened body stream.  This may be
 * necessary when authentication has failed for any request that
 * involves a body stream. 
 */
如果任务需要新的未打开的正文流，则发送。 
当涉及正文流的任何请求的身份验证失败时，这可能是必需的。
- (void)URLSession:(NSURLSession *)session task:(NSURLSessionTask *)task
                              needNewBodyStream:(void (^)(NSInputStream * _Nullable bodyStream))completionHandler;

/* Sent periodically to notify the delegate of upload progress.  This
 * information is also available as properties of the task.
 */
定期发送以通知代理上传进度。 该信息也可作为任务的属性。
- (void)URLSession:(NSURLSession *)session task:(NSURLSessionTask *)task
                                didSendBodyData:(int64_t)bytesSent
                                 totalBytesSent:(int64_t)totalBytesSent
                       totalBytesExpectedToSend:(int64_t)totalBytesExpectedToSend;

/*
 * Sent when complete statistics information has been collected for the task.
 */
当完成任务的完整统计信息时发送。
- (void)URLSession:(NSURLSession *)session task:(NSURLSessionTask *)task didFinishCollectingMetrics:(NSURLSessionTaskMetrics *)metrics API_AVAILABLE(macosx(10.12), ios(10.0), watchos(3.0), tvos(10.0));

/* Sent as the last message related to a specific task.  Error may be
 * nil, which implies that no error occurred and this task is complete. 
 */
作为与特定任务相关的最后一条消息发送。 错误可能为nil，
这意味着没有发生错误，并且此任务已完成。
- (void)URLSession:(NSURLSession *)session task:(NSURLSessionTask *)task
                           didCompleteWithError:(nullable NSError *)error;

@end

NSURLSessionDataDelegate

下面看一下API文档

/*
 * Messages related to the operation of a task that delivers data
 * directly to the delegate.
与将数据直接传递给代理的任务的操作有关的消息
 */
@protocol NSURLSessionDataDelegate <NSURLSessionTaskDelegate>
@optional
/* The task has received a response and no further messages will be
 * received until the completion block is called. The disposition
 * allows you to cancel a request or to turn a data task into a
 * download task. This delegate message is optional - if you do not
 * implement it, you can get the response as a property of the task.
 *
 * This method will not be called for background upload tasks (which cannot be converted to download tasks).
 */
该任务已收到响应，直到完成块被调用不会收到更多消息。 该配置允许您取消请求或将数据任务转换
为下载任务。 此代理消息是可选的 - 如果您没有实现它，则可以将响应作为任务的属性获取。

此方法不会被后台上传任务（不能转换为下载任务）调用。
- (void)URLSession:(NSURLSession *)session dataTask:(NSURLSessionDataTask *)dataTask
                                 didReceiveResponse:(NSURLResponse *)response
                                  completionHandler:(void (^)(NSURLSessionResponseDisposition disposition))completionHandler;

/* Notification that a data task has become a download task.  No
 * future messages will be sent to the data task.
 */
通知数据任务已成为下载任务。 没有更多的消息将被发送到数据任务。
- (void)URLSession:(NSURLSession *)session dataTask:(NSURLSessionDataTask *)dataTask
                              didBecomeDownloadTask:(NSURLSessionDownloadTask *)downloadTask;

/*
 * Notification that a data task has become a bidirectional stream
 * task.  No future messages will be sent to the data task.  The newly
 * created streamTask will carry the original request and response as
 * properties.
 *
 * For requests that were pipelined, the stream object will only allow
 * reading, and the object will immediately issue a
 * -URLSession:writeClosedForStream:.  Pipelining can be disabled for
 * all requests in a session, or by the NSURLRequest
 * HTTPShouldUsePipelining property.
 *
 * The underlying connection is no longer considered part of the HTTP
 * connection cache and won't count against the total number of
 * connections per host.
 */
通知数据任务已成为双向流任务。 没有更多的消息将被发送到数据任务。 新创建的streamTask将作为属性携带原始请求和响应。

对于流水线的请求，流对象只允许读取，而对象将立即发出-URLSession：writeClosedForStream :。
对于会话中的所有请求，或者NSURLRequest 的HTTPShouldUsePipelining属性，都可以禁用管道传输。

底层连接不再被认为是HTTP连接缓存的一部分，并且不会计入每个主机的连接总数。
- (void)URLSession:(NSURLSession *)session dataTask:(NSURLSessionDataTask *)dataTask
                                didBecomeStreamTask:(NSURLSessionStreamTask *)streamTask;

/* Sent when data is available for the delegate to consume.  It is
 * assumed that the delegate will retain and not copy the data.  As
 * the data may be discontiguous, you should use 
 * [NSData enumerateByteRangesUsingBlock:] to access it.
 */
数据可供代理使用时发送。 假定代理将保留并不复制数据。 由于数据可能不连续，因此应该
使用[NSData enumerateByteRangesUsingBlock：]来访问它。
- (void)URLSession:(NSURLSession *)session dataTask:(NSURLSessionDataTask *)dataTask
                                     didReceiveData:(NSData *)data;

/* Invoke the completion routine with a valid NSCachedURLResponse to
 * allow the resulting data to be cached, or pass nil to prevent
 * caching. Note that there is no guarantee that caching will be
 * attempted for a given resource, and you should not rely on this
 * message to receive the resource data.
 */
用有效的NSCachedURLResponse调用完成例程以允许缓存结果数据，或通过nil来防止缓存。 
请注意，不能保证将为给定资源尝试缓存，并且不应该依赖此消息来接收资源数据。
- (void)URLSession:(NSURLSession *)session dataTask:(NSURLSessionDataTask *)dataTask
                                  willCacheResponse:(NSCachedURLResponse *)proposedResponse 
                                  completionHandler:(void (^)(NSCachedURLResponse * _Nullable cachedResponse))completionHandler;

@end

NSURLSessionDownloadDelegate

下面看一下API

/*
 * Messages related to the operation of a task that writes data to a
 * file and notifies the delegate upon completion.
  与将数据写入文件并在完成时通知代理的任务的操作有关的消息
 */
@protocol NSURLSessionDownloadDelegate <NSURLSessionTaskDelegate>

/* Sent when a download task that has completed a download.  The delegate should 
 * copy or move the file at the given location to a new location as it will be 
 * removed when the delegate message returns. URLSession:task:didCompleteWithError: will
 * still be called.
 */
当完成下载的下载任务时发送。 代理应该将指定位置的文件复制或移动到新位置，因为代理消息返回
时将被删除。 URLSession：task：didCompleteWithError：仍然会被调用。
- (void)URLSession:(NSURLSession *)session downloadTask:(NSURLSessionDownloadTask *)downloadTask
                              didFinishDownloadingToURL:(NSURL *)location;

@optional
/* Sent periodically to notify the delegate of download progress. */
定期发送以通知代理下载进度
- (void)URLSession:(NSURLSession *)session downloadTask:(NSURLSessionDownloadTask *)downloadTask
                                           didWriteData:(int64_t)bytesWritten
                                      totalBytesWritten:(int64_t)totalBytesWritten
                              totalBytesExpectedToWrite:(int64_t)totalBytesExpectedToWrite;

/* Sent when a download has been resumed. If a download failed with an
 * error, the -userInfo dictionary of the error will contain an
 * NSURLSessionDownloadTaskResumeData key, whose value is the resume
 * data. 
 */
下载已恢复时发送。 如果下载失败并显示错误，则error的-userInfo字典将包含NSURLSessionDownloadTaskResumeData键，其值为恢复的数据。
- (void)URLSession:(NSURLSession *)session downloadTask:(NSURLSessionDownloadTask *)downloadTask
                                      didResumeAtOffset:(int64_t)fileOffset
                                     expectedTotalBytes:(int64_t)expectedTotalBytes;

@end

NSURLSessionStreamDelegate