Session Delegate Reference

Session Delegate Reference

NSURLSessionDelegate

@protocol NSURLSessionDelegate <NSObject>- (void)URLSession:(NSURLSession *)session didBecomeInvalidWithError:(nullable NSError *)error;- (void)URLSession:(NSURLSession *)session didReceiveChallenge:(NSURLAuthenticationChallenge *)challenge completionHandler:(void (^)(NSURLSessionAuthChallengeDisposition disposition, NSURLCredential * __nullable credential))completionHandler;- (void)URLSessionDidFinishEventsForBackgroundURLSession:(NSURLSession *)session;@end

NSURLSessionTaskDelegate

@protocol NSURLSessionTaskDelegate <NSURLSessionDelegate>- (void)URLSession:(NSURLSession *)session task:(NSURLSessionTask *)task willPerformHTTPRedirection:(NSHTTPURLResponse *)response newRequest:(NSURLRequest *)request completionHandler:(void (^)(NSURLRequest * __nullable))completionHandler;- (void)URLSession:(NSURLSession *)session task:(NSURLSessionTask *)task didReceiveChallenge:(NSURLAuthenticationChallenge *)challenge completionHandler:(void (^)(NSURLSessionAuthChallengeDisposition disposition, NSURLCredential * __nullable credential))completionHandler;- (void)URLSession:(NSURLSession *)session task:(NSURLSessionTask *)task needNewBodyStream:(void (^)(NSInputStream * __nullable bodyStream))completionHandler;- (void)URLSession:(NSURLSession *)session task:(NSURLSessionTask *)task didSendBodyData:(int64_t)bytesSent totalBytesSent:(int64_t)totalBytesSent totalBytesExpectedToSend:(int64_t)totalBytesExpectedToSend;- (void)URLSession:(NSURLSession *)session task:(NSURLSessionTask *)task didCompleteWithError:(nullable NSError *)error;@end

NSURLSessionDataDelegate

@protocol NSURLSessionDataDelegate <NSURLSessionTaskDelegate>@optional- (void)URLSession:(NSURLSession *)session dataTask:(NSURLSessionDataTask *)dataTask didReceiveResponse:(NSURLResponse *)response completionHandler:(void (^)(NSURLSessionResponseDisposition disposition))completionHandler;- (void)URLSession:(NSURLSession *)session dataTask:(NSURLSessionDataTask *)dataTask didBecomeDownloadTask:(NSURLSessionDownloadTask *)downloadTask;- (void)URLSession:(NSURLSession *)session dataTask:(NSURLSessionDataTask *)dataTask didBecomeStreamTask:(NSURLSessionStreamTask *)streamTask;- (void)URLSession:(NSURLSession *)session dataTask:(NSURLSessionDataTask *)dataTask didReceiveData:(NSData *)data;- (void)URLSession:(NSURLSession *)session dataTask:(NSURLSessionDataTask *)dataTask willCacheResponse:(NSCachedURLResponse *)proposedResponse completionHandler:(void (^)(NSCachedURLResponse * __nullable cachedResponse))completionHandler;@end

NSURLSessionDownloadDelegate

- (void)URLSession:(NSURLSession *)session downloadTask:(NSURLSessionDownloadTask *)downloadTask didFinishDownloadingToURL:(NSURL *)location;@optional- (void)URLSession:(NSURLSession *)session downloadTask:(NSURLSessionDownloadTask *)downloadTask didWriteData:(int64_t)bytesWritten totalBytesWritten:(int64_t)totalBytesWritten totalBytesExpectedToWrite:(int64_t)totalBytesExpectedToWrite;- (void)URLSession:(NSURLSession *)session downloadTask:(NSURLSessionDownloadTask *)downloadTask didResumeAtOffset:(int64_t)fileOffset expectedTotalBytes:(int64_t)expectedTotalBytes;@end

NSURLSessionStreamDelegate

@optional- (void)URLSession:(NSURLSession *)session readClosedForStreamTask:(NSURLSessionStreamTask *)streamTask;- (void)URLSession:(NSURLSession *)session writeClosedForStreamTask:(NSURLSessionStreamTask *)streamTask;- (void)URLSession:(NSURLSession *)session betterRouteDiscoveredForStreamTask:(NSURLSessionStreamTask *)streamTask;- (void)URLSession:(NSURLSession *)session streamTask:(NSURLSessionStreamTask *)streamTask didBecomeInputStream:(NSInputStream *)inputStream outputStream:(NSOutputStream *)outputStream;@end

• 当在 SSL 握手阶段，如果服务器要求验证客户端身份或向客户端提供其证书用于验证时，则会调用URLSession:didReceiveChallenge:completionHandler:或
  URLSession:task:didReceiveChallenge:completionHandler:方法。传入的参数除了对应的 session 和 task，还有NSURLAuthenticationChallenge对象，它封装了服务端对客户端的验证请求，根据它的 protectionSpace 属性的
  authenticationMethod，可以知道服务端要通过哪种方式验证客户端或是要求客户端验证服务端的证书。在代理方法中要执行传入的
  completionHandler Block，这个回调接收两个参数：
  NSURLSessionAuthChallengeDisposition类型的 disposition，描述了如何处理验证请求，NSURLCredential对象，当处理方式需要提供证书时，传入该参数。当 authenticationMethod 的值为：
  NSURLAuthenticationMethodNTLM、NSURLAuthenticationMethodNegotiate、
  NSURLAuthenticationMethodClientCertificate和
  NSURLAuthenticationMethodServerTrust时，系统会先尝试调用 session 级的处理方法，若 session 级未实现，则尝试调用 task 级的处理方法，而其他情况则是直接调用 task 级的处理方法，无论 session 级方法是否实现。
• 当使用- uploadTaskWithStreamedRequest:方法创建的 task 发起请求时，必须实现代理方法URLSession:task:needNewBodyStream:，以提供请求需要的 stream。因为从输入流读数据是不可逆的，所以在上传失败时，可能会重新调用该方法读取流。在方法中执行 block completionHandler 参数，向其传入
  NSInputStream对象。
• 当执行 upload task 时，系统会定期的调用
  URLSession:task:didSendBodyData:totalBytesSent:totalBytesExpectedToSend:方法，报告上传请求体的进度。
• 当响应为重定向到其他请求时，系统会调用代理方法
  URLSession:task:willPerformHTTPRedirection:newRequest:completionHandler:，在方法中要执行 block 参数 completionHandler，可向其传入重定向的新的NSURLRequest对象，那么会正常执行重定向请求，也可以传入 nil，则不执行重定向请求并以当前响应体作为重定向后的响应。
• 当执行以方法- downloadTaskWithResumeData:或
  - downloadTaskWithResumeData:completionHandler:创建的 download task 时，会调用代理方法
  URLSession:downloadTask:didResumeAtOffset:expectedTotalBytes:
• 当 data task 收到响应时，会调用代理方法
  URLSession:dataTask:didReceiveResponse:completionHandler:，在方法中要执行 block 参数 completionHandler，向其传入
  NSURLSessionResponseDisposition枚举类型参数，指明继续正常返回响应体，还是取消请求，或者将 task 转变为 download task。支持
  multipart/x-mixed-replace时，传入NSURLSessionResponseBecomeDownload，将 task 转换为 download task 后，会调用代理方法
  URLSession:dataTask:didBecomeDownloadTask:
• 当从服务端接收数据时，系统会调用相应的代理方法，定期提供已接收到的数据，对于 data task，会调用方法URLSession:dataTask:didReceiveData:，而 download task 则会调用方法
  URLSession:downloadTask:didWriteData:totalBytesWritten:totalBytesExpectedToWrite:
• 对于 data task 或 upload task，在收到所有数据后，可能会调用方法
  URLSession:dataTask:willCacheResponse:completionHandler:，提供给应用决定是否缓存响应的机会。方法中要执行 block 参数 completionHandler，如果缓存则传入一个NSCachedURLResponse对象，若不想缓存可传入 nil。当返回的响应为缓存中的时候，则不调用该方法。
• 当 task 执行完成后，会调用代理方法
  URLSession:task:didCompleteWithError:，如果 task 失败，error 参数为包含具体信息的NSError对象，若成功，error 则为 nil。对于 HTTP 协议来说，服务器返回的响应 code 为失败时，不属于 task 执行失败的情况，以 task 的角度看，这个请求 task 是成功执行的，data 中会包含返回的内容。当 download task 失败时，在 error 对象的 userInfo 中可以根据 key
  NSURLSessionDownloadTaskResumeData获得已下载的数据，之后可用于创建从断点处继续下载的 task。当 download task 成功执行完成后，还会执行代理方法URLSession:downloadTask:didFinishDownloadingToURL:，这个方法是
  NSURLSessionDownloadDelegate协议中必须实现的，方法参数传入一个下载文件的临时保存路径，应用需要读取文件的内容或将文件移到其他地方，因为代理方法执行结束后，该路径下的文件会被删除，注意，如果读取文件内容的话，则要在单独的线程中进行，否则可能会造成页面卡死，影响用户体验。
• 当对 session 对象执行了 invalidate 的相关方法后，会调用代理方法
  URLSession:didBecomeInvalidWithError:。之后 session 会释放对代理对象的强引用。

拷贝策略

当拷贝一个 session 对象或 task 对象时，并不会创建新的实例，而是返回该对象本身。

后台 session

当挂起的应用执行的后台传输(下载、上传)完成或者发生错误以及需要身份验证时，系统会运行应用并调用应用代理的
- application:handleEventsForBackgroundURLSession:completionHandler:方法。如果传输完成可以执行一些更新界面的操作，如果没有成功，则可以根据 identifier 参数重新创建 background session 继续执行。在该方法中应使用实例变量强引用 block 参数 completionHandler，在上述相关操作(如重新关联 session)完成后，系统会调用 session 的代理方法
URLSessionDidFinishEventsForBackgroundURLSession:，此时在该代理方法中运行之前应用代理维持的 block，以通知系统应用已完成处理工作，要注意的是，该 completionHandler 要在主线程中执行。