1# @ohos.file.backup (Backup and Restore) (System API) 2 3The **file.backup** module provides APIs for backing up and restoring data for applications. 4 5> **NOTE** 6> 7> - The initial APIs of this module are supported since API version 10. Newly added APIs will be marked with a superscript to indicate their earliest API version. 8> - The APIs provided by this module are system APIs. 9 10## Modules to Import 11 12```ts 13import backup from '@ohos.file.backup'; 14``` 15 16## FileMeta 17 18Defines a file metadata object, which includes the application name and file URI. **FileMeta** is an indispensable object for data backup and restore. 19 20**System capability**: SystemCapability.FileManagement.StorageService.Backup 21 22| Name | Type | Mandatory| Description | 23| ---------- | ------ | ---- | --------------------------------------------------------------------------------------------------- | 24| bundleName | string | Yes | Application name, which can be obtained from [bundleManager.BundleInfo](../apis-ability-kit/js-apis-bundleManager-bundleInfo.md).| 25| uri | string | Yes | URI of the file in the application sandbox.<br>Currently, the URI is not in the standard format. It can consist of digits (0–9), letters (a–z and A–Z), underscores (_), and period (.) only. | 26 27## FileData 28 29Defines a file data object, which includes the file descriptor (FD) of the file opened. **FileData** is an indispensable object for data backup and restore. 30 31> **NOTE** 32> 33> The **FileData** must be closed after being used. Otherwise, memory leakage may occur. For details about how to close a **FileData** object, see [fs.closeSync](js-apis-file-fs.md#fsclosesync) provided by [@ohos.file.fs](js-apis-file-fs.md). 34 35**System capability**: SystemCapability.FileManagement.StorageService.Backup 36 37| Name| Type | Mandatory| Description | 38| ---- | ------ | ---- | ---------------------------------------- | 39| fd | number | Yes | FD, which can be obtained through the backup service.| 40 41## FileManifestData<sup>12+</sup> 42 43Defines a file data object, which includes the file descriptor (FD) of the file opened. The file opened by **FileManifestData** provides basic information about the files involved in incremental backup or restore. **FileManifestData** is an indispensable object for incremental backup or restore. 44 45> **NOTE** 46> 47> For details about how to close **FileManifestData**, see [fs.closeSync](js-apis-file-fs.md#fsclosesync). 48 49**System capability**: SystemCapability.FileManagement.StorageService.Backup 50| Name | Type | Mandatory| Description | 51| ---------- | ------ | ---- | ---------------------------------------- | 52| manifestFd | number | Yes | FD, which can be obtained through the backup service.| 53 54## IncrementalBackupTime<sup>12+</sup> 55 56Represents the time of the last incremental backup. 57 58**System capability**: SystemCapability.FileManagement.StorageService.Backup 59 60| Name | Type | Mandatory| Description | 61| ------------------- | ------ | ---- | --------------------------------------------------------------------------------------------------- | 62| bundleName | string | Yes | Application name, which can be obtained from [bundleManager.BundleInfo](../apis-ability-kit/js-apis-bundleManager-bundleInfo.md).| 63| lastIncrementalTime | number | Yes | Time when the last incremental backup was performed. | 64 65## BackupParams<sup>12+</sup> 66 67Represents optional parameters in JSON strings for backup and restore. 68 69**System capability**: SystemCapability.FileManagement.StorageService.Backup 70 71| Name | Type | Mandatory| Description | 72| ---------- | ------ | ---- | -------------------------------------------------- | 73| parameters | string | No | Optional parameters for backup or restore, in JSON strings.| 74 75## BackupPriority<sup>12+</sup> 76 77Represents the backup priority. 78 79**System capability**: SystemCapability.FileManagement.StorageService.Backup 80 81| Name | Type | Mandatory| Description | 82| -------- | ------ | ---- | ------------------------------------------------------ | 83| priority | number | No | Backup priority. A larger value indicates a higher priority. If the priorities are the same, the API called first is executed first.| 84 85## IncrementalBackupData<sup>12+</sup> 86 87Represents an incremental backup object, which inherits from [IncrementalBackupTime](#incrementalbackuptime12), [FileManifestData](#filemanifestdata12), [BackupParams](#backupparams12), and [BackupPriority](#backuppriority12). 88 89> **NOTE** 90> 91> This object provides information about the last incremental backup time and the FD of the file that contains a list of the files involved in the incremental backup. Optional parameters include backup and restore configuration and backup priority. 92 93**System capability**: SystemCapability.FileManagement.StorageService.Backup 94 95## File 96 97Defines a file object, which 98inherits [FileMeta](#filemeta) and [FileData](#filedata). 99 100> **NOTE** 101> 102> **file.backup.File** is different from [File](js-apis-file-fs.md#file) provided in @ohos.file.fs. The former is an object that inherits from [FileMeta](#filemeta) and [FileData](#filedata), while the latter has only one FD object. Pay attention to the difference between them. 103 104**System capability**: SystemCapability.FileManagement.StorageService.Backup 105 106## File <sup>12+</sup> 107 108Defines a file object, which 109inherits from [FileMeta](#filemeta), [FileData](#filedata), and [FileManifestData](#filemanifestdata12). 110 111> **NOTE** 112> 113> **file.backup.File** is different from [File](js-apis-file-fs.md#file) provided in @ohos.file.fs. The former is an object that inherits from [FileMeta](#filemeta) and [FileData](#filedata), while the latter has only one FD object. Pay attention to the difference between them. 114 115**System capability**: SystemCapability.FileManagement.StorageService.Backup 116 117## GeneralCallbacks 118 119Provides callbacks to be used in the backup or restore process. The backup service uses these callbacks to notify the client of the backup/restore progress of the application. 120 121**System capability**: SystemCapability.FileManagement.StorageService.Backup 122 123### onFileReady 124 125onFileReady : AsyncCallback<File> 126 127Called when the file is ready for sending to the client. If the callback is invoked successfully, [File](#file) is returned. Otherwise, an **err** object is returned. 128 129> **NOTE** 130> 131> The **File** returned by **AsyncCallback** is the file.backup.[File](#file). The returned file belongs to the backup service. Once the file is closed, the backup service shall clear the resources used by the file. However, the client must close the file handle first. 132 133**System capability**: SystemCapability.FileManagement.StorageService.Backup 134 135**Error codes** 136 137For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 138 139| ID| Error Message | 140| -------- | ----------------------- | 141| 13600001 | IPC error | 142| 13900005 | I/O error | 143| 13900011 | Out of memory | 144| 13900020 | Invalid argument | 145| 13900025 | No space left on device | 146| 13900042 | Unknown error | 147 148**Example** 149 150 ```ts 151 import fs from '@ohos.file.fs'; 152 import { BusinessError } from '@ohos.base'; 153 154 onFileReady: (err: BusinessError, file: backup.File) => { 155 if (err) { 156 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 157 return; 158 } 159 console.info('onFileReady success with file: ' + file.bundleName + ' ' + file.uri); 160 fs.closeSync(file.fd); 161 } 162 ``` 163 164### onBundleBegin 165 166onBundleBegin : AsyncCallback<string, void | string> 167 168Called when the application backup or restore starts. If the callback is successfully invoked, **bundleName** is returned. Otherwise, an **err** object is returned. Since API version 12, **err** and **bundleName** are returned. 169 170**System capability**: SystemCapability.FileManagement.StorageService.Backup 171 172**Return value** 173 174| Name | Type | Mandatory| Description | 175| ---------- | ------------- | ---- | ----------------------------------------------------------- | 176| bundleName | string | Yes | Application name. | 177| err | BusinessError | No | Error returned if the operation fails. If the operation is successful, **err** is **undefined**, and **data** is the bundle name.| 178 179**Error codes** 180 181For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 182 183| ID| Error Message | 184| -------- | ----------------------------------------------------- | 185| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verifcation faild| 186| 13500001 | The application is not added to the backup or restore | 187| 13500002 | Failed to start application extension Procedure | 188| 13600001 | IPC error | 189| 13900005 | I/O error | 190| 13900011 | Out of memory | 191| 13900020 | Invalid argument | 192| 13900025 | No space left on device | 193| 13900042 | Unknown error | 194 195**Example** 196 197 ```ts 198 import { BusinessError } from '@ohos.base'; 199 200 onBundleBegin: (err: BusinessError, bundleName: string) => { 201 if (err) { 202 console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code)); 203 return; 204 } 205 console.info('onBundleBegin success'); 206 } 207 ``` 208 209 ```ts 210 import { BusinessError } from '@ohos.base'; 211 212 onBundleBegin: (err: BusinessError<string>, bundleName: string) => { 213 if (err) { 214 console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data); 215 return; 216 } 217 console.info('onBundleBegin success'); 218 } 219 ``` 220 221### onBundleEnd 222 223onBundleEnd : AsyncCallback<string, void | string> 224 225Called when the application backup or restore ends. If the callback is successfully invoked, **bundleName** is returned. Otherwise, an **err** object is returned. Since API version 12, **err** and **bundleName** are returned. 226 227**System capability**: SystemCapability.FileManagement.StorageService.Backup 228 229**Return value** 230 231| Name | Type | Mandatory| Description | 232| ---------- | ------------- | ---- | ----------------------------------------------------------- | 233| bundleName | string | Yes | Application name. | 234| err | BusinessError | No | Error returned if the operation fails. If the operation is successful, **err** is **undefined**, and **data** is the bundle name.| 235 236**Error codes** 237 238For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 239 240| ID| Error Message | 241| -------- | ------------------------------- | 242| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verifcation faild| 243| 13500003 | Backup or restore timed out | 244| 13500004 | Application extension death | 245| 13600001 | IPC error | 246| 13900005 | I/O error | 247| 13900011 | Out of memory | 248| 13900020 | Invalid argument | 249| 13900025 | No space left on device | 250| 13900042 | Unknown error | 251 252**Example** 253 254 ```ts 255 import { BusinessError } from '@ohos.base'; 256 257 onBundleEnd: (err: BusinessError, bundleName: string) => { 258 if (err) { 259 console.error('onBundleEnd failed with err: ' + JSON.stringify(err)); 260 return; 261 } 262 console.info('onBundleEnd success with bundleName: ' + bundleName); 263 } 264 ``` 265 266 ```ts 267 import { BusinessError } from '@ohos.base'; 268 269 onBundleEnd: (err: BusinessError<string>, bundleName: string) => { 270 if (err) { 271 console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data); 272 return; 273 } 274 console.info('onBundleEnd success'); 275 } 276 ``` 277 278### onAllBundlesEnd 279 280onAllBundlesEnd : AsyncCallback<undefined> 281 282Called when the backup or restore of all applications ends. If the callback fails to be invoked, an **err** object is returned. 283 284**System capability**: SystemCapability.FileManagement.StorageService.Backup 285 286**Error codes** 287 288For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 289 290| ID| Error Message | 291| -------- | ----------------------- | 292| 13600001 | IPC error | 293| 13900005 | I/O error | 294| 13900011 | Out of memory | 295| 13900020 | Invalid argument | 296| 13900025 | No space left on device | 297| 13900042 | Unknown error | 298 299**Example** 300 301 ```ts 302 import { BusinessError } from '@ohos.base'; 303 304 onAllBundlesEnd: (err: BusinessError) => { 305 if (err) { 306 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 307 return; 308 } 309 console.info('onAllBundlesEnd success'); 310 } 311 ``` 312 313### onBackupServiceDied 314 315onBackupServiceDied : Callback<undefined> 316 317Called when the backup service is suspended. If this callback fails to be invoked, an **err** object is returned. 318 319**System capability**: SystemCapability.FileManagement.StorageService.Backup 320 321**Example** 322 323 ```ts 324 onBackupServiceDied: () => { 325 console.info('onBackupServiceDied success'); 326 } 327 ``` 328 329### onResultReport 330 331onResultReport (bundleName: string, result: string) 332 333Called when the backup or restore is complete. If the callback is invoked successfully, the application bundle name and backup or restore information (such as the number of backed up or restored records or exception information) are returned. 334 335**System capability**: SystemCapability.FileManagement.StorageService.Backup 336 337**Return value** 338 339| Name | Type | Mandatory| Description | 340| ---------- | ------ | ---- | ------------------------------- | 341| bundleName | string | Yes | Bundle name of the application. | 342| result | string | Yes | Application backup/restore information returned in JSON format.| 343 344**Example** 345 346 ```ts 347 import backup from '@ohos.file.backup'; 348 349 onResultReport: (bundleName: string, result: string) => { 350 console.info('onResultReport bundleName : ' + bundleName); 351 console.info('onResultReport result : ' + result); 352 } 353 ``` 354 355### onProcess 356 357onProcess (bundleName: string, process: string) 358 359Called to report the backup or restore progress information. If the callback is invoked successfully, the progress information or exception information are returned. 360 361**System capability**: SystemCapability.FileManagement.StorageService.Backup 362 363**Return value** 364 365| Name | Type | Mandatory| Description | 366| ---------- | ------ | ---- | ------------------------------- | 367| bundleName | string | Yes | Bundle name of the application. | 368| process | string | Yes | Backup/restore progress information in JSON format.| 369 370**Example** 371 372 ```ts 373 import backup from '@ohos.file.backup'; 374 375 onProcess: (bundleName: string, process: string) => { 376 console.info('onProcess bundleName : ' + bundleName); 377 console.info('onProcess processInfo : ' + process); 378 } 379 ``` 380 381## backup.getLocalCapabilities 382 383getLocalCapabilities(callback: AsyncCallback<FileData>): void 384 385Obtains a JSON file that describes local capabilities. This API uses an asynchronous callback to return the result. 386 387**Required permissions**: ohos.permission.BACKUP 388 389**System capability**: SystemCapability.FileManagement.StorageService.Backup 390 391**Parameters** 392 393| Name | Type | Mandatory| Description | 394| -------- | ------------------------------------------ | ---- | -------------------------------------------------- | 395| callback | AsyncCallback<[FileData](#filedata)> | Yes | Callback used to return the **FileData** object obtained.| 396 397**Error codes** 398 399For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 400 401| ID| Error Message | 402| -------- | ----------------------- | 403| 13600001 | IPC error | 404| 13900005 | I/O error | 405| 13900011 | Out of memory | 406| 13900025 | No space left on device | 407| 13900042 | Unknown error | 408 409**Example** 410 411 ```ts 412 import fs from '@ohos.file.fs'; 413 import { BusinessError } from '@ohos.base'; 414 415 try { 416 backup.getLocalCapabilities((err: BusinessError, fileData: backup.FileData) => { 417 if (err) { 418 console.error('getLocalCapabilities failed with err: ' + JSON.stringify(err)); 419 return; 420 } 421 console.info('getLocalCapabilities success'); 422 console.info('fileData info:' + fileData.fd); 423 fs.closeSync(fileData.fd); 424 }); 425 } catch (error) { 426 let err: BusinessError = error as BusinessError; 427 console.error('getLocalCapabilities failed with err: ' + JSON.stringify(err)); 428 } 429 ``` 430 431The capability file can be obtained by using [fs.stat](js-apis-file-fs.md#fsstat-1) of the [@ohos.file.fs](js-apis-file-fs.md) module. The following is an example of the capability file. 432 433 ```json 434 { 435 "bundleInfos" :[{ 436 "allToBackup" : true, 437 "extensionName" : "BackupExtensionAbility", 438 "name" : "com.example.hiworld", 439 "needToInstall" : false, 440 "spaceOccupied" : 0, 441 "versionCode" : 1000000, 442 "versionName" : "1.0.0" 443 }], 444 "deviceType" : "default", 445 "systemFullName" : "OpenHarmony-4.0.0.0" 446 } 447 ``` 448 449## backup.getLocalCapabilities 450 451getLocalCapabilities(): Promise<FileData> 452 453Obtains a JSON file that describes local capabilities. This API uses a promise to return the result. 454 455**Required permissions**: ohos.permission.BACKUP 456 457**System capability**: SystemCapability.FileManagement.StorageService.Backup 458 459**Return value** 460 461| Type | Description | 462| ------------------------------------ | ------------------------------- | 463| Promise<[FileData](#filedata)> | Promise **FileData** object obtained.| 464 465**Error codes** 466 467For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 468 469| ID| Error Message | 470| -------- | ----------------------- | 471| 13600001 | IPC error | 472| 13900005 | I/O error | 473| 13900011 | Out of memory | 474| 13900025 | No space left on device | 475| 13900042 | Unknown error | 476 477**Example** 478 479 ```ts 480 import fs from '@ohos.file.fs'; 481 import { BusinessError } from '@ohos.base'; 482 483 async function getLocalCapabilities() { 484 try { 485 let fileData = await backup.getLocalCapabilities(); 486 console.info('getLocalCapabilities success'); 487 console.info('fileData info:' + fileData.fd); 488 fs.closeSync(fileData.fd); 489 } catch (error) { 490 let err: BusinessError = error as BusinessError; 491 console.error('getLocalCapabilities failed with err: ' + JSON.stringify(err)); 492 } 493 } 494 ``` 495 496 The capability file can be obtained by using [fs.stat](js-apis-file-fs.md#fsstat) of the [@ohos.file.fs](js-apis-file-fs.md) module. The following is an example of the capability file. 497 498 ```json 499 { 500 "bundleInfos" :[{ 501 "allToBackup" : true, 502 "extensionName" : "BackupExtensionAbility", 503 "name" : "com.example.hiworld", 504 "needToInstall" : false, 505 "spaceOccupied" : 0, 506 "versionCode" : 1000000, 507 "versionName" : "1.0.0" 508 }], 509 "deviceType" : "default", 510 "systemFullName" : "OpenHarmony-4.0.0.0" 511 } 512 ``` 513 514## backup.getLocalCapabilities<sup>12+</sup> 515 516getLocalCapabilities(dataList:Array<IncrementalBackupTime>): Promise<FileData> 517 518Obtains local capabilities. The local capabilities of an application are queried based on the **dataList** parameter passed in. This API uses a promise to return the result. 519 520**Required permissions**: ohos.permission.BACKUP 521 522**System capability**: SystemCapability.FileManagement.StorageService.Backup 523 524**Parameters** 525| Name | Type | Mandatory| Description | 526| -------- | -------------------------------------------------------------- | ---- | ---------------------------------------------- | 527| dataList | Array<[IncrementalBackupTime](#incrementalbackuptime12)> | Yes | List of the files involved in the incremental backup.| 528 529**Return value** 530 531| Type | Description | 532| ------------------------------------ | ------------------------------- | 533| Promise<[FileData](#filedata)> | Promise **FileData** object obtained.| 534 535**Error codes** 536 537For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 538 539| ID| Error Message | 540| -------- | ---------------------------------------------------------------------------------------------- | 541| 201 | Permission verification failed, usually the result returned by VerifyAccessToken. | 542| 202 | Permission verification failed, application which is not a system application uses system API. | 543| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verifcation faild| 544| 13600001 | IPC error | 545| 13900005 | I/O error | 546| 13900011 | Out of memory | 547| 13900020 | Invalid argument | 548| 13900025 | No space left on device | 549| 13900042 | Unknown error | 550 551**Example** 552 553 ```ts 554 import fs from '@ohos.file.fs'; 555 import { BusinessError } from '@ohos.base'; 556 557 async function getLocalCapabilities() { 558 try { 559 let backupApps: backup.IncrementalBackupTime[] = [{ 560 bundleName: "com.example.hiworld", 561 lastIncrementalTime: 1700107870 // Time of the last incremental backup. 562 }]; 563 let fileData = await backup.getLocalCapabilities(backupApps); 564 console.info('getLocalCapabilities success'); 565 console.info('fileData info:' + fileData.fd); 566 fs.closeSync(fileData.fd); 567 } catch (error) { 568 let err: BusinessError = error as BusinessError; 569 console.error('getLocalCapabilities failed with err: ' + JSON.stringify(err)); 570 } 571 } 572 ``` 573 574## backup.getBackupInfo 575 576getBackupInfo(bundleToBackup: string): string; 577 578Obtains information about the application to back up. 579 580**Required permissions**: ohos.permission.BACKUP 581 582**System capability**: SystemCapability.FileManagement.StorageService.Backup 583 584**Parameters** 585 586| Name | Type | Mandatory| Description | 587| --------------- | -------- | ---- | -------------------------- | 588| bundleToBackup | string | Yes | Name of the application to back up.| 589 590**Return value** 591 592| Type | Description | 593| ------------------- | ----------------------- | 594| string | Application information obtained.| 595 596**Error codes** 597 598For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 599 600| ID| Error Message | 601| -------- | ----------------------- | 602| 13600001 | IPC error | 603| 13900001 | Operation not permitted | 604| 13900005 | I/O error | 605| 13900011 | Out of memory | 606| 13900020 | Invalid argument | 607| 13900025 | No space left on device | 608| 13900042 | Unknown error | 609 610**Example** 611 612 ```ts 613 import fs from '@ohos.file.fs'; 614 import { BusinessError } from '@ohos.base'; 615 import backup from '@ohos.file.backup'; 616 617 function getBackupInfo() { 618 try { 619 let backupApp = "com.example.hiworld"; 620 let result = backup.getBackupInfo(backupApp); 621 console.info('getBackupInfo success, result: ' + result); 622 } catch (error) { 623 let err: BusinessError = error as BusinessError; 624 console.error('getBackupInfo failed with err: ' + JSON.stringify(err)); 625 } 626 } 627 ``` 628 629## backup.updateTimer 630 631updateTimer(bundleName: string, timeout: number): void; 632 633Called after **onBundleBegin** and before **onBundleEnd** to set the backup or restore timer. 634 635**Required permissions**: ohos.permission.BACKUP 636 637**System capability**: SystemCapability.FileManagement.StorageService.Backup 638 639**Parameters** 640 641| Name | Type | Mandatory| Description | 642| --------------- | -------- | ---- | -------------------------- | 643| bundleName | string | Yes | Name of the application, for which you want to set the backup or restore duration.| 644| timeout | number | Yes | Maximum backup or restore duration, in ms.<br>Value range: [0, 14400000]| 645 646**Return value** 647 648| Type | Description | 649| ------------------- | ----------------------- | 650| boolean | A Boolean value indicating whether the backup or restore timeout is set successfully. The value **true** indicates that the setting is successful, and the value **false** indicates that the setting fails.| 651 652**Error codes** 653 654| ID| Error Message | 655| -------- | ----------------------- | 656| 201 | Permission verification failed, usually the result returned by VerifyAccessToken. | 657| 202 | Permission verification failed, application which is not a system application uses system API. | 658| 401 | The input parameter is invalid. | 659 660**Example** 661 662 ```ts 663 import { BusinessError } from '@ohos.base'; 664 import backup from '@ohos.file.backup'; 665 666 function updateTimer() { 667 try { 668 let timeout = 30000; 669 let bundleName = "com.example.hiworld"; 670 let result = backup.updateTimer(bundleName, timeout); 671 if (result) { 672 console.info('updateTimer success'); 673 } else { 674 console.info('updateTimer fail'); 675 } 676 } catch (error) { 677 let err: BusinessError = error as BusinessError; 678 console.error('updateTimer failed with err: ' + JSON.stringify(err)); 679 } 680 } 681 ``` 682 683## backup.updateSendRate 684 685updateSendRate(bundleName: string, sendRate: number): boolean; 686 687Called after **onBundleBegin** and before **onBundleEnd** to set the backup or restore timer. 688 689**Required permissions**: ohos.permission.BACKUP 690 691**System capability**: SystemCapability.FileManagement.StorageService.Backup 692 693**Parameters** 694 695| Name | Type | Mandatory| Description | 696| --------------- | -------- | ---- | -------------------------- | 697| bundleName|string | Yes | Name of the target application. 698| sendRate | number | Yes | Send rate to set, in file descriptors (FDs) per second.<br>Value range: 0 to 800<br>Default value: 60 FDs/second <br>The value **0** means to stop transmission. If the value is greater than **800**, the send rate is 800 FDs/second.| 699 700**Return value** 701 702| Type | Description | 703| ------------------- | ----------------------- | 704| boolean | A Boolean value indicating whether the send rate is set successfully. The value **true** indicates that the setting is successful, and the value **false** indicates that the setting fails.| 705 706**Error codes** 707 708| ID| Error Message | 709| -------- | ----------------------- | 710| 201 | Permission verification failed, usually the result returned by VerifyAccessToken. | 711| 202 | Permission verification failed, application which is not a system application uses system API. | 712| 401 | The input parameter is invalid. | 713 714**Example** 715 716 ```ts 717 import { BusinessError } from '@ohos.base'; 718 import backup from '@ohos.file.backup'; 719 720 function updateSendRate() { 721 try { 722 let bundleName = "com.example.myApp"; 723 let sendRate = 300; 724 let result = backup.updateSendRate(bundleName, sendRate); 725 if (result) { 726 console.info('updateSendRate success'); 727 } else { 728 console.info('updateSendRate fail'); 729 } 730 } catch (error) { 731 let err: BusinessError = error as BusinessError; 732 console.error('updateSendRate failed with err: ' + JSON.stringify(err)); 733 } 734 } 735 ``` 736 737## SessionBackup 738 739Provides a backup process object to support the application backup process. Before using the APIs of this class, you need to create a **SessionBackup** instance. 740 741### constructor 742 743constructor(callbacks: GeneralCallbacks); 744 745A constructor used to create a **SessionBackup** instance. 746 747**Required permissions**: ohos.permission.BACKUP 748 749**System capability**: SystemCapability.FileManagement.StorageService.Backup 750 751**Parameters** 752 753| Name | Type | Mandatory| Description | 754| -------- | ------------------------------------- | ---- | -------------------- | 755| callback | [GeneralCallbacks](#generalcallbacks) | Yes | Callbacks to be invoked during the backup process.| 756 757**Example** 758 759 ```ts 760 import fs from '@ohos.file.fs'; 761 import { BusinessError } from '@ohos.base'; 762 763 let generalCallbacks: backup.GeneralCallbacks = { 764 onFileReady: (err: BusinessError, file: backup.File) => { 765 if (err) { 766 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 767 return; 768 } 769 console.info('onFileReady success'); 770 fs.closeSync(file.fd); 771 }, 772 onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => { 773 if (err) { 774 console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data); 775 return; 776 } 777 console.info('onBundleBegin success'); 778 }, 779 onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => { 780 if (err) { 781 console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data); 782 return; 783 } 784 console.info('onBundleEnd success'); 785 }, 786 onAllBundlesEnd: (err: BusinessError) => { 787 if (err) { 788 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 789 return; 790 } 791 console.info('onAllBundlesEnd success'); 792 }, 793 onBackupServiceDied: () => { 794 console.info('service died'); 795 }, 796 onResultReport: (bundleName: string, result: string) => { 797 console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result); 798 }, 799 onProcess: (bundleName: string, process: string) => { 800 console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process); 801 } 802 }; 803 let sessionBackup = new backup.SessionBackup(generalCallbacks); // Create a backup process. 804 ``` 805 806### appendBundles 807 808appendBundles(bundlesToBackup: string[], callback: AsyncCallback<void>): void 809 810Appends the applications whose data needs to be backed up. Currently, the obtained **SessionBackup** instance can be called only once in the entire backup process. This API uses an asynchronous callback to return the result. 811 812**Required permissions**: ohos.permission.BACKUP 813 814**System capability**: SystemCapability.FileManagement.StorageService.Backup 815 816**Parameters** 817 818| Name | Type | Mandatory| Description | 819| --------------- | ------------------------- | ---- | ---------------------------- | 820| bundlesToBackup | string[] | Yes | Array of the application names to append. | 821| callback | AsyncCallback<void> | Yes | Callback used to return the result.| 822 823**Error codes** 824 825For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 826 827| ID| Error Message | 828| -------- | ----------------------- | 829| 13600001 | IPC error | 830| 13900001 | Operation not permitted | 831| 13900005 | I/O error | 832| 13900011 | Out of memory | 833| 13900020 | Invalid argument | 834| 13900025 | No space left on device | 835| 13900042 | Unknown error | 836 837**Example** 838 839 ```ts 840 import fs from '@ohos.file.fs'; 841 import { BusinessError } from '@ohos.base'; 842 843 let generalCallbacks: backup.GeneralCallbacks = { 844 onFileReady: (err: BusinessError, file: backup.File) => { 845 if (err) { 846 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 847 return; 848 } 849 console.info('onFileReady success'); 850 fs.closeSync(file.fd); 851 }, 852 onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => { 853 if (err) { 854 console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data); 855 return; 856 } 857 console.info('onBundleBegin success'); 858 }, 859 onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => { 860 if (err) { 861 console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data); 862 return; 863 } 864 console.info('onBundleEnd success'); 865 }, 866 onAllBundlesEnd: (err: BusinessError) => { 867 if (err) { 868 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 869 return; 870 } 871 console.info('onAllBundlesEnd success'); 872 }, 873 onBackupServiceDied: () => { 874 console.info('service died'); 875 }, 876 onResultReport: (bundleName: string, result: string) => { 877 console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result); 878 }, 879 onProcess: (bundleName: string, process: string) => { 880 console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process); 881 } 882 }; 883 let sessionBackup = new backup.SessionBackup(generalCallbacks); // Create a backup process. 884 try { 885 let backupApps: Array<string> = [ 886 "com.example.hiworld", 887 ]; 888 sessionBackup.appendBundles(backupApps, (err: BusinessError) => { 889 if (err) { 890 console.error('appendBundles failed with err: ' + JSON.stringify(err)); 891 return; 892 } 893 console.info('appendBundles success'); 894 }); 895 } catch (error) { 896 let err: BusinessError = error as BusinessError; 897 console.error('appendBundles failed with err: ' + JSON.stringify(err)); 898 } 899 ``` 900 901### appendBundles 902 903appendBundles(bundlesToBackup: string[], infos?: string[]): Promise<void> 904 905Appends the applications whose data needs to be backed up. Currently, the obtained **SessionBackup** instance can be called only once in the entire backup process. This API uses a promise to return the result. 906 907From API version 12, the optional parameter **infos** is added to carry information about each application to be backed up. The mappings between **infos** and **bundlesToBackup** are identified by index. 908 909**Required permissions**: ohos.permission.BACKUP 910 911**System capability**: SystemCapability.FileManagement.StorageService.Backup 912 913**Parameters** 914 915| Name | Type | Mandatory| Description | 916| --------------- | -------- | ---- | -------------------------- | 917| bundlesToBackup | string[] | Yes | Array of the application names to append.| 918| infos | string[] | No | Array of the information about each application to be backed up. The mappings between **infos** and **bundlesToBackup** are identified by index. This parameter is supported since API version 12.| 919 920**Return value** 921 922| Type | Description | 923| ------------------- | ----------------------- | 924| Promise<void> | Promise that returns no value.| 925 926**Error codes** 927 928For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 929 930| ID| Error Message | 931| -------- | ----------------------- | 932| 13600001 | IPC error | 933| 13900001 | Operation not permitted | 934| 13900005 | I/O error | 935| 13900011 | Out of memory | 936| 13900020 | Invalid argument | 937| 13900025 | No space left on device | 938| 13900042 | Unknown error | 939 940**Example** 941 942 ```ts 943 import fs from '@ohos.file.fs'; 944 import { BusinessError } from '@ohos.base'; 945 946 let generalCallbacks: backup.GeneralCallbacks = { 947 onFileReady: (err: BusinessError, file: backup.File) => { 948 if (err) { 949 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 950 return; 951 } 952 console.info('onFileReady success'); 953 fs.closeSync(file.fd); 954 }, 955 onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => { 956 if (err) { 957 console.error('onBundleBegin failed with err: ' + JSON.stringify(err)); 958 return; 959 } 960 console.info('onBundleBegin success'); 961 }, 962 onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => { 963 if (err) { 964 console.error('onBundleEnd failed with err: ' + JSON.stringify(err)); 965 return; 966 } 967 console.info('onBundleEnd success'); 968 }, 969 onAllBundlesEnd: (err: BusinessError) => { 970 if (err) { 971 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 972 return; 973 } 974 console.info('onAllBundlesEnd success'); 975 }, 976 onBackupServiceDied: () => { 977 console.info('service died'); 978 }, 979 onResultReport: (bundleName: string, result: string) => { 980 console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result); 981 }, 982 onProcess: (bundleName: string, process: string) => { 983 console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process); 984 } 985 }; 986 let sessionBackup = new backup.SessionBackup(generalCallbacks); // Create a backup process. 987 async function appendBundles() { 988 try { 989 let backupApps: Array<string> = [ 990 "com.example.hiworld", 991 "com.example.myApp" 992 ]; 993 await sessionBackup.appendBundles(backupApps); 994 console.info('appendBundles success'); 995 // Application information is carried. In the following, infos, details, and type are fixed parameters. 996 let infos: Array<string> = [ 997 ` 998 { 999 "infos": [ 1000 { 1001 "details": [ 1002 { 1003 "detail": [ 1004 { 1005 "key1": "value1", 1006 "key2": "value2" 1007 } 1008 ] 1009 } 1010 ], 1011 "type": "unicast", 1012 "bundleName": "com.example.hiworld" 1013 } 1014 ] 1015 }, 1016 { 1017 "infos": [ 1018 { 1019 "details": [ 1020 { 1021 "detail": [ 1022 { 1023 "key1": "value1", 1024 "key2": "value2" 1025 } 1026 ] 1027 } 1028 ], 1029 "type": "unicast", 1030 "bundleName": "com.example.myApp" 1031 } 1032 ] 1033 } 1034 ` 1035 ] 1036 await sessionBackup.appendBundles(backupApps, infos); 1037 console.info('appendBundles success'); 1038 } catch (error) { 1039 let err: BusinessError = error as BusinessError; 1040 console.error('appendBundles failed with err: ' + JSON.stringify(err)); 1041 } 1042 } 1043 ``` 1044 1045### release<sup>12+</sup> 1046 1047release(): Promise<void> 1048 1049Releases the backup session when the backup process is complete. This API disconnects the application from the backup and restore service and exits the service. This API uses a promise to return the result. 1050 1051**Required permissions**: ohos.permission.BACKUP 1052 1053**System capability**: SystemCapability.FileManagement.StorageService.Backup 1054 1055**Return value** 1056 1057| Type | Description | 1058| ------------------- | ----------------------- | 1059| Promise<void> | Promise that returns no value.| 1060 1061**Error codes** 1062 1063For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 1064 1065| ID| Error Message | 1066| -------- | ---------------------------------------------------------------------------------------------- | 1067| 201 | Permission verification failed, usually the result returned by VerifyAccessToken. | 1068| 202 | Permission verification failed, application which is not a system application uses system API. | 1069| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verifcation faild| 1070| 13600001 | IPC error | 1071| 13900001 | Operation not permitted | 1072| 13900005 | I/O error | 1073| 13900042 | Unknown error | 1074 1075**Example** 1076 1077 ```ts 1078 import fs from '@ohos.file.fs'; 1079 import { BusinessError } from '@ohos.base'; 1080 1081 let generalCallbacks: backup.GeneralCallbacks = { 1082 onFileReady: (err: BusinessError, file: backup.File) => { 1083 if (err) { 1084 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 1085 return; 1086 } 1087 console.info('onFileReady success'); 1088 fs.closeSync(file.fd); 1089 }, 1090 onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => { 1091 if (err) { 1092 console.error('onBundleBegin failed with err: ' + JSON.stringify(err)); 1093 return; 1094 } 1095 console.info('onBundleBegin success'); 1096 }, 1097 onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => { 1098 if (err) { 1099 console.error('onBundleEnd failed with err: ' + JSON.stringify(err)); 1100 return; 1101 } 1102 console.info('onBundleEnd success'); 1103 }, 1104 onAllBundlesEnd: (err: BusinessError) => { 1105 if (err) { 1106 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 1107 return; 1108 } 1109 console.info('onAllBundlesEnd success'); 1110 }, 1111 onBackupServiceDied: () => { 1112 console.info('service died'); 1113 }, 1114 onResultReport: (bundleName: string, result: string) => { 1115 console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result); 1116 }, 1117 onProcess: (bundleName: string, process: string) => { 1118 console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process); 1119 } 1120 }; 1121 let sessionBackup = new backup.SessionBackup(generalCallbacks); // Create a backup process. 1122 async function release() { 1123 try { 1124 await sessionBackup.release(); 1125 console.info('release success'); 1126 } catch (error) { 1127 let err: BusinessError = error as BusinessError; 1128 console.error('release failed with err: ' + JSON.stringify(err)); 1129 } 1130 } 1131 ``` 1132 1133## SessionRestore 1134 1135Provides an object to support the application restore process. Before using the APIs of this class, you need to create a **SessionRestore** instance. 1136 1137### constructor 1138 1139constructor(callbacks: GeneralCallbacks); 1140 1141A constructor used to create a **SessionRestore** instance. 1142 1143**Required permissions**: ohos.permission.BACKUP 1144 1145**System capability**: SystemCapability.FileManagement.StorageService.Backup 1146 1147**Parameters** 1148 1149| Name | Type | Mandatory| Description | 1150| -------- | ------------------------------------- | ---- | -------------------- | 1151| callback | [GeneralCallbacks](#generalcallbacks) | Yes | Callbacks to be invoked during the data restore process.| 1152 1153**Example** 1154 1155 ```ts 1156 import fs from '@ohos.file.fs'; 1157 import { BusinessError } from '@ohos.base'; 1158 1159 let generalCallbacks: backup.GeneralCallbacks = { 1160 onFileReady: (err: BusinessError, file: backup.File) => { 1161 if (err) { 1162 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 1163 return; 1164 } 1165 console.info('onFileReady success'); 1166 fs.closeSync(file.fd); 1167 }, 1168 onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => { 1169 if (err) { 1170 console.error('onBundleBegin failed with err: ' + JSON.stringify(err)); 1171 return; 1172 } 1173 console.info('onBundleBegin success'); 1174 }, 1175 onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => { 1176 if (err) { 1177 console.error('onBundleEnd failed with err: ' + JSON.stringify(err)); 1178 return; 1179 } 1180 console.info('onBundleEnd success'); 1181 }, 1182 onAllBundlesEnd: (err: BusinessError) => { 1183 if (err) { 1184 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 1185 return; 1186 } 1187 console.info('onAllBundlesEnd success'); 1188 }, 1189 onBackupServiceDied: () => { 1190 console.info('service died'); 1191 }, 1192 onResultReport: (bundleName: string, result: string) => { 1193 console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result); 1194 }, 1195 onProcess: (bundleName: string, process: string) => { 1196 console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process); 1197 } 1198 }; 1199 let sessionRestore = new backup.SessionRestore(generalCallbacks); // Create a restore process. 1200 ``` 1201 1202### appendBundles 1203 1204appendBundles(remoteCapabilitiesFd: number, bundlesToBackup: string[], callback: AsyncCallback<void>): void 1205 1206Appends the applications whose data needs to be restored. Currently, the obtained **SessionRestore** instance can be called only once in the entire restore process. 1207 1208> **NOTE** 1209> 1210> - During the data restore, the capability file needs to be verified. 1211> - Therefore, **remoteCapabilitiesFd** can be obtained by using the [getLocalCapabilities](#backupgetlocalcapabilities) API provided by the backup service. You can modify the parameters based on the actual situation of your application. You can also use the JSON file example provided by **getLocalCapabilities** to generate a capability file. 1212 1213**Required permissions**: ohos.permission.BACKUP 1214 1215**System capability**: SystemCapability.FileManagement.StorageService.Backup 1216 1217**Parameters** 1218 1219| Name | Type | Mandatory| Description | 1220| -------------------- | ------------------------- | ---- | ---------------------------------- | 1221| remoteCapabilitiesFd | number | Yes | FD of the file containing the capabilities to be restored.| 1222| bundlesToBackup | string[] | Yes | Array of the application names to append. | 1223| callback | AsyncCallback<void> | Yes | Callback used to return the result.| 1224 1225**Error codes** 1226 1227For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 1228 1229| ID| Error Message | 1230| -------- | ----------------------- | 1231| 13600001 | IPC error | 1232| 13900001 | Operation not permitted | 1233| 13900005 | I/O error | 1234| 13900011 | Out of memory | 1235| 13900020 | Invalid argument | 1236| 13900025 | No space left on device | 1237| 13900042 | Unknown error | 1238 1239**Example** 1240 1241 ```ts 1242 import fs from '@ohos.file.fs'; 1243 import { BusinessError } from '@ohos.base'; 1244 1245 let generalCallbacks: backup.GeneralCallbacks = { 1246 onFileReady: (err: BusinessError, file: backup.File) => { 1247 if (err) { 1248 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 1249 return; 1250 } 1251 console.info('onFileReady success'); 1252 fs.closeSync(file.fd); 1253 }, 1254 onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => { 1255 if (err) { 1256 console.error('onBundleBegin failed with err: ' + JSON.stringify(err)); 1257 return; 1258 } 1259 console.info('onBundleBegin success'); 1260 }, 1261 onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => { 1262 if (err) { 1263 console.error('onBundleEnd failed with err: ' + JSON.stringify(err)); 1264 return; 1265 } 1266 console.info('onBundleEnd success'); 1267 }, 1268 onAllBundlesEnd: (err: BusinessError) => { 1269 if (err) { 1270 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 1271 return; 1272 } 1273 console.info('onAllBundlesEnd success'); 1274 }, 1275 onBackupServiceDied: () => { 1276 console.info('service died'); 1277 }, 1278 onResultReport: (bundleName: string, result: string) => { 1279 console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result); 1280 }, 1281 onProcess: (bundleName: string, process: string) => { 1282 console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process); 1283 } 1284 }; 1285 let sessionRestore = new backup.SessionRestore(generalCallbacks); // Create a restore process. 1286 async function appendBundles() { 1287 let fileData : backup.FileData = { 1288 fd : -1 1289 } 1290 try { 1291 fileData = await backup.getLocalCapabilities(); 1292 console.info('getLocalCapabilities success'); 1293 let restoreApps: Array<string> = [ 1294 "com.example.hiworld", 1295 ]; 1296 sessionRestore.appendBundles(fileData.fd, restoreApps, (err: BusinessError) => { 1297 if (err) { 1298 console.error('appendBundles failed with err: ' + JSON.stringify(err)); 1299 return; 1300 } 1301 console.info('appendBundles success'); 1302 }); 1303 } catch (error) { 1304 let err: BusinessError = error as BusinessError; 1305 console.error('getLocalCapabilities failed with err: ' + JSON.stringify(err)); 1306 } finally { 1307 fs.closeSync(fileData.fd); 1308 } 1309 } 1310 ``` 1311 1312### appendBundles 1313 1314appendBundles(remoteCapabilitiesFd: number, bundlesToBackup: string[], infos?: string[]): Promise<void> 1315 1316Appends the applications whose data needs to be restored. From API version 12, the optional parameter **infos** is added to carry information about each application to be restored. The mappings between **infos** and **bundlesToBackup** are identified by index. 1317Currently, the obtained **SessionRestore** instance can be called only once in the entire restore process. This API uses a promise to return the result. 1318 1319> **NOTE** 1320> 1321> - During the data restore, the capability file needs to be verified. 1322> - You can use [getLocalCapabilities](#backupgetlocalcapabilities) to obtain **remoteCapabilitiesFd**, 1323 and modify the parameters based on the application to be restored. You can also use the JSON file example provided by **getLocalCapabilities** to generate a capability file. 1324 1325**Required permissions**: ohos.permission.BACKUP 1326 1327**System capability**: SystemCapability.FileManagement.StorageService.Backup 1328 1329**Parameters** 1330 1331| Name | Type | Mandatory| Description | 1332| -------------------- | -------- | ---- | ---------------------------------- | 1333| remoteCapabilitiesFd | number | Yes | FD of the file containing the capabilities to be restored.| 1334| bundlesToBackup | string[] | Yes | Array of the application names to append. | 1335| infos<sup>12+</sup> | string[] | No | Array of the information about each application to be restored. The mappings between **infos** and **bundlesToBackup** are identified by index. This parameter is supported since API version 12.| 1336 1337**Return value** 1338 1339| Type | Description | 1340| ------------------- | ----------------------- | 1341| Promise<void> | Promise that returns no value.| 1342 1343**Error codes** 1344 1345For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 1346 1347| ID| Error Message | 1348| -------- | ----------------------- | 1349| 13600001 | IPC error | 1350| 13900001 | Operation not permitted | 1351| 13900005 | I/O error | 1352| 13900011 | Out of memory | 1353| 13900020 | Invalid argument | 1354| 13900025 | No space left on device | 1355| 13900042 | Unknown error | 1356 1357**Example** 1358 1359 ```ts 1360 import fs from '@ohos.file.fs'; 1361 import { BusinessError } from '@ohos.base'; 1362 1363 let generalCallbacks: backup.GeneralCallbacks = { 1364 onFileReady: (err: BusinessError, file: backup.File) => { 1365 if (err) { 1366 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 1367 return; 1368 } 1369 console.info('onFileReady success'); 1370 fs.closeSync(file.fd); 1371 }, 1372 onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => { 1373 if (err) { 1374 console.error('onBundleBegin failed with err: ' + JSON.stringify(err)); 1375 return; 1376 } 1377 console.info('onBundleBegin success'); 1378 }, 1379 onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => { 1380 if (err) { 1381 console.error('onBundleEnd failed with err: ' + JSON.stringify(err)); 1382 return; 1383 } 1384 console.info('onBundleEnd success'); 1385 }, 1386 onAllBundlesEnd: (err: BusinessError) => { 1387 if (err) { 1388 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 1389 return; 1390 } 1391 console.info('onAllBundlesEnd success'); 1392 }, 1393 onBackupServiceDied: () => { 1394 console.info('service died'); 1395 }, 1396 onResultReport: (bundleName: string, result: string) => { 1397 console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result); 1398 }, 1399 onProcess: (bundleName: string, process: string) => { 1400 console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process); 1401 } 1402 }; 1403 let sessionRestore = new backup.SessionRestore(generalCallbacks); // Create a restore process. 1404 async function appendBundles() { 1405 let fileData : backup.FileData = { 1406 fd : -1 1407 } 1408 try { 1409 fileData = await backup.getLocalCapabilities(); 1410 console.info('getLocalCapabilities success'); 1411 let restoreApps: Array<string> = [ 1412 "com.example.hiworld", 1413 ]; 1414 await sessionRestore.appendBundles(fileData.fd, restoreApps); 1415 console.info('appendBundles success'); 1416 // Information of the applications to restore. 1417 let infos: Array<string> = [ 1418 ` 1419 { 1420 "infos":[ 1421 { 1422 "details": [ 1423 { 1424 "detail": [ 1425 { 1426 "source": "com.example.hiworld", // Old bundle name of the application. 1427 "target": "com.example.helloworld" // New bundle name of the application. 1428 } 1429 ], 1430 "type": "app_mapping_relation" 1431 } 1432 ], 1433 "type":"broadcast" 1434 } 1435 ] 1436 } 1437 ` 1438 ] 1439 await sessionRestore.appendBundles(fileData.fd, restoreApps, infos); 1440 console.info('appendBundles success'); 1441 } catch (error) { 1442 let err: BusinessError = error as BusinessError; 1443 console.error('getLocalCapabilities failed with err: ' + JSON.stringify(err)); 1444 } finally { 1445 fs.closeSync(fileData.fd); 1446 } 1447 } 1448 ``` 1449 1450### getFileHandle 1451 1452getFileHandle(fileMeta: FileMeta, callback: AsyncCallback<void>): void 1453 1454Obtains the handle of the shared file from the service. This API uses an asynchronous callback to return the result. 1455 1456> **NOTE** 1457> 1458> - This interface is part of the zero-copy feature, which reduces unnecessary memory copies and increases transmission efficiency. For details about the zero-copy methods, see the zero-copy APIs such as [fs.copyFile](js-apis-file-fs.md#fscopyfile) provided by [@ohos.file.fs](js-apis-file-fs.md). 1459> - Before using **getFileHandle**, you need to obtain a **SessionRestore** instance and add the applications with data to be restored by using **appendBundles**. 1460> - You can use **onFileReady** to obtain the file handle. When file operations are completed at the client, you need to use **publishFile** to publish the file. 1461> - **getFileHandle** can be called multiple times based on the number of files to be restored. 1462> - File to be restored cannot be a relative path (**../**) or soft link. 1463 1464**Required permissions**: ohos.permission.BACKUP 1465 1466**System capability**: SystemCapability.FileManagement.StorageService.Backup 1467 1468**Parameters** 1469 1470| Name | Type | Mandatory| Description | 1471| -------- | ------------------------- | ---- | -------------------------------- | 1472| fileMeta | [FileMeta](#filemeta) | Yes | Metadata of the file to restore. | 1473| callback | AsyncCallback<void> | Yes | Callback used to return the result.| 1474 1475**Error codes** 1476 1477For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 1478 1479| ID| Error Message | 1480| -------- | ----------------------- | 1481| 13600001 | IPC error | 1482| 13900001 | Operation not permitted | 1483| 13900020 | Invalid argument | 1484| 13900042 | Unknown error | 1485 1486**Example** 1487 1488 ```ts 1489 import fs from '@ohos.file.fs'; 1490 import { BusinessError } from '@ohos.base'; 1491 1492 let generalCallbacks: backup.GeneralCallbacks = { 1493 onFileReady: (err: BusinessError, file: backup.File) => { 1494 if (err) { 1495 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 1496 return; 1497 } 1498 console.info('onFileReady success'); 1499 fs.closeSync(file.fd); 1500 }, 1501 onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => { 1502 if (err) { 1503 console.error('onBundleBegin failed with err: ' + JSON.stringify(err)); 1504 return; 1505 } 1506 console.info('onBundleBegin success'); 1507 }, 1508 onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => { 1509 if (err) { 1510 console.error('onBundleEnd failed with err: ' + JSON.stringify(err)); 1511 return; 1512 } 1513 console.info('onBundleEnd success'); 1514 }, 1515 onAllBundlesEnd: (err: BusinessError) => { 1516 if (err) { 1517 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 1518 return; 1519 } 1520 console.info('onAllBundlesEnd success'); 1521 }, 1522 onBackupServiceDied: () => { 1523 console.info('service died'); 1524 }, 1525 onResultReport: (bundleName: string, result: string) => { 1526 console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result); 1527 }, 1528 onProcess: (bundleName: string, process: string) => { 1529 console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process); 1530 } 1531 }; 1532 let sessionRestore = new backup.SessionRestore(generalCallbacks); // Create a restore process. 1533 let fileMeta: backup.FileMeta = { 1534 bundleName: "com.example.hiworld", 1535 uri: "test.txt" 1536 } 1537 sessionRestore.getFileHandle(fileMeta, (err: BusinessError) => { 1538 if (err) { 1539 console.error('getFileHandle failed with err: ' + JSON.stringify(err)); 1540 } 1541 console.info('getFileHandle success'); 1542 }); 1543 ``` 1544 1545### getFileHandle 1546 1547getFileHandle(fileMeta: FileMeta): Promise<void> 1548 1549Obtains the handle of the shared file from the service. This API uses a promise to return the result. 1550 1551> **NOTE** 1552> 1553> - This interface is part of the zero-copy feature, which reduces unnecessary memory copies and increases transmission efficiency. For details about the zero-copy methods, see the zero-copy APIs such as [fs.copyFile](js-apis-file-fs.md#fscopyfile) provided by [@ohos.file.fs](js-apis-file-fs.md). 1554> - Before using **getFileHandle**, you need to obtain a **SessionRestore** instance and add the applications with data to be restored by using **appendBundles**. 1555> - You can use **onFileReady** to obtain the file handle. When file operations are completed at the client, you need to use **publishFile** to publish the file. 1556> - **getFileHandle** can be called multiple times based on the number of files to be restored. 1557> - File to be restored cannot be a relative path (**../**) or soft link. 1558 1559**Required permissions**: ohos.permission.BACKUP 1560 1561**System capability**: SystemCapability.FileManagement.StorageService.Backup 1562 1563**Parameters** 1564 1565| Name | Type | Mandatory| Description | 1566| -------- | --------------------- | ---- | ------------------ | 1567| fileMeta | [FileMeta](#filemeta) | Yes | Metadata of the file to restore.| 1568 1569**Return value** 1570 1571| Type | Description | 1572| ------------------- | ----------------------- | 1573| Promise<void> | Promise that returns no value.| 1574 1575**Error codes** 1576 1577For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 1578 1579| ID| Error Message | 1580| -------- | ----------------------- | 1581| 13600001 | IPC error | 1582| 13900001 | Operation not permitted | 1583| 13900020 | Invalid argument | 1584| 13900042 | Unknown error | 1585 1586**Example** 1587 1588 ```ts 1589 import fs from '@ohos.file.fs'; 1590 import { BusinessError } from '@ohos.base'; 1591 1592 let generalCallbacks: backup.GeneralCallbacks = { 1593 onFileReady: (err: BusinessError, file: backup.File) => { 1594 if (err) { 1595 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 1596 return; 1597 } 1598 console.info('onFileReady success'); 1599 fs.closeSync(file.fd); 1600 }, 1601 onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => { 1602 if (err) { 1603 console.error('onBundleBegin failed with err: ' + JSON.stringify(err)); 1604 return; 1605 } 1606 console.info('onBundleBegin success'); 1607 }, 1608 onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => { 1609 if (err) { 1610 console.error('onBundleEnd failed with err: ' + JSON.stringify(err)); 1611 return; 1612 } 1613 console.info('onBundleEnd success'); 1614 }, 1615 onAllBundlesEnd: (err: BusinessError) => { 1616 if (err) { 1617 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 1618 return; 1619 } 1620 console.info('onAllBundlesEnd success'); 1621 }, 1622 onBackupServiceDied: () => { 1623 console.info('service died'); 1624 }, 1625 onResultReport: (bundleName: string, result: string) => { 1626 console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result); 1627 }, 1628 onProcess: (bundleName: string, process: string) => { 1629 console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process); 1630 } 1631 }; 1632 let sessionRestore = new backup.SessionRestore(generalCallbacks); // Create a restore process. 1633 async function getFileHandle() { 1634 try { 1635 let fileMeta: backup.FileMeta = { 1636 bundleName: "com.example.hiworld", 1637 uri: "test.txt" 1638 } 1639 await sessionRestore.getFileHandle(fileMeta); 1640 console.info('getFileHandle success'); 1641 } catch (error) { 1642 let err: BusinessError = error as BusinessError; 1643 console.error('getFileHandle failed with err: ' + JSON.stringify(err)); 1644 } 1645 } 1646 ``` 1647 1648### publishFile 1649 1650publishFile(fileMeta: FileMeta, callback: AsyncCallback<void>): void 1651 1652Publishes **FileMeta** to the backup service to indicate that the file content is ready. This API uses an asynchronous callback to return the result. 1653 1654> **NOTE** 1655> 1656> - This interface is part of the zero-copy feature, which reduces unnecessary memory copies and increases transmission efficiency. For details about the zero-copy methods, see the zero-copy APIs such as [fs.copyFile](js-apis-file-fs.md#fscopyfile) provided by [@ohos.file.fs](js-apis-file-fs.md). 1657> - After the server returns a file handle through **onFileReady**, the client can copy data to the file corresponding to the file handle provided by the server through zero-copy operations. 1658> - This API can be called only after the caller has written all the data to be restored. The caller must ensure the consistency and integrity of the data to be written. 1659 1660**Required permissions**: ohos.permission.BACKUP 1661 1662**System capability**: SystemCapability.FileManagement.StorageService.Backup 1663 1664**Parameters** 1665 1666| Name | Type | Mandatory| Description | 1667| -------- | ------------------------- | ---- | ---------------------------- | 1668| fileMeta | [FileMeta](#filemeta) | Yes | Metadata of the file to restore. | 1669| callback | AsyncCallback<void> | Yes | Callback used to return the result.| 1670 1671**Error codes** 1672 1673For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 1674 1675| ID| Error Message | 1676| -------- | ----------------------- | 1677| 13600001 | IPC error | 1678| 13900001 | Operation not permitted | 1679| 13900020 | Invalid argument | 1680| 13900042 | Unknown error | 1681 1682**Example** 1683 1684 ```ts 1685 import fs from '@ohos.file.fs'; 1686 import { BusinessError } from '@ohos.base'; 1687 1688 let g_session: backup.SessionRestore; 1689 let initMap = new Map<string, number>(); 1690 let testFileNum = 123; // Number of files required for the restore. 1691 let testBundleName = 'com.example.myapplication'; // Test bundle name. 1692 initMap.set(testBundleName, testFileNum); 1693 let countMap = new Map<string, number>(); 1694 countMap.set(testBundleName, 0); // Initialize the number of files written. 1695 function createSessionRestore() { 1696 let generalCallbacks: backup.GeneralCallbacks = { 1697 onFileReady: (err: BusinessError, file: backup.File) => { 1698 if (err) { 1699 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 1700 return; 1701 } 1702 console.info('onFileReady success'); 1703 fs.closeSync(file.fd); 1704 countMap[file.bundleName]++; // Update the number of files written. 1705 // Called only when the number of files to be restored is the same as the number of files actually written. This ensures data consistency and integrity. 1706 if (countMap[file.bundleName] == initMap[file.bundleName]) { // Trigger publishFile when all the files of each package are received. 1707 let fileMeta: backup.FileMeta = { 1708 bundleName: file.bundleName, 1709 uri: '' 1710 } 1711 g_session.publishFile(fileMeta, (err: BusinessError) => { 1712 if (err) { 1713 console.error('publishFile failed with err: ' + JSON.stringify(err)); 1714 return; 1715 } 1716 console.info('publishFile success'); 1717 }); 1718 } 1719 }, 1720 onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => { 1721 if (err) { 1722 console.error('onBundleBegin failed with err: ' + JSON.stringify(err)); 1723 return; 1724 } 1725 console.info('onBundleBegin success'); 1726 }, 1727 onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => { 1728 if (err) { 1729 console.error('onBundleEnd failed with err: ' + JSON.stringify(err)); 1730 return; 1731 } 1732 console.info('onBundleEnd success'); 1733 }, 1734 onAllBundlesEnd: (err: BusinessError) => { 1735 if (err) { 1736 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 1737 return; 1738 } 1739 console.info('onAllBundlesEnd success'); 1740 }, 1741 onBackupServiceDied: () => { 1742 console.info('service died'); 1743 }, 1744 onResultReport: (bundleName: string, result: string) => { 1745 console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result); 1746 }, 1747 onProcess: (bundleName: string, process: string) => { 1748 console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process); 1749 } 1750 }; 1751 let sessionRestore = new backup.SessionRestore(generalCallbacks); // Create a restore process. 1752 return sessionRestore; 1753 } 1754 g_session = createSessionRestore(); 1755 ``` 1756 1757### publishFile 1758 1759publishFile(fileMeta: FileMeta): Promise<void> 1760 1761Publishes **FileMeta** to the backup service to indicate that the file content is ready. This API uses a promise to return the result. 1762 1763> **NOTE** 1764> 1765> - This interface is part of the zero-copy feature, which reduces unnecessary memory copies and increases transmission efficiency. For details about the zero-copy methods, see the zero-copy APIs such as [fs.copyFile](js-apis-file-fs.md#fscopyfile) provided by [@ohos.file.fs](js-apis-file-fs.md). 1766> - After the server returns a file handle through **onFileReady**, the client can copy data to the file corresponding to the file handle provided by the server through zero-copy operations. 1767> - This API can be called only after the caller has written all the data to be restored. The caller must ensure the consistency and integrity of the data to be written. 1768 1769**Required permissions**: ohos.permission.BACKUP 1770 1771**System capability**: SystemCapability.FileManagement.StorageService.Backup 1772 1773**Parameters** 1774 1775| Name | Type | Mandatory| Description | 1776| -------- | --------------------- | ---- | ---------------- | 1777| fileMeta | [FileMeta](#filemeta) | Yes | Metadata of the file to restore.| 1778 1779**Return value** 1780 1781| Type | Description | 1782| ------------------- | ----------------------- | 1783| Promise<void> | Promise that returns no value.| 1784 1785**Error codes** 1786 1787For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 1788 1789| ID| Error Message | 1790| -------- | ----------------------- | 1791| 13600001 | IPC error | 1792| 13900001 | Operation not permitted | 1793| 13900020 | Invalid argument | 1794| 13900042 | Unknown error | 1795 1796**Example** 1797 1798 ```ts 1799 import fs from '@ohos.file.fs'; 1800 import { BusinessError } from '@ohos.base'; 1801 1802 let g_session: backup.SessionRestore; 1803 let initMap = new Map<string, number>(); 1804 let testFileNum = 123; // Number of files required for the restore. 1805 let testBundleName = 'com.example.myapplication'; // Test bundle name. 1806 initMap.set(testBundleName, testFileNum); 1807 let countMap = new Map<string, number>(); 1808 countMap.set(testBundleName, 0); // Initialize the number of files written. 1809 async function publishFile(file: backup.FileMeta) { 1810 let fileMeta: backup.FileMeta = { 1811 bundleName: file.bundleName, 1812 uri: '' 1813 } 1814 await g_session.publishFile(fileMeta); 1815 } 1816 function createSessionRestore() { 1817 let generalCallbacks: backup.GeneralCallbacks = { 1818 onFileReady: (err: BusinessError, file: backup.File) => { 1819 if (err) { 1820 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 1821 return; 1822 } 1823 console.info('onFileReady success'); 1824 fs.closeSync(file.fd); 1825 countMap[file.bundleName]++; // Update the number of files written. 1826 // Called only when the number of files to be restored is the same as the number of files actually written. This ensures data consistency and integrity. 1827 if (countMap[file.bundleName] == initMap[file.bundleName]) { // Trigger publishFile when all the files of each package are received. 1828 publishFile(file); 1829 } 1830 console.info('publishFile success'); 1831 }, 1832 onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => { 1833 if (err) { 1834 console.error('onBundleBegin failed with err: ' + JSON.stringify(err)); 1835 return; 1836 } 1837 console.info('onBundleBegin success'); 1838 }, 1839 onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => { 1840 if (err) { 1841 console.error('onBundleEnd failed with err: ' + JSON.stringify(err)); 1842 return; 1843 } 1844 console.info('onBundleEnd success'); 1845 }, 1846 onAllBundlesEnd: (err: BusinessError) => { 1847 if (err) { 1848 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 1849 return; 1850 } 1851 console.info('onAllBundlesEnd success'); 1852 }, 1853 onBackupServiceDied: () => { 1854 console.info('service died'); 1855 }, 1856 onResultReport: (bundleName: string, result: string) => { 1857 console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result); 1858 }, 1859 onProcess: (bundleName: string, process: string) => { 1860 console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process); 1861 } 1862 }; 1863 let sessionRestore = new backup.SessionRestore(generalCallbacks); // Create a restore process. 1864 return sessionRestore; 1865 } 1866 g_session = createSessionRestore(); 1867 ``` 1868 1869### release<sup>12+</sup> 1870 1871release(): Promise<void> 1872 1873Releases the restore session when the restore process is complete. This API disconnects the application from the backup and restore service and exits the service. This API uses a promise to return the result. 1874 1875**Required permissions**: ohos.permission.BACKUP 1876 1877**System capability**: SystemCapability.FileManagement.StorageService.Backup 1878 1879**Return value** 1880 1881| Type | Description | 1882| ------------------- | ----------------------- | 1883| Promise<void> | Promise that returns no value.| 1884 1885**Error codes** 1886 1887For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 1888 1889| ID| Error Message | 1890| -------- | ---------------------------------------------------------------------------------------------- | 1891| 201 | Permission verification failed, usually the result returned by VerifyAccessToken. | 1892| 202 | Permission verification failed, application which is not a system application uses system API. | 1893| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verifcation faild| 1894| 13600001 | IPC error | 1895| 13900001 | Operation not permitted | 1896| 13900005 | I/O error | 1897| 13900042 | Unknown error | 1898 1899**Example** 1900 1901 ```ts 1902 import fs from '@ohos.file.fs'; 1903 import { BusinessError } from '@ohos.base'; 1904 1905 let g_session: backup.SessionRestore; 1906 let initMap = new Map<string, number>(); 1907 let testFileNum = 123; // Number of files required for the restore. 1908 let testBundleName = 'com.example.myapplication'; // Test bundle name. 1909 initMap.set(testBundleName, testFileNum); 1910 let countMap = new Map<string, number>(); 1911 countMap.set(testBundleName, 0); // Initialize the number of files written. 1912 function createSessionRestore() { 1913 let generalCallbacks: backup.GeneralCallbacks = { 1914 onFileReady: (err: BusinessError, file: backup.File) => { 1915 if (err) { 1916 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 1917 return; 1918 } 1919 console.info('onFileReady success'); 1920 fs.closeSync(file.fd); 1921 countMap[file.bundleName]++; // Update the number of files written. 1922 // Called only when the number of files to be restored is the same as the number of files actually written. This ensures data consistency and integrity. 1923 if (countMap[file.bundleName] == initMap[file.bundleName]) { // Trigger publishFile when all the files of each package are received. 1924 let fileMeta: backup.FileMeta = { 1925 bundleName: file.bundleName, 1926 uri: '' 1927 } 1928 g_session.publishFile(fileMeta, (err: BusinessError) => { 1929 if (err) { 1930 console.error('publishFile failed with err: ' + JSON.stringify(err)); 1931 return; 1932 } 1933 console.info('publishFile success'); 1934 }); 1935 } 1936 }, 1937 onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => { 1938 if (err) { 1939 console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data); 1940 return; 1941 } 1942 console.info('onBundleBegin success'); 1943 }, 1944 onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => { 1945 if (err) { 1946 console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data); 1947 return; 1948 } 1949 console.info('onBundleEnd success'); 1950 }, 1951 onAllBundlesEnd: (err: BusinessError) => { 1952 if (err) { 1953 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 1954 return; 1955 } 1956 console.info('onAllBundlesEnd success'); 1957 }, 1958 onBackupServiceDied: () => { 1959 console.info('service died'); 1960 }, 1961 onResultReport: (bundleName: string, result: string) => { 1962 console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result); 1963 }, 1964 onProcess: (bundleName: string, process: string) => { 1965 console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process); 1966 } 1967 }; 1968 let sessionRestore = new backup.SessionRestore(generalCallbacks); // Create a restore process. 1969 return sessionRestore; 1970 } 1971 g_session = createSessionRestore(); 1972 g_session.release(); 1973 console.info('release success'); 1974 ``` 1975 1976## IncrementalBackupSession<sup>12+</sup> 1977 1978An object used to implement the incremental backup of applications. Before using the APIs of this class, you need to create an **IncrementalBackupSession** instance. 1979 1980### constructor<sup>12+</sup> 1981 1982constructor(callbacks: GeneralCallbacks); 1983 1984A constructor used to create an **IncrementalBackupSession** instance. 1985 1986**Required permissions**: ohos.permission.BACKUP 1987 1988**System capability**: SystemCapability.FileManagement.StorageService.Backup 1989 1990**Parameters** 1991 1992| Name | Type | Mandatory| Description | 1993| -------- | ------------------------------------- | ---- | ------------------------ | 1994| callback | [GeneralCallbacks](#generalcallbacks) | Yes | Callbacks to be invoked during the incremental backup process.| 1995 1996**Error codes** 1997 1998For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 1999 2000| ID| Error Message | 2001| -------- | ---------------------------------------------------------------------------------------------- | 2002| 201 | Permission verification failed, usually the result returned by VerifyAccessToken. | 2003| 202 | Permission verification failed, application which is not a system application uses system API. | 2004| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verifcation faild| 2005 2006**Example** 2007 2008 ```ts 2009 import fs from '@ohos.file.fs'; 2010 import { BusinessError } from '@ohos.base'; 2011 2012 let generalCallbacks: backup.GeneralCallbacks = { 2013 onFileReady: (err: BusinessError, file: backup.File) => { 2014 if (err) { 2015 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 2016 return; 2017 } 2018 console.info('onFileReady success'); 2019 fs.closeSync(file.fd); 2020 }, 2021 onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => { 2022 if (err) { 2023 console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data); 2024 return; 2025 } 2026 console.info('onBundleBegin success'); 2027 }, 2028 onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => { 2029 if (err) { 2030 console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data); 2031 return; 2032 } 2033 console.info('onBundleEnd success'); 2034 }, 2035 onAllBundlesEnd: (err: BusinessError) => { 2036 if (err) { 2037 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 2038 return; 2039 } 2040 console.info('onAllBundlesEnd success'); 2041 }, 2042 onBackupServiceDied: () => { 2043 console.info('service died'); 2044 }, 2045 onResultReport: (bundleName: string, result: string) => { 2046 console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result); 2047 }, 2048 onProcess: (bundleName: string, process: string) => { 2049 console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process); 2050 } 2051 }; 2052 let incrementalBackupSession = new backup.IncrementalBackupSession(generalCallbacks); // Create a session for an incremental backup. 2053 ``` 2054 2055### appendBundles<sup>12+</sup> 2056 2057appendBundles(bundlesToBackup: Array<IncrementalBackupData>): Promise<void> 2058 2059Appends applications that require incremental backup. In the current process, **appendBundles** can be called before **Release()** is called. This API uses a promise to return the result. 2060 2061**Required permissions**: ohos.permission.BACKUP 2062 2063**System capability**: SystemCapability.FileManagement.StorageService.Backup 2064 2065**Parameters** 2066 2067| Name | Type | Mandatory| Description | 2068| --------------- | -------------------------------------------------------------- | ---- | -------------------------- | 2069| bundlesToBackup | Array<[IncrementalBackupData](#incrementalbackupdata12)> | Yes | Array of applications that require incremental backup.| 2070 2071**Return value** 2072 2073| Type | Description | 2074| ------------------- | ----------------------- | 2075| Promise<void> | Promise that returns no value.| 2076 2077**Error codes** 2078 2079For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 2080 2081| ID| Error Message | 2082| -------- | ---------------------------------------------------------------------------------------------- | 2083| 201 | Permission verification failed, usually the result returned by VerifyAccessToken. | 2084| 202 | Permission verification failed, application which is not a system application uses system API. | 2085| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verifcation faild| 2086| 13600001 | IPC error | 2087| 13900001 | Operation not permitted | 2088| 13900005 | I/O error | 2089| 13900011 | Out of memory | 2090| 13900020 | Invalid argument | 2091| 13900025 | No space left on device | 2092| 13900042 | Unknown error | 2093 2094**Example** 2095 2096 ```ts 2097 import fs from '@ohos.file.fs'; 2098 import { BusinessError } from '@ohos.base'; 2099 2100 let generalCallbacks: backup.GeneralCallbacks = { 2101 onFileReady: (err: BusinessError, file: backup.File) => { 2102 if (err) { 2103 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 2104 return; 2105 } 2106 console.info('onFileReady success'); 2107 fs.closeSync(file.fd); 2108 }, 2109 onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => { 2110 if (err) { 2111 console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data); 2112 return; 2113 } 2114 console.info('onBundleBegin success'); 2115 }, 2116 onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => { 2117 if (err) { 2118 console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data); 2119 return; 2120 } 2121 console.info('onBundleEnd success'); 2122 }, 2123 onAllBundlesEnd: (err: BusinessError) => { 2124 if (err) { 2125 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 2126 return; 2127 } 2128 console.info('onAllBundlesEnd success'); 2129 }, 2130 onBackupServiceDied: () => { 2131 console.info('service died'); 2132 }, 2133 onResultReport: (bundleName: string, result: string) => { 2134 console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result); 2135 }, 2136 onProcess: (bundleName: string, process: string) => { 2137 console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process); 2138 } 2139 }; 2140 let incrementalBackupSession = new backup.IncrementalBackupSession(generalCallbacks); // Create a session for an incremental backup. 2141 let incrementalBackupData: backup.IncrementalBackupData = { 2142 bundleName: "com.example.hiworld", 2143 lastIncrementalTime: 1700107870, // Timestamp of the last backup. 2144 manifestFd:1 // FD of the manifest file of the last backed. 2145 } 2146 let incrementalBackupDataArray: backup.IncrementalBackupData[] = [incrementalBackupData]; 2147 incrementalBackupSession.appendBundles(incrementalBackupDataArray).then(() => { 2148 console.info('appendBundles success'); 2149 }).catch((err: BusinessError) => { 2150 console.error('appendBundles failed with err: ' + JSON.stringify(err)); 2151 }); // Appends the applications that require incremental backup. 2152 ``` 2153 2154### appendBundles<sup>12+</sup> 2155 2156appendBundles(bundlesToBackup: Array<IncrementalBackupData>, infos: string[]): Promise<void> 2157 2158Appends applications that require incremental backup. In the current process, **appendBundles** can be called before **Release()** is called. This API uses a promise to return the result. 2159 2160**Required permissions**: ohos.permission.BACKUP 2161 2162**System capability**: SystemCapability.FileManagement.StorageService.Backup 2163 2164**Parameters** 2165 2166| Name | Type | Mandatory| Description | 2167| --------------- | -------------------------------------------------------------- | ---- | -------------------------- | 2168| bundlesToBackup | Array<[IncrementalBackupData](#incrementalbackupdata12)> | Yes | Array of applications that require incremental backup.| 2169| infos | string[] | Yes | Array of the information about each application to be backed up. The mappings between **infos** and **bundlesToBackup** are identified by index. This parameter is supported since API version 12.| 2170 2171**Return value** 2172 2173| Type | Description | 2174| ------------------- | ----------------------- | 2175| Promise<void> | Promise that returns no value.| 2176 2177**Error codes** 2178 2179For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 2180 2181| ID| Error Message | 2182| -------- | ---------------------------------------------------------------------------------------------- | 2183| 201 | Permission verification failed, usually the result returned by VerifyAccessToken. | 2184| 202 | Permission verification failed, application which is not a system application uses system API. | 2185| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verifcation faild| 2186| 13600001 | IPC error | 2187| 13900001 | Operation not permitted | 2188| 13900005 | I/O error | 2189| 13900011 | Out of memory | 2190| 13900020 | Invalid argument | 2191| 13900025 | No space left on device | 2192| 13900042 | Unknown error | 2193 2194**Example** 2195 2196 ```ts 2197 import fs from '@ohos.file.fs'; 2198 import { BusinessError } from '@ohos.base'; 2199 2200 let generalCallbacks: backup.GeneralCallbacks = { 2201 onFileReady: (err: BusinessError, file: backup.File) => { 2202 if (err) { 2203 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 2204 return; 2205 } 2206 console.info('onFileReady success'); 2207 fs.closeSync(file.fd); 2208 }, 2209 onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => { 2210 if (err) { 2211 console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data); 2212 return; 2213 } 2214 console.info('onBundleBegin success'); 2215 }, 2216 onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => { 2217 if (err) { 2218 console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data); 2219 return; 2220 } 2221 console.info('onBundleEnd success'); 2222 }, 2223 onAllBundlesEnd: (err: BusinessError) => { 2224 if (err) { 2225 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 2226 return; 2227 } 2228 console.info('onAllBundlesEnd success'); 2229 }, 2230 onBackupServiceDied: () => { 2231 console.info('service died'); 2232 }, 2233 onResultReport: (bundleName: string, result: string) => { 2234 console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result); 2235 }, 2236 onProcess: (bundleName: string, process: string) => { 2237 console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process); 2238 } 2239 }; 2240 let incrementalBackupSession = new backup.IncrementalBackupSession(generalCallbacks); // Create a session for an incremental backup. 2241 let incrementalBackupData: backup.IncrementalBackupData = { 2242 bundleName: "com.example.hiworld", 2243 lastIncrementalTime: 1700107870, // Timestamp of the last backup. 2244 manifestFd:1 // FD of the manifest file of the last backed. 2245 } 2246 let infos: Array<string> = [ 2247 ` 2248 { 2249 "infos": [ 2250 { 2251 "details": [ 2252 { 2253 "detail": [ 2254 { 2255 "key1": "value1", 2256 "key2": "value2" 2257 } 2258 ] 2259 } 2260 ], 2261 "type": "unicast", 2262 "bundleName": "com.example.hiworld" 2263 } 2264 ] 2265 }, 2266 { 2267 "infos": [ 2268 { 2269 "details": [ 2270 { 2271 "detail": [ 2272 { 2273 "key1": "value1", 2274 "key2": "value2" 2275 } 2276 ] 2277 } 2278 ], 2279 "type": "unicast", 2280 "bundleName": "com.example.myApp" 2281 } 2282 ] 2283 } 2284 ` 2285 ] 2286 let incrementalBackupDataArray: backup.IncrementalBackupData[] = [incrementalBackupData]; 2287 // Appends the applications that require incremental backup. 2288 incrementalBackupSession.appendBundles(incrementalBackupDataArray, infos).then(() => { 2289 console.info('appendBundles success'); 2290 }).catch((err: BusinessError) => { 2291 console.error('appendBundles failed with err: ' + JSON.stringify(err)); 2292 }); 2293 ``` 2294### release<sup>12+</sup> 2295 2296release(): Promise<void> 2297 2298Releases the session for the incremental backup. This API uses a promise to return the result. 2299 2300**Required permissions**: ohos.permission.BACKUP 2301 2302**System capability**: SystemCapability.FileManagement.StorageService.Backup 2303 2304**Return value** 2305 2306| Type | Description | 2307| ------------------- | ----------------------- | 2308| Promise<void> | Promise that returns no value.| 2309 2310**Error codes** 2311 2312For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 2313 2314| ID| Error Message | 2315| -------- | ---------------------------------------------------------------------------------------------- | 2316| 201 | Permission verification failed, usually the result returned by VerifyAccessToken. | 2317| 202 | Permission verification failed, application which is not a system application uses system API. | 2318| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verifcation faild| 2319| 13600001 | IPC error | 2320| 13900001 | Operation not permitted | 2321| 13900005 | I/O error | 2322| 13900020 | Invalid argument | 2323| 13900042 | Unknown error | 2324 2325**Example** 2326 2327 ```ts 2328 import fs from '@ohos.file.fs'; 2329 import { BusinessError } from '@ohos.base'; 2330 2331 let generalCallbacks: backup.GeneralCallbacks = { 2332 onFileReady: (err: BusinessError, file: backup.File) => { 2333 if (err) { 2334 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 2335 return; 2336 } 2337 console.info('onFileReady success'); 2338 fs.closeSync(file.fd); 2339 }, 2340 onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => { 2341 if (err) { 2342 console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data); 2343 return; 2344 } 2345 console.info('onBundleBegin success'); 2346 }, 2347 onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => { 2348 if (err) { 2349 console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data); 2350 return; 2351 } 2352 console.info('onBundleEnd success'); 2353 }, 2354 onAllBundlesEnd: (err: BusinessError) => { 2355 if (err) { 2356 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 2357 return; 2358 } 2359 console.info('onAllBundlesEnd success'); 2360 }, 2361 onBackupServiceDied: () => { 2362 console.info('service died'); 2363 }, 2364 onResultReport: (bundleName: string, result: string) => { 2365 console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result); 2366 }, 2367 onProcess: (bundleName: string, process: string) => { 2368 console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process); 2369 } 2370 }; 2371 let incrementalBackupSession = new backup.IncrementalBackupSession(generalCallbacks); // Create a session for an incremental backup. 2372 incrementalBackupSession.release(); // End the incremental backup process. 2373 console.info('release success'); 2374 ``` 2375