1# @ohos.file.backup (Backup and Restore) 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 | Bundle name, which can be obtained by using the method provided in [bundleManager.BundleInfo](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## File 42 43Defines a file object, which 44inherits from [FileMeta](#filemeta) and [FileData](#filedata). 45 46> **NOTE** 47> 48> **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. 49 50**System capability**: SystemCapability.FileManagement.StorageService.Backup 51 52## GeneralCallbacks 53 54Provides callbacks to be used in the backup or restore process. The backup service uses these callbacks to notify the client of the backup/restore phase of the application. 55 56**System capability**: SystemCapability.FileManagement.StorageService.Backup 57 58### onFileReady 59 60onFileReady : AsyncCallback<File> 61 62Called when the server sends a file to the client. If the file is sent successfully, **err** is **undefined**. Otherwise, **err** is an error object. 63 64> **NOTE** 65> 66> 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. 67 68**System capability**: SystemCapability.FileManagement.StorageService.Backup 69 70**Error codes** 71 72For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). 73 74| ID| Error Message | 75| -------- | ----------------------- | 76| 13600001 | IPC error | 77| 13900005 | I/O error | 78| 13900011 | Out of memory | 79| 13900020 | Invalid argument | 80| 13900025 | No space left on device | 81| 13900042 | Unknown error | 82 83**Example** 84 85 ```ts 86 import fs from '@ohos.file.fs'; 87 import { BusinessError } from '@ohos.base'; 88 89 onFileReady: (err: BusinessError, file: backup.File) => { 90 if (err) { 91 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 92 } 93 console.info('onFileReady success with file: ' + file.bundleName + ' ' + file.uri); 94 fs.closeSync(file.fd); 95 } 96 ``` 97 98### onBundleBegin 99 100onBundleBegin : AsyncCallback<string> 101 102Called when the backup or restore of an application begins. If the backup or restore begins, **err** is undefined. Otherwise, **err** is an error object. 103 104**System capability**: SystemCapability.FileManagement.StorageService.Backup 105 106**Error codes** 107 108For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). 109 110| ID| Error Message | 111| -------- | ----------------------- | 112| 13600001 | IPC error | 113| 13900005 | I/O error | 114| 13900011 | Out of memory | 115| 13900020 | Invalid argument | 116| 13900025 | No space left on device | 117| 13900042 | Unknown error | 118 119**Example** 120 121 ```ts 122 import { BusinessError } from '@ohos.base'; 123 124 onBundleBegin: (err: BusinessError, bundleName: string) => { 125 if (err) { 126 console.error('onBundleBegin failed with err: ' + JSON.stringify(err)); 127 } 128 console.info('onBundleBegin success with bundleName: ' + bundleName); 129 } 130 ``` 131 132### onBundleEnd 133 134onBundleEnd : AsyncCallback<string> 135 136Called when the backup or restore of an application ends. If the backup or restore ends successfully, **err** is undefined. Otherwise, **err** is an error object. 137 138**System capability**: SystemCapability.FileManagement.StorageService.Backup 139 140**Error codes** 141 142For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). 143 144| ID| Error Message | 145| -------- | ----------------------- | 146| 13600001 | IPC error | 147| 13900005 | I/O error | 148| 13900011 | Out of memory | 149| 13900020 | Invalid argument | 150| 13900025 | No space left on device | 151| 13900042 | Unknown error | 152 153**Example** 154 155 ```ts 156 import { BusinessError } from '@ohos.base'; 157 158 onBundleEnd: (err: BusinessError, bundleName: string) => { 159 if (err) { 160 console.error('onBundleEnd failed with err: ' + JSON.stringify(err)); 161 } 162 console.info('onBundleEnd success with bundleName: ' + bundleName); 163 } 164 ``` 165 166### onAllBundlesEnd 167 168onAllBundlesEnd : AsyncCallback<undefined> 169 170Called when the backup or restore of all bundles ends. If the backup or restore of all bundles ends, **err** is **undefined**. Otherwise, **err** is an error object. 171 172**System capability**: SystemCapability.FileManagement.StorageService.Backup 173 174**Error codes** 175 176For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). 177 178| ID| Error Message | 179| -------- | ----------------------- | 180| 13600001 | IPC error | 181| 13900005 | I/O error | 182| 13900011 | Out of memory | 183| 13900020 | Invalid argument | 184| 13900025 | No space left on device | 185| 13900042 | Unknown error | 186 187**Example** 188 189 ```ts 190 import { BusinessError } from '@ohos.base'; 191 192 onAllBundlesEnd: (err: BusinessError) => { 193 if (err) { 194 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 195 } 196 console.info('onAllBundlesEnd success'); 197 } 198 ``` 199 200### onBackupServiceDied 201 202onBackupServiceDied : Callback<undefined> 203 204Called when the backup service is suspended. 205 206**System capability**: SystemCapability.FileManagement.StorageService.Backup 207 208**Example** 209 210 ```ts 211 onBackupServiceDied: () => { 212 console.info('onBackupServiceDied success'); 213 } 214 ``` 215 216## backup.getLocalCapabilities 217 218getLocalCapabilities(callback: AsyncCallback<FileData>): void 219 220Obtains a JSON file that describes local capabilities. This API uses an asynchronous callback to return the result. 221 222**Required permissions**: ohos.permission.BACKUP 223 224**System capability**: SystemCapability.FileManagement.StorageService.Backup 225 226**Parameters** 227 228| Name | Type | Mandatory| Description | 229| -------- | ------------------------------------------ | ---- | ------------------------------------------------------ | 230| callback | AsyncCallback<[FileData](#filedata)> | Yes | Callback invoked to return the **FileData** object obtained.| 231 232**Error codes** 233 234For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). 235 236| ID| Error Message | 237| -------- | ----------------------- | 238| 13600001 | IPC error | 239| 13900005 | I/O error | 240| 13900011 | Out of memory | 241| 13900025 | No space left on device | 242| 13900042 | Unknown error | 243 244**Example** 245 246 ```ts 247 import fs from '@ohos.file.fs'; 248 import { BusinessError } from '@ohos.base'; 249 250 try { 251 backup.getLocalCapabilities((err: BusinessError, fileData: backup.FileData) => { 252 if (err) { 253 console.error('getLocalCapabilities failed with err: ' + JSON.stringify(err)); 254 } 255 console.info('getLocalCapabilities success'); 256 console.info('fileData info:' + fileData.fd); 257 fs.closeSync(fileData.fd); 258 }); 259 } catch (error) { 260 let err: BusinessError = error as BusinessError; 261 console.error('getLocalCapabilities failed with err: ' + JSON.stringify(err)); 262 } 263 ``` 264 265The 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. 266 267 ```json 268 { 269 "bundleInfos" :[{ 270 "allToBackup" : true, 271 "extensionName" : "BackupExtensionAbility", 272 "name" : "com.example.hiworld", 273 "needToInstall" : false, 274 "spaceOccupied" : 0, 275 "versionCode" : 1000000, 276 "versionName" : "1.0.0" 277 }], 278 "deviceType" : "default", 279 "systemFullName" : "OpenHarmony-4.0.0.0" 280 } 281 ``` 282 283## backup.getLocalCapabilities 284 285getLocalCapabilities(): Promise<FileData> 286 287Obtains a JSON file that describes local capabilities. This API uses a promise to return the result. 288 289**Required permissions**: ohos.permission.BACKUP 290 291**System capability**: SystemCapability.FileManagement.StorageService.Backup 292 293**Return value** 294 295| Type | Description | 296| ------------------------------------ | --------------------------------------------------- | 297| Promise<[FileData](#filedata)> | Promise used to return the **FileData** object obtained.| 298 299**Error codes** 300 301For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). 302 303| ID| Error Message | 304| -------- | ----------------------- | 305| 13600001 | IPC error | 306| 13900005 | I/O error | 307| 13900011 | Out of memory | 308| 13900025 | No space left on device | 309| 13900042 | Unknown error | 310 311**Example** 312 313 ```ts 314 import fs from '@ohos.file.fs'; 315 import { BusinessError } from '@ohos.base'; 316 317 async function getLocalCapabilities() { 318 try { 319 let fileData = await backup.getLocalCapabilities(); 320 console.info('getLocalCapabilities success'); 321 console.info('fileData info:' + fileData.fd); 322 fs.closeSync(fileData.fd); 323 } catch (error) { 324 let err: BusinessError = error as BusinessError; 325 console.error('getLocalCapabilities failed with err: ' + JSON.stringify(err)); 326 } 327 } 328 ``` 329 330 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. 331 332 ```json 333 { 334 "bundleInfos" :[{ 335 "allToBackup" : true, 336 "extensionName" : "BackupExtensionAbility", 337 "name" : "com.example.hiworld", 338 "needToInstall" : false, 339 "spaceOccupied" : 0, 340 "versionCode" : 1000000, 341 "versionName" : "1.0.0" 342 }], 343 "deviceType" : "default", 344 "systemFullName" : "OpenHarmony-4.0.0.0" 345 } 346 ``` 347 348## SessionBackup 349 350Provides a backup process object to support the application backup process. Before using the APIs of this class, you need to create a **SessionBackup** instance. 351 352### constructor 353 354constructor(callbacks: GeneralCallbacks); 355 356A constructor used to create a **SessionBackup** instance. 357 358**Required permissions**: ohos.permission.BACKUP 359 360**System capability**: SystemCapability.FileManagement.StorageService.Backup 361 362**Parameters** 363 364| Name | Type | Mandatory| Description | 365| -------- | ------------------------------------- | ---- | -------------------- | 366| callback | [GeneralCallbacks](#generalcallbacks) | Yes | Callbacks to be invoked during the backup process.| 367 368**Example** 369 370 ```ts 371 import fs from '@ohos.file.fs'; 372 import { BusinessError } from '@ohos.base'; 373 374 let generalCallbacks: backup.GeneralCallbacks = { 375 onFileReady: (err: BusinessError, file: backup.File) => { 376 if (err) { 377 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 378 } 379 console.info('onFileReady success'); 380 fs.closeSync(file.fd); 381 }, 382 onBundleBegin: (err: BusinessError, bundleName: string) => { 383 if (err) { 384 console.error('onBundleBegin failed with err: ' + JSON.stringify(err)); 385 } 386 console.info('onBundleBegin success'); 387 }, 388 onBundleEnd: (err: BusinessError, bundleName: string) => { 389 if (err) { 390 console.error('onBundleEnd failed with err: ' + JSON.stringify(err)); 391 } 392 console.info('onBundleEnd success'); 393 }, 394 onAllBundlesEnd: (err: BusinessError) => { 395 if (err) { 396 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 397 } 398 console.info('onAllBundlesEnd success'); 399 }, 400 onBackupServiceDied: () => { 401 console.info('service died'); 402 } 403 }; 404 let sessionBackup = new backup.SessionBackup(generalCallbacks); 405 ``` 406 407### appendBundles 408 409appendBundles(bundlesToBackup: string[], callback: AsyncCallback<void>): void 410 411Appends 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. 412 413**Required permissions**: ohos.permission.BACKUP 414 415**System capability**: SystemCapability.FileManagement.StorageService.Backup 416 417**Parameters** 418 419| Name | Type | Mandatory| Description | 420| --------------- | ------------------------- | ---- | -------------------------------------------------------------- | 421| bundlesToBackup | string[] | Yes | Array of the application names to append. | 422| callback | AsyncCallback<void> | Yes | Callback invoked to return the result.| 423 424**Error codes** 425 426For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). 427 428| ID| Error Message | 429| -------- | ----------------------- | 430| 13600001 | IPC error | 431| 13900001 | Operation not permitted | 432| 13900005 | I/O error | 433| 13900011 | Out of memory | 434| 13900020 | Invalid argument | 435| 13900025 | No space left on device | 436| 13900042 | Unknown error | 437 438**Example** 439 440 ```ts 441 import fs from '@ohos.file.fs'; 442 import { BusinessError } from '@ohos.base'; 443 444 let generalCallbacks: backup.GeneralCallbacks = { 445 onFileReady: (err: BusinessError, file: backup.File) => { 446 if (err) { 447 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 448 } 449 console.info('onFileReady success'); 450 fs.closeSync(file.fd); 451 }, 452 onBundleBegin: (err: BusinessError, bundleName: string) => { 453 if (err) { 454 console.error('onBundleBegin failed with err: ' + JSON.stringify(err)); 455 } 456 console.info('onBundleBegin success'); 457 }, 458 onBundleEnd: (err: BusinessError, bundleName: string) => { 459 if (err) { 460 console.error('onBundleEnd failed with err: ' + JSON.stringify(err)); 461 } 462 console.info('onBundleEnd success'); 463 }, 464 onAllBundlesEnd: (err: BusinessError) => { 465 if (err) { 466 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 467 } 468 console.info('onAllBundlesEnd success'); 469 }, 470 onBackupServiceDied: () => { 471 console.info('service died'); 472 } 473 }; 474 let sessionBackup = new backup.SessionBackup(generalCallbacks); 475 try { 476 let backupApps: Array<string> = [ 477 "com.example.hiworld", 478 ]; 479 sessionBackup.appendBundles(backupApps, (err: BusinessError) => { 480 if (err) { 481 console.error('appendBundles failed with err: ' + JSON.stringify(err)); 482 } 483 console.info('appendBundles success'); 484 }); 485 } catch (error) { 486 let err: BusinessError = error as BusinessError; 487 console.error('appendBundles failed with err: ' + JSON.stringify(err)); 488 } 489 ``` 490 491### appendBundles 492 493appendBundles(bundlesToBackup: string[]): Promise<void> 494 495Appends 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. 496 497**Required permissions**: ohos.permission.BACKUP 498 499**System capability**: SystemCapability.FileManagement.StorageService.Backup 500 501**Parameters** 502 503| Name | Type | Mandatory| Description | 504| --------------- | -------- | ---- | -------------------------- | 505| bundlesToBackup | string[] | Yes | Array of the application names to append.| 506 507**Return value** 508 509| Type | Description | 510| ------------------- | -------------------------------------- | 511| Promise<void> | Promise that returns no value.| 512 513**Error codes** 514 515For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). 516 517| ID| Error Message | 518| -------- | ----------------------- | 519| 13600001 | IPC error | 520| 13900001 | Operation not permitted | 521| 13900005 | I/O error | 522| 13900011 | Out of memory | 523| 13900020 | Invalid argument | 524| 13900025 | No space left on device | 525| 13900042 | Unknown error | 526 527**Example** 528 529 ```ts 530 import fs from '@ohos.file.fs'; 531 import { BusinessError } from '@ohos.base'; 532 533 let generalCallbacks: backup.GeneralCallbacks = { 534 onFileReady: (err: BusinessError, file: backup.File) => { 535 if (err) { 536 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 537 } 538 console.info('onFileReady success'); 539 fs.closeSync(file.fd); 540 }, 541 onBundleBegin: (err: BusinessError, bundleName: string) => { 542 if (err) { 543 console.error('onBundleBegin failed with err: ' + JSON.stringify(err)); 544 } 545 console.info('onBundleBegin success'); 546 }, 547 onBundleEnd: (err: BusinessError, bundleName: string) => { 548 if (err) { 549 console.error('onBundleEnd failed with err: ' + JSON.stringify(err)); 550 } 551 console.info('onBundleEnd success'); 552 }, 553 onAllBundlesEnd: (err: BusinessError) => { 554 if (err) { 555 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 556 } 557 console.info('onAllBundlesEnd success'); 558 }, 559 onBackupServiceDied: () => { 560 console.info('service died'); 561 } 562 }; 563 let sessionBackup = new backup.SessionBackup(generalCallbacks); 564 async function appendBundles() { 565 try { 566 let backupApps: Array<string> = [ 567 "com.example.hiworld", 568 ]; 569 await sessionBackup.appendBundles(backupApps); 570 console.info('appendBundles success'); 571 } catch (error) { 572 let err: BusinessError = error as BusinessError; 573 console.error('appendBundles failed with err: ' + JSON.stringify(err)); 574 } 575 } 576 ``` 577 578## SessionRestore 579 580Provides an object to support the application restore process. Before using the APIs of this class, you need to create a **SessionRestore** instance. 581 582### constructor 583 584constructor(callbacks: GeneralCallbacks); 585 586A constructor used to create a **SessionRestore** instance. 587 588**Required permissions**: ohos.permission.BACKUP 589 590**System capability**: SystemCapability.FileManagement.StorageService.Backup 591 592**Parameters** 593 594| Name | Type | Mandatory| Description | 595| -------- | ------------------------------------- | ---- | -------------------- | 596| callback | [GeneralCallbacks](#generalcallbacks) | Yes | Callbacks to be invoked during the data restore process.| 597 598**Example** 599 600 ```ts 601 import fs from '@ohos.file.fs'; 602 import { BusinessError } from '@ohos.base'; 603 604 let generalCallbacks: backup.GeneralCallbacks = { 605 onFileReady: (err: BusinessError, file: backup.File) => { 606 if (err) { 607 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 608 } 609 console.info('onFileReady success'); 610 fs.closeSync(file.fd); 611 }, 612 onBundleBegin: (err: BusinessError, bundleName: string) => { 613 if (err) { 614 console.error('onBundleBegin failed with err: ' + JSON.stringify(err)); 615 } 616 console.info('onBundleBegin success'); 617 }, 618 onBundleEnd: (err: BusinessError, bundleName: string) => { 619 if (err) { 620 console.error('onBundleEnd failed with err: ' + JSON.stringify(err)); 621 } 622 console.info('onBundleEnd success'); 623 }, 624 onAllBundlesEnd: (err: BusinessError) => { 625 if (err) { 626 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 627 } 628 console.info('onAllBundlesEnd success'); 629 }, 630 onBackupServiceDied: () => { 631 console.info('service died'); 632 } 633 }; 634 let sessionRestore = new backup.SessionRestore(generalCallbacks); 635 ``` 636 637### appendBundles 638 639appendBundles(remoteCapabilitiesFd: number, bundlesToBackup: string[], callback: AsyncCallback<void>): void 640 641Appends the applications whose data needs to be restored. Currently, the obtained **SessionRestore** instance can be called only once in the entire restore process. This API uses an asynchronous callback to return the result. 642 643> **NOTE** 644> 645> - During the data restore process, the capability file needs to be verified. 646> - 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. 647 648**Required permissions**: ohos.permission.BACKUP 649 650**System capability**: SystemCapability.FileManagement.StorageService.Backup 651 652**Parameters** 653 654| Name | Type | Mandatory| Description | 655| -------------------- | ------------------------- | ---- | -------------------------------------------------------------- | 656| remoteCapabilitiesFd | number | Yes | FD of the file containing the capabilities to be restored. | 657| bundlesToBackup | string[] | Yes | Array of the application names to append. | 658| callback | AsyncCallback<void> | Yes | Callback invoked to return the result.| 659 660**Error codes** 661 662For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). 663 664| ID| Error Message | 665| -------- | ----------------------- | 666| 13600001 | IPC error | 667| 13900001 | Operation not permitted | 668| 13900005 | I/O error | 669| 13900011 | Out of memory | 670| 13900020 | Invalid argument | 671| 13900025 | No space left on device | 672| 13900042 | Unknown error | 673 674**Example** 675 676 ```ts 677 import fs from '@ohos.file.fs'; 678 import { BusinessError } from '@ohos.base'; 679 680 let generalCallbacks: backup.GeneralCallbacks = { 681 onFileReady: (err: BusinessError, file: backup.File) => { 682 if (err) { 683 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 684 } 685 console.info('onFileReady success'); 686 fs.closeSync(file.fd); 687 }, 688 onBundleBegin: (err: BusinessError, bundleName: string) => { 689 if (err) { 690 console.error('onBundleBegin failed with err: ' + JSON.stringify(err)); 691 } 692 console.info('onBundleBegin success'); 693 }, 694 onBundleEnd: (err: BusinessError, bundleName: string) => { 695 if (err) { 696 console.error('onBundleEnd failed with err: ' + JSON.stringify(err)); 697 } 698 console.info('onBundleEnd success'); 699 }, 700 onAllBundlesEnd: (err: BusinessError) => { 701 if (err) { 702 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 703 } 704 console.info('onAllBundlesEnd success'); 705 }, 706 onBackupServiceDied: () => { 707 console.info('service died'); 708 } 709 }; 710 let sessionRestore = new backup.SessionRestore(generalCallbacks); 711 async function appendBundles() { 712 try { 713 let fileData = await backup.getLocalCapabilities(); 714 console.info('getLocalCapabilities success'); 715 let restoreApps: Array<string> = [ 716 "com.example.hiworld", 717 ]; 718 sessionRestore.appendBundles(fileData.fd, restoreApps, (err: BusinessError) => { 719 if (err) { 720 console.error('appendBundles failed with err: ' + JSON.stringify(err)); 721 } 722 console.info('appendBundles success'); 723 }); 724 } catch (error) { 725 let err: BusinessError = error as BusinessError; 726 console.error('getLocalCapabilities failed with err: ' + JSON.stringify(err)); 727 } finally { 728 fs.closeSync(fileData.fd); 729 } 730 } 731 ``` 732 733### appendBundles 734 735appendBundles(remoteCapabilitiesFd: number, bundlesToBackup: string[]): Promise<void> 736 737Appends the applications whose data needs to be restored. Currently, the obtained **SessionRestore** instance can be called only once in the entire restore process. This API uses a promise to return the result. 738 739> **NOTE** 740> 741> - During the data restore process, the capability file needs to be verified. 742> - 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. 743 744**Required permissions**: ohos.permission.BACKUP 745 746**System capability**: SystemCapability.FileManagement.StorageService.Backup 747 748**Parameters** 749 750| Name | Type | Mandatory| Description | 751| -------------------- | -------- | ---- | ---------------------------------- | 752| remoteCapabilitiesFd | number | Yes | FD of the file containing the capabilities to be restored.| 753| bundlesToBackup | string[] | Yes | Array of the application names to append. | 754 755**Return value** 756 757| Type | Description | 758| ------------------- | -------------------------------------- | 759| Promise<void> | Promise that returns no value.| 760 761**Error codes** 762 763For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). 764 765| ID| Error Message | 766| -------- | ----------------------- | 767| 13600001 | IPC error | 768| 13900001 | Operation not permitted | 769| 13900005 | I/O error | 770| 13900011 | Out of memory | 771| 13900020 | Invalid argument | 772| 13900025 | No space left on device | 773| 13900042 | Unknown error | 774 775**Example** 776 777 ```ts 778 import fs from '@ohos.file.fs'; 779 import { BusinessError } from '@ohos.base'; 780 781 let generalCallbacks: backup.GeneralCallbacks = { 782 onFileReady: (err: BusinessError, file: backup.File) => { 783 if (err) { 784 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 785 } 786 console.info('onFileReady success'); 787 fs.closeSync(file.fd); 788 }, 789 onBundleBegin: (err: BusinessError, bundleName: string) => { 790 if (err) { 791 console.error('onBundleBegin failed with err: ' + JSON.stringify(err)); 792 } 793 console.info('onBundleBegin success'); 794 }, 795 onBundleEnd: (err: BusinessError, bundleName: string) => { 796 if (err) { 797 console.error('onBundleEnd failed with err: ' + JSON.stringify(err)); 798 } 799 console.info('onBundleEnd success'); 800 }, 801 onAllBundlesEnd: (err: BusinessError) => { 802 if (err) { 803 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 804 } 805 console.info('onAllBundlesEnd success'); 806 }, 807 onBackupServiceDied: () => { 808 console.info('service died'); 809 } 810 }; 811 let sessionRestore = new backup.SessionRestore(generalCallbacks); 812 async function appendBundles() { 813 try { 814 let fileData = await backup.getLocalCapabilities(); 815 console.info('getLocalCapabilities success'); 816 let restoreApps: Array<string> = [ 817 "com.example.hiworld", 818 ]; 819 await sessionRestore.appendBundles(fileData.fd, restoreApps); 820 console.info('appendBundles success'); 821 } catch (error) { 822 let err: BusinessError = error as BusinessError; 823 console.error('getLocalCapabilities failed with err: ' + JSON.stringify(err)); 824 } finally { 825 fs.closeSync(fileData.fd); 826 } 827 } 828 ``` 829 830### getFileHandle 831 832getFileHandle(fileMeta: FileMeta, callback: AsyncCallback<void>): void 833 834Obtains the handle of the shared file from the service. This API uses an asynchronous callback to return the result. 835 836> **NOTE** 837> 838> - 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). 839> - Before using **getFileHandle**, you need to obtain a **SessionRestore** instance and add the applications with data to be restored by using **appendBundles**. 840> - 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. 841> - **getFileHandle** can be called multiple times based on the number of files to be restored. 842 843**Required permissions**: ohos.permission.BACKUP 844 845**System capability**: SystemCapability.FileManagement.StorageService.Backup 846 847**Parameters** 848 849| Name | Type | Mandatory| Description | 850| -------- | ------------------------- | ---- | -------------------------------------------------------------- | 851| fileMeta | [FileMeta](#filemeta) | Yes | Metadata of the file to restore. | 852| callback | AsyncCallback<void> | Yes | Callback invoked to return the result.| 853 854**Error codes** 855 856For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). 857 858| ID| Error Message | 859| -------- | ----------------------- | 860| 13600001 | IPC error | 861| 13900001 | Operation not permitted | 862| 13900020 | Invalid argument | 863| 13900042 | Unknown error | 864 865**Example** 866 867 ```ts 868 import fs from '@ohos.file.fs'; 869 import { BusinessError } from '@ohos.base'; 870 871 let generalCallbacks: backup.GeneralCallbacks = { 872 onFileReady: (err: BusinessError, file: backup.File) => { 873 if (err) { 874 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 875 } 876 console.info('onFileReady success'); 877 fs.closeSync(file.fd); 878 }, 879 onBundleBegin: (err: BusinessError, bundleName: string) => { 880 if (err) { 881 console.error('onBundleBegin failed with err: ' + JSON.stringify(err)); 882 } 883 console.info('onBundleBegin success'); 884 }, 885 onBundleEnd: (err: BusinessError, bundleName: string) => { 886 if (err) { 887 console.error('onBundleEnd failed with err: ' + JSON.stringify(err)); 888 } 889 console.info('onBundleEnd success'); 890 }, 891 onAllBundlesEnd: (err: BusinessError) => { 892 if (err) { 893 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 894 } 895 console.info('onAllBundlesEnd success'); 896 }, 897 onBackupServiceDied: () => { 898 console.info('service died'); 899 } 900 }; 901 let sessionRestore = new backup.SessionRestore(generalCallbacks); 902 let fileMeta: backup.FileMeta = { 903 bundleName: "com.example.hiworld", 904 uri: "test.txt" 905 } 906 sessionRestore.getFileHandle(fileMeta, (err: BusinessError) => { 907 if (err) { 908 console.error('getFileHandle failed with err: ' + JSON.stringify(err)); 909 } 910 console.info('getFileHandle success'); 911 }); 912 ``` 913 914### getFileHandle 915 916getFileHandle(fileMeta: FileMeta): Promise<void> 917 918Obtains the handle of the shared file from the service. This API uses a promise to return the result. 919 920> **NOTE** 921> 922> - 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). 923> - Before using **getFileHandle**, you need to obtain a **SessionRestore** instance and add the applications with data to be restored by using **appendBundles**. 924> - 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. 925> - **getFileHandle** can be called multiple times based on the number of files to be restored. 926 927**Required permissions**: ohos.permission.BACKUP 928 929**System capability**: SystemCapability.FileManagement.StorageService.Backup 930 931**Parameters** 932 933| Name | Type | Mandatory| Description | 934| -------- | --------------------- | ---- | ------------------ | 935| fileMeta | [FileMeta](#filemeta) | Yes | Metadata of the file to restore.| 936 937**Return value** 938 939| Type | Description | 940| ------------------- | -------------------------------------- | 941| Promise<void> | Promise that returns no value.| 942 943**Error codes** 944 945For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). 946 947| ID| Error Message | 948| -------- | ----------------------- | 949| 13600001 | IPC error | 950| 13900001 | Operation not permitted | 951| 13900020 | Invalid argument | 952| 13900042 | Unknown error | 953 954**Example** 955 956 ```ts 957 import fs from '@ohos.file.fs'; 958 import { BusinessError } from '@ohos.base'; 959 960 let generalCallbacks: backup.GeneralCallbacks = { 961 onFileReady: (err: BusinessError, file: backup.File) => { 962 if (err) { 963 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 964 } 965 console.info('onFileReady success'); 966 fs.closeSync(file.fd); 967 }, 968 onBundleBegin: (err: BusinessError, bundleName: string) => { 969 if (err) { 970 console.error('onBundleBegin failed with err: ' + JSON.stringify(err)); 971 } 972 console.info('onBundleBegin success'); 973 }, 974 onBundleEnd: (err: BusinessError, bundleName: string) => { 975 if (err) { 976 console.error('onBundleEnd failed with err: ' + JSON.stringify(err)); 977 } 978 console.info('onBundleEnd success'); 979 }, 980 onAllBundlesEnd: (err: BusinessError) => { 981 if (err) { 982 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 983 } 984 console.info('onAllBundlesEnd success'); 985 }, 986 onBackupServiceDied: () => { 987 console.info('service died'); 988 } 989 }; 990 let sessionRestore = new backup.SessionRestore(generalCallbacks); 991 async function getFileHandle() { 992 try { 993 let fileMeta: backup.FileMeta = { 994 bundleName: "com.example.hiworld", 995 uri: "test.txt" 996 } 997 await sessionRestore.getFileHandle(fileMeta); 998 console.info('getFileHandle success'); 999 } catch (error) { 1000 let err: BusinessError = error as BusinessError; 1001 console.error('getFileHandle failed with err: ' + JSON.stringify(err)); 1002 } 1003 } 1004 ``` 1005 1006### publishFile 1007 1008publishFile(fileMeta: FileMeta, callback: AsyncCallback<void>): void 1009 1010Publishes **FileMeta** to the backup service to indicate that the file content is ready. This API uses an asynchronous callback to return the result. 1011 1012> **NOTE** 1013> 1014> - 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). 1015> - 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. 1016> - After the copy is complete, you can use **publishFile** to notify the backup service that the file is ready. 1017 1018**Required permissions**: ohos.permission.BACKUP 1019 1020**System capability**: SystemCapability.FileManagement.StorageService.Backup 1021 1022**Parameters** 1023 1024| Name | Type | Mandatory| Description | 1025| -------- | ------------------------- | ---- | ---------------------------------------------------------- | 1026| fileMeta | [FileMeta](#filemeta) | Yes | Metadata of the file to restore. | 1027| callback | AsyncCallback<void> | Yes | Callback invoked to return the result.| 1028 1029**Error codes** 1030 1031For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). 1032 1033| ID| Error Message | 1034| -------- | ----------------------- | 1035| 13600001 | IPC error | 1036| 13900001 | Operation not permitted | 1037| 13900020 | Invalid argument | 1038| 13900042 | Unknown error | 1039 1040**Example** 1041 1042 ```ts 1043 import fs from '@ohos.file.fs'; 1044 import { BusinessError } from '@ohos.base'; 1045 1046 let g_session: backup.SessionRestore; 1047 function createSessionRestore() { 1048 let generalCallbacks: backup.GeneralCallbacks = { 1049 onFileReady: (err: BusinessError, file: backup.File) => { 1050 if (err) { 1051 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 1052 } 1053 console.info('onFileReady success'); 1054 fs.closeSync(file.fd); 1055 let fileMeta: backup.FileMeta = { 1056 bundleName: file.bundleName, 1057 uri: file.uri 1058 } 1059 g_session.publishFile(fileMeta, (err: BusinessError) => { 1060 if (err) { 1061 console.error('publishFile failed with err: ' + JSON.stringify(err)); 1062 } 1063 console.info('publishFile success'); 1064 }); 1065 }, 1066 onBundleBegin: (err: BusinessError, bundleName: string) => { 1067 if (err) { 1068 console.error('onBundleBegin failed with err: ' + JSON.stringify(err)); 1069 } 1070 console.info('onBundleBegin success'); 1071 }, 1072 onBundleEnd: (err: BusinessError, bundleName: string) => { 1073 if (err) { 1074 console.error('onBundleEnd failed with err: ' + JSON.stringify(err)); 1075 } 1076 console.info('onBundleEnd success'); 1077 }, 1078 onAllBundlesEnd: (err: BusinessError) => { 1079 if (err) { 1080 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 1081 } 1082 console.info('onAllBundlesEnd success'); 1083 }, 1084 onBackupServiceDied: () => { 1085 console.info('service died'); 1086 } 1087 }; 1088 let sessionRestore = new backup.SessionRestore(generalCallbacks); 1089 return sessionRestore; 1090 } 1091 g_session = createSessionRestore(); 1092 ``` 1093 1094### publishFile 1095 1096publishFile(fileMeta: FileMeta): Promise<void> 1097 1098Publishes **FileMeta** to the backup service to indicate that the file content is ready. This API uses a promise to return the result. 1099 1100> **NOTE** 1101> 1102> - 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). 1103> - 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. 1104> - After the copy is complete, you can use **publishFile** to notify the backup service that the file is ready. 1105 1106**Required permissions**: ohos.permission.BACKUP 1107 1108**System capability**: SystemCapability.FileManagement.StorageService.Backup 1109 1110**Parameters** 1111 1112| Name | Type | Mandatory| Description | 1113| -------- | --------------------- | ---- | ---------------- | 1114| fileMeta | [FileMeta](#filemeta) | Yes | Metadata of the file to restore.| 1115 1116**Return value** 1117 1118| Type | Description | 1119| ------------------- | -------------------------------------- | 1120| Promise<void> | Promise that returns no value.| 1121 1122**Error codes** 1123 1124For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). 1125 1126| ID| Error Message | 1127| -------- | ----------------------- | 1128| 13600001 | IPC error | 1129| 13900001 | Operation not permitted | 1130| 13900020 | Invalid argument | 1131| 13900042 | Unknown error | 1132 1133**Example** 1134 1135 ```ts 1136 import fs from '@ohos.file.fs'; 1137 import { BusinessError } from '@ohos.base'; 1138 1139 let g_session: backup.SessionRestore; 1140 async function publishFile(file: backup.FileMeta) { 1141 let fileMeta: backup.FileMeta = { 1142 bundleName: file.bundleName, 1143 uri: file.uri 1144 } 1145 await g_session.publishFile(fileMeta); 1146 } 1147 function createSessionRestore() { 1148 let generalCallbacks: backup.GeneralCallbacks = { 1149 onFileReady: (err: BusinessError, file: backup.File) => { 1150 if (err) { 1151 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 1152 } 1153 console.info('onFileReady success'); 1154 fs.closeSync(file.fd); 1155 publishFile(file); 1156 console.info('publishFile success'); 1157 }, 1158 onBundleBegin: (err: BusinessError, bundleName: string) => { 1159 if (err) { 1160 console.error('onBundleBegin failed with err: ' + JSON.stringify(err)); 1161 } 1162 console.info('onBundleBegin success'); 1163 }, 1164 onBundleEnd: (err: BusinessError, bundleName: string) => { 1165 if (err) { 1166 console.error('onBundleEnd failed with err: ' + JSON.stringify(err)); 1167 } 1168 console.info('onBundleEnd success'); 1169 }, 1170 onAllBundlesEnd: (err: BusinessError) => { 1171 if (err) { 1172 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 1173 } 1174 console.info('onAllBundlesEnd success'); 1175 }, 1176 onBackupServiceDied: () => { 1177 console.info('service died'); 1178 } 1179 }; 1180 let sessionRestore = new backup.SessionRestore(generalCallbacks); 1181 return sessionRestore; 1182 } 1183 g_session = createSessionRestore(); 1184 ``` 1185