-
Notifications
You must be signed in to change notification settings - Fork 29
Usage
配置类, 负责配置下载中所需要的参数, 最好在应用启动后立即配置.
配置 FKDownloader 的工作目录, 下载中途生成的文件都将在此目录中放置, 默认为 Library/Caches/com.fk.downloader.work/ 文件夹. 下载中途修改将产生不可预料的后果, 请在下载前进行配置
[FKConfigure configure].workPath = @"Custom Path";
配置最大下载数量, 默认 3, 设定范围 1 ~ 6
[FKConfigure configure].maxAction = 3;
配置信息分发速率, 默认 5 倍, 最小 1 倍, 最大 10 倍, 1 倍为 0.2 秒
[FKConfigure configure].distributeSpeed = 5;
配置 NSURLSessionConfiguration, 包含 Background Session 和 Foreground Session. 鉴于系统类中包含了新的特性, 所以配置相关都在一个模版上进行配置, FKDownloader 会以此模版进行配置 Session, 其中 allowsCellularAccess 为默认开启
[FKConfigure configure].templateBackgroundConfiguration.allowsCellularAccess = NO;
[FKConfigure configure].templateForegroundConfiguration.allowsCellularAccess = NO;
配置后台下载的系统回调, 此方法在 -[AppDelegate application:handleEventsForBackgroundURLSession:completionHandler] 中使用
- (void)application:(UIApplication *)application handleEventsForBackgroundURLSession:(NSString *)identifier completionHandler:(void (^)(void))completionHandler {
if ([identifier isEqualToString:[FKConfigure configure].backgroundSessionIdentifier]) {
[FKConfigure configure].completionHandler = completionHandler;
}
}
配置完成后, 使配置生效
[[FKConfigure configure] takeSession];
FKDownloader 采用计时器执行轮询执行任务, 间隔 1s, 默认情况下, 该计时器不会激活, 需要显式激活后才可进行任务
[[FKConfigure configure] activateQueue];
构建者主要负责创建任务, 设定任务的基本信息等.
使用链接进行构建, 注意, 如果链接不合法, 将会返回 nil
FKBuilder *builder = [FKBuilder buildWithURL:@"Download URL"];
配置下载类型, 支持前台下载和后台下载, 默认为后台下载
builder.downloadType = FKDownloadBackground;
对下载链接进行预处理, 这一步主要流程为:
- 创建下载任务对应的文件夹与信息描述文件
- 生成内部使用的唯一任务编号
- 将任务放入内部缓存
在此流程中, 任务状态为 FKStatePrepare, 即处理中
[builder prepare];
FKDownloader 的每一个任务都对应一个本地信息文件, 当 App 因为重启等原因丢失内存缓存时, 一些信息获取逻辑会在控制台提示任务不存在等信息, 这时就需要手动执行上述流程, 使任务信息加载到内存中. 该场景可在 Demo 中下载信息列表界面中, 每个 Cell 赋值 URL 时看到.
主要负责控制任务状态
激活任务, 对 FKStateCancel 和 FKStateError 状态生效, 将任务重新排到任务队列中
[FKControl actionRequestWithURL:@"Download URL"];
暂停任务, 对 FKStateAction 和 FKStateIdel 状态生效
[FKControl suspendRequestWithURL:@"Download URL"];
也可执行 +[FKControl suspendAllTask] 暂停所有任务
继续任务, 对 FKStateSuspend 状态生效
对于前台任务, 重启 App 后, 状态会重置为暂停, 执行继续将重新下载
[FKControl resumeRequestWithURL:@"Download URL"];
也可执行 +[FKControl resumeAllTask] 继续下载所有已暂停任务
取消任务, 对 FKStateAction, FKStateSuspend, FKStateIdel 和 FKStateError 状态生效
[FKControl cancelRequestWithURL:@"Download URL"];
取消所有请求, 会对 Background Session 所有的, 状态为 NSURLSessionTaskStateRunning 的 Download Task 进行取消操作
[FKControl cancelAllRequest];
删除任务所有文件, 可视作彻底移除任务, 但最好在任务已完成, 或已取消的状态下执行, 其他状态可能会出现意外情况.
[FKControl trashRequestWithURL:@"Download URL"];
负责获取任务对应的信息
检查 URL 对应的任务是否存在, 将会在下载列表和磁盘缓存中查找
BOOL isExist = [FKMessager existWithURL:@"URL"];
获取下载链接对应任务信息, 会跟随信息分发计时器不断调用, 如果只想在状态改变时获取, 或只想或进度信息, 见 FKMiddleware.
注意, 回调不在主线程, 如需 UI 操作请自行切换线程
[FKMessager messagerWithURL:@"Download URL" info:^(int64_t countOfBytesReceived,
int64_t countOfBytesPreviousReceived,
int64_t countOfBytesExpectedToReceive,
FKState state,
NSError * _Nullable error) {
// do something...
}];
只获取一次任务信息, 回调不在主线程
[FKMessager acqireMessagerInfo:@"Download URL" info:^(int64_t countOfBytesReceived,
int64_t countOfBytesPreviousReceived,
int64_t countOfBytesExpectedToReceive,
FKState state,
NSError * _Nullable error) {
// do something...
}];
将多个链接标记为一个任务集合
// Add
[FKMessager addMessagerWithURLs:@[@"Download URL"] barrel:@"name"];
// Delete
[FKMessager removeMessagerBarrel:@"name"];
对任务集合进行管理
// Add URL
[FKMessager addURL:@"Download URL" fromBarrel:@"name"];
// Delete URL
[FKMessager removeURL:@"Download URL" fromBarrel:@"name"];
也可使用 +[FKMessager acquireURLsWithBarrel:] 获取集合内所有的 URL
获取一个集合的任务信息, 基本上, 集合信息只是最基本的数据, 只有总大小, 上次已下载大小和已下载大小, 状态之类的数据请自行记录和控制
[FKMessager messagerWithBarrel:@"name" info:^(int64_t countOfBytesReceived, int64_t countOfBytesPreviousReceived, int64_t countOfBytesExpectedToReceive) {
// do something...
}];
直接获取下载链接对应任务的状态
FKState state = [FKControl stateWithURL:@"Download URL"];
直接获取下载链接对应任务的错误信息, 可能为空值
NSError *error = [FKControl errorWithURL:@"Download URL"];
直接获取下载链接对应文件的路径, 文件可能不存在
NSString *path = [FKControl downloadedFilePathWithURL:@"Download URL"];
管理中间件, 包括请求中间件, 下载中间件和响应中间件
注册请求中间件, 在构建 NSMutableURLRequest 时, 会依次调用中间件来处理请求, FKDownloader 会使用最终的 NSMutableURLRequest 来进行下载
[[FKMiddleware shared] registeRequestMiddleware:[CustomRequestMiddleware new]];
请求中间件类需要遵循 FKRequestMiddlewareProtocol 协议, 并实现被标记为 @required 的方法与属性, 其中 priority 表示优先级, 类型为正整数, 值越接近 0, 优先级越高, 中间件协议带有 priority 属性的, 都与请求中间件逻辑一致.
在请求中间件中实现协议中的 -[FKMiddleware processRequest:] 方法来处理请求, 该方法会将 NSMutableURLRequest 作为参数传进来, 自定义处理后, 将 NSMutableURLRequest 返回即可
注册下载中间件, 在下载中进度改变时, 和任务状态改变时被调用
[[FKMiddleware shared] registeDownloadMiddleware:[CustomDownloadMiddleware new]];
下载中间件协议中的 -[FKMiddleware downloadURL:state:error:] 会在任务状态改变时被调用, 方法内部为子线程, UI 相关的操作请自行改变线程
-[FKMiddleware downloadURL:countOfBytesReceived:countOfBytesPreviousReceived:countOfBytesExpectedToReceive:] 会在下载进度改变时调用, 与系统下载信息改变同步, 方法内部为子线程, UI 相关的操作请自行改变线程
注册响应中间件, 在任务完成下载或出错中断后被调用, 可以用来处理文件校验, 移动文件到指定路径等操作.
[[FKMiddleware shared] registeResponseMiddleware:[CustomResponseMiddleware new]];
响应中间件协议中 -[FKMiddleware processResponse:] 方法会传进来一个 FKResponse 对象, 对象结构如下:
@interface FKResponse : NSObject
@property (nonatomic, strong) NSString *originalURL;
@property (nonatomic, strong) NSURLResponse *response;
@property (nonatomic, strong) NSString *filePath;
@property (nonatomic, strong, nullable) NSError *error;
@end
其中 originalURL 是在构建时传入的链接, response 为系统返回的请求响应信息, 可从中获取相应头的信息. filePath 为下载的文件路径, 下载请求完成后, 文件会移动到此路径, 注意, 文件可能不存在. error 为系统返回的请求响应错误, 可能为网络中断, 验证无法通过, 不合法的返回值等问题.
便捷类, 针对简单下载封装, 更复杂的逻辑可使用上述类进行实现
添加并开始任务
[FKDownloadTool addURL:@"URL"];
获取任务所有信息, 同 +[FKMessager messagerWithURL:info:] 方法, 将会不停被调用, 回调不在主线程
[FKDownloadTool getInfoWithURL:@"URL" complete:^(int64_t countOfBytesReceived,
int64_t countOfBytesPreviousReceived,
int64_t countOfBytesExpectedToReceive,
FKState state,
NSError * _Nullable error) {
// do something...
}];
暂停任务
[FKDownloadTool suspendWithURL:@"URL"];
暂停所有任务
[FKDownloadTool suspendAllTask];
恢复任务
[FKDownloadTool resumeWithURL:@"URL"];
恢复所有任务
[FKDownloadTool resumeAllTask];
取消并删除任务
[FKDownloadTool cancelWithURL:@"URL"];