1# @ohos.file.backup (备份恢复) 2 3该模块为应用提供备份/恢复数据的能力。 4 5> **说明：** 6> 7> - 本模块首批接口从API version 10开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8> - 本模块接口为系统接口。 9 10## 导入模块 11 12```ts 13import backup from '@ohos.file.backup'; 14``` 15 16## FileMeta 17 18文件的元数据，包含一个应用名称以及文件uri。FileMeta在执行备份/恢复时是不可缺少的对象 19 20**系统能力**：SystemCapability.FileManagement.StorageService.Backup 21 22| 名称 | 类型 | 必填 | 说明 | 23| ---------- | ------ | ---- | ---------------------------------------------------------------------------------------------- | 24| bundleName | string | 是 | 应用名称，可通过[bundle.BundleInfo](js-apis-bundle-BundleInfo.md)提供的获取方式获取。 | 25| uri | string | 是 | 应用沙箱内待传输文件的名称，当前uri尚未升级为标准格式，仅接受0-9a-zA-Z下划线(_)点(.)组成的名称 | 26 27## FileData 28 29文件的元数据，包含一个已经打开的文件描述符。FileData在执行备份/恢复时是不可缺少的对象 30 31> **说明：** 32> 33> FileData使用完成后必须关闭，如不关闭会出现内存泄露问题。关闭的方法可参考由[@ohos.file.fs](js-apis-file-fs.md)提供的[fs.closeSync](js-apis-file-fs.md#fsclosesync)等相关关闭接口。 34 35**系统能力**：SystemCapability.FileManagement.StorageService.Backup 36 37| 名称 | 类型 | 必填 | 说明 | 38| ---- | ------ | ---- | ---------------------------------------- | 39| fd | number | 是 | 已经打开的文件描述符，通过备份服务获取。 | 40 41## File 42 43一个文件对象。 44继承[FileMeta](#filemeta)和[FileData](#filedata) 45 46> **说明：** 47> 48> file.backup.File与@ohos.file.fs中的提供的[File](js-apis-file-fs.md#file)是带有不同的涵义，前者是继承[FileMeta](#filemeta)和[FileData](#filedata)的对象而后者只有一个文件描述符的对象。请注意做区分，不要混淆。 49 50**系统能力**：SystemCapability.FileManagement.StorageService.Backup 51 52## GeneralCallbacks 53 54备份/恢复过程中的通用回调，备份服务将通过这些回调通知客户端其应用的备份/恢复阶段。 55 56**系统能力**：SystemCapability.FileManagement.StorageService.Backup 57 58### onFileReady 59 60onFileReady : AsyncCallback<File> 61 62回调函数。当服务端返向客户端发送文件成功时触发回调，err为undefined，否则为错误对象。 63 64> **说明：** 65> 66> AsyncCallback回调中返回的File 所属file.backup.[File](#file)类型，返回的文件归备份服务所有，一旦文件关闭，备份服务将选择合适的时机去清理，但客户端必须关闭文件句柄。 67 68**系统能力**：SystemCapability.FileManagement.StorageService.Backup 69 70**错误码：** 71 72以下错误码的详细介绍请参见[文件管理子系统错误码](../errorcodes/errorcode-filemanagement.md)。 73 74| 错误码ID | 错误信息 | 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**示例：** 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 回调函数。当应用备份/恢复开始时返回bundle名称成功时触发回调，err为undefined，否则为错误对象。 102 103**系统能力**：SystemCapability.FileManagement.StorageService.Backup 104 105**错误码：** 106 107以下错误码的详细介绍请参见[文件管理子系统错误码](../errorcodes/errorcode-filemanagement.md)。 108 109| 错误码ID | 错误信息 | 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**示例：** 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 134回调函数。当应用备份/恢复结束后返回bundle名称成功时触发回调，err为undefined，否则为错误对象。 135 136**系统能力**：SystemCapability.FileManagement.StorageService.Backup 137 138**错误码：** 139 140以下错误码的详细介绍请参见[文件管理子系统错误码](../errorcodes/errorcode-filemanagement.md)。 141 142| 错误码ID | 错误信息 | 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**示例：** 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 167回调函数。当所有bundle的备份/恢复过程结束成功时触发回调，err为undefined，否则为错误对象。 168 169**系统能力**：SystemCapability.FileManagement.StorageService.Backup 170 171**错误码：** 172 173以下错误码的详细介绍请参见[文件管理子系统错误码](../errorcodes/errorcode-filemanagement.md)。 174 175| 错误码ID | 错误信息 | 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**示例：** 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 200回调函数。备份服务死亡时触发回调。 201 202**系统能力**：SystemCapability.FileManagement.StorageService.Backup 203 204**示例：** 205 206 ```ts 207 onBackupServiceDied: () => { 208 console.info('onBackupServiceDied success'); 209 } 210 ``` 211 212## backup.getLocalCapabilities 213 214getLocalCapabilities(callback: AsyncCallback<FileData>): void 215 216用于获取一个描述本地能力的Json文件。使用callback异步回调。 217 218**需要权限**：ohos.permission.BACKUP 219 220**系统能力**：SystemCapability.FileManagement.StorageService.Backup 221 222**参数：** 223 224| 参数名 | 类型 | 必填 | 说明 | 225| -------- | ------------------------------------------ | ---- | ------------------------------------------------------ | 226| callback | AsyncCallback<[FileData](#filedata)> | 是 | 回调函数。当获取成功，err为undefined，否则为错误对象。 | 227 228**错误码：** 229 230以下错误码的详细介绍请参见[文件管理子系统错误码](../errorcodes/errorcode-filemanagement.md)。 231 232| 错误码ID | 错误信息 | 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**示例：** 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 259**返回的能力文件内容示例：** 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 281用于获取一个描述本地能力的Json文件。使用Promise异步回调。 282 283**需要权限**：ohos.permission.BACKUP 284 285**系统能力**：SystemCapability.FileManagement.StorageService.Backup 286 287**返回值：** 288 289| 类型 | 说明 | 290| ------------------------------------ | --------------------------------------------------- | 291| Promise<[FileData](#filedata)> | Promise对象，返回描述本地能力的Json文件的FileData。 | 292 293**错误码：** 294 295以下错误码的详细介绍请参见[文件管理子系统错误码](../errorcodes/errorcode-filemanagement.md)。 296 297| 错误码ID | 错误信息 | 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**示例：** 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 **返回的能力文件内容示例：** 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 342备份流程对象，用来支撑应用备份的流程。在使用前，需要先创建SessionBackup实例。 343 344### constructor 345 346constructor(callbacks: GeneralCallbacks); 347 348备份流程的构造函数，用于获取SessionBackup类的实例。 349 350**需要权限**：ohos.permission.BACKUP 351 352**系统能力**：SystemCapability.FileManagement.StorageService.Backup 353 354**参数：** 355 356| 参数名 | 类型 | 必填 | 说明 | 357| -------- | ------------------------------------- | ---- | -------------------- | 358| callback | [GeneralCallbacks](#generalcallbacks) | 是 | 备份流程所需的回调。 | 359 360**示例：** 361 362 ```ts 363 import fs from '@ohos.file.fs'; 364 import { BusinessError } from '@ohos.base'; 365 let generalCallbacks: backup.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 402添加需要备份的应用。当前整个流程中，在获取SessionBackup类的实例后只能调用一次。使用callback异步回调。 403 404**需要权限**：ohos.permission.BACKUP 405 406**系统能力**：SystemCapability.FileManagement.StorageService.Backup 407 408**参数：** 409 410| 参数名 | 类型 | 必填 | 说明 | 411| --------------- | ------------------------- | ---- | -------------------------------------------------------------- | 412| bundlesToBackup | string[] | 是 | 需要备份的应用名称的数组。 | 413| callback | AsyncCallback<void> | 是 | 回调函数。当添加备份应用成功，err为undefined，否则为错误对象。 | 414 415**错误码：** 416 417以下错误码的详细介绍请参见[文件管理子系统错误码](../errorcodes/errorcode-filemanagement.md)。 418 419| 错误码ID | 错误信息 | 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**示例：** 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 485添加需要备份的应用。当前整个流程中，在获取SessionBackup类的实例后只能调用一次。使用Promise异步回调。 486 487**需要权限**：ohos.permission.BACKUP 488 489**系统能力**：SystemCapability.FileManagement.StorageService.Backup 490 491**参数：** 492 493| 参数名 | 类型 | 必填 | 说明 | 494| --------------- | -------- | ---- | -------------------------- | 495| bundlesToBackup | string[] | 是 | 需要备份的应用名称的数组。 | 496 497**返回值：** 498 499| 类型 | 说明 | 500| ------------------- | -------------------------------------- | 501| Promise<void> | Promise对象。无返回结果的Promise对象。 | 502 503**错误码：** 504 505以下错误码的详细介绍请参见[文件管理子系统错误码](../errorcodes/errorcode-filemanagement.md)。 506 507| 错误码ID | 错误信息 | 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**示例：** 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 569恢复流程对象，用来支撑应用恢复的流程。在使用前，需要先创建SessionRestore实例。 570 571### constructor 572 573constructor(callbacks: GeneralCallbacks); 574 575恢复流程的构造函数，用于获取SessionRestore类的实例。 576 577**需要权限**：ohos.permission.BACKUP 578 579**系统能力**：SystemCapability.FileManagement.StorageService.Backup 580 581**参数：** 582 583| 参数名 | 类型 | 必填 | 说明 | 584| -------- | ------------------------------------- | ---- | -------------------- | 585| callback | [GeneralCallbacks](#generalcallbacks) | 是 | 恢复流程所需的回调。 | 586 587**示例：** 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 629添加需要恢复的应用。当前整个流程中，在获取SessionRestore类的实例后只能调用一次。使用callback异步回调。 630 631> **说明：** 632> 633> - 服务在恢复时需要其能力文件进行相关校验。 634> - 因此remoteCapabilitiesFd可通过备份端服务所提供的[getLocalCapabilities](#backupgetlocalcapabilities)接口获取，可对其内容根据恢复应用的实际状况修改参数。也可通过getLocalCapabilities提供的json示例自行生成能力文件。 635 636**需要权限**：ohos.permission.BACKUP 637 638**系统能力**：SystemCapability.FileManagement.StorageService.Backup 639 640**参数：** 641 642| 参数名 | 类型 | 必填 | 说明 | 643| -------------------- | ------------------------- | ---- | -------------------------------------------------------------- | 644| remoteCapabilitiesFd | number | 是 | 用于恢复所需能力文件的文件描述符。 | 645| bundlesToBackup | string[] | 是 | 需要恢复的应用名称的数组。 | 646| callback | AsyncCallback<void> | 是 | 回调函数。当添加恢复应用成功，err为undefined，否则为错误对象。 | 647 648**错误码：** 649 650以下错误码的详细介绍请参见[文件管理子系统错误码](../errorcodes/errorcode-filemanagement.md)。 651 652| 错误码ID | 错误信息 | 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**示例：** 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 722添加需要恢复的应用。当前整个流程中，在获取SessionRestore类的实例后只能调用一次。使用Promise异步回调。 723 724> **说明：** 725> 726> - 服务在恢复时需要其能力文件进行相关校验。 727> - 因此remoteCapabilitiesFd可通过备份端服务所提供的[getLocalCapabilities](#backupgetlocalcapabilities)接口获取，可对其内容根据恢复应用的实际状况修改参数。也可通过getLocalCapabilities提供的json示例自行生成能力文件。 728 729**需要权限**：ohos.permission.BACKUP 730 731**系统能力**：SystemCapability.FileManagement.StorageService.Backup 732 733**参数：** 734 735| 参数名 | 类型 | 必填 | 说明 | 736| -------------------- | -------- | ---- | ---------------------------------- | 737| remoteCapabilitiesFd | number | 是 | 用于恢复所需能力文件的文件描述符。 | 738| bundlesToBackup | string[] | 是 | 需要恢复的应用包名称的数组。 | 739 740**返回值：** 741 742| 类型 | 说明 | 743| ------------------- | -------------------------------------- | 744| Promise<void> | Promise对象。无返回结果的Promise对象。 | 745 746**错误码：** 747 748以下错误码的详细介绍请参见[文件管理子系统错误码](../errorcodes/errorcode-filemanagement.md)。 749 750| 错误码ID | 错误信息 | 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**示例：** 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 816用于请求从服务中获取共享文件。使用callback异步回调。 817 818> **说明：** 819> 820> - 这个接口是零拷贝特性（减少不必要的内存拷贝，实现了更高效率的传输）的一部分。零拷贝方法可参考由[@ohos.file.fs](js-apis-file-fs.md)提供的[fs.copyFile](js-apis-file-fs.md#fscopyfile)等相关零拷贝接口。 821> - 使用getFileHandle前需要获取SessionRestore类的实例，并且成功通过appendBundles添加需要待恢复的应用。 822> - 开发者可以通过onFileReady回调来获取文件句柄，当客户端完成文件操作时，需要使用publishFile来进行发布。 823> - 根据所需要恢复的文件个数，可以多次调用getFileHandle。 824 825**需要权限**：ohos.permission.BACKUP 826 827**系统能力**：SystemCapability.FileManagement.StorageService.Backup 828 829**参数：** 830 831| 参数名 | 类型 | 必填 | 说明 | 832| -------- | ------------------------- | ---- | -------------------------------------------------------------- | 833| fileMeta | [FileMeta](#filemeta) | 是 | 恢复文件的元数据。 | 834| callback | AsyncCallback<void> | 是 | 回调函数。当请求文件句柄成功，err为undefined，否则为错误对象。 | 835 836**错误码：** 837 838以下错误码的详细介绍请参见[文件管理子系统错误码](../errorcodes/errorcode-filemanagement.md)。 839 840| 错误码ID | 错误信息 | 841| -------- | ----------------------- | 842| 13600001 | IPC error | 843| 13900001 | Operation not permitted | 844| 13900020 | Invalid argument | 845| 13900042 | Unknown error | 846 847**示例：** 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 899用于请求从服务中获取共享文件。使用Promise异步回调。 900 901> **说明：** 902> 903> - 这个接口是零拷贝特性（减少不必要的内存拷贝，实现了更高效率的传输）的一部分。零拷贝方法可参考由[@ohos.file.fs](js-apis-file-fs.md)提供的[fs.copyFile](js-apis-file-fs.md#fscopyfile)等相关零拷贝接口。 904> - 使用getFileHandle前需要获取SessionRestore类的实例，并且成功通过appendBundles添加需要待恢复的应用。 905> - 开发者可以通过onFileReady回调来获取文件句柄，当客户端完成文件操作时，需要使用publishFile来进行发布。 906> - 根据所需要恢复的文件个数，可以多次调用getFileHandle。 907 908**需要权限**：ohos.permission.BACKUP 909 910**系统能力**：SystemCapability.FileManagement.StorageService.Backup 911 912**参数：** 913 914| 参数名 | 类型 | 必填 | 说明 | 915| -------- | --------------------- | ---- | ------------------ | 916| fileMeta | [FileMeta](#filemeta) | 是 | 恢复文件的元数据。 | 917 918**返回值：** 919 920| 类型 | 说明 | 921| ------------------- | -------------------------------------- | 922| Promise<void> | Promise对象。无返回结果的Promise对象。 | 923 924**错误码：** 925 926以下错误码的详细介绍请参见[文件管理子系统错误码](../errorcodes/errorcode-filemanagement.md)。 927 928| 错误码ID | 错误信息 | 929| -------- | ----------------------- | 930| 13600001 | IPC error | 931| 13900001 | Operation not permitted | 932| 13900020 | Invalid argument | 933| 13900042 | Unknown error | 934 935**示例：** 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 990用于将FileMeta发布到备份服务，使服务知道文件的内容已经准备完成。使用callback异步回调。 991 992> **说明：** 993> 994> - 这个接口是零拷贝特性（减少不必要的内存拷贝，实现了更高效率的传输）的一部分。零拷贝方法可参考由[@ohos.file.fs](js-apis-file-fs.md)提供的[fs.copyFile](js-apis-file-fs.md#fscopyfile)等相关零拷贝接口。 995> - 服务端通过onFileReady返回文件句柄后，客户端可通过零拷贝操作将其对应的文件内容拷贝到服务端提供的文件句柄中。 996> - 在完成拷贝操作后可使用publishFile通知备份服务文件已经准备完成。 997 998**需要权限**：ohos.permission.BACKUP 999 1000**系统能力**：SystemCapability.FileManagement.StorageService.Backup 1001 1002**参数：** 1003 1004| 参数名 | 类型 | 必填 | 说明 | 1005| -------- | ------------------------- | ---- | ---------------------------------------------------------- | 1006| fileMeta | [FileMeta](#filemeta) | 是 | 恢复文件元数据。 | 1007| callback | AsyncCallback<void> | 是 | 回调函数。当发布文件成功，err为undefined，否则为错误对象。 | 1008 1009**错误码：** 1010 1011以下错误码的详细介绍请参见[文件管理子系统错误码](../errorcodes/errorcode-filemanagement.md)。 1012 1013| 错误码ID | 错误信息 | 1014| -------- | ----------------------- | 1015| 13600001 | IPC error | 1016| 13900001 | Operation not permitted | 1017| 13900020 | Invalid argument | 1018| 13900042 | Unknown error | 1019 1020**示例：** 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 1077用于将FileMeta发布到备份服务，使服务知道文件的内容已经准备完成。使用Promise异步回调。 1078 1079> **说明：** 1080> 1081> - 这个接口是零拷贝特性（减少不必要的内存拷贝，实现了更高效率的传输）的一部分。零拷贝方法可参考由[@ohos.file.fs](js-apis-file-fs.md)提供的[fs.copyFile](js-apis-file-fs.md#fscopyfile)等相关零拷贝接口。 1082> - 服务端通过onFileReady返回文件句柄后，客户端可通过零拷贝操作将其对应的文件内容拷贝到服务端提供的文件句柄中。 1083> - 在完成拷贝操作后可使用publishFile通知备份服务文件已经准备完成。 1084 1085**需要权限**：ohos.permission.BACKUP 1086 1087**系统能力**：SystemCapability.FileManagement.StorageService.Backup 1088 1089**参数：** 1090 1091| 参数名 | 类型 | 必填 | 说明 | 1092| -------- | --------------------- | ---- | ---------------- | 1093| fileMeta | [FileMeta](#filemeta) | 是 | 恢复文件元数据。 | 1094 1095**返回值：** 1096 1097| 类型 | 说明 | 1098| ------------------- | -------------------------------------- | 1099| Promise<void> | Promise对象。无返回结果的Promise对象。 | 1100 1101**错误码：** 1102 1103以下错误码的详细介绍请参见[文件管理子系统错误码](../errorcodes/errorcode-filemanagement.md)。 1104 1105| 错误码ID | 错误信息 | 1106| -------- | ----------------------- | 1107| 13600001 | IPC error | 1108| 13900001 | Operation not permitted | 1109| 13900020 | Invalid argument | 1110| 13900042 | Unknown error | 1111 1112**示例：** 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