基本用法

初始化

// 在 AppDelegate.swift 文件里
// 最好成为AppDelegate的属性
// 注意:不能使用懒加载
var sessionManager: SessionManager = {
 var configuration = SessionConfiguration()
 configuration.allowsCellularAccess = true
 let manager = SessionManager("default", configuration: configuration)
 return manager
}()
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
 // 如果需要做一些配置,那么必须保证在这个方法结束前完成SessionManager初始化
 
 return true
}
// 必须实现此方法,并且把identifier对应的completionHandler保存起来
func application(_ application: UIApplication, handleEventsForBackgroundURLSession identifier: String, completionHandler: @escaping () -> Void) {
 if sessionManager.identifier == identifier {
 sessionManager.completionHandler = completionHandler
 }
}

开启下载

// 创建下载任务并且开启下载,同时返回可选类型的DownloadTask实例,如果url无效,则返回nil
let task = sessionManager.download("http://dldir1.qq.com/qqfile/QQforMac/QQ_V4.2.4.dmg")
// 批量创建下载任务并且开启下载,返回有效url对应的任务数组,url需要跟fileNames一一对应
let tasks = sessionManager.multiDownload(URLStrings)

public protocol URLConvertible {
 func asURL() throws -> URL
}

状态回调

任务的状态回调

let task = sessionManager.download("http://dldir1.qq.com/qqfile/QQforMac/QQ_V4.2.4.dmg")
// 回调闭包的参数是DownloadTask实例,可以得到所有相关的信息
// 所有闭包都可以选择是否在主线程上执行,由参数onMainQueue控制,如果onMainQueue传false,则会在sessionManager初始化时指定的队列上执行,onMainQueue默认为true
// progress 闭包:如果任务正在下载,就会触发
// success 闭包:任务已经下载过,或者下载成功,都会触发,这时候task.status == .succeeded
// failure 闭包:只要task.status != .succeeded,就会触发:
// 1. 暂停任务,这时候task.status == .suspended
// 2. 任务下载失败,这时候task.status == .failed
// 3. 取消任务,这时候task.status == .canceled
// 4. 移除任务,这时候task.status == .removed
task?.progress(onMainQueue: true) { (task) in
 let progress = task.progress.fractionCompleted
 print("下载中, 进度:\(progress)")
}.success { (task) in
 print("下载完成")
}.failure { (task) in
 print("下载失败")
}
// 为了让代码更加统一,新增了completion闭包,与success和failure互斥,当使用completion时,success和failure无效
task?.progress(onMainQueue: true) { (task) in
 let progress = task.progress.fractionCompleted
 print("下载中, 进度:\(progress)")
}.completion { (task) in 
 if task.status == .succeeded {
 	// 下载成功
 } else {
 	// 其他状态
 }
}

SessionManager的状态回调

sessionManager.progress { [weak self] (manager) in
	// 下载中
}.completion { [weak self] (manager) in
 if manager.status == .succeeded {
 // 下载成功
 } else {
 // 其他状态
 }
}

通知

public extension DownloadTask {
 static let runningNotification: Notification.Name
 static let didCompleteNotification: Notification.Name
}
public extension SessionManager {
 static let runningNotification: Notification.Name
 static let didCompleteNotification: Notification.Name
}
extension Notification {
 public var downloadTask: DownloadTask? 
 public var sessionManager: SessionManager? 
}

// 接受task的通知
NotificationCenter.default.addObserver(forName: DownloadTask.didCompleteNotification, object: nil, queue: nil) { (notification) in
 guard let task = notification.downloadTask else { return }
 print(task.status)
}

操作任务

单个任务

let URLString = "http://dldir1.qq.com/qqfile/QQforMac/QQ_V4.2.4.dmg"
// 开始下载
// 如果调用suspend暂停了下载,可以调用这个方法继续下载
sessionManager.start(URLString)
// 暂停下载
sessionManager.suspend(URLString)
// 取消下载,没有下载成功的任务会被移除,不保留缓存,已经下载完成的不受影响
sessionManager.cancel(URLString)
// 移除下载,任何状态的任务都会被移除,没有下载完成的缓存文件会被删除,可以选择是否保留已经下载完成的文件
sessionManager.remove(URLString, completely: false)

let URLString = "http://dldir1.qq.com/qqfile/QQforMac/QQ_V4.2.4.dmg"
let task = sessionManager.fetchTask(URLString)
sessionManager.start(task)
sessionManager.suspend(task)
sessionManager.cancel(task)
sessionManager.remove(task, completely: false)

批量操作

sessionManager.multiDownload(URLStrings)
sessionManager.totalStart()
sessionManager.totalSuspend()
sessionManager.totalCancel()
sessionManager.totalRemove(completely: false)

操作回调

// 暂停下载
sessionManager.cancel(task, onMainQueue: true) { [weak self] (task) in
 self?.tableView.reloadData()
}
// 批量操作的回调
sessionManager.totalCancel() { [weak self] _ in
 self?.tableView.reloadData()
}

后台下载

文件校验

let task = sessionManager.download("http://dldir1.qq.com/qqfile/QQforMac/QQ_V4.2.4.dmg")
// 回调闭包可以选择是否在主线程上执行
task?.validateFile(code: "9e2a3650530b563da297c9246acaad5c",
 type: .md5,
 onMainQueue: true)
 { (task) in
 if task.validation == .correct {
 // 文件正确
 } else {
 // 文件错误
 }
}

/// 对文件进行校验,是在子线程进行的
///
/// - Parameters:
/// - filePath: 文件路径
/// - verificationCode: 文件的Hash值
/// - verificationType: Hash类型
/// - completion: 完成回调, 在子线程运行
public static func validateFile(_ filePath: String,
 code: String,
 type: FileVerificationType,
 completion: @escaping (Result<Bool, FileVerificationError>) -> ()) {

日志

public enum LogOption {
 case `default`
 case none
}
public enum LogType {
 case sessionManager(_ message: String, manager: SessionManager)
 case downloadTask(_ message: String, task: DownloadTask)
 case error(_ message: String, error: Error)
}
public protocol Logable {
 var identifier: String { get }
 
 var option: LogOption { get set }
 
 func log(_ type: LogType)
}

错误处理

进阶用法

SessionManager

/// SessionManager的初始化方法
/// - Parameters:
/// - identifier: 设置SessionManager实例的标识,用于区分不同的下载模块,同时也是URLSession实例的标识,原生级别的后台下载必须要有唯一标识
/// - configuration: SessionManager的配置
/// - logger: 用于该SessionManager实例里所有的日志打印
/// - cache: 用于下载任务的持久化
/// - operationQueue: URLSession的代理执行队列,SessionManager中的所有闭包回调如果没有指定在主线程执行,也会在此队列中执行
public init(_ identifier: String,
 configuration: SessionConfiguration,
 logger: Logable? = nil,
 cache: Cache? = nil,
 operationQueue: DispatchQueue = DispatchQueue(label: "com.Tiercel.SessionManager.operationQueue")) {
 // 实现的代码... 
} 

// 回调闭包的参数是SessionManager实例,可以得到所有相关的信息
// 所有闭包都可以选择是否在主线程上执行,由onMainQueue参数控制,如果onMainQueue传false,则会在sessionManager初始化时指定的队列上执行,onMainQueue默认为true
// progress 闭包:只要有一个任务正在下载,就会触发
// success 闭包:只有一种情况会触发:
// 所有任务都下载成功(取消和移除的任务会被移除然后销毁,不再被manager管理) ,这时候manager.status == .succeeded
// failure 闭包:只要manager.status != .succeeded,就会触发:
// 1. 调用全部暂停的方法,或者没有等待运行的任务,也没有正在运行的任务,这时候manager.status == .suspended
// 2. 所有任务都结束,但有一个或者多个是失败的,这时候manager.status == .failed
// 3. 调用全部取消的方法,或者剩下一个任务的时候把这个任务取消,这时候manager.status == .canceled
// 4. 调用全部移除的方法,或者剩下一个任务的时候把这个任务移除,这时候manager.status == .removed
sessionManager.progress(onMainQueue: true) { (manager) in
 let progress = manager.progress.fractionCompleted
 print("downloadManager运行中, 总进度:\(progress)")
 }.success { (manager) in
 print("所有下载任务都成功了")
 }.failure { (manager) in
 if manager.status == .suspended {
 print("所有下载任务都暂停了")
 } else if manager.status == .failed {
 print("存在下载失败的任务")
 } else if manager.status == .canceled {
 print("所有下载任务都取消了")
 } else if manager.status == .removed {
 print("所有下载任务都移除了")
 }
}

// 用于日志打印
public var logger: Logable
// 是否需要对networkActivityIndicator进行管理
public var isControlNetworkActivityIndicator: Bool
// urlSession的代理回调执行队列,SessionManager中的所有闭包回调如果没有指定在主线程执行,也会在此队列中执行
public let operationQueue: DispatchQueue
// SessionManager的状态
public var status: Status
// SessionManager的缓存管理实例
public let cache: Cache
// SessionManager的标识,区分不同的下载模块
public let identifier: String
// SessionManager的进度
public var progress: Progress
// SessionManager的配置,可以设置请求超时时间,最大并发数,是否允许蜂窝网络下载等
public var configuration: SessionConfiguration
// 所有下载中的任务加起来的总速度
public var speed: Int64
public var speedString: String
// 所有下载中的任务需要的剩余时间
public var timeRemaining
public var timeRemainingString: String
// SessionManager管理的下载任务,取消和移除的任务会被销毁,但操作是异步的,在回调闭包里面获取才能保证正确
public var tasks: [Task]

// 改变单个任务的位置
public func moveTask(at sourceIndex: Int, to destinationIndex: Int) {
 // ...
}
// 对所有任务进行排序
public func tasksSort(by areInIncreasingOrder: (DownloadTask, DownloadTask) throws -> Bool) rethrows {
 // ...
}

SessionConfiguration

// 请求超时时间
public var timeoutIntervalForRequest
// 最大并发数
// 支持后台下载的任务,系统会进行最大并发数限制
// 在iOS 11及以上是6,iOS 11以下是3
public var maxConcurrentTasksLimit
// 是否允许蜂窝网络下载
public var allowsCellularAccess = false
// 昂贵网络访问限制,只能在iOS 13及以上系统使用
public var allowsExpensiveNetworkAccess: Bool = true
// 低数据网络访问限制,只能在iOS 13及以上系统使用
public var allowsConstrainedNetworkAccess: Bool = true

// 无论是否有下载任务正在运行,都可以更改SessionManager配置
// 如果只是更改某一项,可以直接对SessionManager属性设置
sessionManager.configuration.allowsCellularAccess = true
// 如果是需要更改多项,需要重新创建SessionConfiguration,再进行赋值
let configuration = SessionConfiguration()
configuration.allowsCellularAccess = true
configuration.maxConcurrentTasksLimit = 2
configuration.timeoutIntervalForRequest = 60
sessionManager.configuration = configuration

// 不要这样操作
sessionManager.configuration.allowsCellularAccess = true
let task = sessionManager.download("http://dldir1.qq.com/qqfile/QQforMac/QQ_V4.2.4.dmg")

// 如果实在需要,请延迟开启任务
sessionManager.configuration.allowsCellularAccess = true
DispatchQueue.main.asyncAfter(deadline: .now() + 1) {
 let task = sessionManager.download("http://dldir1.qq.com/qqfile/QQforMac/QQ_V4.2.4.dmg")
}

DownloadTask

// 保存到沙盒的下载文件的文件名,如果在下载的时候没有设置,则默认为url的md5加上文件扩展名
public var fileName: String
// 下载任务对应的url
public let url: URL
// 下载任务的状态
public var status: Status
// 下载文件的校验状态
public var validation: Validation
// 下载任务的进度
public var progress: Progress = Progress()
// 下载任务的开始日期
public var startDate: TimeInterval
public var startDateString: String	
// 下载任务的结束日期
public var endDate: TimeInterval
public var endDateString: String
// 下载任务的速度
public var speed: Int64
public var speedString: String
// 下载任务的剩余时间
public var timeRemaining: Int64 = 0
public var timeRemainingString: String
// 下载文件路径
public var filePath: String
// 下载文件的扩展名
public var pathExtension: String?
// 下载任务失败的error
public var error: Error?

Cache

/// 初始化方法
/// - Parameters:
/// - identifier: 不同的identifier代表不同的下载模块。如果没有自定义下载目录,Cache会提供默认的目录,这些目录跟identifier相关
/// - downloadPath: 存放用于DownloadTask持久化的数据,默认提供的downloadTmpPath、downloadFilePath也是在里面
/// - downloadTmpPath: 存放下载中的临时文件
/// - downloadFilePath: 存放下载完成后的文件
public init(_ identifier: String,
 downloadPath: String? = nil,
 downloadTmpPath: String? = nil,
 downloadFilePath: String? = nil) {
 	// ... 
}

// 下载模块的目录路径
public let downloadPath: String
// 没有完成的下载文件缓存的目录路径
public let downloadTmpPath: String
// 下载完成的文件的目录路径
public let downloadFilePath: String

// 传入文件名来返回String、URL,或者判断文件是否存在
public func filePath(fileName: String) -> String?
public func fileURL(fileName: String) -> URL? 
public func fileExists(fileName: String) -> Bool 
// 传入url来返回String、URL,或者判断文件是否存在
public func filePath(url: URLConvertible) -> String? 
public func fileURL(url: URLConvertible) -> URL? 
public func fileExists(url: URLConvertible) -> Bool 
// 清除磁盘缓存
public func clearDiskCache(onMainQueue: Bool = true, handler: Handler<Cache>? = nil)