OpenHarmony 升级服务组件（UpdateService）
文章目录
- [OpenHarmony 升级服务组件（UpdateService）](#OpenHarmony 升级服务组件（UpdateService）)
-
- [1. 模块概述](#1. 模块概述)
- [2. 模块结构](#2. 模块结构)
- [3. 模块间交互](#3. 模块间交互)
- [4. 状态机转换图](#4. 状态机转换图)
- [5. 接口设计](#5. 接口设计)
- 附录
-
- [A. 错误码定义](#A. 错误码定义)
- [B. 权限要求](#B. 权限要求)
- [C. 配置文件](#C. 配置文件)
1. 模块概述
源码：https://gitcode.com/openharmony/update_updateservice
1.1 功能与目标
主要功能
升级服务组件（UpdateService）是OpenHarmony系统中负责设备系统升级的核心服务模块，主要提供以下功能：
| 功能模块 | 描述 |
|---|---|
| 版本检查 | 查找可用的升级包版本，与服务器通信获取最新版本信息 |
| 升级包下载 | 支持升级包的下载、暂停、恢复下载功能 |
| 升级策略管理 | 设置/获取升级策略，支持自动升级、定时升级等策略 |
| 升级执行 | 触发升级流程，包括安装、验证、应用新版本 |
| 工厂重置 | 提供设备恢复出厂设置功能 |
| 本地升级 | 支持本地升级包的验证和应用 |
设计目标
- 可靠性: 确保升级过程的稳定性和数据完整性
- 可扩展性: 支持多种升级类型（OTA、固件升级等）
- 安全性: 升级包验证、权限控制
- 用户体验: 支持后台下载、进度通知、断点续传
使用场景
- 系统OTA（Over-The-Air）在线升级
- 本地升级包安装
- 设备固件升级
- 系统恢复出厂设置
1.2 系统位置
升级服务组件是一个System Ability (SA) ，由OHOS的init进程负责启动，SA ID为3006。
系统定位
- 核心模块: 属于updater子系统的核心组件
- 服务类型: 系统能力服务（SystemCapability.Update.UpdateService）
- 运行方式: 独立进程运行，按需启动
系统架构图
┌─────────────────────────────────────────────────────────────────────────────┐
│ OpenHarmony 系统架构 │
├─────────────────────────────────────────────────────────────────────────────┤
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ 升级应用 │ │ 设置应用 │ │ 其他应用 │ 应用层 │
│ │ (update_app)│ │ │ │ │ │
│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │
├─────────┼──────────────────┼──────────────────┼─────────────────────────────┤
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ NAPI 接口层 │ 框架层 │
│ │ (frameworks/js/napi/client) │ │
│ └────────────────────────────┬────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ UpdateServiceKits (客户端SDK) │ │
│ │ (interfaces/inner_api) │ │
│ └────────────────────────────┬────────────────────────────────┘ │
│ │ IPC │
├───────────────────────────────┼─────────────────────────────────────────────┤
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ UpdateService (SA 3006) │ 服务层 │
│ │ (services/engine) │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │UpdateService│ │ Firmware │ │ Callback │ │ │
│ │ │ Stub │ │ Module │ │ Module │ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │ │
├───────────────────────────────┼─────────────────────────────────────────────┤
│ ▼ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ c_utils │ │ hilog │ │ IPC │ │ samgr │ 系统服务层 │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ curl │ │ libxml2 │ │ cJSON │ │ SQLite │ 三方库 │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘1.3 设计思路与模式
设计思路
- 分层架构: 采用清晰的分层设计，将接口层、服务层、数据层分离
- 模块化设计: 将升级流程拆分为检查、下载、安装、应用等独立模块
- 状态机驱动: 使用状态机管理升级流程的各个阶段
- 回调机制: 通过回调接口通知客户端升级进度和状态变化
设计模式
| 设计模式 | 应用场景 | 说明 |
|---|---|---|
| 代理模式 (Proxy) | UpdateServiceProxy | 客户端通过代理类访问远程服务 |
| 单例模式 (Singleton) | UpdateService, FirmwareStatusCache | 确保服务实例唯一性 |
| 工厂模式 (Factory) | FirmwareInstallFactory | 根据安装类型创建不同的安装器 |
| 策略模式 (Strategy) | FirmwareIExecuteMode | 不同升级模式的策略实现 |
| 观察者模式 (Observer) | IUpdateCallback | 升级状态变化通知机制 |
| 模板方法模式 (Template Method) | FirmwareIExecutor | 定义升级执行的骨架流程 |
| 状态模式 (State) | UpgradeStatus | 管理升级过程的状态转换 |
2. 模块结构
2.1 源文件与头文件
目录结构
base/update/updateservice/
├── interfaces/ # 接口定义目录
│ ├── kits/ # 对外接口封装
│ │ └── js/ # JS接口声明
│ └── inner_api/ # SA接口定义和封装
│ ├── include/ # 头文件
│ └── engine/ # 接口实现
├── frameworks/ # 框架实现
│ └── js/napi/ # NAPI实现
│ ├── base/ # 基础工具类
│ └── client/ # 客户端实现
├── services/ # 服务实现
│ ├── callback/ # 回调接口
│ ├── engine/ # 引擎服务
│ ├── firmware/ # 固件升级模块
│ ├── startup/ # 启动管理
│ └── utils/ # 工具类
└── test/ # 测试代码核心文件说明
| 文件路径 | 功能描述 |
|---|---|
interfaces/inner_api/include/iupdate_service.h |
升级服务接口定义 |
interfaces/inner_api/include/iupdate_callback.h |
回调接口定义 |
interfaces/inner_api/include/update_helper.h |
数据结构和辅助类定义 |
interfaces/inner_api/include/update_service_kits.h |
客户端SDK接口 |
services/engine/include/update_service.h |
升级服务主类 |
services/engine/include/update_service_stub.h |
IPC Stub实现 |
services/engine/include/update_service_impl_firmware.h |
固件升级实现 |
services/firmware/upgrade/flow/include/firmware_flow_manager.h |
固件升级流程管理 |
2.2 类、结构体、函数与方法
核心类图 - 接口层
<<interface>>
IRemoteBroker
<<interface>>
IUpdateService
+CheckNewVersion()
+Download()
+Upgrade()
+GetNewVersionInfo()
+SetUpgradePolicy()
+GetUpgradePolicy()
+FactoryReset()
+RegisterUpdateCallback()
+UnregisterUpdateCallback()
<<interface>>
IUpdateCallback
+OnCheckVersionDone()
+OnEvent()
<<interface>>
IServiceOnlineUpdater
+CheckNewVersion()
+Download()
+Upgrade()
<<interface>>
IServiceLocalUpdater
+ApplyNewVersion()
+VerifyUpgradePackage()
<<interface>>
IServiceRestorer
+FactoryReset()
UpdateCallbackStub
+OnRemoteRequest()
UpdateCallbackProxy
+OnCheckVersionDone()
+OnEvent()
核心类图 - 服务层
SystemAbility
+OnStart()
+OnStop()
UpdateServiceStub
-requestFuncMap_
+OnRemoteRequest()
UpdateService
-clientProxyMap_ : map
-updateImplMgr_ : UpdateServiceImplManager
+OnStart()
+OnStop()
+RegisterUpdateCallback()
+CheckNewVersion()
+Download()
+Upgrade()
+GetInstance()
UpdateServiceImplManager
-updateImpMap_ : map
+GetOnlineUpdater()
UpdateServiceImplFirmware
-preferencesUtil_ : FirmwarePreferencesUtil
+CheckNewVersion()
+Download()
+Upgrade()
+GetNewVersionInfo()
<<interface>>
IServiceOnlineUpdater
核心类图 - 固件升级模块
FirmwareFlowManager
-executeMode_ : FirmwareIExecuteMode
-executor_ : FirmwareIExecutor
-nextStep_ : FirmwareStep
+SetExecuteMode()
+Start()
+Execute()
<<interface>>
FirmwareIExecutor
+Execute()
FirmwareCheckExecutor
+Execute()
FirmwareDownloadExecutor
+Execute()
FirmwareInstallExecutor
+Execute()
FirmwareApplyExecutor
+Execute()
<<interface>>
FirmwareIExecuteMode
+GetNextStep()
+SetCheckResult()
+HandleComplete()
+GetDownloadOptions()
+GetUpgradeOptions()
FirmwareManualCheckMode
+GetNextStep()
+HandleComplete()
FirmwareDownloadMode
+GetNextStep()
+SetDownloadProgress()
FirmwareInstallApplyMode
+GetNextStep()
+SetInstallResult()
核心结构体
cpp
// 升级信息
struct UpgradeInfo {
std::string upgradeApp; // 升级应用包名
BusinessType businessType; // 业务类型
std::string upgradeDevId; // 升级设备ID
std::string controlDevId; // 控制设备ID
};
// 版本组件信息
struct VersionComponent {
std::string componentId; // 组件ID
int32_t componentType; // 组件类型
std::string upgradeAction; // 升级动作
std::string displayVersion; // 显示版本号
std::string innerVersion; // 内部版本号
size_t size; // 包大小
size_t effectiveMode; // 生效模式
DescriptionInfo descriptionInfo; // 描述信息
};
// 新版本信息
struct NewVersionInfo {
VersionDigestInfo versionDigestInfo; // 版本摘要
std::vector<VersionComponent> versionComponents; // 版本组件列表
};
// 升级策略
struct UpgradePolicy {
bool downloadStrategy; // 下载策略
bool autoUpgradeStrategy; // 自动升级策略
UpgradePeriod autoUpgradePeriods[2]; // 自动升级时间段
};
// 任务信息
struct TaskInfo {
bool existTask; // 是否存在任务
TaskBody taskBody; // 任务详情
};
// 业务错误
struct BusinessError {
std::string message; // 错误消息
CallResult errorNum; // 错误码
std::vector<ErrorMessage> data; // 错误详情
};核心枚举类型
cpp
// 升级状态
enum class UpgradeStatus {
INIT = 0, // 初始化
CHECKING_VERSION = 10, // 正在检查版本
CHECK_VERSION_FAIL, // 检查版本失败
CHECK_VERSION_SUCCESS, // 检查版本成功
DOWNLOADING = 20, // 正在下载
DOWNLOAD_PAUSE, // 下载暂停
DOWNLOAD_CANCEL, // 下载取消
DOWNLOAD_FAIL, // 下载失败
DOWNLOAD_SUCCESS, // 下载成功
VERIFYING = 30, // 正在验证
VERIFY_FAIL, // 验证失败
VERIFY_SUCCESS, // 验证成功
INSTALLING = 80, // 正在安装
INSTALL_FAIL, // 安装失败
INSTALL_SUCCESS, // 安装成功
UPDATING = 90, // 正在升级
UPDATE_FAIL, // 升级失败
UPDATE_SUCCESS // 升级成功
};
// 固件升级步骤
enum class FirmwareStep {
INIT = 0, // 初始化
CHECK_STEP, // 检查步骤
DOWNLOAD_STEP, // 下载步骤
AUTH_STEP, // 认证步骤
INSTALL_STEP, // 安装步骤
APPLY_STEP, // 应用步骤
COMPLETE = 10 // 完成
};
// 事件ID
enum class EventId {
EVENT_TASK_BASE = 0x01000000,
EVENT_TASK_RECEIVE, // 接收任务
EVENT_DOWNLOAD_START, // 下载开始
EVENT_DOWNLOAD_UPDATE, // 下载更新
EVENT_DOWNLOAD_SUCCESS, // 下载成功
EVENT_DOWNLOAD_FAIL, // 下载失败
EVENT_UPGRADE_START, // 升级开始
EVENT_UPGRADE_SUCCESS, // 升级成功
EVENT_UPGRADE_FAIL, // 升级失败
// ... 更多事件
};2.3 继承与多态
继承关系图
执行器继承链
FirmwareIExecutor
FirmwareCheckExecutor
FirmwareDownloadExecutor
FirmwareInstallExecutor
FirmwareApplyExecutor
回调继承链
IRemoteBroker
IUpdateCallback
UpdateCallbackStub
UpdateCallback
UpdateCallbackProxy
服务继承链
IRemoteBroker
IUpdateService
UpdateServiceStub
UpdateService
SystemAbility
多态设计目的
- IServiceOnlineUpdater: 支持不同类型的在线升级实现（固件升级、参数升级等）
- FirmwareIExecutor: 统一升级流程中各步骤的执行接口
- FirmwareIExecuteMode: 支持不同升级模式（手动检查、自动下载、安装应用等）
2.4 模块内部依赖框图
┌─────────────────────────────────────────────────────────────────────────────┐
│ UpdateService 模块内部依赖 │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌───────────────────────────────────────────────────────────────┐ │
│ │ Engine Layer │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │ │
│ │ │UpdateService│─>│UpdateService│─>│UpdateServiceImpl │ │ │
│ │ │ │ │ ImplManager│ │ Firmware │ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────────────┘ │ │
│ │ │ │ │ │
│ │ │ ▼ │ │
│ │ │ ┌───────────────────────────────────┐ │ │
│ │ │ │ Firmware Module │ │ │
│ │ │ │ ┌─────────────┐ ┌────────────┐ │ │ │
│ │ │ │ │ FlowManager │─>│ Executor │ │ │ │
│ │ │ │ └─────────────┘ └────────────┘ │ │ │
│ │ │ │ │ │ │ │ │
│ │ │ │ ▼ ▼ │ │ │
│ │ │ │ ┌─────────────┐ ┌────────────┐ │ │ │
│ │ │ │ │ExecuteMode │ │DataProcessor│ │ │ │
│ │ │ │ └─────────────┘ └────────────┘ │ │ │
│ │ │ └───────────────────────────────────┘ │ │
│ │ │ │ │ │
│ │ ▼ ▼ │ │
│ │ ┌─────────────┐ ┌─────────────────┐ │ │
│ │ │ Callback │ │ Data Layer │ │ │
│ │ │ Module │ │ ┌───────────┐ │ │ │
│ │ │ ┌─────────┐ │ │ │ Database │ │ │ │
│ │ │ │CallbackU│ │ │ │(SQLite) │ │ │ │
│ │ │ │ tils │ │ │ └───────────┘ │ │ │
│ │ │ └─────────┘ │ │ ┌───────────┐ │ │ │
│ │ └─────────────┘ │ │Preferences│ │ │ │
│ │ │ │ Utils │ │ │ │
│ │ │ └───────────┘ │ │ │
│ │ └─────────────────┘ │ │
│ └───────────────────────────────────────────────────────────────┘ │
│ │
│ ┌───────────────────────────────────────────────────────────────┐ │
│ │ Core Ability Layer │ │
│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │
│ │ │ Adapter │ │ Alarm │ │ Net │ │ Utils │ │ Log │ │ │
│ │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ │
│ └───────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘3. 模块间交互
3.1 交互描述
与外部模块的交互
| 交互模块 | 交互方式 | 描述 |
|---|---|---|
| 升级应用 (update_app) | IPC/Binder | 通过UpdateServiceKits SDK调用升级服务 |
| SAMGR | 系统服务注册 | 注册为System Ability (ID: 3006) |
| Init进程 | 进程启动 | 由init进程负责启动升级服务 |
| 升级服务器 | HTTPS | 通过curl库进行网络通信，检查版本、下载升级包 |
| Updater子系统 | 系统调用 | 触发重启进入updater模式执行升级 |
| 文件系统 | 文件I/O | 读写升级包、配置文件、数据库 |
外部库依赖
cpp
// 系统组件依赖
"c_utils" // 基础工具库
"hilog" // 日志系统
"ipc" // IPC通信
"safwk" // SA框架
"samgr" // SA管理器
"napi" // JS接口
"startup_l2" // 启动服务
// 第三方库依赖
"curl" // HTTP/HTTPS通信
"libxml2" // XML解析
"cJSON" // JSON解析
"bounds_checking_function" // 安全函数异步处理机制
- 版本检查 : 异步执行，通过回调
OnCheckVersionDone通知结果 - 下载任务 : 后台线程执行，通过事件
OnEvent通知进度 - 升级执行: 异步执行，支持进度通知和状态回调
事件驱动机制
cpp
// 事件分类
enum class EventClassify {
TASK = 0x01000000, // 任务事件
};
// 事件通知接口
class IUpdateCallback {
public:
virtual void OnCheckVersionDone(const BusinessError &businessError,
const CheckResult &checkResult) = 0;
virtual void OnEvent(const EventInfo &eventInfo) = 0;
};多线程处理
- 主线程: 处理IPC请求，分发任务
- 工作线程: 执行网络请求、文件下载、包验证等耗时操作
- 回调线程: 通过IPC回调客户端
3.2 外部依赖框图
┌─────────────────────────────────────────────────────────────────────────────┐
│ UpdateService 外部依赖关系 │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌───────────────────┐ │
│ │ 升级应用 │ │
│ │ (update_app) │ │
│ └─────────┬─────────┘ │
│ │ JS API │
│ ▼ │
│ ┌───────────────────┐ │
│ │ NAPI Layer │ │
│ └─────────┬─────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────────────────────────────────┐ │
│ │ UpdateServiceKits (SDK) │ │
│ └──────────────────────────────┬───────────────────────────────────────┘ │
│ │ IPC │
│ ▼ │
│ ┌──────────────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ UpdateService (SA 3006) │ │
│ │ │ │
│ └─────┬────────────┬────────────┬────────────┬────────────┬───────────┘ │
│ │ │ │ │ │ │
│ ▼ ▼ ▼ ▼ ▼ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ SAMGR │ │ IPC │ │ hilog │ │ c_utils │ │ safwk │ │
│ │ (服务管理)│ │ (进程通信)│ │ (日志) │ │ (工具库) │ │ (SA框架) │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────────────────────┐ │
│ │ 第三方库依赖 │ │
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
│ │ │ curl │ │ libxml2 │ │ cJSON │ │ SQLite │ │ │
│ │ │(网络通信)│ │(XML解析) │ │(JSON解析)│ │ (数据库) │ │ │
│ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ │
│ └──────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────────────────────┐ │
│ │ 外部系统交互 │ │
│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │
│ │ │ 升级服务器 │ │ Updater │ │ Init进程 │ │ │
│ │ │ (HTTPS) │ │ 子系统 │ │ (进程管理) │ │ │
│ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │
│ └──────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘4. 状态机转换图
4.1 状态机模型
升级服务采用分层状态机模型，包含升级状态机 和固件步骤状态机两个层次。
状态机树图
ROOT
系统
IDLE
空闲
UPGRADING
升级中
ERROR
错误
CHECKING
检查中
DOWNLOADING
下载中
INSTALLING
安装中
PAUSED
暂停
RESUMING
恢复中
CANCELING
取消中
APPLYING
应用中
4.2 状态机切换规则
升级状态转换表
| 当前状态 | 触发事件 | 目标状态 | 条件 |
|---|---|---|---|
| INIT | CheckNewVersion | CHECKING_VERSION | 用户触发检查 |
| CHECKING_VERSION | 检查成功 | CHECK_VERSION_SUCCESS | 发现新版本 |
| CHECKING_VERSION | 检查失败 | CHECK_VERSION_FAIL | 网络错误或无新版本 |
| CHECK_VERSION_SUCCESS | Download | DOWNLOADING | 用户触发下载 |
| DOWNLOADING | 下载完成 | DOWNLOAD_SUCCESS | 文件完整性验证通过 |
| DOWNLOADING | 暂停下载 | DOWNLOAD_PAUSE | 用户暂停或网络断开 |
| DOWNLOADING | 取消下载 | DOWNLOAD_CANCEL | 用户取消 |
| DOWNLOADING | 下载失败 | DOWNLOAD_FAIL | 网络错误或空间不足 |
| DOWNLOAD_PAUSE | ResumeDownload | DOWNLOADING | 用户恢复下载 |
| DOWNLOAD_SUCCESS | Upgrade | INSTALLING | 用户触发安装 |
| INSTALLING | 安装成功 | INSTALL_SUCCESS | 安装完成 |
| INSTALLING | 安装失败 | INSTALL_FAIL | 安装过程错误 |
| INSTALL_SUCCESS | 应用 | UPDATING | 触发重启应用 |
| UPDATING | 升级成功 | UPDATE_SUCCESS | 重启后验证成功 |
| UPDATING | 升级失败 | UPDATE_FAIL | 重启后验证失败 |
固件步骤状态转换
cpp
// 固件升级步骤状态机
enum class FirmwareStep {
INIT = 0, // 初始状态
CHECK_STEP, // 检查步骤
DOWNLOAD_STEP, // 下载步骤
AUTH_STEP, // 认证步骤
INSTALL_STEP, // 安装步骤
APPLY_STEP, // 应用步骤
COMPLETE = 10 // 完成状态
};4.3 升级状态机转换图
系统启动
CheckNewVersion()
检查成功
发现新版本
检查失败
网络错误/无新版本
重试
Download()
下载完成
暂停下载
下载失败
取消下载
ResumeDownload()
重试
Upgrade()
安装成功
安装失败
Apply()
升级成功
重启后验证通过
升级失败
重启后验证失败
回滚
INIT
CHECKING_VERSION
CHECK_VERSION_SUCCESS
CHECK_VERSION_FAIL
DOWNLOADING
DOWNLOAD_SUCCESS
DOWNLOAD_PAUSE
DOWNLOAD_FAIL
DOWNLOAD_CANCEL
INSTALLING
INSTALL_SUCCESS
INSTALL_FAIL
UPDATING
UPDATE_SUCCESS
UPDATE_FAIL
4.4 固件流程状态机
┌─────────────────────────────────────────────────────────────────────────────┐
│ 固件升级流程状态机 │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ INIT │────>│ CHECK │────>│ DOWNLOAD │────>│ AUTH │ │
│ └──────┘ │ STEP │ │ STEP │ │ STEP │ │
│ └──────────┘ └──────────┘ └──────────┘ │
│ │ │ │ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ COMPLETE │<────│ INSTALL │<────│ APPLY │ │
│ │ │ │ STEP │ │ STEP │ │
│ └──────────┘ └──────────┘ └──────────┘ │
│ │
│ 执行器映射: │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ CHECK_STEP -> FirmwareCheckExecutor │ │
│ │ DOWNLOAD_STEP -> FirmwareDownloadExecutor │ │
│ │ AUTH_STEP -> FirmwareCheckExecutor (认证模式) │ │
│ │ INSTALL_STEP -> FirmwareInstallExecutor │ │
│ │ APPLY_STEP -> FirmwareApplyExecutor │ │
│ └────────────────────────────────────────────────────────────────────┘ │
│ │5. 接口设计
5.1 公共接口
IUpdateService 接口
cpp
class IUpdateService : public OHOS::IRemoteBroker {
public:
// 回调注册
virtual int32_t RegisterUpdateCallback(const UpgradeInfo &info,
const sptr<IUpdateCallback>& updateCallback) = 0;
virtual int32_t UnregisterUpdateCallback(const UpgradeInfo &info) = 0;
// 版本检查
virtual int32_t CheckNewVersion(const UpgradeInfo &info) = 0;
virtual int32_t GetNewVersionInfo(const UpgradeInfo &info,
NewVersionInfo &newVersionInfo, BusinessError &businessError) = 0;
virtual int32_t GetNewVersionDescription(const UpgradeInfo &info,
const VersionDigestInfo &versionDigestInfo,
const DescriptionOptions &descriptionOptions,
VersionDescriptionInfo &newVersionDescriptionInfo,
BusinessError &businessError) = 0;
// 当前版本信息
virtual int32_t GetCurrentVersionInfo(const UpgradeInfo &info,
CurrentVersionInfo ¤tVersionInfo, BusinessError &businessError) = 0;
virtual int32_t GetCurrentVersionDescription(const UpgradeInfo &info,
const DescriptionOptions &descriptionOptions,
VersionDescriptionInfo ¤tVersionDescriptionInfo,
BusinessError &businessError) = 0;
// 下载管理
virtual int32_t Download(const UpgradeInfo &info,
const VersionDigestInfo &versionDigestInfo,
const DownloadOptions &downloadOptions, BusinessError &businessError) = 0;
virtual int32_t PauseDownload(const UpgradeInfo &info,
const VersionDigestInfo &versionDigestInfo,
const PauseDownloadOptions &pauseDownloadOptions,
BusinessError &businessError) = 0;
virtual int32_t ResumeDownload(const UpgradeInfo &info,
const VersionDigestInfo &versionDigestInfo,
const ResumeDownloadOptions &resumeDownloadOptions,
BusinessError &businessError) = 0;
// 升级执行
virtual int32_t Upgrade(const UpgradeInfo &info,
const VersionDigestInfo &versionDigest,
const UpgradeOptions &upgradeOptions, BusinessError &businessError) = 0;
virtual int32_t ClearError(const UpgradeInfo &info,
const VersionDigestInfo &versionDigest,
const ClearOptions &clearOptions, BusinessError &businessError) = 0;
virtual int32_t TerminateUpgrade(const UpgradeInfo &info,
BusinessError &businessError) = 0;
// 任务管理
virtual int32_t GetTaskInfo(const UpgradeInfo &info, TaskInfo &taskInfo,
BusinessError &businessError) = 0;
virtual int32_t Cancel(const UpgradeInfo &info, int32_t service,
BusinessError &businessError) = 0;
// 策略管理
virtual int32_t SetUpgradePolicy(const UpgradeInfo &info,
const UpgradePolicy &policy, BusinessError &businessError) = 0;
virtual int32_t GetUpgradePolicy(const UpgradeInfo &info,
UpgradePolicy &policy, BusinessError &businessError) = 0;
// 本地升级
virtual int32_t ApplyNewVersion(const UpgradeInfo &info,
const std::string &miscFile, const std::string &packageName,
BusinessError &businessError) = 0;
virtual int32_t VerifyUpgradePackage(const std::string &packagePath,
const std::string &keyPath, BusinessError &businessError) = 0;
// 恢复出厂
virtual int32_t FactoryReset(BusinessError &businessError) = 0;
};IUpdateCallback 回调接口
cpp
class IUpdateCallback : public OHOS::IRemoteBroker {
public:
// 版本检查完成回调
virtual void OnCheckVersionDone(const BusinessError &businessError,
const CheckResult &checkResult) = 0;
// 事件通知回调
virtual void OnEvent(const EventInfo &eventInfo) = 0;
};接口参数说明
| 接口名称 | 参数 | 返回值 | 异常处理 |
|---|---|---|---|
| CheckNewVersion | UpgradeInfo | int32_t (0成功) | IPC_ERR, PARAM_ERR |
| Download | UpgradeInfo, VersionDigestInfo, DownloadOptions | int32_t | NET_ERROR, IO_ERROR |
| Upgrade | UpgradeInfo, VersionDigestInfo, UpgradeOptions | int32_t | FORBIDDEN, DB_ERROR |
| FactoryReset | - | int32_t | APP_NOT_GRANTED |
5.2 数据交换接口
IPC通信协议
使用OpenHarmony IPC框架进行进程间通信，接口码定义如下：
cpp
enum class UpdaterSaInterfaceCode {
CHECK_VERSION = 1,
DOWNLOAD,
PAUSE_DOWNLOAD,
RESUME_DOWNLOAD,
UPGRADE,
CLEAR_ERROR,
TERMINATE_UPGRADE,
SET_POLICY,
GET_POLICY,
GET_NEW_VERSION,
GET_NEW_VERSION_DESCRIPTION,
GET_CURRENT_VERSION,
GET_CURRENT_VERSION_DESCRIPTION,
GET_TASK_INFO,
REGISTER_CALLBACK,
UNREGISTER_CALLBACK,
CANCEL,
FACTORY_RESET,
APPLY_NEW_VERSION,
VERIFY_UPGRADE_PACKAGE
};数据序列化
使用MessageParcel进行数据序列化：
cpp
class MessageParcelHelper {
public:
static void WriteUpgradeInfo(MessageParcel &data, const UpgradeInfo &info);
static void ReadUpgradeInfo(MessageParcel &data, UpgradeInfo &info);
static void WriteVersionDigestInfo(MessageParcel &data,
const VersionDigestInfo &info);
static void ReadVersionDigestInfo(MessageParcel &data,
VersionDigestInfo &info);
static void WriteBusinessError(MessageParcel &data,
const BusinessError &error);
static void ReadBusinessError(MessageParcel &data, BusinessError &error);
// ... 其他数据结构的序列化方法
};5.3 接口调用时序图
版本检查时序图
Server (Remote) Firmware Module UpdateService UpdateServiceProxy Client (App) Server (Remote) Firmware Module UpdateService UpdateServiceProxy Client (App) CheckNewVersion() IPC Request CheckNewVersion() HTTP Request HTTP Response Check Result IPC Response OnCheckVersionDone(callback)
下载升级包时序图
Server (Remote) Download Executor UpdateService Client (App) Server (Remote) Download Executor UpdateService Client (App) loop [下载过程] Download() Start Download HTTP GET (Range) Data Stream Progress Update OnEvent(DOWNLOAD_UPDATE) Download Complete OnEvent(DOWNLOAD_SUCCESS)
升级执行时序图
Updater Subsystem Install Executor UpdateService Client (App) Updater Subsystem Install Executor UpdateService Client (App) System Reboot... Upgrade() Start Install OnEvent(UPGRADE_START) Verify Package Write to misc Progress Update OnEvent(UPGRADE_UPDATE) Trigger Reboot OnEvent(UPGRADE_SUCCESS)
附录
A. 错误码定义
| 错误码 | 名称 | 描述 |
|---|---|---|
| 0 | SUCCESS | 成功 |
| 100 | FAIL | 失败 |
| 102 | DEV_UPG_INFO_ERR | 设备升级信息错误 |
| 103 | FORBIDDEN | 禁止操作 |
| 104 | IPC_ERR | IPC通信错误 |
| 201 | APP_NOT_GRANTED | 应用未授权 |
| 202 | NOT_SYSTEM_APP | 非系统应用 |
| 401 | PARAM_ERR | 参数错误 |
| 402 | TIME_OUT | 超时 |
| 501 | DB_ERROR | 数据库错误 |
| 502 | IO_ERROR | IO错误 |
| 503 | NET_ERROR | 网络错误 |
| 801 | UN_SUPPORT | 不支持 |
B. 权限要求
| 权限名称 | 描述 |
|---|---|
| ohos.permission.UPDATE_SYSTEM | 系统升级权限 |
| ohos.permission.FACTORY_RESET | 恢复出厂设置权限 |
C. 配置文件
SA配置文件 (3006.json):
json
{
"process": "updater_sa",
"systemability": [
{
"name": 3006,
"libpath": "libupdateservice.z.so",
"run-on-create": true,
"distributed": false,
"dump_level": 1
}
]
}