• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Update
2
3> **NOTE**<br>
4> 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.
5
6The Update module applies to updates throughout the entire system, including built-in resources and preset applications, but not third-party applications.
7
8There are two types of updates: SD card update and over the air (OTA) update.
9
10- The SD card update depends on the update packages and SD cards.
11- 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.
12
13## Modules to Import
14
15```js
16import update from '@ohos.update'
17```
18
19## Required Permissions
20
21None
22
23## update.getUpdater
24
25getUpdater(upgradeFile: string, updateType?: UpdateTypes): Updater
26
27Obtains the **Updater** object for local update.
28
29**System capability**: SystemCapability.Update.UpdateService
30
31**Parameters**
32
33| Name        | Type                        | Mandatory | Description  |
34| ----------- | --------------------------- | --------- | ------------ |
35| upgradeFile | string                      | Yes       | Update file. |
36| updateType  | [UpdateTypes](#updatetypes) | Yes       | Update type. |
37
38**Return value**
39
40| Type                | Description         |
41| ------------------- | ------------------- |
42| [Updater](#updater) | **Updater** object. |
43
44**Example**
45
46```
47try {
48  let updater = update.getUpdater('/data/updater/updater.zip', 'OTA');
49} catch(error) {
50  console.error(" Fail to get updater error: " + error);
51}
52```
53
54## update.getUpdaterForOther
55
56getUpdaterForOther(upgradeFile: string, device: string, updateType?: UpdateTypes): Updater
57
58Obtains the **Updater** object for the device to be updated.
59
60**System capability**: SystemCapability.Update.UpdateService
61
62**Parameters**
63
64| Name        | Type                        | Mandatory | Description           |
65| ----------- | --------------------------- | --------- | --------------------- |
66| upgradeFile | string                      | Yes       | Update file.          |
67| device      | string                      | Yes       | Device to be updated. |
68| updateType  | [UpdateTypes](#updatetypes) | Yes       | Update type.          |
69
70**Return value**
71
72| Type                | Description         |
73| ------------------- | ------------------- |
74| [Updater](#updater) | **Updater** object. |
75
76**Example**
77
78```
79try {
80  let updater = update.getUpdaterForOther('/data/updater/updater.zip', '1234567890', 'OTA');
81} catch(error) {
82  console.error(" Fail to get updater error: " + error);
83}
84```
85
86## update.getUpdaterFromOther
87
88getUpdaterFromOther(upgradeFile: string, device: string, updateType?: UpdateTypes): Updater
89
90Obtains the **Updater** object from another device for the device to be updated.
91
92**System capability**: SystemCapability.Update.UpdateService
93
94**Parameters**
95
96| Name        | Type                        | Mandatory | Description           |
97| ----------- | --------------------------- | --------- | --------------------- |
98| upgradeFile | string                      | Yes       | Update file.          |
99| device      | string                      | Yes       | Device to be updated. |
100| updateType  | [UpdateTypes](#updatetypes) | Yes       | Update type.          |
101
102**Return value**
103
104| Type                | Description         |
105| ------------------- | ------------------- |
106| [Updater](#updater) | **Updater** object. |
107
108**Example**
109
110```
111try {
112  let updater = update.getUpdaterFromOther('/data/updater/updater.zip', '1234567890', 'OTA');
113} catch(error) {
114  console.error(" Fail to get updater error: " + error);
115}
116```
117
118## Updater
119
120###  getNewVersionInfo
121
122getNewVersionInfo(callback: AsyncCallback\<NewVersionInfo>): void
123
124Obtains the new version information. This function uses an asynchronous callback to return the result.
125
126**System capability**: SystemCapability.Update.UpdateService
127
128**Parameters**
129
130| Name     | Type                                     | Mandatory | Description                              |
131| -------- | ---------------------------------------- | --------- | ---------------------------------------- |
132| callback | AsyncCallback<[NewVersionInfo](#newversioninfo)> | No        | Callback used to return the new version information. |
133
134**Example**
135
136```
137updater.getNewVersionInfo((err, info) => {
138  console.log("getNewVersionInfo success  " + info.status);
139  console.log(`info versionName = ` + info.checkResults[0].versionName);
140  console.log(`info versionCode = ` + info.checkResults[0].versionCode);
141  console.log(`info verifyInfo = ` + info.checkResults[0].verifyInfo);
142});
143```
144
145### getNewVersionInfo
146
147getNewVersionInfo(): Promise\<NewVersionInfo>
148
149Obtains the new version information. This function uses a promise to return the result.
150
151**System capability**: SystemCapability.Update.UpdateService
152
153**Return value**
154
155| Type                                     | Description                              |
156| ---------------------------------------- | ---------------------------------------- |
157| Promise\<[NewVersionInfo](#newversioninfo)> | Promise used to return the new version information. |
158
159**Example**
160
161```
162updater.getNewVersionInfo().then(value => {
163  console.log(`info versionName = ` + value.checkResults[0].versionName);
164  console.log(`info versionCode = ` + value.checkResults[0].versionCode);
165  console.log(`info verifyInfo = ` + value.checkResults[0].verifyInfo);
166}).catch(err => {
167  console.log("getNewVersionInfo promise error: " + err.code);
168});
169```
170
171### checkNewVersion
172
173checkNewVersion(callback: AsyncCallback\<NewVersionInfo>): void
174
175Checks whether the current version is the latest. This function uses an asynchronous callback to return the result.
176
177**System capability**: SystemCapability.Update.UpdateService
178
179**Parameters**
180
181| Name     | Type                                     | Mandatory | Description                              |
182| -------- | ---------------------------------------- | --------- | ---------------------------------------- |
183| callback | AsyncCallback\<[NewVersionInfo](#newversioninfo)> | No        | Callback used to return the new version information. |
184
185**Example**
186
187```
188updater.checkNewVersion((err, info) => {
189  console.log("checkNewVersion success  " + info.status);
190  console.log(`info versionName = ` + info.checkResults[0].versionName);
191  console.log(`info versionCode = ` + info.checkResults[0].versionCode);
192  console.log(`info verifyInfo = ` + info.checkResults[0].verifyInfo);
193});
194```
195
196### checkNewVersion
197
198checkNewVersion(): Promise\<NewVersionInfo>
199
200Checks whether the current version is the latest. This function uses a promise to return the result.
201
202**System capability**: SystemCapability.Update.UpdateService
203
204**Return value**
205
206| Type                                     | Description                              |
207| ---------------------------------------- | ---------------------------------------- |
208| Promise\<[NewVersionInfo](#newversioninfo)> | Promise used to return the new version information. |
209
210**Example**
211
212```
213updater.checkNewVersion().then(value => {
214  console.log(`info versionName = ` + value.checkResults[0].versionName);
215  console.log(`info versionCode = ` + value.checkResults[0].versionCode);
216  console.log(`info verifyInfo = ` + value.checkResults[0].verifyInfo);
217}).catch(err => {
218  console.log("checkNewVersion promise error: " + err.code);
219});
220```
221
222### verifyUpdatePackage
223
224verifyUpdatePackage(upgradeFile: string, certsFile: string): void
225
226Verifies whether the update package is valid.
227
228**System capability**: SystemCapability.Update.UpdateService
229
230**Parameters**
231
232| Name        | Type   | Mandatory | Description                              |
233| ----------- | ------ | --------- | ---------------------------------------- |
234| upgradeFile | string | Yes       | Path of the update package to be verified. |
235| certsFile   | string | Yes       | Certificate path.                        |
236
237**Example**
238
239```
240updater.on("verifyProgress", callback => {
241  console.info('on verifyProgress ' + callback.percent);
242});
243update.verifyUpdatePackage("XXX", "XXX");
244```
245
246### rebootAndCleanUserData<sup>8+</sup>
247
248rebootAndCleanUserData(): Promise\<number>
249
250Reboots the device and clears the user partition data. This function uses a promise to return the result.
251
252**System capability**: SystemCapability.Update.UpdateService
253
254**Return value**
255
256| Type             | Description                              |
257| ---------------- | ---------------------------------------- |
258| Promise\<number> | Promise used to return the execution result. |
259
260**Example**
261
262```
263updater.rebootAndCleanUserData().then(result => {
264  console.log("rebootAndCleanUserData " + result);
265}).catch(err => {
266  console.info("rebootAndCleanUserData promise error: " + err.code);
267});
268```
269
270### rebootAndCleanUserData<sup>8+</sup>
271
272rebootAndCleanUserData(callback: AsyncCallback\<number>): void
273
274Reboots the device and clears the user partition data. This function uses a promise to return the result.
275
276**System capability**: SystemCapability.Update.UpdateService
277
278**Parameters**
279
280| Name     | Type                   | Mandatory | Description                              |
281| -------- | ---------------------- | --------- | ---------------------------------------- |
282| callback | AsyncCallback\<number> | Yes       | Callback used to return the execution result. |
283
284**Example**
285
286```
287updater.rebootAndCleanUserData((err, result) => {
288  console.log("rebootAndCleanUserData ", result)
289});
290```
291
292### applyNewVersion
293
294applyNewVersion(): Promise\<number>
295
296Installs the update package. This function uses a promise to return the result.
297
298**System capability**: SystemCapability.Update.UpdateService
299
300**Return value**
301
302| Type             | Description                              |
303| ---------------- | ---------------------------------------- |
304| Promise\<number> | Promise used to return the execution result. |
305
306**Example**
307
308```
309updater.applyNewVersion().then(result => {
310    console.log("appVewVersion ", result)
311}).catch(err => {
312    console.info("applyNewVersion promise error: " + err.code);
313});
314```
315
316### applyNewVersion
317
318applyNewVersion(callback: AsyncCallback\<number>): void
319
320Installs the update package. This function uses a promise to return the result.
321
322**System capability**: SystemCapability.Update.UpdateService
323
324**Parameters**
325
326| Name     | Type                   | Mandatory | Description                              |
327| -------- | ---------------------- | --------- | ---------------------------------------- |
328| callback | AsyncCallback\<number> | Yes       | Callback used to return the execution result. |
329
330**Example**
331
332```
333updater.applyNewVersion((err, result) => {
334  console.log("applyNewVersion ", result)
335});
336```
337
338### download
339
340download(): void
341
342Downloads the new version and displays the download process.
343
344**System capability**: SystemCapability.Update.UpdateService
345
346**Example**
347
348```
349updater.on("downloadProgress", progress => {
350  console.log("downloadProgress on" + progress);
351  console.log(`downloadProgress status: ` + progress.status);
352  console.log(`downloadProgress percent: ` + progress.percent);
353});
354updater.download();
355```
356
357### upgrade
358
359upgrade():void
360
361Starts an update.
362
363**System capability**: SystemCapability.Update.UpdateService
364
365**Example**
366
367```
368updater.on("upgradeProgress", progress => {
369  console.log("upgradeProgress on" + progress);
370  console.log(`upgradeProgress status: ` + progress.status);
371  console.log(`upgradeProgress percent: ` + progress.percent);
372});
373updater.upgrade();
374```
375
376### setUpdatePolicy
377
378setUpdatePolicy(policy: UpdatePolicy, callback: AsyncCallback\<number>): void
379
380Sets the update policy. This function uses an asynchronous callback to return the result.
381
382**System capability**: SystemCapability.Update.UpdateService
383
384**Parameters**
385
386| Name     | Type                                     | Mandatory | Description                              |
387| -------- | ---------------------------------------- | --------- | ---------------------------------------- |
388| policy   | [UpdatePolicy](#updatepolicy)            | Yes       | Update policy to set.                    |
389| callback | Callback used to return the execution result. | Yes       | Callback used to return the execution result. |
390
391**Example**
392
393```
394// Set the update policy.
395let policy = {
396  autoDownload: false,
397  autoDownloadNet: true,
398  mode: 2,
399  autoUpgradeInterval: [ 2, 3 ],
400  autoUpgradeCondition: 2
401}
402updater.setUpdatePolicy(policy, (err, result) => {
403  console.log("setUpdatePolicy ", result)
404});
405```
406
407### setUpdatePolicy
408
409setUpdatePolicy(policy: UpdatePolicy): Promise\<number>
410
411Sets the update policy. This function uses a promise to return the result.
412
413**System capability**: SystemCapability.Update.UpdateService
414
415**Parameters**
416
417| Name   | Type                          | Mandatory | Description           |
418| ------ | ----------------------------- | --------- | --------------------- |
419| policy | [UpdatePolicy](#updatepolicy) | Yes       | Update policy to set. |
420
421**Return value**
422
423| Type             | Description                              |
424| ---------------- | ---------------------------------------- |
425| Promise\<number> | Promise used to return the execution result. |
426
427**Example**
428
429```
430let policy = {
431  autoDownload: false,
432  autoDownloadNet: true,
433  mode: 2,
434  autoUpgradeInterval: [ 2, 3 ],
435  autoUpgradeCondition: 2
436}
437updater.setUpdatePolicy(policy).then(result =>
438  console.log("setUpdatePolicy ", result)
439).catch(err => {
440  console.log("setUpdatePolicy promise error: " + err.code);
441});
442```
443
444### getUpdatePolicy
445
446getUpdatePolicy(callback: AsyncCallback\<UpdatePolicy>): void
447
448Obtains the update policy. This function uses an asynchronous callback to return the result.
449
450**System capability**: SystemCapability.Update.UpdateService
451
452**Parameters**
453
454| Name     | Type                                     | Mandatory | Description                              |
455| -------- | ---------------------------------------- | --------- | ---------------------------------------- |
456| callback | AsyncCallback\<[UpdatePolicy](#updatepolicy)> | No        | Callback used to return the update policy. |
457
458**Example**
459
460```
461updater.getUpdatePolicy((err, policy) => {
462  console.log("getUpdatePolicy success");
463  console.log(`policy autoDownload = ` + policy.autoDownload);
464  console.log(`policy autoDownloadNet = ` + policy.autoDownloadNet);
465  console.log(`policy mode = ` + policy.mode);
466});
467```
468
469### getUpdatePolicy
470
471getUpdatePolicy(): Promise\<UpdatePolicy>
472
473Obtains the update policy. This function uses a promise to return the result.
474
475**System capability**: SystemCapability.Update.UpdateService
476
477**Return value**
478
479| Type                                    | Description                              |
480| --------------------------------------- | ---------------------------------------- |
481| Promise\<[UpdatePolicy](#updatepolicy)> | Promise used to return the update policy. |
482
483**Example**
484
485```
486updater.getUpdatePolicy().then(value => {
487  console.log(`info autoDownload = ` + value.autoDownload);
488  console.log(`info autoDownloadNet = ` + value.autoDownloadNet);
489  console.log(`info mode = ` + value.mode);
490}).catch(err => {
491  console.log("getUpdatePolicy promise error: " + err.code);
492});
493```
494
495## UpdateTypes
496
497Enumerates update types.
498
499**System capability**: SystemCapability.Update.UpdateService
500
501| Name  | Description   |
502| ----- | ------------- |
503| OTA   | OTA update.   |
504| patch | Patch update. |
505
506## PackageTypes
507
508Enumerates update package types.
509
510**System capability**: SystemCapability.Update.UpdateService
511
512| Name                 | Default Value | Description                             |
513| -------------------- | ------------- | --------------------------------------- |
514| PACKAGE_TYPE_NORMAL  | 1             | Common update package.                  |
515| PACKAGE_TYPE_BASE    | 2             | Basic update package.                   |
516| PACKAGE_TYPE_CUST    | 3             | Custom update package.                  |
517| PACKAGE_TYPE_PRELOAD | 4             | Preinstalled update package.            |
518| PACKAGE_TYPE_COTA    | 5             | Parameter configuration update package. |
519| PACKAGE_TYPE_VERSION | 6             | Version update package.                 |
520| PACKAGE_TYPE_PATCH   | 7             | Patch package.                          |
521
522## InstallMode
523
524Enumerates update modes.
525
526**System capability**: SystemCapability.Update.UpdateService
527
528| Name                | Default Value | Description       |
529| ------------------- | ------------- | ----------------- |
530| INSTALL_MODE_NORMAL | 0             | Normal update.    |
531| INSTALL_MODE_NIGHT  | 1             | Update at night.  |
532| INSTALL_MODE_AUTO   | 2             | Automatic update. |
533
534## NewVersionStatus
535
536Enumerates new version check results.
537
538**System capability**: SystemCapability.Update.UpdateService
539
540| Name                | Default Value | Description                              |
541| ------------------- | ------------- | ---------------------------------------- |
542| VERSION_STATUS_ERR  | -1            | System error while checking for the new version. |
543| VERSION_STATUS_NEW  | 0             | New version detected.                    |
544| VERSION_STATUS_NONE | 1             | No new version detected.                 |
545| VERSION_STATUS_BUSY | 2             | System busy while checking for the new version. |
546
547## UpdatePolicy
548
549Defines the update policy.
550
551**System capability**: SystemCapability.Update.UpdateService
552
553| Name                | Type                        | Mandatory | Description                          |
554| ------------------- | --------------------------- | --------- | ------------------------------------ |
555| autoDownload        | bool                        | Yes       | Automatic update switch.             |
556| installMode         | [InstallMode](#installmode) | Yes       | Update mode.                         |
557| autoUpgradeInterval | Array\<number>              | Yes       | Period of time for automatic update. |
558
559## NewVersionInfo
560
561Defines the new version information.
562
563**System capability**: SystemCapability.Update.UpdateService
564
565| Name            | Type                                     | Mandatory | Description                      |
566| --------------- | ---------------------------------------- | --------- | -------------------------------- |
567| status          | [NewVersionStatus](#newversionstatus)    | Yes       | Update status.                   |
568| errMsg          | string                                   | Yes       | Error message.                   |
569| checkResults    | Array<[CheckResult](#checkresult)>       | Yes       | Version check result.            |
570| descriptionInfo | Array\<[DescriptionInfo](#descriptioninfo)> | Yes       | Version description information. |
571
572## CheckResult
573
574Defines the version check result.
575
576**System capability**: SystemCapability.Update.UpdateService
577
578| Name          | Type                          | Mandatory | Description                       |
579| ------------- | ----------------------------- | --------- | --------------------------------- |
580| versionName   | string                        | Yes       | Version name.                     |
581| versionCode   | number                        | Yes       | Version code.                     |
582| size          | number                        | Yes       | Version size.                     |
583| verifyInfo    | string                        | Yes       | Version verification information. |
584| packageType   | [PackageTypes](#packagetypes) | Yes       | Version type.                     |
585| descriptionId | string                        | Yes       | Version description information.  |
586
587## DescriptionInfo
588
589Defines the version description information.
590
591**System capability**: SystemCapability.Update.UpdateService
592
593| Name          | Type   | Mandatory | Description                    |
594| ------------- | ------ | --------- | ------------------------------ |
595| descriptionId | string | Yes       | Version ID information.        |
596| content       | string | Yes       | Version changelog information. |
597