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 | 是 | 应用名称，可通过[bundleManager.BundleInfo](../apis-ability-kit/js-apis-bundleManager-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## FileManifestData<sup>12+</sup> 42 43文件的元数据，包含一个已经打开的文件描述符。FileManifestData所打开的内容是一个清单文件，用于描述应用增量备份/恢复时对应文件的基础信息。FileManifestData在执行增量备份/恢复时是不可缺少的对象。 44 45> **说明：** 46> 47> 关闭的方法可参考[fs.closeSync](js-apis-file-fs.md#fsclosesync)等关闭接口。 48 49**系统能力**：SystemCapability.FileManagement.StorageService.Backup 50 51| 名称 | 类型 | 必填 | 说明 | 52| ---------- | ------ | ---- | ---------------------------------------- | 53| manifestFd | number | 是 | 已经打开的文件描述符，通过备份服务获取。 | 54 55## IncrementalBackupTime<sup>12+</sup> 56 57用于记录最后一次的增量备份时间，用于描述备份增量的时间点。 58 59**系统能力**：SystemCapability.FileManagement.StorageService.Backup 60 61| 名称 | 类型 | 必填 | 说明 | 62| ------------------- | ------ | ---- | --------------------------------------------------------------------------------------------------- | 63| bundleName | string | 是 | 应用名称，可通过[bundleManager.BundleInfo](../apis-ability-kit/js-apis-bundleManager-bundleInfo.md)提供的获取方式获取。 | 64| lastIncrementalTime | number | 是 | 最后一次的增量备份时间。 | 65 66## BackupParams<sup>12+</sup> 67 68为备份恢复提供可选配置参数以json格式的字符串形式存在。 69 70**系统能力**：SystemCapability.FileManagement.StorageService.Backup 71 72| 名称 | 类型 | 必填 | 说明 | 73| ---------- | ------ | ---- | -------------------------------------------------- | 74| parameters | string | 否 | 以json格式为配置项的字符串，为备份恢复提供可选选项。默认为空。 | 75 76## BackupPriority<sup>12+</sup> 77 78为备份恢复提供优先级配置。 79 80**系统能力**：SystemCapability.FileManagement.StorageService.Backup 81 82| 名称 | 类型 | 必填 | 说明 | 83| -------- | ------ | ---- | ------------------------------------------------------ | 84| priority | number | 否 | 数值越大优先级越高；优先级相同的情况下，先调用的先执行。默认为0。 | 85 86## IncrementalBackupData<sup>12+</sup> 87 88一次增量备份对象。继承[IncrementalBackupTime](#incrementalbackuptime12)，[FileManifestData](#filemanifestdata12)，[BackupParams](#backupparams12)，[BackupPriority](#backuppriority12)。 89 90> **说明：** 91> 92> 记录应用最后一次的增量时间以及增量备份清单文件的文件描述符，清单文件中记录着增量时间内已备份的文件信息。可选参数包含了备份恢复的可选配置项，优先级配置项。 93 94**系统能力**：SystemCapability.FileManagement.StorageService.Backup 95 96## File 97 98一个文件对象。 99继承[FileMeta](#filemeta)和[FileData](#filedata)。 100 101> **说明：** 102> 103> file.backup.File与@ohos.file.fs中的提供的[File](js-apis-file-fs.md#file)是带有不同的涵义，前者是继承[FileMeta](#filemeta)和[FileData](#filedata)的对象而后者只有一个文件描述符的对象。请注意区分，不要混淆。 104 105**系统能力**：SystemCapability.FileManagement.StorageService.Backup 106 107## File<sup>12+</sup> 108 109一个文件对象。 110继承[FileMeta](#filemeta)和[FileData](#filedata)和[FileManifestData](#filemanifestdata12)。 111 112> **说明：** 113> 114> file.backup.File与@ohos.file.fs中的提供的[File](js-apis-file-fs.md#file)是带有不同的涵义，前者是继承[FileMeta](#filemeta)和[FileData](#filedata)的对象而后者只有一个文件描述符的对象。请注意区分，不要混淆。 115 116**系统能力**：SystemCapability.FileManagement.StorageService.Backup 117 118## GeneralCallbacks 119 120备份/恢复过程中的通用回调，备份服务将通过这些回调通知客户端其应用的备份/恢复阶段。 121 122**系统能力**：SystemCapability.FileManagement.StorageService.Backup 123 124### 属性 125 126**系统能力**：SystemCapability.FileManagement.StorageService.Backup 127 128| 名称 | 类型 | 只读 | 可选 | 说明 | 129| -------- | -------- | -------- | -------- | -------- | 130| onBackupSizeReport<sup>18+</sup> | [OnBackupSizeReport](#onbackupsizereport18) | 否 | 是 | 框架获取到的待备份的数据量大小的信息。 | 131 132### onFileReady 133 134onFileReady : AsyncCallback<File> 135 136回调函数。当服务端返向客户端发送文件，如果成功触发回调，返回对应文件的[File](#file)内容；如果触发失败，则返回err错误对象。 137 138> **说明：** 139> 140> AsyncCallback回调中返回的File所属file.backup.[File](#file)类型。返回的文件归备份服务所有，一旦文件关闭，备份服务将选择合适的时机去清理，但客户端必须关闭文件句柄。 141 142**系统能力**：SystemCapability.FileManagement.StorageService.Backup 143 144**错误码：** 145 146以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 147 148| 错误码ID | 错误信息 | 149| -------- | ----------------------- | 150| 13600001 | IPC error. | 151| 13900005 | I/O error. | 152| 13900011 | Out of memory. | 153| 13900020 | Invalid argument. | 154| 13900025 | No space left on device. | 155| 13900042 | Unknown error. | 156 157**示例：** 158 159 ```ts 160 import fs from '@ohos.file.fs'; 161 import { BusinessError } from '@ohos.base'; 162 163 onFileReady: (err: BusinessError, file: backup.File) => { 164 if (err) { 165 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 166 return; 167 } 168 console.info('onFileReady success with file: ' + file.bundleName + ' ' + file.uri); 169 fs.closeSync(file.fd); 170 } 171 ``` 172 173### onBundleBegin 174 175onBundleBegin : AsyncCallback<string, void | string> 176 177回调函数。当应用备份/恢复开始时，如果成功触发回调，返回对应的bundleName；如果触发失败，则返回err错误对象。从API version 12开始，返回err的同时，将同时返回第二个string参数bundleName。 178 179**系统能力**：SystemCapability.FileManagement.StorageService.Backup 180 181**返回值：** 182 183| 参数名 | 类型 | 必填 | 说明 | 184| ---------- | ------------- | ---- | ----------------------------------------------------------- | 185| bundleName | string | 是 | 服务返回的应用名称。 | 186| err | BusinessError | 否 | 当发生err时，为错误对象；否则为undefined data为bundle名称。 | 187 188**错误码：** 189 190以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 191 192| 错误码ID | 错误信息 | 193| -------- | ----------------------------------------------------- | 194| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verifcation faild.| 195| 13500001 | The application is not added to the backup or restore. | 196| 13500002 | Failed to start application extension Procedure. | 197| 13600001 | IPC error. | 198| 13900005 | I/O error. | 199| 13900011 | Out of memory. | 200| 13900020 | Invalid argument. | 201| 13900025 | No space left on device. | 202| 13900042 | Unknown error. | 203 204**示例：** 205 206 ```ts 207 import { BusinessError } from '@ohos.base'; 208 209 onBundleBegin: (err: BusinessError, bundleName: string) => { 210 if (err) { 211 console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code)); 212 return; 213 } 214 console.info('onBundleBegin success'); 215 } 216 ``` 217 218 ```ts 219 import { BusinessError } from '@ohos.base'; 220 221 onBundleBegin: (err: BusinessError<string>, bundleName: string) => { 222 if (err) { 223 console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data); 224 return; 225 } 226 console.info('onBundleBegin success'); 227 } 228 ``` 229 230### onBundleEnd 231 232onBundleEnd : AsyncCallback<string, void | string> 233 234回调函数。当应用备份/恢复结束后，如果成功触发回调，返回对应的bundleName；如果触发失败，则返回err错误对象。从API version 12开始，返回err的同时，将同时返回第二个string参数bundleName。 235 236**系统能力**：SystemCapability.FileManagement.StorageService.Backup 237 238**返回值：** 239 240| 参数名 | 类型 | 必填 | 说明 | 241| ---------- | ------------- | ---- | ----------------------------------------------------------- | 242| bundleName | string | 是 | 服务返回的应用名称。 | 243| err | BusinessError | 否 | 当发生err时，为错误对象，否则为undefined data为bundle名称。 | 244 245**错误码：** 246 247以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 248 249| 错误码ID | 错误信息 | 250| -------- | ------------------------------- | 251| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verifcation faild.| 252| 13500003 | Backup or restore timed out. | 253| 13500004 | Application extension death. | 254| 13600001 | IPC error. | 255| 13900005 | I/O error. | 256| 13900011 | Out of memory. | 257| 13900020 | Invalid argument. | 258| 13900025 | No space left on device. | 259| 13900042 | Unknown error. | 260 261**示例：** 262 263 ```ts 264 import { BusinessError } from '@ohos.base'; 265 266 onBundleEnd: (err: BusinessError, bundleName: string) => { 267 if (err) { 268 console.error('onBundleEnd failed with err: ' + JSON.stringify(err)); 269 return; 270 } 271 console.info('onBundleEnd success with bundleName: ' + bundleName); 272 } 273 ``` 274 275 ```ts 276 import { BusinessError } from '@ohos.base'; 277 278 onBundleEnd: (err: BusinessError<string>, bundleName: string) => { 279 if (err) { 280 console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data); 281 return; 282 } 283 console.info('onBundleEnd success'); 284 } 285 ``` 286 287### onAllBundlesEnd 288 289onAllBundlesEnd : AsyncCallback<undefined> 290 291回调函数。当所有bundle的备份/恢复过程结束成功时触发回调，如果触发失败，则返回err错误对象。 292 293**系统能力**：SystemCapability.FileManagement.StorageService.Backup 294 295**错误码：** 296 297以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 298 299| 错误码ID | 错误信息 | 300| -------- | ----------------------- | 301| 13600001 | IPC error. | 302| 13900005 | I/O error. | 303| 13900011 | Out of memory. | 304| 13900020 | Invalid argument. | 305| 13900025 | No space left on device. | 306| 13900042 | Unknown error. | 307 308**示例：** 309 310 ```ts 311 import { BusinessError } from '@ohos.base'; 312 313 onAllBundlesEnd: (err: BusinessError) => { 314 if (err) { 315 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 316 return; 317 } 318 console.info('onAllBundlesEnd success'); 319 } 320 ``` 321 322### onBackupServiceDied 323 324onBackupServiceDied : Callback<undefined> 325 326回调函数。备份服务死亡时触发回调，如果触发失败，则返回err错误对象。 327 328**系统能力**：SystemCapability.FileManagement.StorageService.Backup 329 330**示例：** 331 332 ```ts 333 onBackupServiceDied: () => { 334 console.info('onBackupServiceDied success'); 335 } 336 ``` 337 338### onResultReport<sup>12+</sup> 339 340onResultReport (bundleName: string, result: string) 341 342回调函数。当应用备份/恢复结束后，如果成功触发回调，返回应用包名及应用备份/恢复信息（备份/恢复数量或异常信息等）。 343 344**系统能力**：SystemCapability.FileManagement.StorageService.Backup 345 346**返回值：** 347 348| 参数名 | 类型 | 必填 | 说明 | 349| ---------- | ------ | ---- | ------------------------------- | 350| bundleName | string | 是 | 应用包名。 | 351| result | string | 是 | json格式返回的应用备份/恢复信息。 | 352 353**示例：** 354 355 ```ts 356 import backup from '@ohos.file.backup'; 357 358 onResultReport: (bundleName: string, result: string) => { 359 console.info('onResultReport bundleName : ' + bundleName); 360 console.info('onResultReport result : ' + result); 361 } 362 ``` 363 364### onProcess<sup>12+</sup> 365 366onProcess (bundleName: string, process: string) 367 368回调函数。应用备份/恢复过程中进度信息的回调，返回应用执行业务的进度信息和异常信息等。 369 370**系统能力**：SystemCapability.FileManagement.StorageService.Backup 371 372**返回值：** 373 374| 参数名 | 类型 | 必填 | 说明 | 375| ---------- | ------ | ---- | ------------------------------- | 376| bundleName | string | 是 | 应用包名。 | 377| process | string | 是 | json格式返回应用备份/恢复的进度信息。 | 378 379**示例：** 380 381 ```ts 382 import backup from '@ohos.file.backup'; 383 384 onProcess: (bundleName: string, process: string) => { 385 console.info('onProcess bundleName : ' + bundleName); 386 console.info('onProcess processInfo : ' + process); 387 } 388 ``` 389 390## backup.getBackupVersion<sup>18+</sup> 391 392getBackupVersion(): string; 393 394获取备份恢复版本号信息。 395 396**需要权限**：ohos.permission.BACKUP 397 398**系统能力**：SystemCapability.FileManagement.StorageService.Backup 399 400**返回值：** 401 402| 类型 | 说明 | 403| ------------------- | ----------------------- | 404| string | 返回备份恢复版本号信息。<br/>版本号格式为API版本。内部版本，例如API16，则版本号为16.0。 | 405 406**错误码：** 407 408以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 409 410| 错误码ID | 错误信息 | 411| -------- | ----------------------- | 412| 201 | Permission verification failed, usually the result returned by VerifyAccessToken. | 413| 202 | Permission verification failed, application which is not a system application uses system API. | 414 415**示例：** 416 417 ```ts 418 import { BusinessError } from '@ohos.base'; 419 import backup from '@ohos.file.backup'; 420 421 function getBackupVersion() { 422 try { 423 let result = backup.getBackupVersion(); 424 console.info('getBackupVersion success， result: ' + result); 425 } catch (error) { 426 let err: BusinessError = error as BusinessError; 427 console.error('getBackupVersion failed with err: ' + JSON.stringify(err)); 428 } 429 } 430 ``` 431 432**内容示例：** 433 434 ```json 435 { "backupVersion" : "16.0" } 436 ``` 437 438## backup.getLocalCapabilities 439 440getLocalCapabilities(callback: AsyncCallback<FileData>): void 441 442用于获取一个描述本地能力的Json文件。使用callback异步回调。 443 444**需要权限**：ohos.permission.BACKUP 445 446**系统能力**：SystemCapability.FileManagement.StorageService.Backup 447 448**参数：** 449 450| 参数名 | 类型 | 必填 | 说明 | 451| -------- | ------------------------------------------ | ---- | -------------------------------------------------- | 452| callback | AsyncCallback<[FileData](#filedata)> | 是 | 异步获取本地能力文件之后的回调。返回FileData对象。 | 453 454**错误码：** 455 456以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 457 458| 错误码ID | 错误信息 | 459| -------- | ----------------------- | 460| 13600001 | IPC error. | 461| 13900005 | I/O error. | 462| 13900011 | Out of memory. | 463| 13900025 | No space left on device. | 464| 13900042 | Unknown error. | 465 466**示例：** 467 468 ```ts 469 import fs from '@ohos.file.fs'; 470 import { BusinessError } from '@ohos.base'; 471 472 try { 473 backup.getLocalCapabilities((err: BusinessError, fileData: backup.FileData) => { 474 if (err) { 475 console.error('getLocalCapabilities failed with err: ' + JSON.stringify(err)); 476 return; 477 } 478 console.info('getLocalCapabilities success'); 479 console.info('fileData info:' + fileData.fd); 480 fs.closeSync(fileData.fd); 481 }); 482 } catch (error) { 483 let err: BusinessError = error as BusinessError; 484 console.error('getLocalCapabilities failed with err: ' + JSON.stringify(err)); 485 } 486 ``` 487 488**能力文件可以通过[@ohos.file.fs](js-apis-file-fs.md)提供的[fs.stat](js-apis-file-fs.md#fsstat-1)等相关接口获取，能力文件内容示例：** 489 490 ```json 491 { 492 "backupVersion" : "16.0", 493 "bundleInfos" :[{ 494 "allToBackup" : true, 495 "extensionName" : "BackupExtensionAbility", 496 "name" : "com.example.hiworld", 497 "needToInstall" : false, 498 "spaceOccupied" : 0, 499 "versionCode" : 1000000, 500 "versionName" : "1.0.0" 501 }], 502 "deviceType" : "default", 503 "systemFullName" : "OpenHarmony-4.0.0.0" 504 } 505 ``` 506 507## backup.getLocalCapabilities 508 509getLocalCapabilities(): Promise<FileData> 510 511用于获取一个描述本地能力的Json文件。使用Promise异步回调。 512 513**需要权限**：ohos.permission.BACKUP 514 515**系统能力**：SystemCapability.FileManagement.StorageService.Backup 516 517**返回值：** 518 519| 类型 | 说明 | 520| ------------------------------------ | ------------------------------- | 521| Promise<[FileData](#filedata)> | Promise对象。返回FileData对象。 | 522 523**错误码：** 524 525以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 526 527| 错误码ID | 错误信息 | 528| -------- | ----------------------- | 529| 13600001 | IPC error. | 530| 13900005 | I/O error. | 531| 13900011 | Out of memory. | 532| 13900025 | No space left on device. | 533| 13900042 | Unknown error. | 534 535**示例：** 536 537 ```ts 538 import fs from '@ohos.file.fs'; 539 import { BusinessError } from '@ohos.base'; 540 541 async function getLocalCapabilities() { 542 try { 543 let fileData = await backup.getLocalCapabilities(); 544 console.info('getLocalCapabilities success'); 545 console.info('fileData info:' + fileData.fd); 546 fs.closeSync(fileData.fd); 547 } catch (error) { 548 let err: BusinessError = error as BusinessError; 549 console.error('getLocalCapabilities failed with err: ' + JSON.stringify(err)); 550 } 551 } 552 ``` 553 554 **能力文件可以通过[@ohos.file.fs](js-apis-file-fs.md)提供的[fs.stat](js-apis-file-fs.md#fsstat)等相关接口获取，能力文件内容示例：** 555 556 ```json 557 { 558 "backupVersion" : "16.0", 559 "bundleInfos" :[{ 560 "allToBackup" : true, 561 "extensionName" : "BackupExtensionAbility", 562 "name" : "com.example.hiworld", 563 "needToInstall" : false, 564 "spaceOccupied" : 0, 565 "versionCode" : 1000000, 566 "versionName" : "1.0.0" 567 }], 568 "deviceType" : "default", 569 "systemFullName" : "OpenHarmony-4.0.0.0" 570 } 571 ``` 572 573## backup.getLocalCapabilities<sup>12+</sup> 574 575getLocalCapabilities(dataList:Array<IncrementalBackupTime>): Promise<FileData> 576 577用于获取一个描述本地能力的Json文件，根据dataList内传递的参数查询对应应用的本地能力数据。使用Promise异步回调。 578 579**需要权限**：ohos.permission.BACKUP 580 581**系统能力**：SystemCapability.FileManagement.StorageService.Backup 582 583**参数：** 584 585| 参数名 | 类型 | 必填 | 说明 | 586| -------- | -------------------------------------------------------------- | ---- | ---------------------------------------------- | 587| dataList | Array<[IncrementalBackupTime](#incrementalbackuptime12)> | 是 | 增量备份数据列表，用于描述增量备份的文件信息。 | 588 589**返回值：** 590 591| 类型 | 说明 | 592| ------------------------------------ | ------------------------------- | 593| Promise<[FileData](#filedata)> | Promise对象。返回FileData对象。 | 594 595**错误码：** 596 597以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 598 599| 错误码ID | 错误信息 | 600| -------- | ---------------------------------------------------------------------------------------------- | 601| 201 | Permission verification failed, usually the result returned by VerifyAccessToken. | 602| 202 | Permission verification failed, application which is not a system application uses system API. | 603| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verifcation faild.| 604| 13600001 | IPC error. | 605| 13900005 | I/O error. | 606| 13900011 | Out of memory. | 607| 13900020 | Invalid argument. | 608| 13900025 | No space left on device. | 609| 13900042 | Unknown error. | 610 611**示例：** 612 613 ```ts 614 import fs from '@ohos.file.fs'; 615 import { BusinessError } from '@ohos.base'; 616 617 async function getLocalCapabilities() { 618 try { 619 let backupApps: backup.IncrementalBackupTime[] = [{ 620 bundleName: "com.example.hiworld", 621 lastIncrementalTime: 1700107870 //调用者根据上次记录的增量备份时间 622 }]; 623 let fileData = await backup.getLocalCapabilities(backupApps); 624 console.info('getLocalCapabilities success'); 625 console.info('fileData info:' + fileData.fd); 626 fs.closeSync(fileData.fd); 627 } catch (error) { 628 let err: BusinessError = error as BusinessError; 629 console.error('getLocalCapabilities failed with err: ' + JSON.stringify(err)); 630 } 631 } 632 ``` 633 634## backup.getBackupInfo<sup>12+</sup> 635 636getBackupInfo(bundleToBackup: string): string; 637 638获取需要备份的应用信息。 639 640**需要权限**：ohos.permission.BACKUP 641 642**系统能力**：SystemCapability.FileManagement.StorageService.Backup 643 644**参数：** 645 646| 参数名 | 类型 | 必填 | 说明 | 647| --------------- | -------- | ---- | -------------------------- | 648| bundleToBackup | string | 是 | 需要备份的应用名称。 | 649 650**返回值：** 651 652| 类型 | 说明 | 653| ------------------- | ----------------------- | 654| string | 返回应用上报的信息。 | 655 656**错误码：** 657 658以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 659 660| 错误码ID | 错误信息 | 661| -------- | ----------------------- | 662| 13600001 | IPC error. | 663| 13900001 | Operation not permitted. | 664| 13900005 | I/O error. | 665| 13900011 | Out of memory. | 666| 13900020 | Invalid argument. | 667| 13900025 | No space left on device. | 668| 13900042 | Unknown error. | 669 670**示例：** 671 672 ```ts 673 import fs from '@ohos.file.fs'; 674 import { BusinessError } from '@ohos.base'; 675 import backup from '@ohos.file.backup'; 676 677 function getBackupInfo() { 678 try { 679 let backupApp = "com.example.hiworld"; 680 let result = backup.getBackupInfo(backupApp); 681 console.info('getBackupInfo success， result: ' + result); 682 } catch (error) { 683 let err: BusinessError = error as BusinessError; 684 console.error('getBackupInfo failed with err: ' + JSON.stringify(err)); 685 } 686 } 687 ``` 688 689## backup.updateTimer<sup>12+</sup> 690 691updateTimer(bundleName: string, timeout: number): void; 692 693调用时机为onBundleBegin之后，onBundleEnd之前。 694 695**需要权限**：ohos.permission.BACKUP 696 697**系统能力**：SystemCapability.FileManagement.StorageService.Backup 698 699**参数：** 700 701| 参数名 | 类型 | 必填 | 说明 | 702| --------------- | -------- | ---- | -------------------------- | 703| bundleName | string | 是 | 需要设置备份或恢复时长的应用名称。 | 704| timeout | number | 是 | 备份或恢复的限制时长，入参范围[0,14400000]，单位:ms。 | 705 706**返回值：** 707 708| 类型 | 说明 | 709| ------------------- | ----------------------- | 710| boolean | 超时时间是否设置成功。true为设置成功；false为设置失败。 | 711 712**错误码：** 713 714| 错误码ID | 错误信息 | 715| -------- | ----------------------- | 716| 201 | Permission verification failed, usually the result returned by VerifyAccessToken. | 717| 202 | Permission verification failed, application which is not a system application uses system API. | 718| 401 | The input parameter is invalid. | 719 720**示例：** 721 722 ```ts 723 import { BusinessError } from '@ohos.base'; 724 import backup from '@ohos.file.backup'; 725 726 function updateTimer() { 727 try { 728 let timeout = 30000; 729 let bundleName = "com.example.hiworld"; 730 let result = backup.updateTimer(bundleName, timeout); 731 if (result) { 732 console.info('updateTimer success'); 733 } else { 734 console.info('updateTimer fail'); 735 } 736 } catch (error) { 737 let err: BusinessError = error as BusinessError; 738 console.error('updateTimer failed with err: ' + JSON.stringify(err)); 739 } 740 } 741 ``` 742 743## backup.updateSendRate<sup>12+</sup> 744 745updateSendRate(bundleName: string, sendRate: number): boolean; 746 747调用时机为onBundleBegin之后，onBundleEnd之前。 748 749**需要权限**：ohos.permission.BACKUP 750 751**系统能力**：SystemCapability.FileManagement.StorageService.Backup 752 753**参数：** 754 755| 参数名 | 类型 | 必填 | 说明 | 756| --------------- | -------- | ---- | -------------------------- | 757| bundleName|string | 是 | 需要控制速率对应的应用名称。 758| sendRate | number | 是 | 需要应用设置的fd发送速率大小，以秒为单位，范围0~800，默认60/秒。当为0时，表示停止发送，等到设置非0值时激活发送。如果设置值超过最大值800，按照800进行发送。 | 759 760**返回值：** 761 762| 类型 | 说明 | 763| ------------------- | ----------------------- | 764| boolean | 发送速率是否设置成功。true为设置成功；false为设置失败。 | 765 766**错误码：** 767 768| 错误码ID | 错误信息 | 769| -------- | ----------------------- | 770| 201 | Permission verification failed, usually the result returned by VerifyAccessToken. | 771| 202 | Permission verification failed, application which is not a system application uses system API. | 772| 401 | The input parameter is invalid. | 773 774**示例：** 775 776 ```ts 777 import { BusinessError } from '@ohos.base'; 778 import backup from '@ohos.file.backup'; 779 780 function updateSendRate() { 781 try { 782 let bundleName = "com.example.myApp"; 783 let sendRate = 300; 784 let result = backup.updateSendRate(bundleName, sendRate); 785 if (result) { 786 console.info('updateSendRate success'); 787 } else { 788 console.info('updateSendRate fail'); 789 } 790 } catch (error) { 791 let err: BusinessError = error as BusinessError; 792 console.error('updateSendRate failed with err: ' + JSON.stringify(err)); 793 } 794 } 795 ``` 796 797## OnBackupSizeReport<sup>18+</sup> 798 799type OnBackupSizeReport = (reportInfo: string) => void; 800 801框架返回的应用待备份的数据量大小。 802 803**系统能力**：SystemCapability.FileManagement.StorageService.Backup 804 805| 参数名 | 类型 | 必填 | 说明 | 806| -------- | ------------------------------------- | ---- | -------------------- | 807| reportInfo | string | 是 | 框架获取到的应用待备份数据量大小的信息。 | 808 809**示例：** 810 811 ```ts 812 import backup from '@ohos.file.backup'; 813 814 onBackupSizeReport: (OnBackupSizeReport) => { 815 console.info('dataSizeCallback success'); 816 console.info('dataSizeCallback report : ' + OnBackupSizeReport); 817 } 818 ``` 819 820## SessionBackup 821 822备份流程对象，用来支撑应用备份的流程。在使用前，需要先创建SessionBackup实例。 823 824### constructor 825 826constructor(callbacks: GeneralCallbacks); 827 828备份流程的构造函数，用于获取SessionBackup类的实例。 829 830**需要权限**：ohos.permission.BACKUP 831 832**系统能力**：SystemCapability.FileManagement.StorageService.Backup 833 834**参数：** 835 836| 参数名 | 类型 | 必填 | 说明 | 837| -------- | ------------------------------------- | ---- | -------------------- | 838| callback | [GeneralCallbacks](#generalcallbacks) | 是 | 备份流程所需的回调。 | 839 840**示例：** 841 842 ```ts 843 import fs from '@ohos.file.fs'; 844 import { BusinessError } from '@ohos.base'; 845 846 let generalCallbacks: backup.GeneralCallbacks = { 847 onFileReady: (err: BusinessError, file: backup.File) => { 848 if (err) { 849 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 850 return; 851 } 852 console.info('onFileReady success'); 853 fs.closeSync(file.fd); 854 }, 855 onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => { 856 if (err) { 857 console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data); 858 return; 859 } 860 console.info('onBundleBegin success'); 861 }, 862 onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => { 863 if (err) { 864 console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data); 865 return; 866 } 867 console.info('onBundleEnd success'); 868 }, 869 onAllBundlesEnd: (err: BusinessError) => { 870 if (err) { 871 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 872 return; 873 } 874 console.info('onAllBundlesEnd success'); 875 }, 876 onBackupServiceDied: () => { 877 console.info('service died'); 878 }, 879 onResultReport: (bundleName: string, result: string) => { 880 console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result); 881 }, 882 onProcess: (bundleName: string, process: string) => { 883 console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process); 884 } 885 }; 886 let sessionBackup = new backup.SessionBackup(generalCallbacks); // 创建备份流程 887 ``` 888 889### getLocalCapabilities<sup>18+</sup> 890 891getLocalCapabilities(): Promise<FileData> 892 893用于在备份业务中获取一个描述本地能力的Json文件。使用Promise异步回调。 894 895**需要权限**：ohos.permission.BACKUP 896 897**系统接口**：此接口为系统接口 898 899**系统能力**：SystemCapability.FileManagement.StorageService.Backup 900 901**返回值：** 902 903| 类型 | 说明 | 904| ------------------------------------ | ------------------------------- | 905| Promise<[FileData](#filedata)> | Promise对象。返回FileData对象。 | 906 907**错误码：** 908 909以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理子系统错误码](errorcode-filemanagement.md)。 910 911| 错误码ID | 错误信息 | 912| -------- | ------------------------------------------------------------ | 913| 201 | Permission verification failed, usually the result returned by VerifyAccessToken. | 914| 202 | Permission verification failed, application which is not a system application uses system API. | 915| 13600001 | IPC error. | 916| 13900001 | Operation not permitted. | 917| 13900020 | Invalid argument. | 918| 13900042 | Internal error. | 919 920**示例：** 921 922```ts 923 import fs from '@ohos.file.fs'; 924 import { BusinessError } from '@ohos.base'; 925 926 interface test { // 用于解析能力文件 927 bundleInfos: []; 928 deviceType: string; 929 systemFullName: string; 930 } 931 932 interface BundleInfo { // 用于获取单个应用的本地能力信息 933 name: string; 934 appIndex: number; 935 versionCode: number; 936 versionName: string; 937 spaceOccupied: number; 938 allToBackup: boolean; 939 increSpaceOccupied?: number; 940 fullBackupOnly: boolean; 941 extensionName: string; 942 restoreDeps: string; 943 supportScene: string; 944 extraInfo: object; 945 } 946 947 let generalCallbacks: backup.GeneralCallbacks = { // 定义备份/恢复过程中的通用回调 948 onFileReady: (err: BusinessError, file: backup.File) => { 949 if (err) { 950 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 951 return; 952 } 953 console.info('onFileReady success'); 954 fs.closeSync(file.fd); 955 }, 956 onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => { 957 if (err) { 958 console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data); 959 return; 960 } 961 console.info('onBundleBegin success'); 962 }, 963 onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => { 964 if (err) { 965 console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data); 966 return; 967 } 968 console.info('onBundleEnd success'); 969 }, 970 onAllBundlesEnd: (err: BusinessError) => { 971 if (err) { 972 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 973 return; 974 } 975 console.info('onAllBundlesEnd success'); 976 }, 977 onBackupServiceDied: () => { 978 console.info('service died'); 979 }, 980 onResultReport: (bundleName: string, result: string) => { 981 console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result); 982 }, 983 onProcess: (bundleName: string, process: string) => { 984 console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process); 985 } 986 }; 987 let sessionBackup = new backup.SessionBackup(generalCallbacks); // 创建备份流程 988 let basePath = '/data/storage/el2/base/backup'; 989 let path = basePath + '/localCapabilities.json'; // 本地保存能力文件的路径 990 try { 991 let fileData = await sessionBackup.getLocalCapabilities(); // 获取本地能力文件 992 if (fileData) { 993 console.info('getLocalCapabilities success'); 994 console.info('fileData info:' + fileData.fd); 995 if (!fs.accessSync(basePath)) { 996 fs.mkdirSync(basePath); 997 console.info('creat success' + basePath); 998 } 999 fs.copyFileSync(fileData.fd, path); // 将获取的本地能力文件保存到本地 1000 fs.closeSync(fileData.fd); 1001 } 1002 } catch (error) { 1003 let err: BusinessError = error as BusinessError; 1004 console.error('getLocalCapabilities failed with err: ' + JSON.stringify(err)); 1005 } 1006 let data = await fs.readTextSync(path, 'utf8'); // 从本地的能力文件中获取信息 1007 try { 1008 const jsonsObj: test | null = JSON.parse(data); // 解析本地的能力文件并打印部分信息 1009 if (jsonsObj) { 1010 const infos:BundleInfo [] = jsonsObj.bundleInfos; 1011 for (let i = 0; i < infos.length; i++) { 1012 console.info('name: ' + infos[i].name); 1013 console.info('appIndex: ' + infos[i].appIndex); 1014 console.info('allToBackup: ' + infos[i].allToBackup); 1015 } 1016 const systemFullName: string = jsonsObj.systemFullName; 1017 console.info('systemFullName: ' + systemFullName); 1018 const deviceType: string = jsonsObj.deviceType; 1019 console.info('deviceType: ' + deviceType); 1020 } 1021 } catch (error) { 1022 console.error('parse failed with err: ' + JSON.stringify(error)); 1023 } 1024``` 1025 1026**能力文件可以通过[@ohos.file.fs](js-apis-file-fs.md)提供的[fs.stat](js-apis-file-fs.md#fsstat-1)等相关接口获取，能力文件内容示例：** 1027 1028 ```json 1029 { 1030 "backupVersion" : "16.0", 1031 "bundleInfos" :[{ 1032 "allToBackup" : true, 1033 "extensionName" : "BackupExtensionAbility", 1034 "name" : "com.example.hiworld", 1035 "needToInstall" : false, 1036 "spaceOccupied" : 0, 1037 "versionCode" : 1000000, 1038 "versionName" : "1.0.0" 1039 }], 1040 "deviceType" : "default", 1041 "systemFullName" : "OpenHarmony-4.0.0.0" 1042 } 1043 ``` 1044 1045### getBackupDataSize<sup>18+</sup> 1046 1047getBackupDataSize(isPreciseScan: boolean, dataList: Array\<IncrementalBackupTime\>): Promise<void> 1048 1049用于获取应用待备份数据量，在appendBundles之前调用。以异步callback方式（generalCallbacks中的onBackupSizeReport）每隔固定时间（每隔5秒返回一次，如果5秒内获取完则立即返回）返回一次扫描结果，直到datalist中所有的应用数据量全部返回。 1050 1051**需要权限**：ohos.permission.BACKUP 1052 1053**系统接口**：此接口为系统接口 1054 1055**系统能力**：SystemCapability.FileManagement.StorageService.Backup 1056 1057**参数：** 1058 1059| 参数名 | 类型 | 必填 | 说明 | 1060| ------------- | -------------------------------------------------------- | ---- | ------------------------------------------------------------ | 1061| isPreciseScan | boolean | 是 | 是否精确扫描。true为精确扫描，false为非精确扫描。非精确扫描速度快，为估算数据量；精确扫描速度慢，结果更准确。但由于在实际备份过程中待备份数据可能发生变动，精确扫描结果和实际备份数据量不保证完全匹配。 | 1062| dataList | Array<[IncrementalBackupTime](#incrementalbackuptime12)> | 是 | 备份应用列表，用于描述待获取数据量的应用和上一次备份时间（全量备份填0）。 | 1063 1064**错误码：** 1065 1066以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理子系统错误码](errorcode-filemanagement.md)。 1067 1068| 错误码ID | 错误信息 | 1069| -------- | ------------------------------------------------------------ | 1070| 201 | Permission verification failed, usually the result returned by VerifyAccessToken. | 1071| 202 | Permission verification failed, application which is not a system application uses system API. | 1072| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verifcation faild. | 1073| 13600001 | IPC error. | 1074| 13900001 | Operation not permitted. | 1075| 13900020 | Invalid argument. | 1076| 13900042 | Internal error. | 1077 1078**示例：** 1079 1080```ts 1081 import fs from '@ohos.file.fs'; 1082 import { BusinessError } from '@ohos.base'; 1083 1084 interface scanedInfos { //用于解析扫描结果 1085 scaned: []; 1086 scanning: string; 1087 } 1088 1089 interface ScanedInfo { //用于解析单个应用的扫描结果 1090 bundleName: string; 1091 dataSize: number; 1092 incDataSize: number; 1093 } 1094 1095 let generalCallbacks: backup.GeneralCallbacks = { // 定义备份/恢复过程中的通用回调 1096 onFileReady: (err: BusinessError, file: backup.File) => { 1097 if (err) { 1098 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 1099 return; 1100 } 1101 console.info('onFileReady success'); 1102 fs.closeSync(file.fd); 1103 }, 1104 onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => { 1105 if (err) { 1106 console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data); 1107 return; 1108 } 1109 console.info('onBundleBegin success'); 1110 }, 1111 onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => { 1112 if (err) { 1113 console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data); 1114 return; 1115 } 1116 console.info('onBundleEnd success'); 1117 }, 1118 onAllBundlesEnd: (err: BusinessError) => { 1119 if (err) { 1120 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 1121 return; 1122 } 1123 console.info('onAllBundlesEnd success'); 1124 }, 1125 onBackupServiceDied: () => { 1126 console.info('service died'); 1127 }, 1128 onResultReport: (bundleName: string, result: string) => { 1129 console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result); 1130 }, 1131 onProcess: (bundleName: string, process: string) => { 1132 console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process); 1133 }, 1134 onBackupSizeReport: (OnBackupSizeReport) => { // 回调函数 与getBackupDataSize配套使用，返回已获取到应用的数据量大小和正在获取数据量的应用的包名 1135 console.info('dataSizeCallback success'); 1136 const jsonObj: scanedInfos | null = JSON.parse(OnBackupSizeReport); // 解析返回的信息并打印 1137 if (jsonObj) { 1138 const infos: ScanedInfo [] = jsonObj.scaned; 1139 for (let i = 0; i < infos.length; i++) { 1140 console.info('name: ' + infos[i].bundleName); 1141 console.info('dataSize: ' + infos[i].dataSize); 1142 console.info('incDataSize: ' + infos[i].incDataSize); 1143 } 1144 const scanning: string = jsonObj.scanning; 1145 console.info('scanning: ' + scanning); 1146 } 1147 } 1148 }; 1149 1150 let sessionBackup = new backup.SessionBackup(generalCallbacks); // 创建备份流程 1151 let backupApps: backup.IncrementalBackupTime[] = [{ 1152 bundleName: "com.example.hiworld", 1153 lastIncrementalTime: 0 // 调用者根据上次记录的增量备份时间，全量时为0 1154 }]; 1155 try { 1156 sessionBackup.getBackupDataSize(false, backupApps); // 获取backupApps中指定应用的待备份的数据量大小，false表示使用非精确扫描 1157 } catch (error) { 1158 let err: BusinessError = error as BusinessError; 1159 console.error('getBackupDataSize failed with err: ' + JSON.stringify(err)); 1160 } 1161``` 1162 1163**异步返回JSON串示例：** 1164 1165```json 1166{ 1167 "scaned" :[ // 本次扫描完成的应用，已返回结果的应用在下一次回调中不会再继续返回 1168 { 1169 "name": "com.example.hiworld", // 应用名称 1170 "dataSize": 1006060, // 数据量大小 1171 "incDataSize":-1 // 增量数据量大小，全量扫描、非精确扫描时为-1，增量精确扫描时为实际增量数据量大小 1172 }, 1173 { 1174 "name": "com.example.myAPP", 1175 "dataSize": 5000027, 1176 "incDataSize": -1 1177 } 1178 ], 1179 "scanning" :"com.example.smartAPP" // 正在扫描的应用，在最后一次结果返回时，该字段为空 1180} 1181``` 1182 1183### appendBundles 1184 1185appendBundles(bundlesToBackup: string[], callback: AsyncCallback<void>): void 1186 1187添加需要备份的应用。当前整个流程中，在获取SessionBackup类的实例后只能调用一次。使用callback异步回调。 1188 1189**需要权限**：ohos.permission.BACKUP 1190 1191**系统能力**：SystemCapability.FileManagement.StorageService.Backup 1192 1193**参数：** 1194 1195| 参数名 | 类型 | 必填 | 说明 | 1196| --------------- | ------------------------- | ---- | ---------------------------- | 1197| bundlesToBackup | string[] | 是 | 需要备份的应用名称的数组。 | 1198| callback | AsyncCallback<void> | 是 | 异步添加备份应用之后的回调。 | 1199 1200**错误码：** 1201 1202以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 1203 1204| 错误码ID | 错误信息 | 1205| -------- | ----------------------- | 1206| 13600001 | IPC error | 1207| 13900001 | Operation not permitted | 1208| 13900005 | I/O error | 1209| 13900011 | Out of memory | 1210| 13900020 | Invalid argument | 1211| 13900025 | No space left on device | 1212| 13900042 | Unknown error | 1213 1214**示例：** 1215 1216 ```ts 1217 import fs from '@ohos.file.fs'; 1218 import { BusinessError } from '@ohos.base'; 1219 1220 let generalCallbacks: backup.GeneralCallbacks = { 1221 onFileReady: (err: BusinessError, file: backup.File) => { 1222 if (err) { 1223 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 1224 return; 1225 } 1226 console.info('onFileReady success'); 1227 fs.closeSync(file.fd); 1228 }, 1229 onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => { 1230 if (err) { 1231 console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data); 1232 return; 1233 } 1234 console.info('onBundleBegin success'); 1235 }, 1236 onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => { 1237 if (err) { 1238 console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data); 1239 return; 1240 } 1241 console.info('onBundleEnd success'); 1242 }, 1243 onAllBundlesEnd: (err: BusinessError) => { 1244 if (err) { 1245 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 1246 return; 1247 } 1248 console.info('onAllBundlesEnd success'); 1249 }, 1250 onBackupServiceDied: () => { 1251 console.info('service died'); 1252 }, 1253 onResultReport: (bundleName: string, result: string) => { 1254 console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result); 1255 }, 1256 onProcess: (bundleName: string, process: string) => { 1257 console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process); 1258 } 1259 }; 1260 let sessionBackup = new backup.SessionBackup(generalCallbacks); // 创建备份流程 1261 try { 1262 let backupApps: Array<string> = [ 1263 "com.example.hiworld", 1264 ]; 1265 sessionBackup.appendBundles(backupApps, (err: BusinessError) => { 1266 if (err) { 1267 console.error('appendBundles failed with err: ' + JSON.stringify(err)); 1268 return; 1269 } 1270 console.info('appendBundles success'); 1271 }); 1272 } catch (error) { 1273 let err: BusinessError = error as BusinessError; 1274 console.error('appendBundles failed with err: ' + JSON.stringify(err)); 1275 } 1276 ``` 1277 1278### appendBundles 1279 1280appendBundles(bundlesToBackup: string[], infos?: string[]): Promise<void> 1281 1282添加需要备份的应用。当前整个流程中，在获取SessionBackup类的实例后只能调用一次。使用Promise异步回调。 1283 1284从API version 12开始, 新增可选参数infos, 可携带备份时各应用所需要的扩展信息, infos和bundlesToBackup根据索引一一对应。 1285 1286**需要权限**：ohos.permission.BACKUP 1287 1288**系统能力**：SystemCapability.FileManagement.StorageService.Backup 1289 1290**参数：** 1291 1292| 参数名 | 类型 | 必填 | 说明 | 1293| --------------- | -------- | ---- | -------------------------- | 1294| bundlesToBackup | string[] | 是 | 需要备份的应用名称的数组。 | 1295| infos | string[] | 否 | 备份时各应用所需扩展信息的数组, 与bundlesToBackup根据索引一一对应。默认值为空。从API version 12开始支持。| 1296 1297**返回值：** 1298 1299| 类型 | 说明 | 1300| ------------------- | ----------------------- | 1301| Promise<void> | Promise对象。无返回值。 | 1302 1303**错误码：** 1304 1305以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 1306 1307| 错误码ID | 错误信息 | 1308| -------- | ----------------------- | 1309| 13600001 | IPC error | 1310| 13900001 | Operation not permitted | 1311| 13900005 | I/O error | 1312| 13900011 | Out of memory | 1313| 13900020 | Invalid argument | 1314| 13900025 | No space left on device | 1315| 13900042 | Unknown error | 1316 1317**示例：** 1318 1319 ```ts 1320 import fs from '@ohos.file.fs'; 1321 import { BusinessError } from '@ohos.base'; 1322 1323 let generalCallbacks: backup.GeneralCallbacks = { 1324 onFileReady: (err: BusinessError, file: backup.File) => { 1325 if (err) { 1326 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 1327 return; 1328 } 1329 console.info('onFileReady success'); 1330 fs.closeSync(file.fd); 1331 }, 1332 onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => { 1333 if (err) { 1334 console.error('onBundleBegin failed with err: ' + JSON.stringify(err)); 1335 return; 1336 } 1337 console.info('onBundleBegin success'); 1338 }, 1339 onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => { 1340 if (err) { 1341 console.error('onBundleEnd failed with err: ' + JSON.stringify(err)); 1342 return; 1343 } 1344 console.info('onBundleEnd success'); 1345 }, 1346 onAllBundlesEnd: (err: BusinessError) => { 1347 if (err) { 1348 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 1349 return; 1350 } 1351 console.info('onAllBundlesEnd success'); 1352 }, 1353 onBackupServiceDied: () => { 1354 console.info('service died'); 1355 }, 1356 onResultReport: (bundleName: string, result: string) => { 1357 console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result); 1358 }, 1359 onProcess: (bundleName: string, process: string) => { 1360 console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process); 1361 } 1362 }; 1363 let sessionBackup = new backup.SessionBackup(generalCallbacks); // 创建备份流程 1364 async function appendBundles() { 1365 try { 1366 let backupApps: Array<string> = [ 1367 "com.example.hiworld", 1368 "com.example.myApp" 1369 ]; 1370 await sessionBackup.appendBundles(backupApps); 1371 console.info('appendBundles success'); 1372 // 携带扩展参数, 其中infos,details和外层的type节点为固定节点 1373 let infos: Array<string> = [ 1374 ` 1375 { 1376 "infos": [ 1377 { 1378 "details": [ 1379 { 1380 "detail": [ 1381 { 1382 "key1": "value1", 1383 "key2": "value2" 1384 } 1385 ] 1386 } 1387 ], 1388 "type": "unicast", 1389 "bundleName": "com.example.hiworld" 1390 } 1391 ] 1392 }, 1393 { 1394 "infos": [ 1395 { 1396 "details": [ 1397 { 1398 "detail": [ 1399 { 1400 "key1": "value1", 1401 "key2": "value2" 1402 } 1403 ] 1404 } 1405 ], 1406 "type": "unicast", 1407 "bundleName": "com.example.myApp" 1408 } 1409 ] 1410 } 1411 ` 1412 ] 1413 await sessionBackup.appendBundles(backupApps, infos); 1414 console.info('appendBundles success'); 1415 } catch (error) { 1416 let err: BusinessError = error as BusinessError; 1417 console.error('appendBundles failed with err: ' + JSON.stringify(err)); 1418 } 1419 } 1420 ``` 1421 1422### release<sup>12+</sup> 1423 1424release(): Promise<void> 1425 1426备份流程结束后，应用与服务断开连接，使备份恢复服务退出。使用Promise异步回调。 1427 1428**需要权限**：ohos.permission.BACKUP 1429 1430**系统能力**：SystemCapability.FileManagement.StorageService.Backup 1431 1432**返回值：** 1433 1434| 类型 | 说明 | 1435| ------------------- | ----------------------- | 1436| Promise<void> | Promise对象。无返回值。 | 1437 1438**错误码：** 1439 1440以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 1441 1442| 错误码ID | 错误信息 | 1443| -------- | ---------------------------------------------------------------------------------------------- | 1444| 201 | Permission verification failed, usually the result returned by VerifyAccessToken. | 1445| 202 | Permission verification failed, application which is not a system application uses system API. | 1446| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verifcation faild.| 1447| 13600001 | IPC error. | 1448| 13900001 | Operation not permitted. | 1449| 13900005 | I/O error. | 1450| 13900042 | Unknown error. | 1451 1452**示例：** 1453 1454 ```ts 1455 import fs from '@ohos.file.fs'; 1456 import { BusinessError } from '@ohos.base'; 1457 1458 let generalCallbacks: backup.GeneralCallbacks = { 1459 onFileReady: (err: BusinessError, file: backup.File) => { 1460 if (err) { 1461 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 1462 return; 1463 } 1464 console.info('onFileReady success'); 1465 fs.closeSync(file.fd); 1466 }, 1467 onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => { 1468 if (err) { 1469 console.error('onBundleBegin failed with err: ' + JSON.stringify(err)); 1470 return; 1471 } 1472 console.info('onBundleBegin success'); 1473 }, 1474 onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => { 1475 if (err) { 1476 console.error('onBundleEnd failed with err: ' + JSON.stringify(err)); 1477 return; 1478 } 1479 console.info('onBundleEnd success'); 1480 }, 1481 onAllBundlesEnd: (err: BusinessError) => { 1482 if (err) { 1483 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 1484 return; 1485 } 1486 console.info('onAllBundlesEnd success'); 1487 }, 1488 onBackupServiceDied: () => { 1489 console.info('service died'); 1490 }, 1491 onResultReport: (bundleName: string, result: string) => { 1492 console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result); 1493 }, 1494 onProcess: (bundleName: string, process: string) => { 1495 console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process); 1496 } 1497 }; 1498 let sessionBackup = new backup.SessionBackup(generalCallbacks); // 创建备份流程 1499 sessionBackup.release(); // 备份业务执行完成后，释放session 1500 console.info('release success'); 1501 ``` 1502 1503### cancel<sup>18+</sup> 1504 1505cancel(bundleName: string): number; 1506 1507备份任务过程中，工具应用发现数据异常，需要取消某应用的备份时调用此接口，使此应用的备份任务终止。 1508 1509**需要权限**：ohos.permission.BACKUP 1510 1511**系统能力**：SystemCapability.FileManagement.StorageService.Backup 1512 1513**参数：** 1514 1515| 参数名 | 类型 | 必填 | 说明 | 1516| --------------- | -------- | ---- | -------------------------- | 1517| bundleName | string | 是 | 需要取消备份的应用名称。 | 1518 1519**返回值：** 1520 1521| 类型 | 说明 | 1522| ------------------- | ----------------------- | 1523| number | 返回取消状态。<br/>0：取消任务下发成功；<br/> 13500011：想要取消的任务未开始；<br/> 13500012：想要取消的任务不存在。| 1524 1525**错误码：** 1526 1527以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 1528 1529| 错误码ID | 错误信息 | 1530| -------- | ---------------------------------------------------------------------------------------------- | 1531| 201 | Permission verification failed, usually the result returned by VerifyAccessToken. | 1532| 202 | Permission verification failed, application which is not a system application uses system API. | 1533| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verifcation faild.| 1534 1535**示例：** 1536 1537 ```ts 1538 import fs from '@ohos.file.fs'; 1539 import { BusinessError } from '@ohos.base'; 1540 import backup from '@ohos.file.backup'; 1541 1542 sessionBackup?: backup.SessionBackup; 1543 1544 let generalCallbacks: backup.GeneralCallbacks = { 1545 onFileReady: (err: BusinessError, file: backup.File) => { 1546 if (err) { 1547 // 文件fd传输失败，调用取消接口，取消此应用的备份任务 1548 let result = this.sessionBackup.cancel("com.example.myapplication"); 1549 console.info('cancel result:' + result); 1550 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 1551 return; 1552 } 1553 console.info('onFileReady success'); 1554 fs.closeSync(file.fd); 1555 }, 1556 onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => { 1557 if (err) { 1558 console.error('onBundleBegin failed with err: ' + JSON.stringify(err)); 1559 return; 1560 } 1561 console.info('onBundleBegin success'); 1562 }, 1563 onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => { 1564 if (err) { 1565 console.error('onBundleEnd failed with err: ' + JSON.stringify(err)); 1566 return; 1567 } 1568 console.info('onBundleEnd success'); 1569 }, 1570 onAllBundlesEnd: (err: BusinessError) => { 1571 if (err) { 1572 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 1573 return; 1574 } 1575 console.info('onAllBundlesEnd success'); 1576 }, 1577 onBackupServiceDied: () => { 1578 console.info('service died'); 1579 }, 1580 onResultReport: (bundleName: string, result: string) => { 1581 console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result); 1582 }, 1583 onProcess: (bundleName: string, process: string) => { 1584 console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process); 1585 } 1586 }; 1587 this.sessionBackup = new backup.SessionBackup(generalCallbacks); // 创建备份流程 1588 ``` 1589 1590## SessionRestore 1591 1592恢复流程对象，用来支撑应用恢复的流程。在使用前，需要先创建SessionRestore实例。 1593 1594### constructor 1595 1596constructor(callbacks: GeneralCallbacks); 1597 1598恢复流程的构造函数，用于获取SessionRestore类的实例。 1599 1600**需要权限**：ohos.permission.BACKUP 1601 1602**系统能力**：SystemCapability.FileManagement.StorageService.Backup 1603 1604**参数：** 1605 1606| 参数名 | 类型 | 必填 | 说明 | 1607| -------- | ------------------------------------- | ---- | -------------------- | 1608| callback | [GeneralCallbacks](#generalcallbacks) | 是 | 恢复流程所需的回调。 | 1609 1610**示例：** 1611 1612 ```ts 1613 import fs from '@ohos.file.fs'; 1614 import { BusinessError } from '@ohos.base'; 1615 1616 let generalCallbacks: backup.GeneralCallbacks = { 1617 onFileReady: (err: BusinessError, file: backup.File) => { 1618 if (err) { 1619 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 1620 return; 1621 } 1622 console.info('onFileReady success'); 1623 fs.closeSync(file.fd); 1624 }, 1625 onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => { 1626 if (err) { 1627 console.error('onBundleBegin failed with err: ' + JSON.stringify(err)); 1628 return; 1629 } 1630 console.info('onBundleBegin success'); 1631 }, 1632 onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => { 1633 if (err) { 1634 console.error('onBundleEnd failed with err: ' + JSON.stringify(err)); 1635 return; 1636 } 1637 console.info('onBundleEnd success'); 1638 }, 1639 onAllBundlesEnd: (err: BusinessError) => { 1640 if (err) { 1641 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 1642 return; 1643 } 1644 console.info('onAllBundlesEnd success'); 1645 }, 1646 onBackupServiceDied: () => { 1647 console.info('service died'); 1648 }, 1649 onResultReport: (bundleName: string, result: string) => { 1650 console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result); 1651 }, 1652 onProcess: (bundleName: string, process: string) => { 1653 console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process); 1654 } 1655 }; 1656 let sessionRestore = new backup.SessionRestore(generalCallbacks); // 创建恢复流程 1657 ``` 1658 1659### getLocalCapabilities<sup>18+</sup> 1660 1661getLocalCapabilities(): Promise<FileData> 1662 1663用于在恢复业务中获取一个描述本地能力的Json文件。使用Promise异步回调。 1664 1665**需要权限**：ohos.permission.BACKUP 1666 1667**系统接口**：此接口为系统接口 1668 1669**系统能力**：SystemCapability.FileManagement.StorageService.Backup 1670 1671**返回值：** 1672 1673| 类型 | 说明 | 1674| ------------------------------------ | ------------------------------- | 1675| Promise<[FileData](#filedata)> | Promise对象。返回FileData对象。 | 1676 1677**错误码：** 1678 1679以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理子系统错误码](errorcode-filemanagement.md)。 1680 1681| 错误码ID | 错误信息 | 1682| -------- | ------------------------------------------------------------ | 1683| 201 | Permission verification failed, usually the result returned by VerifyAccessToken. | 1684| 202 | Permission verification failed, application which is not a system application uses system API. | 1685| 13600001 | IPC error. | 1686| 13900001 | Operation not permitted. | 1687| 13900020 | Invalid argument. | 1688| 13900042 | Internal error. | 1689 1690**示例：** 1691 1692```ts 1693 import fs from '@ohos.file.fs'; 1694 import { BusinessError } from '@ohos.base'; 1695 1696 interface test { // 用于解析能力文件 1697 bundleInfos: []; 1698 deviceType: string; 1699 systemFullName: string; 1700 } 1701 1702 interface BundleInfo { // 用于获取单个应用的本地能力信息 1703 name: string; 1704 appIndex: number; 1705 versionCode: number; 1706 versionName: string; 1707 spaceOccupied: number; 1708 allToBackup: boolean; 1709 increSpaceOccupied?: number; 1710 fullBackupOnly: boolean; 1711 extensionName: string; 1712 restoreDeps: string; 1713 supportScene: string; 1714 extraInfo: object; 1715 } 1716 1717 let generalCallbacks: backup.GeneralCallbacks = { // 定义备份/恢复过程中的通用回调 1718 onFileReady: (err: BusinessError, file: backup.File) => { 1719 if (err) { 1720 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 1721 return; 1722 } 1723 console.info('onFileReady success'); 1724 fs.closeSync(file.fd); 1725 }, 1726 onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => { 1727 if (err) { 1728 console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data); 1729 return; 1730 } 1731 console.info('onBundleBegin success'); 1732 }, 1733 onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => { 1734 if (err) { 1735 console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data); 1736 return; 1737 } 1738 console.info('onBundleEnd success'); 1739 }, 1740 onAllBundlesEnd: (err: BusinessError) => { 1741 if (err) { 1742 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 1743 return; 1744 } 1745 console.info('onAllBundlesEnd success'); 1746 }, 1747 onBackupServiceDied: () => { 1748 console.info('service died'); 1749 }, 1750 onResultReport: (bundleName: string, result: string) => { 1751 console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result); 1752 }, 1753 onProcess: (bundleName: string, process: string) => { 1754 console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process); 1755 } 1756 }; 1757 let sessionRestore = new backup.SessionRestore(generalCallbacks); // 创建恢复流程 1758 let basePath = '/data/storage/el2/base/backup'; 1759 let path = basePath + '/localCapabilities.json'; // 本地保存能力文件的路径 1760 try { 1761 let fileData = await sessionRestore.getLocalCapabilities(); // 获取本地能力文件 1762 if (fileData) { 1763 console.info('getLocalCapabilities success'); 1764 console.info('fileData info:' + fileData.fd); 1765 if (!fs.accessSync(basePath)) { 1766 fs.mkdirSync(basePath); 1767 console.info('creat success' + basePath); 1768 } 1769 fs.copyFileSync(fileData.fd, path); // 将获取的本地能力文件保存到本地 1770 fs.closeSync(fileData.fd); 1771 } 1772 } catch (error) { 1773 let err: BusinessError = error as BusinessError; 1774 console.error('getLocalCapabilities failed with err: ' + JSON.stringify(err)); 1775 } 1776 let data = await fs.readTextSync(path, 'utf8'); // 从本地的能力文件中获取信息 1777 try { 1778 const jsonsObj: test | null = JSON.parse(data); // 解析本地的能力文件并打印部分信息 1779 if (jsonsObj) { 1780 const infos:BundleInfo [] = jsonsObj.bundleInfos; 1781 for (let i = 0; i < infos.length; i++) { 1782 console.info('name: ' + infos[i].name); 1783 console.info('appIndex: ' + infos[i].appIndex); 1784 console.info('allToBackup: ' + infos[i].allToBackup); 1785 } 1786 const systemFullName: string = jsonsObj.systemFullName; 1787 console.info('systemFullName: ' + systemFullName); 1788 const deviceType: string = jsonsObj.deviceType; 1789 console.info('deviceType: ' + deviceType); 1790 } 1791 } catch (error) { 1792 console.error('parse failed with err: ' + JSON.stringify(error)); 1793 } 1794``` 1795 1796**能力文件可以通过[@ohos.file.fs](js-apis-file-fs.md)提供的[fs.stat](js-apis-file-fs.md#fsstat-1)等相关接口获取，能力文件内容示例：** 1797 1798 ```json 1799 { 1800 "backupVersion" : "16.0", 1801 "bundleInfos" :[{ 1802 "allToBackup" : true, 1803 "extensionName" : "BackupExtensionAbility", 1804 "name" : "com.example.hiworld", 1805 "needToInstall" : false, 1806 "spaceOccupied" : 0, 1807 "versionCode" : 1000000, 1808 "versionName" : "1.0.0" 1809 }], 1810 "deviceType" : "default", 1811 "systemFullName" : "OpenHarmony-4.0.0.0" 1812 } 1813 ``` 1814 1815### appendBundles 1816 1817appendBundles(remoteCapabilitiesFd: number, bundlesToBackup: string[], callback: AsyncCallback<void>): void 1818 1819添加需要恢复的应用。当前整个流程中，在获取SessionRestore类的实例后只能调用一次，使用callback异步回调。 1820 1821> **说明：** 1822> 1823> - 服务在恢复时需要其能力文件进行相关校验。 1824> - 因此remoteCapabilitiesFd可通过备份端服务所提供的[getLocalCapabilities](#backupgetlocalcapabilities)接口获取，可对其内容根据恢复应用的实际状况修改参数。也可通过getLocalCapabilities提供的json示例自行生成能力文件。 1825 1826**需要权限**：ohos.permission.BACKUP 1827 1828**系统能力**：SystemCapability.FileManagement.StorageService.Backup 1829 1830**参数：** 1831 1832| 参数名 | 类型 | 必填 | 说明 | 1833| -------------------- | ------------------------- | ---- | ---------------------------------- | 1834| remoteCapabilitiesFd | number | 是 | 用于恢复所需能力文件的文件描述符。 | 1835| bundlesToBackup | string[] | 是 | 需要恢复的应用名称的数组。 | 1836| callback | AsyncCallback<void> | 是 | 异步添加需要恢复的应用之后的回调。 | 1837 1838**错误码：** 1839 1840以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 1841 1842| 错误码ID | 错误信息 | 1843| -------- | ----------------------- | 1844| 13600001 | IPC error. | 1845| 13900001 | Operation not permitted. | 1846| 13900005 | I/O error. | 1847| 13900011 | Out of memory. | 1848| 13900020 | Invalid argument. | 1849| 13900025 | No space left on device. | 1850| 13900042 | Unknown error. | 1851 1852**示例：** 1853 1854 ```ts 1855 import fs from '@ohos.file.fs'; 1856 import { BusinessError } from '@ohos.base'; 1857 1858 let generalCallbacks: backup.GeneralCallbacks = { 1859 onFileReady: (err: BusinessError, file: backup.File) => { 1860 if (err) { 1861 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 1862 return; 1863 } 1864 console.info('onFileReady success'); 1865 fs.closeSync(file.fd); 1866 }, 1867 onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => { 1868 if (err) { 1869 console.error('onBundleBegin failed with err: ' + JSON.stringify(err)); 1870 return; 1871 } 1872 console.info('onBundleBegin success'); 1873 }, 1874 onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => { 1875 if (err) { 1876 console.error('onBundleEnd failed with err: ' + JSON.stringify(err)); 1877 return; 1878 } 1879 console.info('onBundleEnd success'); 1880 }, 1881 onAllBundlesEnd: (err: BusinessError) => { 1882 if (err) { 1883 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 1884 return; 1885 } 1886 console.info('onAllBundlesEnd success'); 1887 }, 1888 onBackupServiceDied: () => { 1889 console.info('service died'); 1890 }, 1891 onResultReport: (bundleName: string, result: string) => { 1892 console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result); 1893 }, 1894 onProcess: (bundleName: string, process: string) => { 1895 console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process); 1896 } 1897 }; 1898 let sessionRestore = new backup.SessionRestore(generalCallbacks); // 创建恢复流程 1899 async function appendBundles() { 1900 let fileData : backup.FileData = { 1901 fd : -1 1902 } 1903 try { 1904 fileData = await backup.getLocalCapabilities(); 1905 console.info('getLocalCapabilities success'); 1906 let restoreApps: Array<string> = [ 1907 "com.example.hiworld", 1908 ]; 1909 sessionRestore.appendBundles(fileData.fd, restoreApps, (err: BusinessError) => { 1910 if (err) { 1911 console.error('appendBundles failed with err: ' + JSON.stringify(err)); 1912 return; 1913 } 1914 console.info('appendBundles success'); 1915 }); 1916 } catch (error) { 1917 let err: BusinessError = error as BusinessError; 1918 console.error('getLocalCapabilities failed with err: ' + JSON.stringify(err)); 1919 } finally { 1920 fs.closeSync(fileData.fd); 1921 } 1922 } 1923 ``` 1924 1925### appendBundles 1926 1927appendBundles(remoteCapabilitiesFd: number, bundlesToBackup: string[], infos?: string[]): Promise<void> 1928 1929添加需要恢复的应用。从API version 12开始，新增可选参数infos，可携带应用恢复所需信息，infos和bundlesToBackup根据索引一一对应。 1930当前整个流程中，在获取SessionRestore类的实例后只能调用一次。使用Promise异步回调。 1931 1932> **说明：** 1933> 1934> - 服务在恢复时需要其能力文件进行相关校验。 1935> - 因此remoteCapabilitiesFd可通过备份端服务所提供的[getLocalCapabilities](#backupgetlocalcapabilities)接口获取， 1936 可对其内容根据恢复应用的实际状况修改参数。也可通过getLocalCapabilities提供的json示例自行生成能力文件。 1937 1938**需要权限**：ohos.permission.BACKUP 1939 1940**系统能力**：SystemCapability.FileManagement.StorageService.Backup 1941 1942**参数：** 1943 1944| 参数名 | 类型 | 必填 | 说明 | 1945| -------------------- | -------- | ---- | ---------------------------------- | 1946| remoteCapabilitiesFd | number | 是 | 用于恢复所需能力文件的文件描述符。 | 1947| bundlesToBackup | string[] | 是 | 需要恢复的应用包名称的数组。 | 1948| infos<sup>12+</sup> | string[] | 否 | 恢复时各应用所需要扩展信息的数组，与bundlesToBackup根据索引一一对应。默认值为空。从API version 12开始支持。 | 1949 1950**返回值：** 1951 1952| 类型 | 说明 | 1953| ------------------- | ----------------------- | 1954| Promise<void> | Promise对象。无返回值。 | 1955 1956**错误码：** 1957 1958以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 1959 1960| 错误码ID | 错误信息 | 1961| -------- | ----------------------- | 1962| 13600001 | IPC error. | 1963| 13900001 | Operation not permitted. | 1964| 13900005 | I/O error. | 1965| 13900011 | Out of memory. | 1966| 13900020 | Invalid argument. | 1967| 13900025 | No space left on device. | 1968| 13900042 | Unknown error. | 1969 1970**示例：** 1971 1972 ```ts 1973 import fs from '@ohos.file.fs'; 1974 import { BusinessError } from '@ohos.base'; 1975 1976 let generalCallbacks: backup.GeneralCallbacks = { 1977 onFileReady: (err: BusinessError, file: backup.File) => { 1978 if (err) { 1979 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 1980 return; 1981 } 1982 console.info('onFileReady success'); 1983 fs.closeSync(file.fd); 1984 }, 1985 onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => { 1986 if (err) { 1987 console.error('onBundleBegin failed with err: ' + JSON.stringify(err)); 1988 return; 1989 } 1990 console.info('onBundleBegin success'); 1991 }, 1992 onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => { 1993 if (err) { 1994 console.error('onBundleEnd failed with err: ' + JSON.stringify(err)); 1995 return; 1996 } 1997 console.info('onBundleEnd success'); 1998 }, 1999 onAllBundlesEnd: (err: BusinessError) => { 2000 if (err) { 2001 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 2002 return; 2003 } 2004 console.info('onAllBundlesEnd success'); 2005 }, 2006 onBackupServiceDied: () => { 2007 console.info('service died'); 2008 }, 2009 onResultReport: (bundleName: string, result: string) => { 2010 console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result); 2011 }, 2012 onProcess: (bundleName: string, process: string) => { 2013 console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process); 2014 } 2015 }; 2016 let sessionRestore = new backup.SessionRestore(generalCallbacks); // 创建恢复流程 2017 async function appendBundles() { 2018 let fileData : backup.FileData = { 2019 fd : -1 2020 } 2021 try { 2022 fileData = await backup.getLocalCapabilities(); 2023 console.info('getLocalCapabilities success'); 2024 let restoreApps: Array<string> = [ 2025 "com.example.hiworld", 2026 ]; 2027 await sessionRestore.appendBundles(fileData.fd, restoreApps); 2028 console.info('appendBundles success'); 2029 // 携带扩展参数的调用 2030 let infos: Array<string> = [ 2031 ` 2032 { 2033 "infos":[ 2034 { 2035 "details": [ 2036 { 2037 "detail": [ 2038 { 2039 "source": "com.example.hiworld", // 应用旧系统包名 2040 "target": "com.example.helloworld" // 应用新系统包名 2041 } 2042 ]， 2043 "type": "app_mapping_relation" 2044 } 2045 ], 2046 "type":"broadcast" 2047 } 2048 ] 2049 } 2050 ` 2051 ] 2052 await sessionRestore.appendBundles(fileData.fd, restoreApps, infos); 2053 console.info('appendBundles success'); 2054 } catch (error) { 2055 let err: BusinessError = error as BusinessError; 2056 console.error('getLocalCapabilities failed with err: ' + JSON.stringify(err)); 2057 } finally { 2058 fs.closeSync(fileData.fd); 2059 } 2060 } 2061 ``` 2062 2063### getFileHandle 2064 2065getFileHandle(fileMeta: FileMeta, callback: AsyncCallback<void>): void 2066 2067用于请求从服务中获取共享文件。使用callback异步回调。 2068 2069> **说明：** 2070> 2071> - 这个接口是零拷贝特性（减少不必要的内存拷贝，实现了更高效率的传输）的一部分。零拷贝方法可参考由[@ohos.file.fs](js-apis-file-fs.md)提供的[fs.copyFile](js-apis-file-fs.md#fscopyfile)等相关零拷贝接口。 2072> - 使用getFileHandle前需要获取SessionRestore类的实例，并且成功通过appendBundles添加需要待恢复的应用。 2073> - 开发者可以通过onFileReady回调来获取文件句柄，当客户端完成文件操作时，需要使用publishFile来进行发布。 2074> - 根据所需要恢复的文件个数，可以多次调用getFileHandle。 2075> - 所需恢复的文件，不支持使用相对路径(../)和软链接。 2076 2077**需要权限**：ohos.permission.BACKUP 2078 2079**系统能力**：SystemCapability.FileManagement.StorageService.Backup 2080 2081**参数：** 2082 2083| 参数名 | 类型 | 必填 | 说明 | 2084| -------- | ------------------------- | ---- | -------------------------------- | 2085| fileMeta | [FileMeta](#filemeta) | 是 | 恢复文件的元数据。 | 2086| callback | AsyncCallback<void> | 是 | 异步请求文件句柄成功之后的回调。 | 2087 2088**错误码：** 2089 2090以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 2091 2092| 错误码ID | 错误信息 | 2093| -------- | ----------------------- | 2094| 13600001 | IPC error. | 2095| 13900001 | Operation not permitted. | 2096| 13900020 | Invalid argument. | 2097| 13900042 | Unknown error. | 2098 2099**示例：** 2100 2101 ```ts 2102 import fs from '@ohos.file.fs'; 2103 import { BusinessError } from '@ohos.base'; 2104 2105 let generalCallbacks: backup.GeneralCallbacks = { 2106 onFileReady: (err: BusinessError, file: backup.File) => { 2107 if (err) { 2108 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 2109 return; 2110 } 2111 console.info('onFileReady success'); 2112 fs.closeSync(file.fd); 2113 }, 2114 onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => { 2115 if (err) { 2116 console.error('onBundleBegin failed with err: ' + JSON.stringify(err)); 2117 return; 2118 } 2119 console.info('onBundleBegin success'); 2120 }, 2121 onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => { 2122 if (err) { 2123 console.error('onBundleEnd failed with err: ' + JSON.stringify(err)); 2124 return; 2125 } 2126 console.info('onBundleEnd success'); 2127 }, 2128 onAllBundlesEnd: (err: BusinessError) => { 2129 if (err) { 2130 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 2131 return; 2132 } 2133 console.info('onAllBundlesEnd success'); 2134 }, 2135 onBackupServiceDied: () => { 2136 console.info('service died'); 2137 }, 2138 onResultReport: (bundleName: string, result: string) => { 2139 console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result); 2140 }, 2141 onProcess: (bundleName: string, process: string) => { 2142 console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process); 2143 } 2144 }; 2145 let sessionRestore = new backup.SessionRestore(generalCallbacks); // 创建恢复流程 2146 let fileMeta: backup.FileMeta = { 2147 bundleName: "com.example.hiworld", 2148 uri: "test.txt" 2149 } 2150 sessionRestore.getFileHandle(fileMeta, (err: BusinessError) => { 2151 if (err) { 2152 console.error('getFileHandle failed with err: ' + JSON.stringify(err)); 2153 } 2154 console.info('getFileHandle success'); 2155 }); 2156 ``` 2157 2158### getFileHandle 2159 2160getFileHandle(fileMeta: FileMeta): Promise<void> 2161 2162用于请求从服务中获取共享文件。使用Promise异步回调。 2163 2164> **说明：** 2165> 2166> - 这个接口是零拷贝特性（减少不必要的内存拷贝，实现了更高效率的传输）的一部分。零拷贝方法可参考由[@ohos.file.fs](js-apis-file-fs.md)提供的[fs.copyFile](js-apis-file-fs.md#fscopyfile)等相关零拷贝接口。 2167> - 使用getFileHandle前需要获取SessionRestore类的实例，并且成功通过appendBundles添加需要待恢复的应用。 2168> - 开发者可以通过onFileReady回调来获取文件句柄，当客户端完成文件操作时，需要使用publishFile来进行发布。 2169> - 根据所需要恢复的文件个数，可以多次调用getFileHandle。 2170> - 所需恢复的文件，不支持使用相对路径(../)和软链接。 2171 2172**需要权限**：ohos.permission.BACKUP 2173 2174**系统能力**：SystemCapability.FileManagement.StorageService.Backup 2175 2176**参数：** 2177 2178| 参数名 | 类型 | 必填 | 说明 | 2179| -------- | --------------------- | ---- | ------------------ | 2180| fileMeta | [FileMeta](#filemeta) | 是 | 恢复文件的元数据。 | 2181 2182**返回值：** 2183 2184| 类型 | 说明 | 2185| ------------------- | ----------------------- | 2186| Promise<void> | Promise对象。无返回值。 | 2187 2188**错误码：** 2189 2190以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 2191 2192| 错误码ID | 错误信息 | 2193| -------- | ----------------------- | 2194| 13600001 | IPC error. | 2195| 13900001 | Operation not permitted. | 2196| 13900020 | Invalid argument. | 2197| 13900042 | Unknown error. | 2198 2199**示例：** 2200 2201 ```ts 2202 import fs from '@ohos.file.fs'; 2203 import { BusinessError } from '@ohos.base'; 2204 2205 let generalCallbacks: backup.GeneralCallbacks = { 2206 onFileReady: (err: BusinessError, file: backup.File) => { 2207 if (err) { 2208 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 2209 return; 2210 } 2211 console.info('onFileReady success'); 2212 fs.closeSync(file.fd); 2213 }, 2214 onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => { 2215 if (err) { 2216 console.error('onBundleBegin failed with err: ' + JSON.stringify(err)); 2217 return; 2218 } 2219 console.info('onBundleBegin success'); 2220 }, 2221 onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => { 2222 if (err) { 2223 console.error('onBundleEnd failed with err: ' + JSON.stringify(err)); 2224 return; 2225 } 2226 console.info('onBundleEnd success'); 2227 }, 2228 onAllBundlesEnd: (err: BusinessError) => { 2229 if (err) { 2230 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 2231 return; 2232 } 2233 console.info('onAllBundlesEnd success'); 2234 }, 2235 onBackupServiceDied: () => { 2236 console.info('service died'); 2237 }, 2238 onResultReport: (bundleName: string, result: string) => { 2239 console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result); 2240 }, 2241 onProcess: (bundleName: string, process: string) => { 2242 console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process); 2243 } 2244 }; 2245 let sessionRestore = new backup.SessionRestore(generalCallbacks); // 创建恢复流程 2246 async function getFileHandle() { 2247 try { 2248 let fileMeta: backup.FileMeta = { 2249 bundleName: "com.example.hiworld", 2250 uri: "test.txt" 2251 } 2252 await sessionRestore.getFileHandle(fileMeta); 2253 console.info('getFileHandle success'); 2254 } catch (error) { 2255 let err: BusinessError = error as BusinessError; 2256 console.error('getFileHandle failed with err: ' + JSON.stringify(err)); 2257 } 2258 } 2259 ``` 2260 2261### publishFile 2262 2263publishFile(fileMeta: FileMeta, callback: AsyncCallback<void>): void 2264 2265用于将FileMeta发布到备份服务，使服务知道文件的内容已经准备完成。使用callback异步回调。 2266 2267> **说明：** 2268> 2269> - 这个接口是零拷贝特性（减少不必要的内存拷贝，实现了更高效率的传输）的一部分。零拷贝方法可参考由[@ohos.file.fs](js-apis-file-fs.md)提供的[fs.copyFile](js-apis-file-fs.md#fscopyfile)等相关零拷贝接口。 2270> - 服务端通过onFileReady返回文件句柄后，客户端可通过零拷贝操作将其对应的文件内容拷贝到服务端提供的文件句柄中。 2271> - 这个接口仅在调用方完成所有待恢复数据的写入操作后才能调用，且调用方需要确保待写入恢复数据的一致性与完整性。 2272 2273**需要权限**：ohos.permission.BACKUP 2274 2275**系统能力**：SystemCapability.FileManagement.StorageService.Backup 2276 2277**参数：** 2278 2279| 参数名 | 类型 | 必填 | 说明 | 2280| -------- | ------------------------- | ---- | ---------------------------- | 2281| fileMeta | [FileMeta](#filemeta) | 是 | 恢复文件元数据。 | 2282| callback | AsyncCallback<void> | 是 | 异步发布文件成功之后的回调。 | 2283 2284**错误码：** 2285 2286以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 2287 2288| 错误码ID | 错误信息 | 2289| -------- | ----------------------- | 2290| 13600001 | IPC error. | 2291| 13900001 | Operation not permitted. | 2292| 13900020 | Invalid argument. | 2293| 13900042 | Unknown error. | 2294 2295**示例：** 2296 2297 ```ts 2298 import fs from '@ohos.file.fs'; 2299 import { BusinessError } from '@ohos.base'; 2300 2301 let g_session: backup.SessionRestore; 2302 let initMap = new Map<string, number>(); 2303 let testFileNum = 123; // 123: 恢复所需文件个数示例 2304 let testBundleName = 'com.example.myapplication'; // 测试包名 2305 initMap.set(testBundleName, testFileNum); 2306 let countMap = new Map<string, number>(); 2307 countMap.set(testBundleName, 0); // 实际写入文件个数初始化 2308 function createSessionRestore() { 2309 let generalCallbacks: backup.GeneralCallbacks = { 2310 onFileReady: (err: BusinessError, file: backup.File) => { 2311 if (err) { 2312 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 2313 return; 2314 } 2315 console.info('onFileReady success'); 2316 fs.closeSync(file.fd); 2317 countMap[file.bundleName]++; // 实际写入文件个数更新 2318 // 恢复所需文件个数与实际写入文件个数相等时调用，保证数据的一致性和完整性 2319 if (countMap[file.bundleName] == initMap[file.bundleName]) { // 每个包的所有文件收到后触发publishFile 2320 let fileMeta: backup.FileMeta = { 2321 bundleName: file.bundleName, 2322 uri: '' 2323 } 2324 g_session.publishFile(fileMeta, (err: BusinessError) => { 2325 if (err) { 2326 console.error('publishFile failed with err: ' + JSON.stringify(err)); 2327 return; 2328 } 2329 console.info('publishFile success'); 2330 }); 2331 } 2332 }, 2333 onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => { 2334 if (err) { 2335 console.error('onBundleBegin failed with err: ' + JSON.stringify(err)); 2336 return; 2337 } 2338 console.info('onBundleBegin success'); 2339 }, 2340 onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => { 2341 if (err) { 2342 console.error('onBundleEnd failed with err: ' + JSON.stringify(err)); 2343 return; 2344 } 2345 console.info('onBundleEnd success'); 2346 }, 2347 onAllBundlesEnd: (err: BusinessError) => { 2348 if (err) { 2349 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 2350 return; 2351 } 2352 console.info('onAllBundlesEnd success'); 2353 }, 2354 onBackupServiceDied: () => { 2355 console.info('service died'); 2356 }, 2357 onResultReport: (bundleName: string, result: string) => { 2358 console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result); 2359 }, 2360 onProcess: (bundleName: string, process: string) => { 2361 console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process); 2362 } 2363 }; 2364 let sessionRestore = new backup.SessionRestore(generalCallbacks); // 创建恢复流程 2365 return sessionRestore; 2366 } 2367 g_session = createSessionRestore(); 2368 ``` 2369 2370### publishFile 2371 2372publishFile(fileMeta: FileMeta): Promise<void> 2373 2374用于将FileMeta发布到备份服务，使服务知道文件的内容已经准备完成。使用Promise异步回调。 2375 2376> **说明：** 2377> 2378> - 这个接口是零拷贝特性（减少不必要的内存拷贝，实现了更高效率的传输）的一部分。零拷贝方法可参考由[@ohos.file.fs](js-apis-file-fs.md)提供的[fs.copyFile](js-apis-file-fs.md#fscopyfile)等相关零拷贝接口。 2379> - 服务端通过onFileReady返回文件句柄后，客户端可通过零拷贝操作将其对应的文件内容拷贝到服务端提供的文件句柄中。 2380> - 这个接口仅在调用方完成所有待恢复数据的写入操作后才能调用，且调用方需要确保待写入恢复数据的一致性与完整性。 2381 2382**需要权限**：ohos.permission.BACKUP 2383 2384**系统能力**：SystemCapability.FileManagement.StorageService.Backup 2385 2386**参数：** 2387 2388| 参数名 | 类型 | 必填 | 说明 | 2389| -------- | --------------------- | ---- | ---------------- | 2390| fileMeta | [FileMeta](#filemeta) | 是 | 恢复文件元数据。 | 2391 2392**返回值：** 2393 2394| 类型 | 说明 | 2395| ------------------- | ----------------------- | 2396| Promise<void> | Promise对象。无返回值。 | 2397 2398**错误码：** 2399 2400以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 2401 2402| 错误码ID | 错误信息 | 2403| -------- | ----------------------- | 2404| 13600001 | IPC error. | 2405| 13900001 | Operation not permitted. | 2406| 13900020 | Invalid argument. | 2407| 13900042 | Unknown error. | 2408 2409**示例：** 2410 2411 ```ts 2412 import fs from '@ohos.file.fs'; 2413 import { BusinessError } from '@ohos.base'; 2414 2415 let g_session: backup.SessionRestore; 2416 let initMap = new Map<string, number>(); 2417 let testFileNum = 123; // 123: 恢复所需文件个数示例 2418 let testBundleName = 'com.example.myapplication'; // 测试包名 2419 initMap.set(testBundleName, testFileNum); 2420 let countMap = new Map<string, number>(); 2421 countMap.set(testBundleName, 0); // 实际写入文件个数初始化 2422 async function publishFile(file: backup.FileMeta) { 2423 let fileMeta: backup.FileMeta = { 2424 bundleName: file.bundleName, 2425 uri: '' 2426 } 2427 await g_session.publishFile(fileMeta); 2428 } 2429 function createSessionRestore() { 2430 let generalCallbacks: backup.GeneralCallbacks = { 2431 onFileReady: (err: BusinessError, file: backup.File) => { 2432 if (err) { 2433 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 2434 return; 2435 } 2436 console.info('onFileReady success'); 2437 fs.closeSync(file.fd); 2438 countMap[file.bundleName]++; // 实际写入文件个数更新 2439 // 恢复所需文件个数与实际写入文件个数相等时调用，保证数据的一致性和完整性 2440 if (countMap[file.bundleName] == initMap[file.bundleName]) { // 每个包的所有文件收到后触发publishFile 2441 publishFile(file); 2442 } 2443 console.info('publishFile success'); 2444 }, 2445 onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => { 2446 if (err) { 2447 console.error('onBundleBegin failed with err: ' + JSON.stringify(err)); 2448 return; 2449 } 2450 console.info('onBundleBegin success'); 2451 }, 2452 onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => { 2453 if (err) { 2454 console.error('onBundleEnd failed with err: ' + JSON.stringify(err)); 2455 return; 2456 } 2457 console.info('onBundleEnd success'); 2458 }, 2459 onAllBundlesEnd: (err: BusinessError) => { 2460 if (err) { 2461 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 2462 return; 2463 } 2464 console.info('onAllBundlesEnd success'); 2465 }, 2466 onBackupServiceDied: () => { 2467 console.info('service died'); 2468 }, 2469 onResultReport: (bundleName: string, result: string) => { 2470 console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result); 2471 }, 2472 onProcess: (bundleName: string, process: string) => { 2473 console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process); 2474 } 2475 }; 2476 let sessionRestore = new backup.SessionRestore(generalCallbacks); // 创建恢复流程 2477 return sessionRestore; 2478 } 2479 g_session = createSessionRestore(); 2480 ``` 2481 2482### release<sup>12+</sup> 2483 2484release(): Promise<void> 2485 2486恢复流程结束后，应用与服务断开连接，使备份恢复服务退出。使用Promise异步回调。 2487 2488**需要权限**：ohos.permission.BACKUP 2489 2490**系统能力**：SystemCapability.FileManagement.StorageService.Backup 2491 2492**返回值：** 2493 2494| 类型 | 说明 | 2495| ------------------- | ----------------------- | 2496| Promise<void> | Promise对象。无返回值。 | 2497 2498**错误码：** 2499 2500以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 2501 2502| 错误码ID | 错误信息 | 2503| -------- | ---------------------------------------------------------------------------------------------- | 2504| 201 | Permission verification failed, usually the result returned by VerifyAccessToken. | 2505| 202 | Permission verification failed, application which is not a system application uses system API. | 2506| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verifcation faild.| 2507| 13600001 | IPC error. | 2508| 13900001 | Operation not permitted. | 2509| 13900005 | I/O error. | 2510| 13900042 | Unknown error. | 2511 2512**示例：** 2513 2514 ```ts 2515 import fs from '@ohos.file.fs'; 2516 import { BusinessError } from '@ohos.base'; 2517 2518 let g_session: backup.SessionRestore; 2519 let initMap = new Map<string, number>(); 2520 let testFileNum = 123; // 123: 恢复所需文件个数示例 2521 let testBundleName = 'com.example.myapplication'; // 测试包名 2522 initMap.set(testBundleName, testFileNum); 2523 let countMap = new Map<string, number>(); 2524 countMap.set(testBundleName, 0); // 实际写入文件个数初始化 2525 function createSessionRestore() { 2526 let generalCallbacks: backup.GeneralCallbacks = { 2527 onFileReady: (err: BusinessError, file: backup.File) => { 2528 if (err) { 2529 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 2530 return; 2531 } 2532 console.info('onFileReady success'); 2533 fs.closeSync(file.fd); 2534 countMap[file.bundleName]++; // 实际写入文件个数更新 2535 // 恢复所需文件个数与实际写入文件个数相等时调用，保证数据的一致性和完整性 2536 if (countMap[file.bundleName] == initMap[file.bundleName]) { // 每个包的所有文件收到后触发publishFile 2537 let fileMeta: backup.FileMeta = { 2538 bundleName: file.bundleName, 2539 uri: '' 2540 } 2541 g_session.publishFile(fileMeta, (err: BusinessError) => { 2542 if (err) { 2543 console.error('publishFile failed with err: ' + JSON.stringify(err)); 2544 return; 2545 } 2546 console.info('publishFile success'); 2547 }); 2548 } 2549 }, 2550 onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => { 2551 if (err) { 2552 console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data); 2553 return; 2554 } 2555 console.info('onBundleBegin success'); 2556 }, 2557 onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => { 2558 if (err) { 2559 console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data); 2560 return; 2561 } 2562 console.info('onBundleEnd success'); 2563 }, 2564 onAllBundlesEnd: (err: BusinessError) => { 2565 if (err) { 2566 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 2567 return; 2568 } 2569 console.info('onAllBundlesEnd success'); 2570 }, 2571 onBackupServiceDied: () => { 2572 console.info('service died'); 2573 }, 2574 onResultReport: (bundleName: string, result: string) => { 2575 console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result); 2576 }, 2577 onProcess: (bundleName: string, process: string) => { 2578 console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process); 2579 } 2580 }; 2581 let sessionRestore = new backup.SessionRestore(generalCallbacks); // 创建恢复流程 2582 return sessionRestore; 2583 } 2584 g_session = createSessionRestore(); 2585 g_session.release(); 2586 console.info('release success'); 2587 ``` 2588 2589### cancel<sup>18+</sup> 2590 2591cancel(bundleName: string): number; 2592 2593恢复任务过程中，工具应用发现数据异常，需要取消某应用的恢复时调用此接口，使此应用的恢复任务终止。 2594 2595**需要权限**：ohos.permission.BACKUP 2596 2597**系统能力**：SystemCapability.FileManagement.StorageService.Backup 2598 2599**参数：** 2600 2601| 参数名 | 类型 | 必填 | 说明 | 2602| --------------- | -------- | ---- | -------------------------- | 2603| bundleName | string | 是 | 需要取消备份的应用名称。 | 2604 2605**返回值：** 2606 2607| 类型 | 说明 | 2608| ------------------- | ----------------------- | 2609| number | 返回取消状态。<br/>0：取消任务下发成功；<br/> 13500011：想要取消的任务未开始；<br/> 13500012：想要取消的任务不存在。| 2610 2611**错误码：** 2612 2613以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 2614 2615| 错误码ID | 错误信息 | 2616| -------- | ---------------------------------------------------------------------------------------------- | 2617| 201 | Permission verification failed, usually the result returned by VerifyAccessToken. | 2618| 202 | Permission verification failed, application which is not a system application uses system API. | 2619| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verifcation faild.| 2620 2621**示例：** 2622 2623 ```ts 2624 import fs from '@ohos.file.fs'; 2625 import { BusinessError } from '@ohos.base'; 2626 import backup from '@ohos.file.backup'; 2627 2628 sessionRestore?: backup.SessionRestore; 2629 2630 let generalCallbacks: backup.GeneralCallbacks = { 2631 onFileReady: (err: BusinessError, file: backup.File) => { 2632 if (err) { 2633 // 文件fd传输失败，调用取消接口，取消此应用的恢复任务 2634 let result = this.sessionRestore.cancel("com.example.myapplication"); 2635 console.info('cancel result:' + result); 2636 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 2637 return; 2638 } 2639 console.info('onFileReady success'); 2640 fs.closeSync(file.fd); 2641 }, 2642 onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => { 2643 if (err) { 2644 console.error('onBundleBegin failed with err: ' + JSON.stringify(err)); 2645 return; 2646 } 2647 console.info('onBundleBegin success'); 2648 }, 2649 onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => { 2650 if (err) { 2651 console.error('onBundleEnd failed with err: ' + JSON.stringify(err)); 2652 return; 2653 } 2654 console.info('onBundleEnd success'); 2655 }, 2656 onAllBundlesEnd: (err: BusinessError) => { 2657 if (err) { 2658 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 2659 return; 2660 } 2661 console.info('onAllBundlesEnd success'); 2662 }, 2663 onBackupServiceDied: () => { 2664 console.info('service died'); 2665 }, 2666 onResultReport: (bundleName: string, result: string) => { 2667 console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result); 2668 }, 2669 onProcess: (bundleName: string, process: string) => { 2670 console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process); 2671 } 2672 }; 2673 this.sessionRestore = new backup.SessionRestore(generalCallbacks); // 创建恢复流程 2674 ``` 2675 2676## IncrementalBackupSession<sup>12+</sup> 2677 2678增量备份流程对象，用来支撑应用增量备份的流程。在使用前，需要先创建IncrementalBackupSession实例。 2679 2680### constructor<sup>12+</sup> 2681 2682constructor(callbacks: GeneralCallbacks); 2683 2684增量备份流程的构造函数，用于获取IncrementalBackupSession类的实例。 2685 2686**需要权限**：ohos.permission.BACKUP 2687 2688**系统能力**：SystemCapability.FileManagement.StorageService.Backup 2689 2690**参数：** 2691 2692| 参数名 | 类型 | 必填 | 说明 | 2693| -------- | ------------------------------------- | ---- | ------------------------ | 2694| callback | [GeneralCallbacks](#generalcallbacks) | 是 | 增量备份流程所需的回调。 | 2695 2696**错误码：** 2697 2698以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 2699 2700| 错误码ID | 错误信息 | 2701| -------- | ---------------------------------------------------------------------------------------------- | 2702| 201 | Permission verification failed, usually the result returned by VerifyAccessToken. | 2703| 202 | Permission verification failed, application which is not a system application uses system API. | 2704| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verifcation faild.| 2705 2706**示例：** 2707 2708 ```ts 2709 import fs from '@ohos.file.fs'; 2710 import { BusinessError } from '@ohos.base'; 2711 2712 let generalCallbacks: backup.GeneralCallbacks = { 2713 onFileReady: (err: BusinessError, file: backup.File) => { 2714 if (err) { 2715 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 2716 return; 2717 } 2718 console.info('onFileReady success'); 2719 fs.closeSync(file.fd); 2720 }, 2721 onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => { 2722 if (err) { 2723 console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data); 2724 return; 2725 } 2726 console.info('onBundleBegin success'); 2727 }, 2728 onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => { 2729 if (err) { 2730 console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data); 2731 return; 2732 } 2733 console.info('onBundleEnd success'); 2734 }, 2735 onAllBundlesEnd: (err: BusinessError) => { 2736 if (err) { 2737 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 2738 return; 2739 } 2740 console.info('onAllBundlesEnd success'); 2741 }, 2742 onBackupServiceDied: () => { 2743 console.info('service died'); 2744 }, 2745 onResultReport: (bundleName: string, result: string) => { 2746 console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result); 2747 }, 2748 onProcess: (bundleName: string, process: string) => { 2749 console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process); 2750 } 2751 }; 2752 let incrementalBackupSession = new backup.IncrementalBackupSession(generalCallbacks); // 创建增量备份流程 2753 ``` 2754 2755### getLocalCapabilities<sup>18+</sup> 2756 2757getLocalCapabilities(): Promise<FileData> 2758 2759用于在增量备份业务中获取一个描述本地能力的Json文件。使用Promise异步回调。 2760 2761**需要权限**：ohos.permission.BACKUP 2762 2763**系统接口**：此接口为系统接口 2764 2765**系统能力**：SystemCapability.FileManagement.StorageService.Backup 2766 2767**返回值：** 2768 2769| 类型 | 说明 | 2770| ------------------------------------ | ------------------------------- | 2771| Promise<[FileData](#filedata)> | Promise对象。返回FileData对象。 | 2772 2773**错误码：** 2774 2775以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理子系统错误码](errorcode-filemanagement.md)。 2776 2777| 错误码ID | 错误信息 | 2778| -------- | ------------------------------------------------------------ | 2779| 201 | Permission verification failed, usually the result returned by VerifyAccessToken. | 2780| 202 | Permission verification failed, application which is not a system application uses system API. | 2781| 13600001 | IPC error. | 2782| 13900001 | Operation not permitted. | 2783| 13900020 | Invalid argument. | 2784| 13900042 | Internal error. | 2785 2786**示例：** 2787 2788```ts 2789 import fs from '@ohos.file.fs'; 2790 import { BusinessError } from '@ohos.base'; 2791 2792 interface test { // 用于解析能力文件 2793 bundleInfos: []; 2794 deviceType: string; 2795 systemFullName: string; 2796 } 2797 2798 interface BundleInfo { // 用于获取单个应用的本地能力信息 2799 name: string; 2800 appIndex: number; 2801 versionCode: number; 2802 versionName: string; 2803 spaceOccupied: number; 2804 allToBackup: boolean; 2805 increSpaceOccupied?: number; 2806 fullBackupOnly: boolean; 2807 extensionName: string; 2808 restoreDeps: string; 2809 supportScene: string; 2810 extraInfo: object; 2811 } 2812 2813 let generalCallbacks: backup.GeneralCallbacks = { // 定义备份/恢复过程中的通用回调 2814 onFileReady: (err: BusinessError, file: backup.File) => { 2815 if (err) { 2816 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 2817 return; 2818 } 2819 console.info('onFileReady success'); 2820 fs.closeSync(file.fd); 2821 }, 2822 onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => { 2823 if (err) { 2824 console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data); 2825 return; 2826 } 2827 console.info('onBundleBegin success'); 2828 }, 2829 onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => { 2830 if (err) { 2831 console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data); 2832 return; 2833 } 2834 console.info('onBundleEnd success'); 2835 }, 2836 onAllBundlesEnd: (err: BusinessError) => { 2837 if (err) { 2838 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 2839 return; 2840 } 2841 console.info('onAllBundlesEnd success'); 2842 }, 2843 onBackupServiceDied: () => { 2844 console.info('service died'); 2845 }, 2846 onResultReport: (bundleName: string, result: string) => { 2847 console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result); 2848 }, 2849 onProcess: (bundleName: string, process: string) => { 2850 console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process); 2851 } 2852 }; 2853 let incrementalBackupSession = new backup.IncrementalBackupSession(generalCallbacks); // 创建增量备份流程 2854 let basePath = '/data/storage/el2/base/backup'; 2855 let path = basePath + '/localCapabilities.json'; // 本地保存能力文件的路径 2856 try { 2857 let fileData = await incrementalBackupSession.getLocalCapabilities(); // 获取本地能力文件 2858 if (fileData) { 2859 console.info('getLocalCapabilities success'); 2860 console.info('fileData info:' + fileData.fd); 2861 if (!fs.accessSync(basePath)) { 2862 fs.mkdirSync(basePath); 2863 console.info('creat success' + basePath); 2864 } 2865 fs.copyFileSync(fileData.fd, path); // 将获取的本地能力文件保存到本地 2866 fs.closeSync(fileData.fd); 2867 } 2868 } catch (error) { 2869 let err: BusinessError = error as BusinessError; 2870 console.error('getLocalCapabilities failed with err: ' + JSON.stringify(err)); 2871 } 2872 let data = await fs.readTextSync(path, 'utf8'); // 从本地的能力文件中获取信息 2873 try { 2874 const jsonsObj: test | null = JSON.parse(data); // 解析本地的能力文件并打印部分信息 2875 if (jsonsObj) { 2876 const infos:BundleInfo [] = jsonsObj.bundleInfos; 2877 for (let i = 0; i < infos.length; i++) { 2878 console.info('name: ' + infos[i].name); 2879 console.info('appIndex: ' + infos[i].appIndex); 2880 console.info('allToBackup: ' + infos[i].allToBackup); 2881 } 2882 const systemFullName: string = jsonsObj.systemFullName; 2883 console.info('systemFullName: ' + systemFullName); 2884 const deviceType: string = jsonsObj.deviceType; 2885 console.info('deviceType: ' + deviceType); 2886 } 2887 } catch (error) { 2888 console.error('parse failed with err: ' + JSON.stringify(error)); 2889 } 2890``` 2891 2892**能力文件可以通过[@ohos.file.fs](js-apis-file-fs.md)提供的[fs.stat](js-apis-file-fs.md#fsstat-1)等相关接口获取，能力文件内容示例：** 2893 2894 ```json 2895 { 2896 "backupVersion" : "16.0", 2897 "bundleInfos" :[{ 2898 "allToBackup" : true, 2899 "extensionName" : "BackupExtensionAbility", 2900 "name" : "com.example.hiworld", 2901 "needToInstall" : false, 2902 "spaceOccupied" : 0, 2903 "versionCode" : 1000000, 2904 "versionName" : "1.0.0" 2905 }], 2906 "deviceType" : "default", 2907 "systemFullName" : "OpenHarmony-4.0.0.0" 2908 } 2909 ``` 2910 2911### getBackupDataSize<sup>18+</sup> 2912 2913getBackupDataSize(isPreciseScan: boolean, dataList: Array\<IncrementalBackupTime\>): Promise<void> 2914 2915用于获取应用待备份数据量，在appendBundles之前调用。以异步callback方式（generalCallbacks中的onBackupSizeReport）每隔固定时间（每隔5秒返回一次，如果5秒内获取完则立即返回）返回一次扫描结果，直到datalist中所有的应用数据量全部返回。 2916 2917**需要权限**：ohos.permission.BACKUP 2918 2919**系统接口**：此接口为系统接口 2920 2921**系统能力**：SystemCapability.FileManagement.StorageService.Backup 2922 2923**参数：** 2924 2925| 参数名 | 类型 | 必填 | 说明 | 2926| ------------- | -------------------------------------------------------- | ---- | ------------------------------------------------------------ | 2927| isPreciseScan | boolean | 是 | 是否精确扫描。非精确扫描速度快，为估算数据量；精确扫描速度慢，结果更准确。但由于在实际备份过程中待备份数据可能发生变动，精确扫描结果和实际备份数据量不保证完全匹配。 | 2928| dataList | Array<[IncrementalBackupTime](#incrementalbackuptime12)> | 是 | 备份应用列表，用于描述待获取数据量的应用和上一次备份时间（全量备份填0）。 | 2929 2930**错误码：** 2931 2932以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理子系统错误码](errorcode-filemanagement.md)。 2933 2934| 错误码ID | 错误信息 | 2935| -------- | ------------------------------------------------------------ | 2936| 201 | Permission verification failed, usually the result returned by VerifyAccessToken. | 2937| 202 | Permission verification failed, application which is not a system application uses system API. | 2938| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verifcation faild. | 2939| 13600001 | IPC error. | 2940| 13900001 | Operation not permitted. | 2941| 13900020 | Invalid argument. | 2942| 13900042 | Internal error. | 2943 2944**示例：** 2945 2946```ts 2947 import fs from '@ohos.file.fs'; 2948 import { BusinessError } from '@ohos.base'; 2949 2950 interface scanedInfos { // 用于解析扫描结果 2951 scaned: []; 2952 scanning: string; 2953 } 2954 2955 interface ScanedInfo { // 用于解析单个应用的扫描结果 2956 bundleName: string; 2957 dataSize: number; 2958 incDataSize: number; 2959 } 2960 2961 let generalCallbacks: backup.GeneralCallbacks = { 2962 onFileReady: (err: BusinessError, file: backup.File) => { // 定义备份/恢复过程中的通用回调 2963 if (err) { 2964 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 2965 return; 2966 } 2967 console.info('onFileReady success'); 2968 fs.closeSync(file.fd); 2969 }, 2970 onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => { 2971 if (err) { 2972 console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data); 2973 return; 2974 } 2975 console.info('onBundleBegin success'); 2976 }, 2977 onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => { 2978 if (err) { 2979 console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data); 2980 return; 2981 } 2982 console.info('onBundleEnd success'); 2983 }, 2984 onAllBundlesEnd: (err: BusinessError) => { 2985 if (err) { 2986 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 2987 return; 2988 } 2989 console.info('onAllBundlesEnd success'); 2990 }, 2991 onBackupServiceDied: () => { 2992 console.info('service died'); 2993 }, 2994 onResultReport: (bundleName: string, result: string) => { 2995 console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result); 2996 }, 2997 onProcess: (bundleName: string, process: string) => { 2998 console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process); 2999 }, 3000 onBackupSizeReport: (OnBackupSizeReport) => { // 回调函数 与getBackupDataSize配套使用，返回已获取到应用的数据量大小和正在获取数据量的应用的包名 3001 console.info('dataSizeCallback success'); 3002 const jsonObj: scanedInfos | null = JSON.parse(OnBackupSizeReport); // 解析返回的信息并打印 3003 if (jsonObj) { 3004 const infos: ScanedInfo [] = jsonObj.scaned; 3005 for (let i = 0; i < infos.length; i++) { 3006 console.info('name: ' + infos[i].bundleName); 3007 console.info('dataSize: ' + infos[i].dataSize); 3008 console.info('incDataSize: ' + infos[i].incDataSize); 3009 } 3010 const scanning: string = jsonObj.scanning; 3011 console.info('scanning: ' + scanning); 3012 } 3013 } 3014 }; 3015 3016 let incrementalBackupSession = new backup.incrementalBackupSession(generalCallbacks); // 创建增量备份流程 3017 3018 let backupApps: backup.IncrementalBackupTime[] = [{ 3019 bundleName: "com.example.hiworld", 3020 lastIncrementalTime: 1700107870 // 调用者根据上次记录的增量备份时间 3021 }]; 3022 try { 3023 incrementalBackupSession.getBackupDataSize(true, backupApps); // 获取backupApps中指定应用的待备份的数据量大小，true表示使用精确扫描 3024 } catch (error) { 3025 let err: BusinessError = error as BusinessError; 3026 console.error('getBackupDataSize failed with err: ' + JSON.stringify(err)); 3027 } 3028``` 3029 3030**异步返回JSON串示例：** 3031 3032```json 3033{ 3034 "scaned" :[ // 本次扫描完成的应用，已返回结果的应用在下一次回调中不会再继续返回 3035 { 3036 "name": "com.example.hiworld", // 应用名称 3037 "dataSize": 1006060, // 数据量大小 3038 "incDataSize": 50800 // 增量数据量大小 3039 }, 3040 { 3041 "name": "com.example.myAPP", 3042 "dataSize": 5000027, 3043 "incDataSize": 232344 3044 } 3045 ], 3046 "scanning" :"com.example.smartAPP" // 正在扫描的应用，在最后一次结果返回时，该字段为空 3047} 3048``` 3049 3050### appendBundles<sup>12+</sup> 3051 3052appendBundles(bundlesToBackup: Array<IncrementalBackupData>): Promise<void> 3053 3054添加需要增量备份的应用。当前整个流程中，触发Release接口之前都可以进行appendBundles的调用。使用Promise异步回调。 3055 3056**需要权限**：ohos.permission.BACKUP 3057 3058**系统能力**：SystemCapability.FileManagement.StorageService.Backup 3059 3060**参数：** 3061 3062| 参数名 | 类型 | 必填 | 说明 | 3063| --------------- | -------------------------------------------------------------- | ---- | -------------------------- | 3064| bundlesToBackup | Array<[IncrementalBackupData](#incrementalbackupdata12)> | 是 | 需要增量备份的应用的数组。 | 3065 3066**返回值：** 3067 3068| 类型 | 说明 | 3069| ------------------- | ----------------------- | 3070| Promise<void> | Promise对象。无返回值。 | 3071 3072**错误码：** 3073 3074以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 3075 3076| 错误码ID | 错误信息 | 3077| -------- | ---------------------------------------------------------------------------------------------- | 3078| 201 | Permission verification failed, usually the result returned by VerifyAccessToken. | 3079| 202 | Permission verification failed, application which is not a system application uses system API. | 3080| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verifcation faild.| 3081| 13600001 | IPC error. | 3082| 13900001 | Operation not permitted. | 3083| 13900005 | I/O error. | 3084| 13900011 | Out of memory. | 3085| 13900020 | Invalid argument. | 3086| 13900025 | No space left on device. | 3087| 13900042 | Unknown error. | 3088 3089**示例：** 3090 3091 ```ts 3092 import fs from '@ohos.file.fs'; 3093 import { BusinessError } from '@ohos.base'; 3094 3095 let generalCallbacks: backup.GeneralCallbacks = { 3096 onFileReady: (err: BusinessError, file: backup.File) => { 3097 if (err) { 3098 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 3099 return; 3100 } 3101 console.info('onFileReady success'); 3102 fs.closeSync(file.fd); 3103 }, 3104 onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => { 3105 if (err) { 3106 console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data); 3107 return; 3108 } 3109 console.info('onBundleBegin success'); 3110 }, 3111 onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => { 3112 if (err) { 3113 console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data); 3114 return; 3115 } 3116 console.info('onBundleEnd success'); 3117 }, 3118 onAllBundlesEnd: (err: BusinessError) => { 3119 if (err) { 3120 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 3121 return; 3122 } 3123 console.info('onAllBundlesEnd success'); 3124 }, 3125 onBackupServiceDied: () => { 3126 console.info('service died'); 3127 }, 3128 onResultReport: (bundleName: string, result: string) => { 3129 console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result); 3130 }, 3131 onProcess: (bundleName: string, process: string) => { 3132 console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process); 3133 } 3134 }; 3135 let incrementalBackupSession = new backup.IncrementalBackupSession(generalCallbacks); // 创建增量备份流程 3136 let incrementalBackupData: backup.IncrementalBackupData = { 3137 bundleName: "com.example.hiworld", 3138 lastIncrementalTime: 1700107870, // 调用者传递上一次备份的时间戳 3139 manifestFd:1 // 调用者传递上一次备份的manifest文件句柄 3140 } 3141 let incrementalBackupDataArray: backup.IncrementalBackupData[] = [incrementalBackupData]; 3142 incrementalBackupSession.appendBundles(incrementalBackupDataArray).then(() => { 3143 console.info('appendBundles success'); 3144 }).catch((err: BusinessError) => { 3145 console.error('appendBundles failed with err: ' + JSON.stringify(err)); 3146 }); // 添加需要增量备份的应用 3147 ``` 3148 3149### appendBundles<sup>12+</sup> 3150 3151appendBundles(bundlesToBackup: Array<IncrementalBackupData>, infos: string[]): Promise<void> 3152 3153添加需要增量备份的应用。当前整个流程中，触发Release接口之前都可以进行appendBundles的调用。使用Promise异步回调。 3154 3155**需要权限**：ohos.permission.BACKUP 3156 3157**系统能力**：SystemCapability.FileManagement.StorageService.Backup 3158 3159**参数：** 3160 3161| 参数名 | 类型 | 必填 | 说明 | 3162| --------------- | -------------------------------------------------------------- | ---- | -------------------------- | 3163| bundlesToBackup | Array<[IncrementalBackupData](#incrementalbackupdata12)> | 是 | 需要增量备份的应用的数组。 | 3164| infos | string[] | 是 | 备份时各应用所需要扩展信息的数组, 与bundlesToBackup根据索引一一对应。从API version 12开始支持。 | 3165 3166**返回值：** 3167 3168| 类型 | 说明 | 3169| ------------------- | ----------------------- | 3170| Promise<void> | Promise对象。无返回值。 | 3171 3172**错误码：** 3173 3174以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 3175 3176| 错误码ID | 错误信息 | 3177| -------- | ---------------------------------------------------------------------------------------------- | 3178| 201 | Permission verification failed, usually the result returned by VerifyAccessToken. | 3179| 202 | Permission verification failed, application which is not a system application uses system API. | 3180| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verifcation faild.| 3181| 13600001 | IPC error. | 3182| 13900001 | Operation not permitted. | 3183| 13900005 | I/O error. | 3184| 13900011 | Out of memory. | 3185| 13900020 | Invalid argument. | 3186| 13900025 | No space left on device. | 3187| 13900042 | Unknown error. | 3188 3189**示例：** 3190 3191 ```ts 3192 import fs from '@ohos.file.fs'; 3193 import { BusinessError } from '@ohos.base'; 3194 3195 let generalCallbacks: backup.GeneralCallbacks = { 3196 onFileReady: (err: BusinessError, file: backup.File) => { 3197 if (err) { 3198 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 3199 return; 3200 } 3201 console.info('onFileReady success'); 3202 fs.closeSync(file.fd); 3203 }, 3204 onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => { 3205 if (err) { 3206 console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data); 3207 return; 3208 } 3209 console.info('onBundleBegin success'); 3210 }, 3211 onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => { 3212 if (err) { 3213 console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data); 3214 return; 3215 } 3216 console.info('onBundleEnd success'); 3217 }, 3218 onAllBundlesEnd: (err: BusinessError) => { 3219 if (err) { 3220 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 3221 return; 3222 } 3223 console.info('onAllBundlesEnd success'); 3224 }, 3225 onBackupServiceDied: () => { 3226 console.info('service died'); 3227 }, 3228 onResultReport: (bundleName: string, result: string) => { 3229 console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result); 3230 }, 3231 onProcess: (bundleName: string, process: string) => { 3232 console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process); 3233 } 3234 }; 3235 let incrementalBackupSession = new backup.IncrementalBackupSession(generalCallbacks); // 创建增量备份流程 3236 let incrementalBackupData: backup.IncrementalBackupData = { 3237 bundleName: "com.example.hiworld", 3238 lastIncrementalTime: 1700107870, // 调用者传递上一次备份的时间戳 3239 manifestFd:1 // 调用者传递上一次备份的manifest文件句柄 3240 } 3241 let infos: Array<string> = [ 3242 ` 3243 { 3244 "infos": [ 3245 { 3246 "details": [ 3247 { 3248 "detail": [ 3249 { 3250 "key1": "value1", 3251 "key2": "value2" 3252 } 3253 ] 3254 } 3255 ], 3256 "type": "unicast", 3257 "bundleName": "com.example.hiworld" 3258 } 3259 ] 3260 }, 3261 { 3262 "infos": [ 3263 { 3264 "details": [ 3265 { 3266 "detail": [ 3267 { 3268 "key1": "value1", 3269 "key2": "value2" 3270 } 3271 ] 3272 } 3273 ], 3274 "type": "unicast", 3275 "bundleName": "com.example.myApp" 3276 } 3277 ] 3278 } 3279 ` 3280 ] 3281 let incrementalBackupDataArray: backup.IncrementalBackupData[] = [incrementalBackupData]; 3282 // 添加需要增量备份的应用 3283 incrementalBackupSession.appendBundles(incrementalBackupDataArray, infos).then(() => { 3284 console.info('appendBundles success'); 3285 }).catch((err: BusinessError) => { 3286 console.error('appendBundles failed with err: ' + JSON.stringify(err)); 3287 }); 3288 ``` 3289### release<sup>12+</sup> 3290 3291release(): Promise<void> 3292 3293结束增量备份流程。使用Promise异步回调。 3294 3295**需要权限**：ohos.permission.BACKUP 3296 3297**系统能力**：SystemCapability.FileManagement.StorageService.Backup 3298 3299**返回值：** 3300 3301| 类型 | 说明 | 3302| ------------------- | ----------------------- | 3303| Promise<void> | Promise对象。无返回值。 | 3304 3305**错误码：** 3306 3307以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 3308 3309| 错误码ID | 错误信息 | 3310| -------- | ---------------------------------------------------------------------------------------------- | 3311| 201 | Permission verification failed, usually the result returned by VerifyAccessToken. | 3312| 202 | Permission verification failed, application which is not a system application uses system API. | 3313| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verifcation faild.| 3314| 13600001 | IPC error. | 3315| 13900001 | Operation not permitted. | 3316| 13900005 | I/O error. | 3317| 13900020 | Invalid argument. | 3318| 13900042 | Unknown error. | 3319 3320**示例：** 3321 3322 ```ts 3323 import fs from '@ohos.file.fs'; 3324 import { BusinessError } from '@ohos.base'; 3325 3326 let generalCallbacks: backup.GeneralCallbacks = { 3327 onFileReady: (err: BusinessError, file: backup.File) => { 3328 if (err) { 3329 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 3330 return; 3331 } 3332 console.info('onFileReady success'); 3333 fs.closeSync(file.fd); 3334 }, 3335 onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => { 3336 if (err) { 3337 console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data); 3338 return; 3339 } 3340 console.info('onBundleBegin success'); 3341 }, 3342 onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => { 3343 if (err) { 3344 console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data); 3345 return; 3346 } 3347 console.info('onBundleEnd success'); 3348 }, 3349 onAllBundlesEnd: (err: BusinessError) => { 3350 if (err) { 3351 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 3352 return; 3353 } 3354 console.info('onAllBundlesEnd success'); 3355 }, 3356 onBackupServiceDied: () => { 3357 console.info('service died'); 3358 }, 3359 onResultReport: (bundleName: string, result: string) => { 3360 console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result); 3361 }, 3362 onProcess: (bundleName: string, process: string) => { 3363 console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process); 3364 } 3365 }; 3366 let incrementalBackupSession = new backup.IncrementalBackupSession(generalCallbacks); // 创建增量备份流程 3367 incrementalBackupSession.release(); // 结束增量备份流程 3368 console.info('release success'); 3369 ``` 3370 3371### cancel<sup>18+</sup> 3372 3373cancel(bundleName: string): number; 3374 3375增量备份任务过程中，工具应用发现数据异常，需要取消某应用的增量备份时调用此接口，使此应用的增量备份任务终止。 3376 3377**需要权限**：ohos.permission.BACKUP 3378 3379**系统能力**：SystemCapability.FileManagement.StorageService.Backup 3380 3381**参数：** 3382 3383| 参数名 | 类型 | 必填 | 说明 | 3384| --------------- | -------- | ---- | -------------------------- | 3385| bundleName | string | 是 | 需要取消备份的应用名称。 | 3386 3387**返回值：** 3388 3389| 类型 | 说明 | 3390| ------------------- | ----------------------- | 3391| number | 返回取消状态。<br/>0：取消任务下发成功；<br/> 13500011：想要取消的任务未开始；<br/> 13500012：想要取消的任务不存在。| 3392 3393**错误码：** 3394 3395以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 3396 3397| 错误码ID | 错误信息 | 3398| -------- | ---------------------------------------------------------------------------------------------- | 3399| 201 | Permission verification failed, usually the result returned by VerifyAccessToken. | 3400| 202 | Permission verification failed, application which is not a system application uses system API. | 3401| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verifcation faild.| 3402 3403**示例：** 3404 3405 ```ts 3406 import fs from '@ohos.file.fs'; 3407 import { BusinessError } from '@ohos.base'; 3408 import backup from '@ohos.file.backup'; 3409 3410 incrementalBackupSession?: backup.IncrementalBackupSession; 3411 3412 let generalCallbacks: backup.GeneralCallbacks = { 3413 onFileReady: (err: BusinessError, file: backup.File) => { 3414 if (err) { 3415 // 文件fd传输失败，调用取消接口，取消此应用的增量备份任务 3416 let result = this.incrementalBackupSession.cancel("com.example.myapplication"); 3417 console.info('cancel result:' + result); 3418 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 3419 return; 3420 } 3421 console.info('onFileReady success'); 3422 fs.closeSync(file.fd); 3423 }, 3424 onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => { 3425 if (err) { 3426 console.error('onBundleBegin failed with err: ' + JSON.stringify(err)); 3427 return; 3428 } 3429 console.info('onBundleBegin success'); 3430 }, 3431 onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => { 3432 if (err) { 3433 console.error('onBundleEnd failed with err: ' + JSON.stringify(err)); 3434 return; 3435 } 3436 console.info('onBundleEnd success'); 3437 }, 3438 onAllBundlesEnd: (err: BusinessError) => { 3439 if (err) { 3440 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 3441 return; 3442 } 3443 console.info('onAllBundlesEnd success'); 3444 }, 3445 onBackupServiceDied: () => { 3446 console.info('service died'); 3447 }, 3448 onResultReport: (bundleName: string, result: string) => { 3449 console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result); 3450 }, 3451 onProcess: (bundleName: string, process: string) => { 3452 console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process); 3453 } 3454 }; 3455 this.incrementalBackupSession = new backup.IncrementalBackupSession(generalCallbacks); // 创建增量备份流程 3456 ```