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