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 from [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 at the proper time. 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. | 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. | 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 used to return the **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 used to return the **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.| 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 form '@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 update the send rate. 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.| 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 form '@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 1463**Required permissions**: ohos.permission.BACKUP 1464 1465**System capability**: SystemCapability.FileManagement.StorageService.Backup 1466 1467**Parameters** 1468 1469| Name | Type | Mandatory| Description | 1470| -------- | ------------------------- | ---- | -------------------------------- | 1471| fileMeta | [FileMeta](#filemeta) | Yes | Metadata of the file to restore. | 1472| callback | AsyncCallback<void> | Yes | Callback used to return the result.| 1473 1474**Error codes** 1475 1476For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 1477 1478| ID| Error Message | 1479| -------- | ----------------------- | 1480| 13600001 | IPC error | 1481| 13900001 | Operation not permitted | 1482| 13900020 | Invalid argument | 1483| 13900042 | Unknown error | 1484 1485**Example** 1486 1487 ```ts 1488 import fs from '@ohos.file.fs'; 1489 import { BusinessError } from '@ohos.base'; 1490 1491 let generalCallbacks: backup.GeneralCallbacks = { 1492 onFileReady: (err: BusinessError, file: backup.File) => { 1493 if (err) { 1494 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 1495 return; 1496 } 1497 console.info('onFileReady success'); 1498 fs.closeSync(file.fd); 1499 }, 1500 onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => { 1501 if (err) { 1502 console.error('onBundleBegin failed with err: ' + JSON.stringify(err)); 1503 return; 1504 } 1505 console.info('onBundleBegin success'); 1506 }, 1507 onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => { 1508 if (err) { 1509 console.error('onBundleEnd failed with err: ' + JSON.stringify(err)); 1510 return; 1511 } 1512 console.info('onBundleEnd success'); 1513 }, 1514 onAllBundlesEnd: (err: BusinessError) => { 1515 if (err) { 1516 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 1517 return; 1518 } 1519 console.info('onAllBundlesEnd success'); 1520 }, 1521 onBackupServiceDied: () => { 1522 console.info('service died'); 1523 }, 1524 onResultReport: (bundleName: string, result: string) => { 1525 console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result); 1526 }, 1527 onProcess: (bundleName: string, process: string) => { 1528 console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process); 1529 } 1530 }; 1531 let sessionRestore = new backup.SessionRestore(generalCallbacks); // Create a restore process. 1532 let fileMeta: backup.FileMeta = { 1533 bundleName: "com.example.hiworld", 1534 uri: "test.txt" 1535 } 1536 sessionRestore.getFileHandle(fileMeta, (err: BusinessError) => { 1537 if (err) { 1538 console.error('getFileHandle failed with err: ' + JSON.stringify(err)); 1539 } 1540 console.info('getFileHandle success'); 1541 }); 1542 ``` 1543 1544### getFileHandle 1545 1546getFileHandle(fileMeta: FileMeta): Promise<void> 1547 1548Obtains the handle of the shared file from the service. This API uses a promise to return the result. 1549 1550> **NOTE** 1551> 1552> - 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). 1553> - Before using **getFileHandle**, you need to obtain a **SessionRestore** instance and add the applications with data to be restored by using **appendBundles**. 1554> - 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. 1555> - **getFileHandle** can be called multiple times based on the number of files to be restored. 1556 1557**Required permissions**: ohos.permission.BACKUP 1558 1559**System capability**: SystemCapability.FileManagement.StorageService.Backup 1560 1561**Parameters** 1562 1563| Name | Type | Mandatory| Description | 1564| -------- | --------------------- | ---- | ------------------ | 1565| fileMeta | [FileMeta](#filemeta) | Yes | Metadata of the file to restore.| 1566 1567**Return value** 1568 1569| Type | Description | 1570| ------------------- | ----------------------- | 1571| Promise<void> | Promise that returns no value.| 1572 1573**Error codes** 1574 1575For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 1576 1577| ID| Error Message | 1578| -------- | ----------------------- | 1579| 13600001 | IPC error | 1580| 13900001 | Operation not permitted | 1581| 13900020 | Invalid argument | 1582| 13900042 | Unknown error | 1583 1584**Example** 1585 1586 ```ts 1587 import fs from '@ohos.file.fs'; 1588 import { BusinessError } from '@ohos.base'; 1589 1590 let generalCallbacks: backup.GeneralCallbacks = { 1591 onFileReady: (err: BusinessError, file: backup.File) => { 1592 if (err) { 1593 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 1594 return; 1595 } 1596 console.info('onFileReady success'); 1597 fs.closeSync(file.fd); 1598 }, 1599 onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => { 1600 if (err) { 1601 console.error('onBundleBegin failed with err: ' + JSON.stringify(err)); 1602 return; 1603 } 1604 console.info('onBundleBegin success'); 1605 }, 1606 onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => { 1607 if (err) { 1608 console.error('onBundleEnd failed with err: ' + JSON.stringify(err)); 1609 return; 1610 } 1611 console.info('onBundleEnd success'); 1612 }, 1613 onAllBundlesEnd: (err: BusinessError) => { 1614 if (err) { 1615 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 1616 return; 1617 } 1618 console.info('onAllBundlesEnd success'); 1619 }, 1620 onBackupServiceDied: () => { 1621 console.info('service died'); 1622 }, 1623 onResultReport: (bundleName: string, result: string) => { 1624 console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result); 1625 }, 1626 onProcess: (bundleName: string, process: string) => { 1627 console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process); 1628 } 1629 }; 1630 let sessionRestore = new backup.SessionRestore(generalCallbacks); // Create a restore process. 1631 async function getFileHandle() { 1632 try { 1633 let fileMeta: backup.FileMeta = { 1634 bundleName: "com.example.hiworld", 1635 uri: "test.txt" 1636 } 1637 await sessionRestore.getFileHandle(fileMeta); 1638 console.info('getFileHandle success'); 1639 } catch (error) { 1640 let err: BusinessError = error as BusinessError; 1641 console.error('getFileHandle failed with err: ' + JSON.stringify(err)); 1642 } 1643 } 1644 ``` 1645 1646### publishFile 1647 1648publishFile(fileMeta: FileMeta, callback: AsyncCallback<void>): void 1649 1650Publishes **FileMeta** to the backup service to indicate that the file content is ready. This API uses an asynchronous callback to return the result. 1651 1652> **NOTE** 1653> 1654> - 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). 1655> - 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. 1656> - 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. 1657 1658**Required permissions**: ohos.permission.BACKUP 1659 1660**System capability**: SystemCapability.FileManagement.StorageService.Backup 1661 1662**Parameters** 1663 1664| Name | Type | Mandatory| Description | 1665| -------- | ------------------------- | ---- | ---------------------------- | 1666| fileMeta | [FileMeta](#filemeta) | Yes | Metadata of the file to restore. | 1667| callback | AsyncCallback<void> | Yes | Callback used to return the result.| 1668 1669**Error codes** 1670 1671For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 1672 1673| ID| Error Message | 1674| -------- | ----------------------- | 1675| 13600001 | IPC error | 1676| 13900001 | Operation not permitted | 1677| 13900020 | Invalid argument | 1678| 13900042 | Unknown error | 1679 1680**Example** 1681 1682 ```ts 1683 import fs from '@ohos.file.fs'; 1684 import { BusinessError } from '@ohos.base'; 1685 1686 let g_session: backup.SessionRestore; 1687 let initMap = new Map<string, number>(); 1688 let testFileNum = 123; // Number of files required for the restore. 1689 let testBundleName = 'com.example.myapplication'; // Test bundle name. 1690 initMap.set(testBundleName, testFileNum); 1691 let countMap = new Map<string, number>(); 1692 countMap.set(testBundleName, 0); // Initialize the number of files written. 1693 function createSessionRestore() { 1694 let generalCallbacks: backup.GeneralCallbacks = { 1695 onFileReady: (err: BusinessError, file: backup.File) => { 1696 if (err) { 1697 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 1698 return; 1699 } 1700 console.info('onFileReady success'); 1701 fs.closeSync(file.fd); 1702 countMap[file.bundleName]++; // Update the number of files written. 1703 // 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. 1704 if (countMap[file.bundleName] == initMap[file.bundleName]) { // Trigger publishFile when all the files of each package are received. 1705 let fileMeta: backup.FileMeta = { 1706 bundleName: file.bundleName, 1707 uri: '' 1708 } 1709 g_session.publishFile(fileMeta, (err: BusinessError) => { 1710 if (err) { 1711 console.error('publishFile failed with err: ' + JSON.stringify(err)); 1712 return; 1713 } 1714 console.info('publishFile success'); 1715 }); 1716 } 1717 }, 1718 onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => { 1719 if (err) { 1720 console.error('onBundleBegin failed with err: ' + JSON.stringify(err)); 1721 return; 1722 } 1723 console.info('onBundleBegin success'); 1724 }, 1725 onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => { 1726 if (err) { 1727 console.error('onBundleEnd failed with err: ' + JSON.stringify(err)); 1728 return; 1729 } 1730 console.info('onBundleEnd success'); 1731 }, 1732 onAllBundlesEnd: (err: BusinessError) => { 1733 if (err) { 1734 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 1735 return; 1736 } 1737 console.info('onAllBundlesEnd success'); 1738 }, 1739 onBackupServiceDied: () => { 1740 console.info('service died'); 1741 }, 1742 onResultReport: (bundleName: string, result: string) => { 1743 console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result); 1744 }, 1745 onProcess: (bundleName: string, process: string) => { 1746 console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process); 1747 } 1748 }; 1749 let sessionRestore = new backup.SessionRestore(generalCallbacks); // Create a restore process. 1750 return sessionRestore; 1751 } 1752 g_session = createSessionRestore(); 1753 ``` 1754 1755### publishFile 1756 1757publishFile(fileMeta: FileMeta): Promise<void> 1758 1759Publishes **FileMeta** to the backup service to indicate that the file content is ready. This API uses a promise to return the result. 1760 1761> **NOTE** 1762> 1763> - 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). 1764> - 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. 1765> - 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. 1766 1767**Required permissions**: ohos.permission.BACKUP 1768 1769**System capability**: SystemCapability.FileManagement.StorageService.Backup 1770 1771**Parameters** 1772 1773| Name | Type | Mandatory| Description | 1774| -------- | --------------------- | ---- | ---------------- | 1775| fileMeta | [FileMeta](#filemeta) | Yes | Metadata of the file to restore.| 1776 1777**Return value** 1778 1779| Type | Description | 1780| ------------------- | ----------------------- | 1781| Promise<void> | Promise that returns no value.| 1782 1783**Error codes** 1784 1785For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 1786 1787| ID| Error Message | 1788| -------- | ----------------------- | 1789| 13600001 | IPC error | 1790| 13900001 | Operation not permitted | 1791| 13900020 | Invalid argument | 1792| 13900042 | Unknown error | 1793 1794**Example** 1795 1796 ```ts 1797 import fs from '@ohos.file.fs'; 1798 import { BusinessError } from '@ohos.base'; 1799 1800 let g_session: backup.SessionRestore; 1801 let initMap = new Map<string, number>(); 1802 let testFileNum = 123; // Number of files required for the restore. 1803 let testBundleName = 'com.example.myapplication'; // Test bundle name. 1804 initMap.set(testBundleName, testFileNum); 1805 let countMap = new Map<string, number>(); 1806 countMap.set(testBundleName, 0); // Initialize the number of files written. 1807 async function publishFile(file: backup.FileMeta) { 1808 let fileMeta: backup.FileMeta = { 1809 bundleName: file.bundleName, 1810 uri: '' 1811 } 1812 await g_session.publishFile(fileMeta); 1813 } 1814 function createSessionRestore() { 1815 let generalCallbacks: backup.GeneralCallbacks = { 1816 onFileReady: (err: BusinessError, file: backup.File) => { 1817 if (err) { 1818 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 1819 return; 1820 } 1821 console.info('onFileReady success'); 1822 fs.closeSync(file.fd); 1823 countMap[file.bundleName]++; // Update the number of files written. 1824 // 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. 1825 if (countMap[file.bundleName] == initMap[file.bundleName]) { // Trigger publishFile when all the files of each package are received. 1826 publishFile(file); 1827 } 1828 console.info('publishFile success'); 1829 }, 1830 onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => { 1831 if (err) { 1832 console.error('onBundleBegin failed with err: ' + JSON.stringify(err)); 1833 return; 1834 } 1835 console.info('onBundleBegin success'); 1836 }, 1837 onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => { 1838 if (err) { 1839 console.error('onBundleEnd failed with err: ' + JSON.stringify(err)); 1840 return; 1841 } 1842 console.info('onBundleEnd success'); 1843 }, 1844 onAllBundlesEnd: (err: BusinessError) => { 1845 if (err) { 1846 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 1847 return; 1848 } 1849 console.info('onAllBundlesEnd success'); 1850 }, 1851 onBackupServiceDied: () => { 1852 console.info('service died'); 1853 }, 1854 onResultReport: (bundleName: string, result: string) => { 1855 console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result); 1856 }, 1857 onProcess: (bundleName: string, process: string) => { 1858 console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process); 1859 } 1860 }; 1861 let sessionRestore = new backup.SessionRestore(generalCallbacks); // Create a restore process. 1862 return sessionRestore; 1863 } 1864 g_session = createSessionRestore(); 1865 ``` 1866 1867### release<sup>12+</sup> 1868 1869release(): Promise<void> 1870 1871Releases 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. 1872 1873**Required permissions**: ohos.permission.BACKUP 1874 1875**System capability**: SystemCapability.FileManagement.StorageService.Backup 1876 1877**Return value** 1878 1879| Type | Description | 1880| ------------------- | ----------------------- | 1881| Promise<void> | Promise that returns no value.| 1882 1883**Error codes** 1884 1885For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 1886 1887| ID| Error Message | 1888| -------- | ---------------------------------------------------------------------------------------------- | 1889| 201 | Permission verification failed, usually the result returned by VerifyAccessToken. | 1890| 202 | Permission verification failed, application which is not a system application uses system API. | 1891| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verifcation faild| 1892| 13600001 | IPC error | 1893| 13900001 | Operation not permitted | 1894| 13900005 | I/O error | 1895| 13900042 | Unknown error | 1896 1897**Example** 1898 1899 ```ts 1900 import fs from '@ohos.file.fs'; 1901 import { BusinessError } from '@ohos.base'; 1902 1903 let g_session: backup.SessionRestore; 1904 let initMap = new Map<string, number>(); 1905 let testFileNum = 123; // Number of files required for the restore. 1906 let testBundleName = 'com.example.myapplication'; // Test bundle name. 1907 initMap.set(testBundleName, testFileNum); 1908 let countMap = new Map<string, number>(); 1909 countMap.set(testBundleName, 0); // Initialize the number of files written. 1910 function createSessionRestore() { 1911 let generalCallbacks: backup.GeneralCallbacks = { 1912 onFileReady: (err: BusinessError, file: backup.File) => { 1913 if (err) { 1914 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 1915 return; 1916 } 1917 console.info('onFileReady success'); 1918 fs.closeSync(file.fd); 1919 countMap[file.bundleName]++; // Update the number of files written. 1920 // 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. 1921 if (countMap[file.bundleName] == initMap[file.bundleName]) { // Trigger publishFile when all the files of each package are received. 1922 let fileMeta: backup.FileMeta = { 1923 bundleName: file.bundleName, 1924 uri: '' 1925 } 1926 g_session.publishFile(fileMeta, (err: BusinessError) => { 1927 if (err) { 1928 console.error('publishFile failed with err: ' + JSON.stringify(err)); 1929 return; 1930 } 1931 console.info('publishFile success'); 1932 }); 1933 } 1934 }, 1935 onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => { 1936 if (err) { 1937 console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data); 1938 return; 1939 } 1940 console.info('onBundleBegin success'); 1941 }, 1942 onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => { 1943 if (err) { 1944 console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data); 1945 return; 1946 } 1947 console.info('onBundleEnd success'); 1948 }, 1949 onAllBundlesEnd: (err: BusinessError) => { 1950 if (err) { 1951 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 1952 return; 1953 } 1954 console.info('onAllBundlesEnd success'); 1955 }, 1956 onBackupServiceDied: () => { 1957 console.info('service died'); 1958 }, 1959 onResultReport: (bundleName: string, result: string) => { 1960 console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result); 1961 }, 1962 onProcess: (bundleName: string, process: string) => { 1963 console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process); 1964 } 1965 }; 1966 let sessionRestore = new backup.SessionRestore(generalCallbacks); // Create a restore process. 1967 return sessionRestore; 1968 } 1969 g_session = createSessionRestore(); 1970 g_session.release(); 1971 console.info('release success'); 1972 ``` 1973 1974## IncrementalBackupSession<sup>12+</sup> 1975 1976An object used to implement the incremental backup of applications. Before using the APIs of this class, you need to create an **IncrementalBackupSession** instance. 1977 1978### constructor<sup>12+</sup> 1979 1980constructor(callbacks: GeneralCallbacks); 1981 1982A constructor used to create an **IncrementalBackupSession** instance. 1983 1984**Required permissions**: ohos.permission.BACKUP 1985 1986**System capability**: SystemCapability.FileManagement.StorageService.Backup 1987 1988**Parameters** 1989 1990| Name | Type | Mandatory| Description | 1991| -------- | ------------------------------------- | ---- | ------------------------ | 1992| callback | [GeneralCallbacks](#generalcallbacks) | Yes | Callbacks to be invoked during the incremental backup process.| 1993 1994**Error codes** 1995 1996For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 1997 1998| ID| Error Message | 1999| -------- | ---------------------------------------------------------------------------------------------- | 2000| 201 | Permission verification failed, usually the result returned by VerifyAccessToken. | 2001| 202 | Permission verification failed, application which is not a system application uses system API. | 2002| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verifcation faild| 2003 2004**Example** 2005 2006 ```ts 2007 import fs from '@ohos.file.fs'; 2008 import { BusinessError } from '@ohos.base'; 2009 2010 let generalCallbacks: backup.GeneralCallbacks = { 2011 onFileReady: (err: BusinessError, file: backup.File) => { 2012 if (err) { 2013 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 2014 return; 2015 } 2016 console.info('onFileReady success'); 2017 fs.closeSync(file.fd); 2018 }, 2019 onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => { 2020 if (err) { 2021 console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data); 2022 return; 2023 } 2024 console.info('onBundleBegin success'); 2025 }, 2026 onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => { 2027 if (err) { 2028 console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data); 2029 return; 2030 } 2031 console.info('onBundleEnd success'); 2032 }, 2033 onAllBundlesEnd: (err: BusinessError) => { 2034 if (err) { 2035 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 2036 return; 2037 } 2038 console.info('onAllBundlesEnd success'); 2039 }, 2040 onBackupServiceDied: () => { 2041 console.info('service died'); 2042 }, 2043 onResultReport: (bundleName: string, result: string) => { 2044 console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result); 2045 }, 2046 onProcess: (bundleName: string, process: string) => { 2047 console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process); 2048 } 2049 }; 2050 let incrementalBackupSession = new backup.IncrementalBackupSession(generalCallbacks); // Create a session for an incremental backup. 2051 ``` 2052 2053### appendBundles<sup>12+</sup> 2054 2055appendBundles(bundlesToBackup: Array<IncrementalBackupData>): Promise<void> 2056 2057Appends 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. 2058 2059**Required permissions**: ohos.permission.BACKUP 2060 2061**System capability**: SystemCapability.FileManagement.StorageService.Backup 2062 2063**Parameters** 2064 2065| Name | Type | Mandatory| Description | 2066| --------------- | -------------------------------------------------------------- | ---- | -------------------------- | 2067| bundlesToBackup | Array<[IncrementalBackupData](#incrementalbackupdata12)> | Yes | Array of applications that require incremental backup.| 2068 2069**Return value** 2070 2071| Type | Description | 2072| ------------------- | ----------------------- | 2073| Promise<void> | Promise that returns no value.| 2074 2075**Error codes** 2076 2077For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 2078 2079| ID| Error Message | 2080| -------- | ---------------------------------------------------------------------------------------------- | 2081| 201 | Permission verification failed, usually the result returned by VerifyAccessToken. | 2082| 202 | Permission verification failed, application which is not a system application uses system API. | 2083| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verifcation faild| 2084| 13600001 | IPC error | 2085| 13900001 | Operation not permitted | 2086| 13900005 | I/O error | 2087| 13900011 | Out of memory | 2088| 13900020 | Invalid argument | 2089| 13900025 | No space left on device | 2090| 13900042 | Unknown error | 2091 2092**Example** 2093 2094 ```ts 2095 import fs from '@ohos.file.fs'; 2096 import { BusinessError } from '@ohos.base'; 2097 2098 let generalCallbacks: backup.GeneralCallbacks = { 2099 onFileReady: (err: BusinessError, file: backup.File) => { 2100 if (err) { 2101 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 2102 return; 2103 } 2104 console.info('onFileReady success'); 2105 fs.closeSync(file.fd); 2106 }, 2107 onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => { 2108 if (err) { 2109 console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data); 2110 return; 2111 } 2112 console.info('onBundleBegin success'); 2113 }, 2114 onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => { 2115 if (err) { 2116 console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data); 2117 return; 2118 } 2119 console.info('onBundleEnd success'); 2120 }, 2121 onAllBundlesEnd: (err: BusinessError) => { 2122 if (err) { 2123 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 2124 return; 2125 } 2126 console.info('onAllBundlesEnd success'); 2127 }, 2128 onBackupServiceDied: () => { 2129 console.info('service died'); 2130 }, 2131 onResultReport: (bundleName: string, result: string) => { 2132 console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result); 2133 }, 2134 onProcess: (bundleName: string, process: string) => { 2135 console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process); 2136 } 2137 }; 2138 let incrementalBackupSession = new backup.IncrementalBackupSession(generalCallbacks); // Create a session for an incremental backup. 2139 let incrementalBackupData: backup.IncrementalBackupData = { 2140 bundleName: "com.example.hiworld", 2141 lastIncrementalTime: 1700107870, // Timestamp of the last backup. 2142 manifestFd:1 // FD of the manifest file of the last backed. 2143 } 2144 let incrementalBackupDataArray: backup.IncrementalBackupData[] = [incrementalBackupData]; 2145 incrementalBackupSession.appendBundles(incrementalBackupDataArray).then(() => { 2146 console.info('appendBundles success'); 2147 }).catch((err: BusinessError) => { 2148 console.error('appendBundles failed with err: ' + JSON.stringify(err)); 2149 }); // Appends the applications that require incremental backup. 2150 ``` 2151 2152### release<sup>12+</sup> 2153 2154release(): Promise<void> 2155 2156Releases the session for the incremental backup. This API uses a promise to return the result. 2157 2158**Required permissions**: ohos.permission.BACKUP 2159 2160**System capability**: SystemCapability.FileManagement.StorageService.Backup 2161 2162**Return value** 2163 2164| Type | Description | 2165| ------------------- | ----------------------- | 2166| Promise<void> | Promise that returns no value.| 2167 2168**Error codes** 2169 2170For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 2171 2172| ID| Error Message | 2173| -------- | ---------------------------------------------------------------------------------------------- | 2174| 201 | Permission verification failed, usually the result returned by VerifyAccessToken. | 2175| 202 | Permission verification failed, application which is not a system application uses system API. | 2176| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verifcation faild| 2177| 13600001 | IPC error | 2178| 13900001 | Operation not permitted | 2179| 13900005 | I/O error | 2180| 13900020 | Invalid argument | 2181| 13900042 | Unknown error | 2182 2183**Example** 2184 2185 ```ts 2186 import fs from '@ohos.file.fs'; 2187 import { BusinessError } from '@ohos.base'; 2188 2189 let generalCallbacks: backup.GeneralCallbacks = { 2190 onFileReady: (err: BusinessError, file: backup.File) => { 2191 if (err) { 2192 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 2193 return; 2194 } 2195 console.info('onFileReady success'); 2196 fs.closeSync(file.fd); 2197 }, 2198 onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => { 2199 if (err) { 2200 console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data); 2201 return; 2202 } 2203 console.info('onBundleBegin success'); 2204 }, 2205 onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => { 2206 if (err) { 2207 console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data); 2208 return; 2209 } 2210 console.info('onBundleEnd success'); 2211 }, 2212 onAllBundlesEnd: (err: BusinessError) => { 2213 if (err) { 2214 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 2215 return; 2216 } 2217 console.info('onAllBundlesEnd success'); 2218 }, 2219 onBackupServiceDied: () => { 2220 console.info('service died'); 2221 }, 2222 onResultReport: (bundleName: string, result: string) => { 2223 console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result); 2224 }, 2225 onProcess: (bundleName: string, process: string) => { 2226 console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process); 2227 } 2228 }; 2229 let incrementalBackupSession = new backup.IncrementalBackupSession(generalCallbacks); // Create a session for an incremental backup. 2230 incrementalBackupSession.release(); // End the incremental backup process. 2231 console.info('release success'); 2232 ``` 2233