diff --git a/en/application-dev/reference/apis/Readme-EN.md b/en/application-dev/reference/apis/Readme-EN.md index b283ed84102e9e4dc2ce877ad6f7c425941dbead..4638d0eecbea195dc7dc5077cf0da512edcbbae3 100644 --- a/en/application-dev/reference/apis/Readme-EN.md +++ b/en/application-dev/reference/apis/Readme-EN.md @@ -21,6 +21,8 @@ - [SMS](js-apis-sms.md) - [SIM Management](js-apis-sim.md) - [Radio](js-apis-radio.md) +- Network and Connectivity + - [WLAN](js-apis-wifi.md) - Device Management - [Sensors](js-apis-sensor.md) - [Vibration](js-apis-vibrator.md) @@ -33,6 +35,7 @@ - [Device Management](js-apis-device-manager.md) - [Window](js-apis-window.md) - [Display](js-apis-display.md) + - [Update](js-apis-update.md) - Basic Features - [Application Context](js-apis-basic-features-app-context.md) - [Console Logs](js-apis-basic-features-logs.md) diff --git a/en/application-dev/reference/apis/js-apis-update.md b/en/application-dev/reference/apis/js-apis-update.md new file mode 100644 index 0000000000000000000000000000000000000000..c3bf1d9d3047dd4dc8bd9001b4a61fc497fe8021 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-update.md @@ -0,0 +1,557 @@ +# Update + +The update module applies to updates throughout the entire OpenHarmony 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. + +- The SD card update depends on the update packages and SD cards. +- The OTA update depends on the server deployed by the phone manufacturer for managing update packages. The OTA server IP address is passed by the caller. The request interface is fixed and developed by the phone manufacturer. + +## Modules to Import + +```js +import client from '@ohos.update' +``` + +## Required Permissions + +None + +## Updater + +### getNewVersionInfo + +getNewVersionInfo(callback: AsyncCallback\): void + +Obtains the new version information. This method uses an asynchronous callback to return the result. + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | ------------------------------------------------ | ---- | ------------------ | +| callback | AsyncCallback<[NewVersionInfo](#newversioninfo)> | No| Callback used to return the new version information.| + +**Example** + +``` +updater.getNewVersionInfo(info => { + console.log("getNewVersionInfo success " + info.status); + console.log(`info versionName = ` + info.result[0].versionName); + console.log(`info versionCode = ` + info.result[0].versionCode); + console.log(`info verifyInfo = ` + info.result[0].verifyInfo); +)}; +``` + +### getNewVersionInfo + +getNewVersionInfo(): Promise\ + +Obtains the new version information. This method uses a promise to return the result. + +**Return values** + +| Type| Description| +| ------------------------------------------- | ------------------------- | +| Promise\<[NewVersionInfo](#newversioninfo)> | Promise used to return the new version information.| + +**Example** + +``` +var p = updater.getNewVersionInfo(); +p.then(function (value) { + console.log(`info versionName = ` + value.result[0].versionName); + console.log(`info versionCode = ` + value.result[0].versionCode); + console.log(`info verifyInfo = ` + value.result[0].verifyInfo); +}).catch(function (err) { + console.log("getNewVersionInfo promise error: " + err.code); +)}; +``` + +### checkNewVersion + +checkNewVersion(callback: AsyncCallback\): void + +Checks whether the current version is the latest. This method uses an asynchronous callback to return the result. + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | ------------------------------------------------- | ---- | ------------------ | +| callback | AsyncCallback\<[NewVersionInfo](#newversioninfo)> | No| Callback used to return the new version information.| + +**Example** + +``` +updater.checkNewVersion(info => { + console.log("checkNewVersion success " + info.status); + console.log(`info versionName = ` + info.result[0].versionName); + console.log(`info versionCode = ` + info.result[0].versionCode); + console.log(`info verifyInfo = ` + info.result[0].verifyInfo); +)}; +``` + +### checkNewVersion + +checkNewVersion(): Promise\ + +Checks whether the current version is the latest. This method uses a promise to return the result. + +**Return values** + +| Type| Description| +| ------------------------------------------- | ------------------------- | +| Promise\<[NewVersionInfo](#newversioninfo)> | Promise used to return the new version information.| + +**Example** + +``` +var p = updater.checkNewVersion(); +p.then(function (value) { + console.log(`info versionName = ` + value.result[0].versionName); + console.log(`info versionCode = ` + value.result[0].versionCode); + console.log(`info verifyInfo = ` + value.result[0].verifyInfo); +}).catch(function (err) { + console.log("checkNewVersion promise error: " + err.code); +)}; +``` + +### verifyUpdatePackage + +verifyUpdatePackage(upgradeFile: string, certsFile: string): void + +Verifies whether the update package is valid. + +**Parameters** + +| Name| Type| Mandatory| Description| +| ----------- | ------ | ---- | ------------------ | +| upgradeFile | string | Yes| Path of the update package to be verified.| +| certsFile | string | Yes| Certificate path.| + +**Example** + +``` +var getVar = update.getUpdater(); +getVar.on("verifyProgress", function (callback){ + console.info('on verifyProgress ' + callback.percent); +}); +getVar.verifyUpdatePackage("XXX", "XXX"); +getVar.off("verifyProgress"); +``` + +### rebootAndCleanUserData + +rebootAndCleanUserData(): Promise\ + +Reboots the device and clears the user partition data. This method uses a promise to return the result. + +**Return values** + +| Type| Description| +| ---------------- | ------------------------------- | +| Promise\ | Promise used to return the execution result.| + +**Example** + +``` +var getVar = update.getUpdater(); +p = getVar.rebootAndCleanUserData(); +p.then(function (value) { + console.info("rebootAndCleanUserData promise success: " + value); +}).catch(function (err) { + console.info("rebootAndCleanUserData promise error: " + err.code); +}); +``` + +### rebootAndCleanUserData + +rebootAndCleanUserData(callback: AsyncCallback\): void + +Reboots the device and clears the user partition data. This method uses an asynchronous callback to return the result. + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | ---- | ---------------------- | +| callback | Function | Yes| AsyncCallback\ | + +**Example** + +``` +var getVar = update.getUpdater(); +getVar.rebootAndCleanUserData(function (err, data) { + if (err.code == 0) { + console.info("rebootAndCleanUserData callback success:" + data) + } else { + console.info("rebootAndCleanUserData callback err:" + err.code) + } +}); +``` + +### applyNewVersion + +applyNewVersion(): Promise\ + +Installs the update package. This method uses a promise to return the result. + +**Return values** + +| Type| Description| +| ---------------- | ------------------------------- | +| Promise\ | Promise used to return the execution result.| + +**Example** + +``` +var getVar = update.getUpdater(); +p.then(function (value) { + console.info("applyNewVersion promise success: " + value); +}).catch(function (err) { + console.info("applyNewVersion promise error: " + err.code); +}); +``` + +### applyNewVersion + +applyNewVersion(callback: AsyncCallback\): void + +Installs the update package. This method uses an asynchronous callback to return the result. + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | ---- | ---------------------- | +| callback | Function | Yes| AsyncCallback\ | + +**Example** + +``` +var getVar = update.getUpdater(); +getVar.applyNewVersion(function (err, data) { + if (err.code == 0) { + console.info("applyNewVersion callback success:" + data) + } else { + console.info("applyNewVersion callback err:" + err.code) + } +}); +``` + +### download + +download(): void + +Downloads the new version and displays the download process. + +**Example** + +``` +updater.on("downloadProgress", progress => { + console.log("downloadProgress on" + progress); + console.log(`downloadProgress status: ` + progress.status); + console.log(`downloadProgress percent: ` + progress.percent); +)}; +updater.download(); +``` + +### upgrade + +updater.upgrade():void + +Starts an update. + +**Example** + +``` +updater.on("upgradeProgress", progress => { + console.log("upgradeProgress on" + progress); + console.log(`upgradeProgress status: ` + progress.status); + console.log(`upgradeProgress percent: ` + progress.percent); +)}; +updater.upgrade(); +``` + +### setUpdatePolicy + +setUpdatePolicy(policy: UpdatePolicy, callback: AsyncCallback\): void + +Sets the update policy. This method uses an asynchronous callback to return the result. + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | ----------------------------- | ---- | ------------ | +| policy | [UpdatePolicy](#updatepolicy) | Yes| Update policy to set.| +| callback | AsyncCallback\ | Yes| Callback used to return the execution result.| + +**Example** + +``` +// Set the update policy. +let policy = { +autoDownload: false, +autoDownloadNet: true, +mode: 2, +autoUpgradeInterval: [ 2, 3 ], +autoUpgradeCondition: 2 +} +updater.setUpdatePolicy(policy, function(result) { +console.log("setUpdatePolicy ", result)}); +``` + +### setUpdatePolicy + +setUpdatePolicy(policy: UpdatePolicy): Promise\ + +Sets the update policy. This method uses a promise to return the result. + +**Parameters** + +| Name| Type| Mandatory| Description| +| ------ | ----------------------------- | ---- | ------------ | +| policy | [UpdatePolicy](#updatepolicy) | Yes| Update policy to set.| + +**Return values** + +| Type| Description| +| ---------------- | ----------------------- | +| Promise\ | Promise used to return the execution result.| + +**Example** + +``` +let policy = { +autoDownload: false, +autoDownloadNet: true, +mode: 2, +autoUpgradeInterval: [ 2, 3 ], +autoUpgradeCondition: 2 +} +updater.setUpdatePolicy(policy) +.then(data=> +console.log('Policy set successfully') +) +``` + +### getUpdatePolicy + +getUpdatePolicy(callback: AsyncCallback\): void + +Obtains the update policy. This method uses an asynchronous callback to return the result. + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | --------------------------------------------- | ---- | -------------------- | +| callback | AsyncCallback\<[UpdatePolicy](#updatepolicy)> | No| Callback used to return the update policy.| + +**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); +)}; +``` + +### getUpdatePolicy + +getUpdatePolicy(): Promise\ + +Obtains the update policy. This method uses a promise to return the result. + +**Return values** + +| Type| Description| +| --------------------------------------- | --------------------------- | +| Promise\<[UpdatePolicy](#updatepolicy)> | Promise used to return the update policy.| + +**Example** + +``` +p = updater.getUpdatePolicy(); +p.then(function (value) { + console.log(`info autoDownload = ` + value.autoDownload); + console.log(`info autoDownloadNet = ` + value.autoDownloadNet); + console.log(`info mode = ` + value.mode); +}).catch(function (err) { + console.log("getUpdatePolicy promise error: " + err.code); +)}; +``` + +## update.getUpdater + +getUpdater(upgradeFile: string, updateType?: UpdateTypes): Updater + +Obtains the updater for the local update. + +**Parameters** + +| Name| Type| Mandatory| Description| +| ----------- | --------------------------- | ---- | -------- | +| upgradeFile | string | Yes| Update file.| +| updateType | [UpdateTypes](#updatetypes) | Yes| Update type.| + +**Return values** + +| Type| Description| +| ------------------- | -------- | +| [Updater](#updater) | Updater object.| + +**Example** + +``` +try { + page.data.updater = update.getUpdater('/data/updater/updater.zip', 'OTA'); +} catch(error) { + console.error("Failed to get updater. Error: " + error); +} +``` + +## update.getUpdaterForOther + +getUpdaterForOther(upgradeFile: string, device: string, updateType?: UpdateTypes): Updater + +Obtains the updater for the device to be updated. + +**Parameters** + +| Name| Type| Mandatory| Description| +| ----------- | --------------------------- | ---- | ---------- | +| upgradeFile | string | Yes| Update file.| +| device | string | Yes| Device to be updated.| +| updateType | [UpdateTypes](#updatetypes) | Yes| Update type.| + +**Return values** + +| Type| Description| +| ------------------- | -------- | +| [Updater](#updater) | Updater object.| + +**Example** + +``` +try { + page.data.updater = update.getUpdaterForOther('/data/updater/updater.zip', '1234567890', 'OTA'); +} catch(error) { + console.error("Failed to get updater. Error: " + error); +} +``` + +## update.getUpdaterFromOther + +getUpdaterFromOther(upgradeFile: string, device: string, updateType?: UpdateTypes): Updater + +Obtains the updater from another device for the device to be updated. + +**Parameters** + +| Name| Type| Mandatory| Description| +| ----------- | --------------------------- | ---- | ---------- | +| upgradeFile | string | Yes| Update file.| +| device | string | Yes| Device to be updated.| +| updateType | [UpdateTypes](#updatetypes) | Yes| Update type.| + +**Return values** + +| Type| Description| +| ------------------- | -------- | +| [Updater](#updater) | Updater object.| + +**Example** + +``` +try { + page.data.updater = update.getUpdaterFromOther('/data/updater/updater.zip', '1234567890', 'OTA'); +} catch(error) { + console.error("Failed to get updater. Error: " + error); +} +``` + +## UpdateTypes + +Describes the update type. + +| Name| Description| +| ------ | -------- | +| OTA | OTA update.| +| patch | Patch update.| + +## PackageTypes + +Enumerates the update package types. + +| 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.| + +## InstallMode + +Enumerates the update modes. + +| Name| Default Value| Description| +| ------------------- | ------ | -------- | +| INSTALL_MODE_NORMAL | 0 | Normal update.| +| INSTALL_MODE_NIGHT | 1 | Update at night.| +| INSTALL_MODE_AUTO | 2 | Automatic update.| + +## NewVersionStatus + +Enumerates the new version check results. + +| 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.| + +## UpdatePolicy + +Defines the update policy. + +| Name| Parameter type.| Mandatory| Description| +| ------------------- | --------------------------- | ---- | -------------- | +| autoDownload | bool | Yes| Automatic update switch.| +| installMode | [InstallMode](#installmode) | Yes| Update mode.| +| autoUpgradeInterval | Array\ | Yes| Period of time for automatic update.| + +## NewVersionInfo + +Defines the new version information. + +| Name| Type| Mandatory| Description| +| --------------- | ------------------------------------------- | ---- | -------- | +| status | [NewVersionStatus](#newversionstatus) | Yes| Update status.| +| errMsg | string | Yes| Error message.| +| checkResults | Array<[CheckResult](#checkresult)> | Yes| Check result.| +| descriptionInfo | Array\<[DescriptionInfo](#descriptioninfo)> | Yes| Description.| + +## CheckResult + +Defines the check result. + +| 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.| + +## DescriptionInfo + +Defines the version description information. + +| Name| Type| Mandatory| Description| +| ------------- | -------- | ---- | ----------------- | +| descriptionId | string | Yes| Version ID information.| +| content | string | Yes| Version changelog information.| diff --git a/en/application-dev/reference/apis/js-apis-wifi.md b/en/application-dev/reference/apis/js-apis-wifi.md new file mode 100644 index 0000000000000000000000000000000000000000..617d88183d0a304378d2f73efaf709a3f636499b --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-wifi.md @@ -0,0 +1,124 @@ +# WLAN + +> ![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. + +## Modules to Import + +``` +import wifi from '@ohos.wifi_native_js'; +``` + +## wifi.isWifiActive + +isWifiActive(): boolean + +Checks whether WLAN is activated. + +**Return values** + +| Type| Description| +| -------- | ---------------------------- | +| boolean | Returns **true** if WLAN is activated; returns **false** otherwise.| + +## wifi.getSignalLevel + +getSignalLevel(rssi: number, band: number): number + +Obtains the WLAN signal strength. + +**Parameters** + +| Name| Type| Mandatory| Description| +| ---------- | -------- | -------- | --------------------- | +| rssi | number | Yes| Signal strength (in dBm) of the hotspot.| +| band | number | Yes| Frequency band of the WLAN access point (AP).| + +**Return values** + +| Type| Description| +| -------- | ---------------------------- | +| number | Signal strength obtained. The value range is 0 to 4.| + +## wifi.scan + +scan(): boolean + +Starts a scan for WLAN. + +**Return values** + +| Type| Description| +| -------- | -------------------------------------------- | +| boolean | Returns **true** if the scan is successful; returns **false** otherwise.| + +## wifi.getScanInfos + +getScanInfos(): Promise> + +Obtains the scan result. This method uses a promise to return the result. + +**Return values** + +| Type| Description| +| ------------------------------------------------ | ---------------------- | +| Promise< Array\<[WifiScanInfo](#wifiscaninfo)> > | Promise used to return the scan result, which is a list of hotspots detected.| + +## wifi.getScanInfos + +getScanInfos(callback: AsyncCallback>): void + +Obtains the scan result. This method uses an asynchronous callback to return the result. + +| Name| Type| Mandatory| Description| +| ---------- | ----------------------------------------------------- | -------- | ------------------------------ | +| callback | AsyncCallback< Array\<[WifiScanInfo](#wifiscaninfo)>> | Yes| Callback invoked to return the result, which is a list of hotspots detected.| + +**Example** + +``` +import wifi from '@ohos.wifi_native_js'; + + +wifi.getScanInfos(result => { + var len = Object.keys(result).length; + console.log("received scan info size: " + len); + for (var i = 0; i < len; ++j) { + console.info("ssid: " + result[i].ssid); + console.info("bssid: " + result[i].bssid); + console.info("securityType: " + result[i].securityType); + console.info("rssi: " + result[i].rssi); + console.info("band: " + result[i].band); + console.info("frequency: " + result[i].frequency); + console.info("timestamp: " + result[i].timestamp); + } +}); + +wifi.getScanInfos().then(result => { + var len = Object.keys(result).length; + console.log("received scan info size: " + len); + for (var i = 0; i < len; ++i) { + console.info("ssid: " + result[i].ssid); + console.info("bssid: " + result[i].bssid); + console.info("securityType: " + result[i].securityType); + console.info("rssi: " + result[i].rssi); + console.info("band: " + result[i].band); + console.info("frequency: " + result[i].frequency); + console.info("timestamp: " + result[i].timestamp); + } +}); +``` + +## WifiScanInfo + +Defines WLAN hotspot information. + +| Name| Type| Readable/Writable| Description| +| ------------ | ---------------- | ------------ | ----------------------------- | +| ssid | string | Read-only| Hotspot service set identifier (SSID), in UTF-8 format.| +| bssid | string | Read-only| Basic service set identifier (BSSID) of the hotspot.| +| securityType | WifiSecurityType | Read-only| WLAN encryption type.| +| rssi | number | Read-only| Signal strength (in dBm) of the hotspot.| +| band | number | Read-only| Frequency band of the WLAN AP.| +| frequency | number | Read-only| Frequency of the WLAN AP.| +| timestamp | number | Read-only| Timestamp.|