From 30db1a9874880a1fc1414537be12744d8954bfd5 Mon Sep 17 00:00:00 2001 From: shawn_he Date: Sat, 30 Jul 2022 09:15:14 +0800 Subject: [PATCH] update doc Signed-off-by: shawn_he --- .../reference/apis/js-apis-update.md | 1691 ++++++++++++++--- 1 file changed, 1422 insertions(+), 269 deletions(-) diff --git a/en/application-dev/reference/apis/js-apis-update.md b/en/application-dev/reference/apis/js-apis-update.md index 251c1d59b6..64d76026ee 100644 --- a/en/application-dev/reference/apis/js-apis-update.md +++ b/en/application-dev/reference/apis/js-apis-update.md @@ -1,8 +1,5 @@ # Update -> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE** -> The initial APIs of this module are supported since API version 6. Newly added APIs will be marked with a superscript to indicate their earliest API version. - The Update module applies to updates throughout the entire system, including built-in resources and preset applications, but not third-party applications. There are two types of updates: SD card update and over the air (OTA) update. @@ -10,135 +7,180 @@ There are two types of updates: SD card update and over the air (OTA) update. - The SD card update depends on the update packages and SD cards. - The OTA update depends on the server deployed by the device manufacturer for managing update packages. The OTA server IP address is passed by the caller. The request interface is fixed and developed by the device manufacturer. +> **NOTE** +> +> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. +> +> The APIs provided by this module are system APIs. + ## Modules to Import ```js import update from '@ohos.update' ``` -## Required Permissions - -None - -## update.getUpdater +## update.getOnlineUpdater -getUpdater(upgradeFile: string, updateType?: UpdateTypes): Updater +getOnlineUpdater(upgradeInfo: UpgradeInfo): Updater -Obtains the **Updater** object for local update. +Obtains an **OnlineUpdater** object. **System capability**: SystemCapability.Update.UpdateService **Parameters** -| Name | Type | Mandatory | Description | -| ----------- | --------------------------- | --------- | ------------ | -| upgradeFile | string | Yes | Update file. | -| updateType | [UpdateTypes](#updatetypes) | Yes | Update type. | +| Name | Type | Mandatory | Description | +| ----------- | --------------------------- | ---- | ---- | +| upgradeInfo | [UpgradeInfo](#upgradeinfo) | Yes | **UpgradeInfo** object.| **Return value** -| Type | Description | -| ------------------- | ------------------- | -| [Updater](#updater) | **Updater** object. | +| Type | Description | +| ------------------- | ---- | +| [Updater](#updater) | **OnlineUpdater** object.| **Example** ``` try { - let updater = update.getUpdater('/data/updater/updater.zip', 'OTA'); + var upgradeInfo = { + upgradeApp: "com.ohos.ota.updateclient", + businessType: { + vendor: update.BusinessVendor.PUBLIC, + subType: update.BusinessSubType.FIRMWARE + } + } + let updater = update.getOnlineUpdater(upgradeInfo); } catch(error) { - console.error(" Fail to get updater error: " + error); + console.error(`Fail to get updater error: ${error}`); } ``` -## update.getUpdaterForOther +## update.getRestorer -getUpdaterForOther(upgradeFile: string, device: string, updateType?: UpdateTypes): Updater +getRestorer(): Restorer -Obtains the **Updater** object for the device to be updated. +Obtains a **Restorer** object for restoring factory settings. **System capability**: SystemCapability.Update.UpdateService -**Parameters** - -| Name | Type | Mandatory | Description | -| ----------- | --------------------------- | --------- | --------------------- | -| upgradeFile | string | Yes | Update file. | -| device | string | Yes | Device to be updated. | -| updateType | [UpdateTypes](#updatetypes) | Yes | Update type. | **Return value** -| Type | Description | -| ------------------- | ------------------- | -| [Updater](#updater) | **Updater** object. | +| Type | Description | +| ------------------- | ---- | +| [Restorer](#restorer) | **Restorer** object for restoring factory settings.| **Example** ``` try { - let updater = update.getUpdaterForOther('/data/updater/updater.zip', '1234567890', 'OTA'); + let restorer = update.getRestorer(); } catch(error) { - console.error(" Fail to get updater error: " + error); + console.error(`Fail to get restorer: ${error}`); } ``` -## update.getUpdaterFromOther +## update.getLocalUpdater -getUpdaterFromOther(upgradeFile: string, device: string, updateType?: UpdateTypes): Updater +getLocalUpdater(): LocalUpdater -Obtains the **Updater** object from another device for the device to be updated. +Obtains a **LocalUpdater** object. **System capability**: SystemCapability.Update.UpdateService -**Parameters** - -| Name | Type | Mandatory | Description | -| ----------- | --------------------------- | --------- | --------------------- | -| upgradeFile | string | Yes | Update file. | -| device | string | Yes | Device to be updated. | -| updateType | [UpdateTypes](#updatetypes) | Yes | Update type. | - **Return value** -| Type | Description | -| ------------------- | ------------------- | -| [Updater](#updater) | **Updater** object. | +| Type | Description | +| ------------------- | ---- | +| [LocalUpdater](#localupdater) | **LocalUpdater** object.| **Example** ``` try { - let updater = update.getUpdaterFromOther('/data/updater/updater.zip', '1234567890', 'OTA'); + let localUpdater = update.getLocalUpdater(); } catch(error) { - console.error(" Fail to get updater error: " + error); + console.error(`Fail to get localUpdater error: ${error}`); } ``` ## Updater +### checkNewVersion + +checkNewVersion(callback: AsyncCallback\): void + +Checks whether a new version is available. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Update.UpdateService + +**Required permission**: ohos.permission.UPDATE_SYSTEM (a system permission) + +**Parameters** + +| Name | Type | Mandatory | Description | +| -------- | ---------------------------------------- | ---- | --------- | +| callback | AsyncCallback\<[CheckResult](#checkresult)> | Yes | Callback used to return the result.| + +**Example** + +``` +updater.checkNewVersion((err, result) => { + console.log(`checkNewVersion isExistNewVersion ${result?.isExistNewVersion}`); +}); +``` + +### checkNewVersion + +checkNewVersion(): Promise\ + +Checks whether a new version is available. This API uses a promise to return the result. + +**System capability**: SystemCapability.Update.UpdateService + +**Required permission**: ohos.permission.UPDATE_SYSTEM (a system permission) + +**Return value** + +| Type | Description | +| ---------------------------------------- | ---------------- | +| Promise\<[CheckResult](#checkresult)> | Promise used to return the result.| + +**Example** + +``` +updater.checkNewVersion().then(result => { + console.log(`checkNewVersion isExistNewVersion: ${result.isExistNewVersion}`); + // Version digest information + console.log(`checkNewVersion versionDigestInfo: ${result.newVersionInfo.versionDigestInfo.versionDigest}`); +}).catch(err => { + console.log(`checkNewVersion promise error ${JSON.stringify(err)}`); +}); +``` + ### getNewVersionInfo getNewVersionInfo(callback: AsyncCallback\): void -Obtains the new version information. This function uses an asynchronous callback to return the result. +Obtains information about the new version. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.Update.UpdateService +**Required permission**: ohos.permission.UPDATE_SYSTEM (a system permission) + **Parameters** -| Name | Type | Mandatory | Description | -| -------- | ---------------------------------------- | --------- | ---------------------------------------- | -| callback | AsyncCallback<[NewVersionInfo](#newversioninfo)> | No | Callback used to return the new version information. | +| Name | Type | Mandatory | Description | +| -------- | ---------------------------------------- | ---- | --------- | +| callback | AsyncCallback\<[NewVersionInfo](#newversioninfo)> | Yes | Callback used to return the result.| **Example** ``` -updater.getNewVersionInfo(info => { - console.log("getNewVersionInfo success " + info.status); - console.log(`info versionName = ` + info.checkResult[0].versionName); - console.log(`info versionCode = ` + info.checkResult[0].versionCode); - console.log(`info verifyInfo = ` + info.checkResult[0].verifyInfo); +updater.getNewVersionInfo((err, info) => { + console.log(`info displayVersion = ${info?.versionComponents[0].displayVersion}`); + console.log(`info innerVersion = ${info?.versionComponents[0].innerVersion}`); }); ``` @@ -146,451 +188,1562 @@ updater.getNewVersionInfo(info => { getNewVersionInfo(): Promise\ -Obtains the new version information. This function uses a promise to return the result. +Obtains information about the new version. This API uses a promise to return the result. **System capability**: SystemCapability.Update.UpdateService +**Required permission**: ohos.permission.UPDATE_SYSTEM (a system permission) + **Return value** -| Type | Description | -| ---------------------------------------- | ---------------------------------------- | -| Promise\<[NewVersionInfo](#newversioninfo)> | Promise used to return the new version information. | +| Type | Description | +| ---------------------------------------- | ---------------- | +| Promise\<[NewVersionInfo](#newversioninfo)> | Promise used to return the result.| **Example** ``` -updater.getNewVersionInfo().then(value => { - console.log(`info versionName = ` + value.checkResult[0].versionName); - console.log(`info versionCode = ` + value.checkResult[0].versionCode); - console.log(`info verifyInfo = ` + value.checkResult[0].verifyInfo); +updater.getNewVersionInfo().then(info => { + console.log(`info displayVersion = ${info.versionComponents[0].displayVersion}`); + console.log(`info innerVersion = ${info.versionComponents[0].innerVersion}`); }).catch(err => { - console.log("getNewVersionInfo promise error: " + err.code); + console.log(`getNewVersionInfo promise error ${JSON.stringify(err)}`); }); ``` -### checkNewVersion +### getNewVersionDescription -checkNewVersion(callback: AsyncCallback\): void +getNewVersionDescription(versionDigestInfo: VersionDigestInfo, descriptionOptions: DescriptionOptions, callback: AsyncCallback\>): void -Checks whether the current version is the latest. This function uses an asynchronous callback to return the result. +Obtains the description file of the new version. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.Update.UpdateService +**Required permission**: ohos.permission.UPDATE_SYSTEM (a system permission) + **Parameters** -| Name | Type | Mandatory | Description | -| -------- | ---------------------------------------- | --------- | ---------------------------------------- | -| callback | AsyncCallback\<[NewVersionInfo](#newversioninfo)> | No | Callback used to return the new version information. | +| Name | Type | Mandatory | Description | +| -------- | ---------------------------------------- | ---- | --------- | +| versionDigestInfo | [VersionDigestInfo](#versiondigestinfo) | Yes | Version digest information.| +| descriptionOptions | [DescriptionOptions](#descriptionoptions) | Yes | Options of the description file.| +| callback | AsyncCallback\>) | Yes | Callback used to return the result.| **Example** ``` -updater.checkNewVersion(info => { - console.log("checkNewVersion success " + info.status); - console.log(`info versionName = ` + info.checkResult[0].versionName); - console.log(`info versionCode = ` + info.checkResult[0].versionCode); - console.log(`info verifyInfo = ` + info.checkResult[0].verifyInfo); +// Version digest information +var versionDigestInfo = { + versionDigest: "versionDigest" // Version digest information in the check result +} + +// Options of the description file +var descriptionOptions = { + format: DescriptionFormat.STANDARD, // Standard format + language: "zh-cn" // Chinese +} + +updater.getNewVersionDescription(versionDigestInfo, descriptionOptions, (err, info) => { + console.log(`getNewVersionDescription info ${JSON.stringify(info)}`); + console.log(`getNewVersionDescription err ${JSON.stringify(err)}`); }); ``` -### checkNewVersion +### getNewVersionDescription + +getNewVersionDescription(versionDigestInfo: VersionDigestInfo, descriptionOptions: DescriptionOptions): Promise\>; + +Obtains the description file of the new version. This API uses a promise to return the result. + +**System capability**: SystemCapability.Update.UpdateService + +**Required permission**: ohos.permission.UPDATE_SYSTEM (a system permission) + +**Parameters** + +| Name | Type | Mandatory | Description | +| -------- | ---------------------------------------- | ---- | --------- | +| versionDigestInfo | [VersionDigestInfo](#versiondigestinfo) | Yes | Version digest information.| +| descriptionOptions | [DescriptionOptions](#descriptionoptions) | Yes | Options of the description file.| + +**Return value** + +| Type | Description | +| ---------------------------------------- | ---------------- | +| Promise\> | Promise used to return the result.| + +**Example** -checkNewVersion(): Promise\ +``` +// Version digest information +var versionDigestInfo = { + versionDigest: "versionDigest" // Version digest information in the check result +} + +// Options of the description file +var descriptionOptions = { + format: DescriptionFormat.STANDARD, // Standard format + language: "zh-cn" // Chinese +} + +updater.getNewVersionDescription(versionDigestInfo, descriptionOptions).then(info => { + console.log(`getNewVersionDescription promise info ${JSON.stringify(info)}`); +}).catch(err => { + console.log(`getNewVersionDescription promise error ${JSON.stringify(err)}`); +}); +``` + +### getCurrentVersionInfo + +getCurrentVersionInfo(callback: AsyncCallback\): void + +Obtains information about the current version. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Update.UpdateService + +**Required permission**: ohos.permission.UPDATE_SYSTEM (a system permission) + +**Parameters** -Checks whether the current version is the latest. This function uses a promise to return the result. +| Name | Type | Mandatory | Description | +| -------- | ---------------------------------------- | ---- | --------- | +| callback | AsyncCallback\<[CurrentVersionInfo](#currentversioninfo)> | Yes | Callback used to return the result.| + +**Example** + +``` +updater.getCurrentVersionInfo((err, info) => { + console.log(`info osVersion = ${info?.osVersion}`); + console.log(`info deviceName = ${info?.deviceName}`); + console.log(`info displayVersion = ${info?.versionComponents[0].displayVersion}`); +}); +``` + +### getCurrentVersionInfo + +getCurrentVersionInfo(): Promise\ + +Obtains information about the current version. This API uses a promise to return the result. **System capability**: SystemCapability.Update.UpdateService +**Required permission**: ohos.permission.UPDATE_SYSTEM (a system permission) + **Return value** -| Type | Description | -| ---------------------------------------- | ---------------------------------------- | -| Promise\<[NewVersionInfo](#newversioninfo)> | Promise used to return the new version information. | +| Type | Description | +| ---------------------------------------- | ---------------- | +| Promise\<[CurrentVersionInfo](#currentversioninfo)> | Promise used to return the result.| **Example** ``` -updater.checkNewVersion().then(value => { - console.log(`info versionName = ` + value.checkResult[0].versionName); - console.log(`info versionCode = ` + value.checkResult[0].versionCode); - console.log(`info verifyInfo = ` + value.checkResult[0].verifyInfo); +updater.getCurrentVersionInfo().then(info => { + console.log(`info osVersion = ${info.osVersion}`); + console.log(`info deviceName = ${info.deviceName}`); + console.log(`info displayVersion = ${info.versionComponents[0].displayVersion}`); }).catch(err => { - console.log("checkNewVersion promise error: " + err.code); + console.log(`getCurrentVersionInfo promise error ${JSON.stringify(err)}`); }); ``` -### verifyUpdatePackage +### getCurrentVersionDescription -verifyUpdatePackage(upgradeFile: string, certsFile: string): void +getCurrentVersionDescription(descriptionOptions: DescriptionOptions, callback: AsyncCallback\>): void -Verifies whether the update package is valid. +Obtains the description file of the current version. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.Update.UpdateService +**Required permission**: ohos.permission.UPDATE_SYSTEM (a system permission) + **Parameters** -| Name | Type | Mandatory | Description | -| ----------- | ------ | --------- | ---------------------------------------- | -| upgradeFile | string | Yes | Path of the update package to be verified. | -| certsFile | string | Yes | Certificate path. | +| Name | Type | Mandatory | Description | +| -------- | ---------------------------------------- | ---- | --------- | +| descriptionOptions | [DescriptionOptions](#descriptionoptions) | Yes | Options of the description file.| +| callback | AsyncCallback\>) | Yes | Callback used to return the result.| **Example** ``` -updater.on("verifyProgress", callback => { - console.info('on verifyProgress ' + callback.percent); +// Options of the description file +var descriptionOptions = { + format: DescriptionFormat.STANDARD, // Standard format + language: "zh-cn" // Chinese +} + +updater.getCurrentVersionDescription(descriptionOptions, (err, info) => { + console.log(`getCurrentVersionDescription info ${JSON.stringify(info)}`); + console.log(`getCurrentVersionDescription err ${JSON.stringify(err)}`); }); -update.verifyUpdatePackage("XXX", "XXX"); ``` -### rebootAndCleanUserData8+ +### getCurrentVersionDescription -rebootAndCleanUserData(): Promise\ +getCurrentVersionDescription(descriptionOptions: DescriptionOptions): Promise\> -Reboots the device and clears the user partition data. This function uses a promise to return the result. +Obtains the description file of the current version. This API uses a promise to return the result. **System capability**: SystemCapability.Update.UpdateService +**Required permission**: ohos.permission.UPDATE_SYSTEM (a system permission) + +**Parameters** + +| Name | Type | Mandatory | Description | +| -------- | ---------------------------------------- | ---- | --------- | +| descriptionOptions | [DescriptionOptions](#descriptionoptions) | Yes | Options of the description file.| + **Return value** -| Type | Description | -| ---------------- | ---------------------------------------- | -| Promise\ | Promise used to return the execution result. | +| Type | Description | +| ---------------------------------------- | ---------------- | +| Promise\> | Promise used to return the result.| **Example** ``` -updater.rebootAndCleanUserData().then(result => { - console.log("rebootAndCleanUserData " + result); +// Options of the description file +var descriptionOptions = { + format: DescriptionFormat.STANDARD, // Standard format + language: "zh-cn" // Chinese +} + +updater.getCurrentVersionDescription(descriptionOptions).then(info => { + console.log(`getCurrentVersionDescription promise info ${JSON.stringify(info)}`); }).catch(err => { - console.info("rebootAndCleanUserData promise error: " + err.code); + console.log(`getCurrentVersionDescription promise error ${JSON.stringify(err)}`); }); ``` -### rebootAndCleanUserData8+ +### getTaskInfo -rebootAndCleanUserData(callback: AsyncCallback\): void +getTaskInfo(callback: AsyncCallback\): void -Reboots the device and clears the user partition data. This function uses a promise to return the result. +Obtains information about the update task. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.Update.UpdateService +**Required permission**: ohos.permission.UPDATE_SYSTEM (a system permission) + **Parameters** -| Name | Type | Mandatory | Description | -| -------- | ---------------------- | --------- | ---------------------------------------- | -| callback | AsyncCallback\ | Yes | Callback used to return the execution result. | +| Name | Type | Mandatory | Description | +| -------- | ---------------------------------------- | ---- | --------- | +| callback | AsyncCallback\<[TaskInfo](#taskinfo)> | Yes | Callback used to return the result.| **Example** ``` -updater.rebootAndCleanUserData(result => { - console.log("rebootAndCleanUserData ", result) +updater.getTaskInfo((err, info) => { + console.log(`getTaskInfo isexistTask= ${info?.existTask}`); }); ``` -### applyNewVersion +### getTaskInfo -applyNewVersion(): Promise\ +getTaskInfo(): Promise\ -Installs the update package. This function uses a promise to return the result. +Obtains information about the update task. This API uses a promise to return the result. **System capability**: SystemCapability.Update.UpdateService +**Required permission**: ohos.permission.UPDATE_SYSTEM (a system permission) + **Return value** -| Type | Description | -| ---------------- | ---------------------------------------- | -| Promise\ | Promise used to return the execution result. | +| Type | Description | +| ---------------------------------------- | ---------------- | +| Promise\<[TaskInfo](#taskinfo)> | Promise used to return the result.| **Example** ``` -updater.applyNewVersion().then(result => { - console.log("appVewVersion ", result) +updater.getTaskInfo().then(info => { + console.log(`getTaskInfo isexistTask= ${info.existTask}`); }).catch(err => { - console.info("applyNewVersion promise error: " + err.code); + console.log(`getTaskInfo promise error ${JSON.stringify(err)}`); }); ``` -### applyNewVersion +### download -applyNewVersion(callback: AsyncCallback\): void +download(versionDigestInfo: VersionDigestInfo, downloadOptions: DownloadOptions, callback: AsyncCallback\): void -Installs the update package. This function uses a promise to return the result. +Downloads the new version. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.Update.UpdateService +**Required permission**: ohos.permission.UPDATE_SYSTEM (a system permission) + **Parameters** -| Name | Type | Mandatory | Description | -| -------- | ---------------------- | --------- | ---------------------------------------- | -| callback | AsyncCallback\ | Yes | Callback used to return the execution result. | +| Name | Type | Mandatory | Description | +| -------- | ---------------------------------------- | ---- | --------- | +| versionDigestInfo | [VersionDigestInfo](#versiondigestinfo) | Yes | Version digest information.| +| downloadOptions | [DownloadOptions](#downloadoptions) | Yes | Download options.| +| callback | AsyncCallback\ | Yes | Callback used to return the result. If the operation is successful, `err` is `undefined`; otherwise, `err` is an `Error` object.| **Example** ``` -updater.applyNewVersion(result => { - console.log("applyNewVersion ", result) +// Version digest information +var versionDigestInfo = { + versionDigest: "versionDigest" // Version digest information in the check result +} + +// Download options +var downloadOptions = { + allowNetwork: update.NetType.CELLULAR, // Whether to allow download over data network + order: update.Order.DOWNLOAD // Download +} +updater.download(versionDigestInfo, downloadOptions, (err) => { + console.log(`download error ${JSON.stringify(err)}`); }); ``` ### download -download(): void +download(versionDigestInfo: VersionDigestInfo, downloadOptions: DownloadOptions): Promise\ -Downloads the new version and displays the download process. +Downloads the new version. This API uses a promise to return the result. **System capability**: SystemCapability.Update.UpdateService +**Required permission**: ohos.permission.UPDATE_SYSTEM (a system permission) + +**Parameters** + +| Name | Type | Mandatory | Description | +| -------- | ---------------------------------------- | ---- | --------- | +| versionDigestInfo | [VersionDigestInfo](#versiondigestinfo) | Yes | Version digest information.| +| downloadOptions | [DownloadOptions](#downloadoptions) | Yes | Download options.| + +**Return value** + +| Type | Description | +| ---------------------------------------- | ---------------- | +| Promise\ | Promise that returns no value.| + **Example** ``` -updater.on("downloadProgress", progress => { - console.log("downloadProgress on" + progress); - console.log(`downloadProgress status: ` + progress.status); - console.log(`downloadProgress percent: ` + progress.percent); +// Version digest information +var versionDigestInfo = { + versionDigest: "versionDigest" // Version digest information in the check result +} + +// Download options +var downloadOptions = { + allowNetwork: update.NetType.CELLULAR, // Whether to allow download over data network + order: update.Order.DOWNLOAD // Download +} +updater.download(versionDigestInfo, downloadOptions).then(() => { + console.log(`download start`); +}).catch(err => { + console.log(`download error ${JSON.stringify(err)}`); }); -updater.download(); ``` -### upgrade +### resumeDownload + +resumeDownload(versionDigestInfo: VersionDigestInfo, resumeDownloadOptions: ResumeDownloadOptions, callback: AsyncCallback\): void + +Resumes download of the new version. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Update.UpdateService + +**Required permission**: ohos.permission.UPDATE_SYSTEM (a system permission) + +**Parameters** + +| Name | Type | Mandatory | Description | +| -------- | ---------------------------------------- | ---- | --------- | +| versionDigestInfo | [VersionDigestInfo](#versiondigestinfo) | Yes | Version digest information.| +| resumeDownloadOptions | [ResumeDownloadOptions](#resumedownloadoptions) | Yes | Options for resuming download.| +| callback | AsyncCallback\ | Yes | Callback used to return the result. If the operation is successful, `err` is `undefined`; otherwise, `err` is an `Error` object.| + +**Example** + +``` +// Version digest information +var versionDigestInfo = { + versionDigest: "versionDigest" // Version digest information in the check result +} + +// Options for resuming download +var resumeDownloadOptions = { + allowNetwork: update.NetType.CELLULAR, // Whether to allow download over data network +} +updater.resumeDownload(versionDigestInfo, resumeDownloadOptions, (err) => { + console.log(`resumeDownload error ${JSON.stringify(err)}`); +}); +``` -upgrade():void +### resumeDownload -Starts an update. +resumeDownload(versionDigestInfo: VersionDigestInfo, resumeDownloadOptions: ResumeDownloadOptions): Promise\ + +Resumes download of the new version. This API uses a promise to return the result. **System capability**: SystemCapability.Update.UpdateService +**Required permission**: ohos.permission.UPDATE_SYSTEM (a system permission) + +**Parameters** + +| Name | Type | Mandatory | Description | +| -------- | ---------------------------------------- | ---- | --------- | +| versionDigestInfo | [VersionDigestInfo](#versiondigestinfo) | Yes | Version digest information.| +| resumeDownloadOptions | [ResumeDownloadOptions](#resumedownloadoptions) | Yes | Options for resuming download.| + +**Return value** + +| Type | Description | +| ---------------------------------------- | ---------------- | +| Promise\ | Promise that returns no value.| + **Example** ``` -updater.on("upgradeProgress", progress => { - console.log("upgradeProgress on" + progress); - console.log(`upgradeProgress status: ` + progress.status); - console.log(`upgradeProgress percent: ` + progress.percent); +// Version digest information +var versionDigestInfo = { + versionDigest: "versionDigest" // Version digest information in the check result +} + +// Options for resuming download +var resumeDownloadOptions = { + allowNetwork: update.NetType.CELLULAR, // Whether to allow download over data network +} +updater.resumeDownload(versionDigestInfo, resumeDownloadOptions).then(value => { + console.log(`resumeDownload start`); +}).catch(err => { + console.log(`resumeDownload error ${JSON.stringify(err)}`); }); -updater.upgrade(); ``` -### setUpdatePolicy +### pauseDownload -setUpdatePolicy(policy: UpdatePolicy, callback: AsyncCallback\): void +pauseDownload(versionDigestInfo: VersionDigestInfo, pauseDownloadOptions: PauseDownloadOptions, callback: AsyncCallback\): void -Sets the update policy. This function uses an asynchronous callback to return the result. +Pauses download of the new version. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.Update.UpdateService +**Required permission**: ohos.permission.UPDATE_SYSTEM (a system permission) + **Parameters** -| Name | Type | Mandatory | Description | -| -------- | ---------------------------------------- | --------- | ---------------------------------------- | -| policy | [UpdatePolicy](#updatepolicy) | Yes | Update policy to set. | -| callback | Callback used to return the execution result. | Yes | Callback used to return the execution result. | +| Name | Type | Mandatory | Description | +| -------- | ---------------------------------------- | ---- | --------- | +| versionDigestInfo | [VersionDigestInfo](#versiondigestinfo) | Yes | Version digest information.| +| pauseDownloadOptions | [PauseDownloadOptions](#pausedownloadoptions) | Yes | Options for pausing download.| +| callback | AsyncCallback\ | Yes | Callback used to return the result. If the operation is successful, `err` is `undefined`; otherwise, `err` is an `Error` object.| **Example** ``` -// Set the update policy. -let policy = { - autoDownload: false, - autoDownloadNet: true, - mode: 2, - autoUpgradeInterval: [ 2, 3 ], - autoUpgradeCondition: 2 +// Version digest information +var versionDigestInfo = { + versionDigest: "versionDigest" // Version digest information in the check result +} + +// Options for pausing download +var pauseDownloadOptions = { + isAllowAutoResume: true // Whether to allow automatic resuming of download } -updater.setUpdatePolicy(policy, result => { - console.log("setUpdatePolicy ", result) +updater.pauseDownload(versionDigestInfo, pauseDownloadOptions, (err) => { + console.log(`pauseDownload error ${JSON.stringify(err)}`); }); ``` -### setUpdatePolicy +### pauseDownload -setUpdatePolicy(policy: UpdatePolicy): Promise\ +pauseDownload(versionDigestInfo: VersionDigestInfo, pauseDownloadOptions: PauseDownloadOptions): Promise\ -Sets the update policy. This function uses a promise to return the result. +Resumes download of the new version. This API uses a promise to return the result. **System capability**: SystemCapability.Update.UpdateService +**Required permission**: ohos.permission.UPDATE_SYSTEM (a system permission) + **Parameters** -| Name | Type | Mandatory | Description | -| ------ | ----------------------------- | --------- | --------------------- | -| policy | [UpdatePolicy](#updatepolicy) | Yes | Update policy to set. | +| Name | Type | Mandatory | Description | +| -------- | ---------------------------------------- | ---- | --------- | +| versionDigestInfo | [VersionDigestInfo](#versiondigestinfo) | Yes | Version digest information.| +| pauseDownloadOptions | [PauseDownloadOptions](#pausedownloadoptions) | Yes | Options for pausing download.| **Return value** -| Type | Description | -| ---------------- | ---------------------------------------- | -| Promise\ | Promise used to return the execution result. | +| Type | Description | +| ---------------------------------------- | ---------------- | +| Promise\ | Promise that returns no value.| **Example** ``` -let policy = { - autoDownload: false, - autoDownloadNet: true, - mode: 2, - autoUpgradeInterval: [ 2, 3 ], - autoUpgradeCondition: 2 +// Version digest information +var versionDigestInfo = { + versionDigest: "versionDigest" // Version digest information in the check result +} + +// Options for pausing download +var pauseDownloadOptions = { + isAllowAutoResume: true // Whether to allow automatic resuming of download } -updater.setUpdatePolicy(policy).then(result => - console.log("setUpdatePolicy ", result) -).catch(err => { - console.log("setUpdatePolicy promise error: " + err.code); +updater.pauseDownload(versionDigestInfo, pauseDownloadOptions).then(value => { + console.log(`pauseDownload`); +}).catch(err => { + console.log(`pauseDownload error ${JSON.stringify(err)}`); }); ``` -### getUpdatePolicy +### upgrade -getUpdatePolicy(callback: AsyncCallback\): void +upgrade(versionDigestInfo: VersionDigestInfo, upgradeOptions: UpgradeOptions, callback: AsyncCallback\): void -Obtains the update policy. This function uses an asynchronous callback to return the result. +Updates the version. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.Update.UpdateService +**Required permission**: ohos.permission.UPDATE_SYSTEM (a system permission) + **Parameters** -| Name | Type | Mandatory | Description | -| -------- | ---------------------------------------- | --------- | ---------------------------------------- | -| callback | AsyncCallback\<[UpdatePolicy](#updatepolicy)> | No | Callback used to return the update policy. | +| Name | Type | Mandatory | Description | +| -------- | ---------------------------------------- | ---- | --------- | +| versionDigestInfo | [VersionDigestInfo](#versiondigestinfo) | Yes | Version digest information.| +| upgradeOptions | [UpgradeOptions](#upgradeoptions) | Yes | Update options.| +| callback | AsyncCallback\ | Yes | Callback used to return the result. If the operation is successful, `err` is `undefined`; otherwise, `err` is an `Error` object.| **Example** ``` -updater.getUpdatePolicy(policy => { - console.log("getUpdatePolicy success"); - console.log(`policy autoDownload = ` + policy.autoDownload); - console.log(`policy autoDownloadNet = ` + policy.autoDownloadNet); - console.log(`policy mode = ` + policy.mode); +// Version digest information +var versionDigestInfo = { + versionDigest: "versionDigest" // Version digest information in the check result +} + +// Installation options +var upgradeOptions = { + order: update.Order.INSTALL // Installation command +} +updater.upgrade(versionDigestInfo, upgradeOptions, (err) => { + console.log(`upgrade error ${JSON.stringify(err)}`); }); ``` -### getUpdatePolicy +### upgrade -getUpdatePolicy(): Promise\ +upgrade(versionDigestInfo: VersionDigestInfo, upgradeOptions: UpgradeOptions): Promise\ -Obtains the update policy. This function uses a promise to return the result. +Updates the version. This API uses a promise to return the result. **System capability**: SystemCapability.Update.UpdateService +**Required permission**: ohos.permission.UPDATE_SYSTEM (a system permission) + +**Parameters** + +| Name | Type | Mandatory | Description | +| -------- | ---------------------------------------- | ---- | --------- | +| versionDigestInfo | [VersionDigestInfo](#versiondigestinfo) | Yes | Version digest information.| +| upgradeOptions | [UpgradeOptions](#upgradeoptions) | Yes | Update options.| + **Return value** -| Type | Description | -| --------------------------------------- | ---------------------------------------- | -| Promise\<[UpdatePolicy](#updatepolicy)> | Promise used to return the update policy. | +| Type | Description | +| ---------------------------------------- | ---------------- | +| Promise\ | Promise that returns no value.| **Example** ``` -updater.getUpdatePolicy().then(value => { - console.log(`info autoDownload = ` + value.autoDownload); - console.log(`info autoDownloadNet = ` + value.autoDownloadNet); - console.log(`info mode = ` + value.mode); +// Version digest information +var versionDigestInfo = { + versionDigest: "versionDigest" // Version digest information in the check result +} + +// Installation options +var upgradeOptions = { + order: update.Order.INSTALL // Installation command +} +updater.upgrade(versionDigestInfo, upgradeOptions).then(() => { + console.log(`upgrade start`); }).catch(err => { - console.log("getUpdatePolicy promise error: " + err.code); + console.log(`upgrade error ${JSON.stringify(err)}`); }); ``` -## UpdateTypes +### clearError + +clearError(versionDigestInfo: VersionDigestInfo, clearOptions: ClearOptions, callback: AsyncCallback\): void -Enumerates update types. +Clears errors. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.Update.UpdateService -| Name | Description | -| ----- | ------------- | -| OTA | OTA update. | -| patch | Patch update. | +**Required permission**: ohos.permission.UPDATE_SYSTEM (a system permission) + +**Parameters** + +| Name | Type | Mandatory | Description | +| -------- | ---------------------------------------- | ---- | --------- | +| versionDigestInfo | [VersionDigestInfo](#versiondigestinfo) | Yes | Version digest information.| +| clearOptions | [ClearOptions](#clearoptions) | Yes | Clear options.| +| callback | AsyncCallback\ | Yes | Callback used to return the result. If the operation is successful, `err` is `undefined`; otherwise, `err` is an `Error` object.| + +**Example** + +``` +// Version digest information +var versionDigestInfo = { + versionDigest: "versionDigest" // Version digest information in the check result +} + +// Options for clearing errors +var clearOptions = { + status: update.UpgradeStatus.UPGRADE_FAIL, +} +updater.clearError(versionDigestInfo, clearOptions, (err) => { + console.log(`clearError error ${JSON.stringify(err)}`); +}); +``` -## PackageTypes +### clearError -Enumerates update package types. +clearError(versionDigestInfo: VersionDigestInfo, clearOptions: ClearOptions): Promise\ + +Clears errors. This API uses a promise to return the result. **System capability**: SystemCapability.Update.UpdateService -| Name | Default Value | Description | -| -------------------- | ------------- | --------------------------------------- | -| PACKAGE_TYPE_NORMAL | 1 | Common update package. | -| PACKAGE_TYPE_BASE | 2 | Basic update package. | -| PACKAGE_TYPE_CUST | 3 | Custom update package. | -| PACKAGE_TYPE_PRELOAD | 4 | Preinstalled update package. | -| PACKAGE_TYPE_COTA | 5 | Parameter configuration update package. | -| PACKAGE_TYPE_VERSION | 6 | Version update package. | -| PACKAGE_TYPE_PATCH | 7 | Patch package. | +**Required permission**: ohos.permission.UPDATE_SYSTEM (a system permission) + +**Parameters** + +| Name | Type | Mandatory | Description | +| -------- | ---------------------------------------- | ---- | --------- | +| versionDigestInfo | [VersionDigestInfo](#versiondigestinfo) | Yes | Version digest information.| +| clearOptions | [ClearOptions](#clearoptions) | Yes | Update options.| + +**Return value** + +| Type | Description | +| ---------------------------------------- | ---------------- | +| Promise\ | Promise that returns no value.| + +**Example** + +``` +// Version digest information +var versionDigestInfo = { + versionDigest: "versionDigest" // Version digest information in the check result +} + +// Options for clearing errors +var clearOptions = { + status: update.UpgradeStatus.UPGRADE_FAIL, +} +updater.clearError(versionDigestInfo, clearOptions).then(() => { + console.log(`clearError success`); +}).catch(err => { + console.log(`clearError error ${JSON.stringify(err)}`); +}); +``` + +### getUpgradePolicy -## InstallMode +getUpgradePolicy(callback: AsyncCallback\): void -Enumerates update modes. +Obtains the update policy. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.Update.UpdateService -| Name | Default Value | Description | -| ------------------- | ------------- | ----------------- | -| INSTALL_MODE_NORMAL | 0 | Normal update. | -| INSTALL_MODE_NIGHT | 1 | Update at night. | -| INSTALL_MODE_AUTO | 2 | Automatic update. | +**Required permission**: ohos.permission.UPDATE_SYSTEM (a system permission) + +**Parameters** + +| Name | Type | Mandatory | Description | +| -------- | ---------------------------------------- | ---- | ---------- | +| callback | AsyncCallback\<[UpgradePolicy](#upgradepolicy)> | Yes | Callback used to return the result.| + +**Example** + +``` +updater.getUpgradePolicy((err, policy) => { + console.log(`policy downloadStrategy = ${policy?.downloadStrategy}`); + console.log(`policy autoUpgradeStrategy = ${policy?.autoUpgradeStrategy}`); +}); +``` + +### getUpgradePolicy -## NewVersionStatus +getUpgradePolicy(): Promise\ -Enumerates new version check results. +Obtains the update policy. This API uses a promise to return the result. **System capability**: SystemCapability.Update.UpdateService -| Name | Default Value | Description | -| ------------------- | ------------- | ---------------------------------------- | -| VERSION_STATUS_ERR | -1 | System error while checking for the new version. | -| VERSION_STATUS_NEW | 0 | New version detected. | -| VERSION_STATUS_NONE | 1 | No new version detected. | -| VERSION_STATUS_BUSY | 2 | System busy while checking for the new version. | +**Required permission**: ohos.permission.UPDATE_SYSTEM (a system permission) + +**Return value** + +| Type | Description | +| --------------------------------------- | ----------------- | +| Promise\<[UpgradePolicy](#upgradepolicy)> | Promise used to return the result.| + +**Example** + +``` +updater.getUpgradePolicy().then(policy => { + console.log(`policy downloadStrategy = ${policy.downloadStrategy}`); + console.log(`policy autoUpgradeStrategy = ${policy.autoUpgradeStrategy}`); +}).catch(err => { + console.log(`getUpgradePolicy promise error ${JSON.stringify(err)}`); +}); +``` -## UpdatePolicy +### setUpgradePolicy -Defines the update policy. +setUpgradePolicy(policy: UpgradePolicy, callback: AsyncCallback\): void + +Sets the update policy. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.Update.UpdateService -| Name | Type | Mandatory | Description | -| ------------------- | --------------------------- | --------- | ------------------------------------ | -| autoDownload | bool | Yes | Automatic update switch. | -| installMode | [InstallMode](#installmode) | Yes | Update mode. | -| autoUpgradeInterval | Array\ | Yes | Period of time for automatic update. | +**Required permission**: ohos.permission.UPDATE_SYSTEM (a system permission) -## NewVersionInfo +**Parameters** + +| Name | Type | Mandatory | Description | +| -------- | ---------------------------------------- | ---- | ---------- | +| policy | [UpgradePolicy](#upgradepolicy) | Yes | Update policy.| +| callback | AsyncCallback\ | Yes | Callback used to return the result.| -Defines the new version information. +**Example** + +``` +let policy = { + downloadStrategy: false, + autoUpgradeStrategy: false, + autoUpgradePeriods: [ { start: 120, end: 240 } ] // Automatic update period, in minutes +} +updater.setUpgradePolicy(policy, (err) => { + console.log(`setUpgradePolicy result: ${err}`); +}); +``` + +### setUpgradePolicy + +setUpgradePolicy(policy: UpgradePolicy): Promise\ + +Sets the update policy. This API uses a promise to return the result. **System capability**: SystemCapability.Update.UpdateService -| Name | Type | Mandatory | Description | -| --------------- | ---------------------------------------- | --------- | -------------------------------- | -| status | [NewVersionStatus](#newversionstatus) | Yes | Update status. | -| errMsg | string | Yes | Error message. | -| checkResults | Array<[CheckResult](#checkresult)> | Yes | Version check result. | -| descriptionInfo | Array\<[DescriptionInfo](#descriptioninfo)> | Yes | Version description information. | +**Required permission**: ohos.permission.UPDATE_SYSTEM (a system permission) -## CheckResult +**Parameters** + +| Name | Type | Mandatory | Description | +| ------ | ----------------------------- | ---- | ------ | +| policy | [UpgradePolicy](#upgradepolicy) | Yes | Update policy.| + +**Return value** + +| Type | Description | +| ---------------- | --------------- | +| Promise\ | Promise used to return the result.| -Defines the version check result. +**Example** + +``` +let policy = { + downloadStrategy: false, + autoUpgradeStrategy: false, + autoUpgradePeriods: [ { start: 120, end: 240 } ] // Automatic update period, in minutes +} +updater.setUpgradePolicy(policy).then(() => { + console.log(`setUpgradePolicy success`); +}).catch(err => { + console.log(`setUpgradePolicy promise error ${JSON.stringify(err)}`); +}); +``` + +### terminateUpgrade + +terminateUpgrade(callback: AsyncCallback\): void + +Terminates the update. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.Update.UpdateService -| Name | Type | Mandatory | Description | -| ------------- | ----------------------------- | --------- | --------------------------------- | -| versionName | string | Yes | Version name. | -| versionCode | number | Yes | Version code. | -| size | number | Yes | Version size. | -| verifyInfo | string | Yes | Version verification information. | -| packageType | [PackageTypes](#packagetypes) | Yes | Version type. | -| descriptionId | string | Yes | Version description information. | +**Required permission**: ohos.permission.UPDATE_SYSTEM (a system permission) -## DescriptionInfo +**Parameters** + +| Name | Type | Mandatory | Description | +| -------- | ---------------------------------------- | ---- | --------- | +| callback | AsyncCallback\ | Yes | Callback used to return the result. If the operation is successful, `err` is `undefined`; otherwise, `err` is an `Error` object.| + +**Example** + +``` +updater.terminateUpgrade((err) => { + console.log(`terminateUpgrade error ${JSON.stringify(err)}`); +}); +``` + +### terminateUpgrade + +terminateUpgrade(): Promise\ + +Terminates the update. This API uses a promise to return the result. + +**System capability**: SystemCapability.Update.UpdateService + +**Required permission**: ohos.permission.UPDATE_SYSTEM (a system permission) + +**Return value** + +| Type | Description | +| ---------------------------------------- | ---------------- | +| Promise\ | Promise that returns no value.| + +**Example** + +``` +updater.terminateUpgrade().then(() => { + console.log(`terminateUpgrade success`); +}).catch(err => { + console.log(`terminateUpgrade error ${JSON.stringify(err)}`); +}); +``` + + +### on +on(eventClassifyInfo: EventClassifyInfo, taskCallback: UpgradeTaskCallback): void + +Enables listening for update events. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Update.UpdateService + +**Parameters** + +| Name | Type | Mandatory | Description | +| -------- | ---------------------------------------- | ---- | --------- | +| eventClassifyInfo | [EventClassifyInfo](#eventclassifyinfo) | Yes | Event information.| +| taskCallback | [UpgradeTaskCallback](#upgradetaskcallback) | Yes | Event callback.| + +**Example** + +``` +var eventClassifyInfo = { + eventClassify: update.EventClassify.TASK, // Listening for update events + extraInfo: "" +} + +updater.on(eventClassifyInfo, (eventInfo) => { + console.log("updater on " + JSON.stringify(eventInfo)); +}); +``` + +### off +off(eventClassifyInfo: EventClassifyInfo, taskCallback?: UpgradeTaskCallback): void + +Disables listening for update events. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Update.UpdateService + +**Parameters** + +| Name | Type | Mandatory | Description | +| -------- | ---------------------------------------- | ---- | --------- | +| eventClassifyInfo | [EventClassifyInfo](#eventclassifyinfo) | Yes | Event information.| +| taskCallback | [UpgradeTaskCallback](#upgradetaskcallback) | No | Event callback.| + +**Example** + +``` +var eventClassifyInfo = { + eventClassify: update.EventClassify.TASK, // Listening for update events + extraInfo: "" +} + +updater.off(eventClassifyInfo, (eventInfo) => { + console.log("updater off " + JSON.stringify(eventInfo)); +}); +``` + +## Restorer + +### factoryReset + +factoryReset(callback: AsyncCallback\): void + +Restores factory settings. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Update.UpdateService + +**Required permission**: ohos.permission.FACTORY_RESET (a system permission) + +**Parameters** + +| Name | Type | Mandatory | Description | +| -------- | ---------------------------------------- | ---- | --------- | +| callback | AsyncCallback\ | Yes | Callback used to return the result. If the operation is successful, `err` is `undefined`; otherwise, `err` is an `Error` object.| + +**Example** + +``` +restorer.factoryReset((err) => { + console.log(`factoryReset error ${JSON.stringify(err)}`); +}); +``` + +### factoryReset + +factoryReset(): Promise\ + +Restores factory settings. This API uses a promise to return the result. + +**System capability**: SystemCapability.Update.UpdateService + +**Required permission**: ohos.permission.FACTORY_RESET (a system permission) + +**Return value** + +| Type | Description | +| ---------------------------------------- | ---------------- | +| Promise\ | Promise that returns no value.| + +**Example** + +``` +restorer.factoryReset().then(() => { + console.log(`factoryReset success`); +}).catch(err => { + console.log(`factoryReset error ${JSON.stringify(err)}`); +}); +``` + +## LocalUpdater + +### verifyUpgradePackage + +verifyUpgradePackage(upgradeFile: UpgradeFile, certsFile: string, callback: AsyncCallback\): void + +Verifies the update package. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Update.UpdateService + +**Required permission**: ohos.permission.UPDATE_SYSTEM (a system permission) + +**Parameters** + +| Name | Type | Mandatory | Description | +| -------- | ---------------------------------------- | ---- | --------- | +| upgradeFile | [UpgradeFile](#upgradefile) | Yes | Update file.| +| certsFile | string | Yes | Path of the certificate file.| +| callback | AsyncCallback\ | Yes | Callback used to return the result.| + +**Example** + +``` +var upgradeFile = { + fileType: update.ComponentType.OTA, // OTA package + filePath: "path" // Path of the local update package +} + +localUpdater.verifyUpgradePackage(upgradeFile, "cerstFilePath", (err) => { + console.log(`factoryReset error ${JSON.stringify(err)}`); +}); +``` + +### verifyUpgradePackage + +verifyUpgradePackage(upgradeFile: UpgradeFile, certsFile: string): Promise\ + +Verifies the update package. This API uses a promise to return the result. + +**System capability**: SystemCapability.Update.UpdateService + +**Required permission**: ohos.permission.UPDATE_SYSTEM (a system permission) + +**Parameters** + +| Name | Type | Mandatory | Description | +| -------- | ---------------------------------------- | ---- | --------- | +| upgradeFile | [UpgradeFile](#upgradefile) | Yes | Update file.| +| certsFile | string | Yes | Path of the certificate file.| + +**Return value** + +| Type | Description | +| ---------------------------------------- | ---------------- | +| Promise\ | Promise used to return the result.| + +**Example** + +``` +var upgradeFile = { + fileType: update.ComponentType.OTA, // OTA package + filePath: "path" // Path of the local update package +} +localUpdater.verifyUpgradePackage(upgradeFile, "cerstFilePath").then(() => { + console.log(`verifyUpgradePackage success`); +}).catch(err => { + console.log(`verifyUpgradePackage error ${JSON.stringify(err)}`); +}); +``` + +### applyNewVersion +applyNewVersion(upgradeFiles: Array<[UpgradeFile](#upgradefile)>, callback: AsyncCallback\): void + +Installs the update package. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Update.UpdateService + +**Required permission**: ohos.permission.UPDATE_SYSTEM (a system permission) + +**Parameters** + +| Name | Type | Mandatory | Description | +| -------- | ---------------------------------------- | ---- | --------- | +| upgradeFile | Array<[UpgradeFile](#upgradefile)> | Yes | Update file.| +| callback | AsyncCallback\ | Yes | Callback used to return the result. If the operation is successful, `err` is `undefined`; otherwise, `err` is an `Error` object.| + +**Example** + +``` +var upgradeFiles = [{ + fileType: update.ComponentType.OTA, // OTA package + filePath: "path" // Path of the local update package +}] + +localUpdater.applyNewVersion(upgradeFiles, (err) => { + console.log(`applyNewVersion error ${JSON.stringify(err)}`); +}); +``` + +### applyNewVersion + +applyNewVersion(upgradeFiles: Array<[UpgradeFile](#upgradefile)>): Promise\ + +Installs the update package. This API uses a promise to return the result. + +**System capability**: SystemCapability.Update.UpdateService + +**Required permission**: ohos.permission.UPDATE_SYSTEM (a system permission) + +**Return value** + +| Type | Description | +| ---------------------------------------- | ---------------- | +| Promise\ | Promise that returns no value.| + +**Example** + +``` +var upgradeFiles = [{ + fileType: update.ComponentType.OTA, // OTA package + filePath: "path" // Path of the local update package +}] +localUpdater.applyNewVersion(upgradeFiles).then(() => { + console.log(`applyNewVersion success`); +}).catch(err => { + console.log(`applyNewVersion error ${JSON.stringify(err)}`); +}); +``` + +### on +on(eventClassifyInfo: EventClassifyInfo, taskCallback: UpgradeTaskCallback): void + +Enables listening for update events. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Update.UpdateService + +**Parameters** + +| Name | Type | Mandatory | Description | +| -------- | ---------------------------------------- | ---- | --------- | +| eventClassifyInfo | [EventClassifyInfo](#eventclassifyinfo) | Yes | Event information.| +| taskCallback | [UpgradeTaskCallback](#upgradetaskcallback) | Yes | Event callback.| + +**Example** + +``` +var eventClassifyInfo = { + eventClassify: update.EventClassify.TASK, // Listening for update events + extraInfo: "" +} + +function onTaskUpdate(eventInfo) { + console.log(`on eventInfo id `, eventInfo.eventId); +} + +localUpdater.on(eventClassifyInfo, onTaskUpdate); +``` + +### off +off(eventClassifyInfo: EventClassifyInfo, taskCallback?: UpgradeTaskCallback): void + +Disables listening for update events. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Update.UpdateService + +**Parameters** + +| Name | Type | Mandatory | Description | +| -------- | ---------------------------------------- | ---- | --------- | +| eventClassifyInfo | [EventClassifyInfo](#eventclassifyinfo) | Yes | Event information.| +| taskCallback | [UpgradeTaskCallback](#upgradetaskcallback) | Yes | Event callback.| + +**Example** + +``` +var eventClassifyInfo = { + eventClassify: update.EventClassify.TASK, // Listening for update events + extraInfo: "" +} + +function onTaskUpdate(eventInfo) { + console.log(`on eventInfo id `, eventInfo.eventId); +} + +localUpdater.off(eventClassifyInfo, onTaskUpdate); +``` + +## UpgradeInfo + +Represents update information. + +**System capability**: SystemCapability.Update.UpdateService + +| Name | Type | Mandatory | Description | +| ------------------- | --------------------------- | ---- | ------- | +| upgradeApp | string | Yes | Application package name. | +| businessType | [BusinessType](#businesstype) | Yes | Update service type. | + +## BusinessType + +Enumerates update service types. + +**System capability**: SystemCapability.Update.UpdateService + +| Name | Type | Mandatory | Description | +| ------------------- | --------------------------- | ---- | ------- | +| vendor | [BusinessVendor](#businessvendor) | Yes | Application vendor. | +| subType | [BusinessSubType](#businesssubtype) | Yes | Update service sub-type. | + +## CheckResult + +Represents the package check result. + +**System capability**: SystemCapability.Update.UpdateService + +| Name | Type | Mandatory | Description | +| ------------------- | --------------------------- | ---- | ------- | +| isExistNewVersion | bool | Yes | Whether a new version is available. | +| newVersionInfo | [NewVersionInfo](#newversioninfo) | No | Information about the new version. | + +## NewVersionInfo + +Represents information about the new version. + +**System capability**: SystemCapability.Update.UpdateService + +| Name | Type | Mandatory | Description | +| ------------------- | --------------------------- | ---- | ------- | +| versionDigestInfo | [VersionDigestInfo](#versiondigestinfo) | Yes | Version digest information. | +| versionComponents | Array\<[VersionComponent](#versioncomponent)> | Yes | Version components. | + +## VersionDigestInfo + +Represents version digest information. + +**System capability**: SystemCapability.Update.UpdateService + +| Name | Type | Mandatory | Description | +| ------------------- | --------------------------- | ---- | ------- | +| versionDigest | string | Yes | Version digest information. | + +## VersionComponent + +Represents a version component. + +**System capability**: SystemCapability.Update.UpdateService + +| Name | Type | Mandatory | Description | +| ------------------- | --------------------------- | ---- | ------- | +| componentId | number | Yes | Component ID. | +| componentType | [ComponentType](#componentyype) | Yes | Component type. | +| upgradeAction | [UpgradeAction](#upgradeaction) | Yes | Update mode. | +| displayVersion | string | Yes | Display version number. | +| innerVersion | string | Yes | Internal version number. | +| size | number | Yes | Update package size. | +| effectiveMode | [EffectiveMode](#effectivemode) | Yes | Effective mode. | +| descriptionInfo | [DescriptionInfo](#descriptioninfo) | Yes | Information about the version description file. | + +## DescriptionOptions + +Represents options of the description file. + +**System capability**: SystemCapability.Update.UpdateService + +| Name | Type | Mandatory | Description | +| ------------------- | --------------------------- | ---- | ------- | +| format | [DescriptionFormat](#descriptionformat) | Yes | Format of the description file. | +| language | string | Yes | Language of the description file. | + +## ComponentDescription + +Represents a component description file. + +**System capability**: SystemCapability.Update.UpdateService + +| Name | Type | Mandatory | Description | +| ------------------- | --------------------------- | ---- | ------- | +| componentId | string | Yes | Component ID. | +| descriptionInfo | [DescriptionInfo](#descriptioninfo) | Yes | Information about the description file. | + +## DescriptionInfo + +Represents information about the version description file. + +**System capability**: SystemCapability.Update.UpdateService + +| Name | Type | Mandatory | Description | +| ------------------- | --------------------------- | ---- | ------- | +| descriptionType | [DescriptionType](#descriptiontype) | Yes | Type of the description file. | +| content | string | Yes | Content of the description file. | + +## CurrentVersionInfo + +Represents information about the current version. + +**System capability**: SystemCapability.Update.UpdateService + +| Name | Type | Mandatory | Description | +| ------------------- | --------------------------- | ---- | ------- | +| osVersion | string | Yes | System version number. | +| deviceName | string | Yes | Device name. | +| versionComponents | Array\<[VersionComponent](#vesioncomponent)> | No | Version components. | + +## DownloadOptions + +Represents download options. + +**System capability**: SystemCapability.Update.UpdateService + +| Name | Type | Mandatory | Description | +| ------------------- | --------------------------- | ---- | ------- | +| allowNetwork | [NetType](#nettype) | Yes | Network type. | +| order | [Order](#order) | Yes | Update command. | + +## ResumeDownloadOptions + +Represents options for resuming download. + +**System capability**: SystemCapability.Update.UpdateService + +| Parameter | Type | Mandatory | Description | +| ------------------- | --------------------------- | ---- | ------- | +| allowNetwork | [NetType](#nettype) | Yes | Network type. | + +## PauseDownloadOptions + +Represents options for pausing download. + +**System capability**: SystemCapability.Update.UpdateService + +| Name | Type | Mandatory | Description | +| ------------------- | --------------------------- | ---- | ------- | +| isAllowAutoResume | bool | Yes | Whether to allow automatic resuming of download. | + +## UpgradeOptions + +Represents update options. + +**System capability**: SystemCapability.Update.UpdateService + +| Name | Type | Mandatory | Description | +| ------------------- | --------------------------- | ---- | ------- | +| order | [Order](#order) | Yes | Update command. | + +## ClearOptions + +Represents options for clearing errors. + +**System capability**: SystemCapability.Update.UpdateService + +| Name | Type | Mandatory | Description | +| ------------------- | --------------------------- | ---- | ------- | +| status | [UpgradeStatus](#upgradestatus) | Yes | Error status. | + +## UpgradePolicy + +Represents an update policy. + +**System capability**: SystemCapability.Update.UpdateService + +| Name | Type | Mandatory | Description | +| ------------------- | --------------------------- | ---- | ------- | +| downloadStrategy | bool | Yes | Automatic download policy. | +| autoUpgradeStrategy | bool | Yes | Automatic update policy. | +| autoUpgradePeriods | Array\<[UpgradePeriod](#upgradeperiod)> | Yes | Automatic update period.| + +## UpgradePeriod + +Represents a period for automatic update. + +**System capability**: SystemCapability.Update.UpdateService + +| Name | Type | Mandatory | Description | +| ------------------- | --------------------------- | ---- | ------- | +| start | number | Yes | Start time. | +| end | number | Yes | End time. | + +## TaskInfo + +Represents task information. + +**System capability**: SystemCapability.Update.UpdateService + +| Name | Type | Mandatory | Description | +| ------------------- | --------------------------- | ---- | ------- | +| existTask | bool | Yes | Whether a task exists. | +| taskBody | [TaskBody](#taskinfo) | Yes | Task data. | + +## EventInfo + +Represents event information. + +**System capability**: SystemCapability.Update.UpdateService + +| Parameter | Type | Mandatory | Description | +| ------------------- | --------------------------- | ---- | ------- | +| eventId | [EventId](#eventid) | Yes | Event ID. | +| taskBody | [TaskBody](#taskinfo) | Yes | Task data. | + +## TaskBody + +Represents task data. + +**System capability**: SystemCapability.Update.UpdateService + +| Name | Type | Mandatory | Description | +| ------------------- | --------------------------- | ---- | ------- | +| versionDigestInfo | [VersionDigestInfo](#versiondigestinfo) | Yes | Version digest information. | +| status | [UpgradeStatus](#upgradestatus) | Yes | Update status. | +| subStatus | number | No | Sub-status. | +| progress | number | Yes | Progress. | +| installMode | number | Yes | Installation mode. | +| errorMessages | Array\<[ErrorMessage](#errormessage)> | No | Error message. | +| versionComponents | Array\<[VersionComponent](#versioncomponent)> | Yes | Version components. | + +## ErrorMessage + +Represents an error message. + +**System capability**: SystemCapability.Update.UpdateService + +| Name | Type | Mandatory | Description | +| ------------------- | --------------------------- | ---- | ------- | +| errorCode | number | Yes | Error code. | +| errorMessage | string | Yes | Error description. | + +## EventClassifyInfo + +Represents event type information. + +**System capability**: SystemCapability.Update.UpdateService + +| Name | Type | Mandatory | Description | +| ------------------- | --------------------------- | ---- | ------- | +| eventClassify | [EventClassify](#eventclassify) | Yes | Event type. | +| extraInfo | string | Yes | Additional information. | + +## UpgradeFile + +Represents an update file. + +**System capability**: SystemCapability.Update.UpdateService + +| Name | Type | Mandatory | Description | +| ------------------- | --------------------------- | ---- | ------- | +| fileType | [ComponentType](#componenttype) | Yes | File type. | +| filePath | string | Yes | File path. | + +## UpgradeTaskCallback + +### (eventInfo: [EventInfo](#eventinfo)): void + +Event callback. + +**System capability**: SystemCapability.Update.UpdateService + +| Parameter | Type | Mandatory | Description | +| --------------- | ---------------------------------------- | ---- | ---- | +| eventInfo | [EventInfo](#eventinfo) | Yes | Event information.| + +## BusinessVendor + +Device vendor. + +**System capability**: SystemCapability.Update.UpdateService + +| Name | Default Value | Description | +| ------------------- | ---- | -------- | +| PUBLIC | "public" | Open source. | + +## BusinessSubType + +Represents an update type. + +**System capability**: SystemCapability.Update.UpdateService + +| Name | Default Value | Description | +| ------------------- | ---- | -------- | +| FIRMWARE | 1 | Firmware. | + +## ComponentType + +Represents a component type. + +**System capability**: SystemCapability.Update.UpdateService + +| Name | Default Value | Description | +| ------------------- | ---- | -------- | +| OTA | 1 | Firmware. | + +## UpgradeAction + +Represents an update mode. + +**System capability**: SystemCapability.Update.UpdateService + +| Name | Default Value | Description | +| ------------------- | ---- | -------- | +| UPGRADE | "upgrade" | Differential package. | +| RECOVERY | "recovery" | Recovery package. | + +## EffectiveMode + +Represents an effective mode. + +**System capability**: SystemCapability.Update.UpdateService + +| Name | Default Value | Description | +| ------------------- | ---- | -------- | +| COLD | 1 | Cold update. | +| LIVE | 2 | Live update. | +| LIVE_AND_COLD | 3 | Hybrid live and cold update. | + +## DescriptionType + +Represents a description file type. + +**System capability**: SystemCapability.Update.UpdateService + +| Name | Default Value | Description | +| ------------------- | ---- | -------- | +| CONTENT | 0 | Content. | +| URI | 1 | Link. | + +## DescriptionFormat + +Represents a description file format. + +**System capability**: SystemCapability.Update.UpdateService + +| Name | Default Value | Description | +| ------------------- | ---- | -------- | +| STANDARD | 0 | Standard format. | +| SIMPLIFIED | 1 | Simple format. | + +## NetType + +Enumerates network types. + +**System capability**: SystemCapability.Update.UpdateService + +| Name | Default Value | Description | +| ------------------- | ---- | -------- | +| CELLULAR | 1 | Data network. | +| METERED_WIFI | 2 | Wi-Fi hotspot. | +| NOT_METERED_WIFI | 4 | Non Wi-Fi hotspot. | +| WIFI | 6 | WIFI | +| CELLULAR_AND_WIFI | 7 | Data network and Wi-Fi. | + +## Order + +Represents an update command. + +**System capability**: SystemCapability.Update.UpdateService + +| Name | Default Value | Description | +| ------------------- | ---- | -------- | +| DOWNLOAD | 1 | Download. | +| INSTALL | 2 | Install. | +| DOWNLOAD_AND_INSTALL | 3 | Download and install. | +| APPLY | 4 | Apply. | +| INSTALL_AND_APPLY | 6 | Install and apply. | + +## UpgradeStatus + +Enumerates update states. + +**System capability**: SystemCapability.Update.UpdateService + +| Name | Default Value | Description | +| ------------------- | ---- | -------- | +| WAITING_DOWNLOAD | 20 | Waiting for download. | +| DOWNLOADING | 21 | Downloading. | +| DOWNLOAD_PAUSED | 22 | Download paused. | +| DOWNLOAD_FAIL | 23 | Download failed. | +| WAITING_INSTALL | 30 | Waiting for installation. | +| UPDATING | 31 | Updating. | +| WAITING_APPLY | 40 | Waiting for applying the update. | +| APPLYING | 21 | Applying the update. | +| UPGRADE_SUCCESS | 50 | Update succeeded. | +| UPGRADE_FAIL | 51 | Update failed. | + +## EventClassify + +Represents an event type. + +**System capability**: SystemCapability.Update.UpdateService + +| Name | Default Value | Description | +| ------------------- | ---- | -------- | +| TASK | 0x01000000 | Task event. | + +## EventId -Defines the version description information. +Enumerates event IDs. **System capability**: SystemCapability.Update.UpdateService -| Name | Type | Mandatory | Description | -| ------------- | ------ | --------- | ------------------------------ | -| descriptionId | string | Yes | Version ID information. | -| content | string | Yes | Version changelog information. | +| Name | Default Value | Description | +| ------------------- | ---- | -------- | +| EVENT_TASK_BASE | 0x01000000 | Indicates a task event. | +| EVENT_TASK_RECEIVE | 0x01000001 | Indicates that a task is received. | +| EVENT_TASK_CANCEL | 0x01000010 | Indicates that a task is cancelled. | +| EVENT_DOWNLOAD_WAIT | 0x01000011 | Indicates the state of waiting for the download. | +| EVENT_DOWNLOAD_START | 0x01000100 | Indicates that the download starts. | +| EVENT_DOWNLOAD_UPDATE | 0x01000101 | Indicates the download progress update. | +| EVENT_DOWNLOAD_PAUSE | 0x01000110 | Indicates that the download is paused. | +| EVENT_DOWNLOAD_RESUME | 0x01000111 | Indicates that the download is resumed. | +| EVENT_DOWNLOAD_SUCCESS | 0x01001000 | Indicates that the download succeeded. | +| EVENT_DOWNLOAD_FAIL | 0x01001001 | Indicates that the download failed. | +| EVENT_UPGRADE_WAIT | 0x01001010 | Indicates the state of waiting for the update. | +| EVENT_UPGRADE_START | 0x01001011 | Indicates that the update starts. | +| EVENT_UPGRADE_UPDATE | 0x01001100 | Indicates that the update is in progress. | +| EVENT_APPLY_WAIT | 0x01001101 | Indicates the state of waiting for applying the update. | +| EVENT_APPLY_START | 0x01001110 | Indicates the state of applying the update. | +| EVENT_UPGRADE_SUCCESS | 0x01001111 | Indicates that the update succeeded. | +| EVENT_UPGRADE_FAIL | 0x01010000 | Indicates that the update failed. | -- GitLab