5 影片下載
更新時間：2023-04-17 15:27:58
PLVVodDownloadManager 是點播 SDK 中的一個單例類別，主要負責影片的下載、下載資訊回呼及下載佇列的管理。下載資訊封裝在類別 PLVVodDownlaodInfo 中，每一個下載任務對應一個 PLVVodDownlaodInfo 物件。
下載器的使用詳見 demo 中 PLVDownloadManagerViewController 的實作。
5.1 下載設定
在進行下載之前，我們需要先進行一些設定。
5.1.1 AppDelegate
首先，在 AppDelegate 中，我們需要進行以下配置：
- (void)application:(UIApplication *)application handleEventsForBackgroundURLSession:(NSString *)identifier
completionHandler:(void (^)(void))completionHandler {
// 处理后台下载完成回调的事件
[[PLVVodDownloadManager sharedManager] handleEventsForBackgroundURLSession:identifier completionHandler:completionHandler];
}
- (void)applicationDidEnterBackground:(UIApplication *)application {
// app 退到后台时进行相关设置
[[PLVVodDownloadManager sharedManager] applicationDidEnterBackground];
}
- (void)applicationWillEnterForeground:(UIApplication *)application {
// app 回到前台时进行相关设置
[[PLVVodDownloadManager sharedManager] applicationWillEnterForeground];
}
- (void)applicationWillTerminate:(UIApplication *)application {
// 程序即将结束时，修改并保存下载中视频的下载状态，用于程序下次启动后，恢复视频下载状态
[[PLVVodDownloadManager sharedManager] applicationWillTerminate];
}
5.1.2 下載器設定
PLVVodDownloadManager 包含以下下載屬性，開發者可以根據需要進行設定，也可以保持預設設定。
5.1.2.1 設定下載目錄
下載目錄預設為沙盒資料夾 "Library/Caches/PolyvVodCache"。請注意，修改下載目錄後，上一個目錄的離線影片將無法索引。修改下載目錄可以透過修改 PLVVodDownloadManager 的屬性 downloadDir，也可以透過方法 -setDownloadDir:skipBackup:error: 進行修改。
// 下载目录，默认为 Library/Caches/PolyvVodCache
@property (nonatomic, copy) NSString *downloadDir;
/**
设置下载目录
@param downloadDir 设置的下载目录
@param skipBackup 是否忽略 iCloud 的备份
@param error 错误回调
@return 是否成功
*/
- (BOOL)setDownloadDir:(NSString *)downloadDir skipBackup:(BOOL)skipBackup error:(NSError **)error;
5.1.2.2 是否允許使用行動網路進行下載
預設允許，如需禁止使用行動網路進行下載，需要修改屬性值 allowsCellularAccess 為 NO。
// 是否允许使用蜂窝移动网络进行下载，默认 YES
@property (nonatomic, assign) BOOL allowsCellularAccess;
5.1.2.3 下載最大並發數
PLVVodDownloadManager 的下載並發數透過 maxRuningCount 設定，預設為 1，最大可設為 3。
// 允许同时下载的最大任务数, 默认为1，最大为3
@property (nonatomic, assign) NSUInteger maxRuningCount;
5.2 下載資訊模型
PLVVodDownloadInfo 是下載資訊模型類別，包含如下唯讀屬性：
// 唯一标识
@property (nonatomic, copy, readonly) NSString *identifier;
// 队列ID
@property (nonatomic, assign, readonly) NSInteger downloadId;
// PLVVodVideo 对象
@property (nonatomic, strong, readonly) PLVVodVideo *video;
// vid 便捷属性
@property (nonatomic, copy, readonly) NSString *vid;
// 清晰度
@property (nonatomic, assign, readonly) PLVVodQuality quality;
// 文件类型,默认为视频
@property (nonatomic, assign, readonly) PLVDownloadFileType fileType;
// 下载相关
@property (nonatomic, assign, readonly) PLVVodDownloadState state; // 下载状态
@property (nonatomic, assign, readonly) double bytesPerSeconds; // 下载速率（单位：byte/s）
@property (nonatomic, assign, readonly) double progress; // 下载进度（0-1）
@property (nonatomic, assign, readonly) double unzipProgress; // 解压进度（0-1）
@property (nonatomic, strong, readonly) NSError *error; // 下载错误
// UI展示
@property (nonatomic, copy, readonly) NSString *snapshot; // 封面
@property (nonatomic, copy, readonly) NSString *title; // 视频名称
@property (nonatomic, assign, readonly) NSUInteger filesize; // 文件大小
其中，清晰度的列舉值定義請參閱點播文件 4.2.1，下載狀態、檔案類型的列舉定義如下：
// 下载状态
typedef NS_ENUM(NSInteger, PLVVodDownloadState) {
PLVVodDownloadStatePreparing = 0, // 准备，默认值
PLVVodDownloadStatePreparingStart = 7, // 准备中，正在创建任务
PLVVodDownloadStateReady = 1, // 就绪，下载任务已创建
PLVVodDownloadStateRunning = 2, // 正在下载
PLVVodDownloadStateStopping = 3, // 正在停止
PLVVodDownloadStateStopped = 4, // 停止下载
PLVVodDownloadStateSuccess = 5, // 下载成功
PLVVodDownloadStateFailed = 6 // 下载失败
};
// 下载文件类型
typedef NS_ENUM(NSUInteger, PLVDownloadFileType) {
PLVDownloadFileTypeVideo = 1 << 0, // 视频文件
PLVDownloadFileTypeAudio = 1 << 1 // 音频文件
};
5.3 影片下載
5.3.1 新增下載任務
使用方法 -downloadVideo: 將影片物件 PLVVodVideo 加入下載佇列中，如果屬性 autoStart 為預設值 NO，則需要呼叫方法 -startDownload 啟動下載，否則則不需要。相關屬性、方法宣告如下：
// 添加任务后是否自动启动，默认 NO
@property (nonatomic, assign) BOOL autoStart;
/**
使用后台设置的默认画质添加至下载队列
@param video PLVVodVideo 视频对象
@return 下载信息
*/
- (PLVVodDownloadInfo *)downloadVideo:(PLVVodVideo *)video;
/**
开始队列下载
*/
- (void)startDownload;
/**
停止队列下载
*/
- (void)stopDownload;
新增影片並開始/停止下載程式碼範例如下：
[[PLVVodDownloadManager sharedManager] downloadVideo:video]; // 将视频 video 添加到下载队列
[[PLVVodDownloadManager sharedManager] startDownload]; // 开始下载
[[PLVVodDownloadManager sharedManager] stopDownload]; // 停止下载
使用以下方法還可以啟動、停止指定 vid 的影片：
/**
从指定视频开始下载
@param vid 视频vid
*/
- (void)startDownloadWithVid:(NSString *)vid;
/**
停止下载指定视频
@param vid 视频vid
*/
- (void)stopDownloadWithVid:(NSString *)vid;
5.3.2 移除下載任務
移除下載任務方法宣告如下：
/**
移除下载任务，并删除对应文件
@param vid vid
@param error 错误回调
*/
- (void)removeDownloadWithVid:(NSString *)vid error:(NSError **)error;
/**
移除所有下载任务，并删除对应文件，与已完成下载的视频无关
@param completion 删除任务后的回调
*/
- (void)removeAllDownloadWithComplete:(void(^)(void *result))completion;
請注意，任務移除之後，對應的影片檔案也會被刪除。移除所有下載任務不包括已成功下載的。
5.3.3 讀取下載任務
使用以下方法，可以取得所有已成功下載的影片資訊/本地影片，也可以根據 vid 取得指定的影片下載資訊。
/**
获取所有已缓存成功视频信息
@return 下载完成的视频数组
*/
- (NSArray<PLVVodDownloadInfo *> *)requestDownloadCompleteList;
/**
根据vid 获取视频下载信息
@param vid 视频vid
*/
- (PLVVodDownloadInfo *)requestDownloadInfoWithVid:(NSString *)vid;
/**
获取已下载的本地视频
@return 一组 PLVVodLocalVideo 对象
*/
- (NSArray<PLVVodLocalVideo *> *)localVideos;
5.4 下載回呼
5.4.1 下載器回呼
PLVVodDownloadManager 使用以下回呼對影片下載進行監聽：
// 完成所有下载回调
@property (nonatomic, copy) void(^completeBlock)(void);
// 单个视频下载完成回调
@property (nonatomic, copy) void(^downloadCompleteBlock)(PLVVodDownloadInfo *info);
// 下载错误回调
@property (nonatomic, copy) void (^downloadErrorHandler)(PLVVodVideo *video, NSError *error);
範例程式碼如下：
PLVVodDownloadManager *downloadManager = [PLVVodDownloadManager sharedManager];
downloadManager.downloadCompleteBlock = ^(PLVVodDownloadInfo *info) {
NSLog(@"video vid %@ download success", info.vid);
};
downloadManager.downloadErrorHandler = ^(PLVVodVideo *video, NSError *error) {
NSLog(@"video vid %@ download error: %@", video.vid, error);
};
downloadManager.completeBlock = ^{
NSLog(@"all video download success");
};
5.4.2 下載任務回呼
每一個影片下載資訊物件 PLVVodDownloadInfo 也有自己的回呼，開發者透過實作這些回呼，可以進行 UI 的更新：
// 下载状态变更回调
@property (nonatomic, copy) void (^stateDidChangeBlock)(PLVVodDownloadInfo *info);
// 下载速率（单位：byte/s）变更回调
@property (nonatomic, copy) void (^bytesPerSecondsDidChangeBlock)(PLVVodDownloadInfo *info);
// 下载进度（0-1）变更回调
@property (nonatomic, copy) void (^progressDidChangeBlock)(PLVVodDownloadInfo *info);
// 解压进度（0-1）变更回调
@property (nonatomic, copy) void (^unzipProgressDidChangeBlock)(PLVVodDownloadInfo *info);
