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| manifestFd | number | 是 | 已经打开的文件描述符，通过备份服务获取。 | 53 54## IncrementalBackupTime<sup>12+</sup> 55 56用于记录最后一次的增量备份时间，用于描述备份增量的时间点。 57 58**系统能力**：SystemCapability.FileManagement.StorageService.Backup 59 60| 名称 | 类型 | 必填 | 说明 | 61| ------------------- | ------ | ---- | --------------------------------------------------------------------------------------------------- | 62| bundleName | string | 是 | 应用名称，可通过[bundleManager.BundleInfo](../apis-ability-kit/js-apis-bundleManager-bundleInfo.md)提供的获取方式获取。 | 63| lastIncrementalTime | number | 是 | 最后一次的增量备份时间 | 64 65## BackupParams<sup>12+</sup> 66 67为备份恢复提供可选配置参数以json格式的字符串形式存在。 68 69**系统能力**：SystemCapability.FileManagement.StorageService.Backup 70 71| 名称 | 类型 | 必填 | 说明 | 72| ---------- | ------ | ---- | -------------------------------------------------- | 73| parameters | string | 否 | 以json格式为配置项的字符串，为备份恢复提供可选选项 | 74 75## BackupPriority<sup>12+</sup> 76 77为备份恢复提供优先级配置。 78 79**系统能力**：SystemCapability.FileManagement.StorageService.Backup 80 81| 名称 | 类型 | 必填 | 说明 | 82| -------- | ------ | ---- | ------------------------------------------------------ | 83| priority | number | 否 | 数值越大优先级越高，优先级相同的情况下，先调用的先执行 | 84 85## IncrementalBackupData<sup>12+</sup> 86 87一次增量备份对象。继承[IncrementalBackupTime](#incrementalbackuptime12)，[FileManifestData](#filemanifestdata12)，[BackupParams](#backupparams12)，[BackupPriority](#backuppriority12)。 88 89> **说明：** 90> 91> 记录应用最后一次的增量时间以及增量备份清单文件的文件描述符，清单文件中记录着增量时间内已备份的文件信息。可选参数包含了备份恢复的可选配置项，优先级配置项。 92 93**系统能力**：SystemCapability.FileManagement.StorageService.Backup 94 95## File 96 97一个文件对象。 98继承[FileMeta](#filemeta)和[FileData](#filedata) 99 100> **说明：** 101> 102> file.backup.File与@ohos.file.fs中的提供的[File](js-apis-file-fs.md#file)是带有不同的涵义，前者是继承[FileMeta](#filemeta)和[FileData](#filedata)的对象而后者只有一个文件描述符的对象。请注意区分，不要混淆。 103 104**系统能力**：SystemCapability.FileManagement.StorageService.Backup 105 106## File <sup>12+</sup> 107 108一个文件对象。 109继承[FileMeta](#filemeta)和[FileData](#filedata)和[FileManifestData](#filemanifestdata12)。 110 111> **说明：** 112> 113> file.backup.File与@ohos.file.fs中的提供的[File](js-apis-file-fs.md#file)是带有不同的涵义，前者是继承[FileMeta](#filemeta)和[FileData](#filedata)的对象而后者只有一个文件描述符的对象。请注意区分，不要混淆。 114 115**系统能力**：SystemCapability.FileManagement.StorageService.Backup 116 117## GeneralCallbacks 118 119备份/恢复过程中的通用回调，备份服务将通过这些回调通知客户端其应用的备份/恢复阶段。 120 121**系统能力**：SystemCapability.FileManagement.StorageService.Backup 122 123### onFileReady 124 125onFileReady : AsyncCallback<File> 126 127回调函数。当服务端返向客户端发送文件，如果成功触发回调，返回对应文件的[File](#file)内容；如果触发失败，则返回err错误对象。 128 129> **说明：** 130> 131> AsyncCallback回调中返回的File 所属file.backup.[File](#file)类型，返回的文件归备份服务所有，一旦文件关闭，备份服务将选择合适的时机去清理，但客户端必须关闭文件句柄。 132 133**系统能力**：SystemCapability.FileManagement.StorageService.Backup 134 135**错误码：** 136 137以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 138 139| 错误码ID | 错误信息 | 140| -------- | ----------------------- | 141| 13600001 | IPC error | 142| 13900005 | I/O error | 143| 13900011 | Out of memory | 144| 13900020 | Invalid argument | 145| 13900025 | No space left on device | 146| 13900042 | Unknown error | 147 148**示例：** 149 150 ```ts 151 import fs from '@ohos.file.fs'; 152 import { BusinessError } from '@ohos.base'; 153 154 onFileReady: (err: BusinessError, file: backup.File) => { 155 if (err) { 156 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 157 return; 158 } 159 console.info('onFileReady success with file: ' + file.bundleName + ' ' + file.uri); 160 fs.closeSync(file.fd); 161 } 162 ``` 163 164### onBundleBegin 165 166onBundleBegin : AsyncCallback<string, void | string> 167 168回调函数。当应用备份/恢复开始时，如果成功触发回调，返回对应的bundleName；如果触发失败，则返回err错误对象。从API version 12开始，返回err的同时，将同时返回第二个string参数bundleName。 169 170**系统能力**：SystemCapability.FileManagement.StorageService.Backup 171 172**返回值：** 173 174| 参数名 | 类型 | 必填 | 说明 | 175| ---------- | ------------- | ---- | ----------------------------------------------------------- | 176| bundleName | string | 是 | 服务返回的应用名称 | 177| err | BusinessError | 否 | 当发生err时，为错误对象，否则为undefined data为bundle名称。 | 178 179**错误码：** 180 181以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 182 183| 错误码ID | 错误信息 | 184| -------- | ----------------------------------------------------- | 185| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verifcation faild| 186| 13500001 | The application is not added to the backup or restore | 187| 13500002 | Failed to start application extension Procedure | 188| 13600001 | IPC error | 189| 13900005 | I/O error | 190| 13900011 | Out of memory | 191| 13900020 | Invalid argument | 192| 13900025 | No space left on device | 193| 13900042 | Unknown error | 194 195**示例：** 196 197 ```ts 198 import { BusinessError } from '@ohos.base'; 199 200 onBundleBegin: (err: BusinessError, bundleName: string) => { 201 if (err) { 202 console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code)); 203 return; 204 } 205 console.info('onBundleBegin success'); 206 } 207 ``` 208 209 ```ts 210 import { BusinessError } from '@ohos.base'; 211 212 onBundleBegin: (err: BusinessError<string>, bundleName: string) => { 213 if (err) { 214 console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data); 215 return; 216 } 217 console.info('onBundleBegin success'); 218 } 219 ``` 220 221### onBundleEnd 222 223onBundleEnd : AsyncCallback<string, void | string> 224 225回调函数。当应用备份/恢复结束后，如果成功触发回调，返回对应的bundleName；如果触发失败，则返回err错误对象。从API version 12开始，返回err的同时，将同时返回第二个string参数bundleName。 226 227**系统能力**：SystemCapability.FileManagement.StorageService.Backup 228 229**返回值：** 230 231| 参数名 | 类型 | 必填 | 说明 | 232| ---------- | ------------- | ---- | ----------------------------------------------------------- | 233| bundleName | string | 是 | 服务返回的应用名称 | 234| err | BusinessError | 否 | 当发生err时，为错误对象，否则为undefined data为bundle名称。 | 235 236**错误码：** 237 238以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 239 240| 错误码ID | 错误信息 | 241| -------- | ------------------------------- | 242| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verifcation faild| 243| 13500003 | Backup or restore timed out | 244| 13500004 | Application extension death | 245| 13600001 | IPC error | 246| 13900005 | I/O error | 247| 13900011 | Out of memory | 248| 13900020 | Invalid argument | 249| 13900025 | No space left on device | 250| 13900042 | Unknown error | 251 252**示例：** 253 254 ```ts 255 import { BusinessError } from '@ohos.base'; 256 257 onBundleEnd: (err: BusinessError, bundleName: string) => { 258 if (err) { 259 console.error('onBundleEnd failed with err: ' + JSON.stringify(err)); 260 return; 261 } 262 console.info('onBundleEnd success with bundleName: ' + bundleName); 263 } 264 ``` 265 266 ```ts 267 import { BusinessError } from '@ohos.base'; 268 269 onBundleEnd: (err: BusinessError<string>, bundleName: string) => { 270 if (err) { 271 console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data); 272 return; 273 } 274 console.info('onBundleEnd success'); 275 } 276 ``` 277 278### onAllBundlesEnd 279 280onAllBundlesEnd : AsyncCallback<undefined> 281 282回调函数。当所有bundle的备份/恢复过程结束成功时触发回调，如果触发失败，则返回err错误对象。 283 284**系统能力**：SystemCapability.FileManagement.StorageService.Backup 285 286**错误码：** 287 288以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 289 290| 错误码ID | 错误信息 | 291| -------- | ----------------------- | 292| 13600001 | IPC error | 293| 13900005 | I/O error | 294| 13900011 | Out of memory | 295| 13900020 | Invalid argument | 296| 13900025 | No space left on device | 297| 13900042 | Unknown error | 298 299**示例：** 300 301 ```ts 302 import { BusinessError } from '@ohos.base'; 303 304 onAllBundlesEnd: (err: BusinessError) => { 305 if (err) { 306 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 307 return; 308 } 309 console.info('onAllBundlesEnd success'); 310 } 311 ``` 312 313### onBackupServiceDied 314 315onBackupServiceDied : Callback<undefined> 316 317回调函数。备份服务死亡时触发回调，如果触发失败，则返回err错误对象。 318 319**系统能力**：SystemCapability.FileManagement.StorageService.Backup 320 321**示例：** 322 323 ```ts 324 onBackupServiceDied: () => { 325 console.info('onBackupServiceDied success'); 326 } 327 ``` 328 329### onResultReport 330 331onResultReport (bundleName: string, result: string) 332 333回调函数。当应用备份/恢复结束后，如果成功触发回调，返回应用包名及应用备份/恢复信息（备份/恢复数量或异常信息等）。 334 335**系统能力**：SystemCapability.FileManagement.StorageService.Backup 336 337**返回值：** 338 339| 参数名 | 类型 | 必填 | 说明 | 340| ---------- | ------ | ---- | ------------------------------- | 341| bundleName | string | 是 | 应用包名 | 342| result | string | 是 | json格式返回的应用备份/恢复信息 | 343 344**示例：** 345 346 ```ts 347 import backup from '@ohos.file.backup'; 348 349 onResultReport: (bundleName: string, result: string) => { 350 console.info('onResultReport bundleName : ' + bundleName); 351 console.info('onResultReport result : ' + result); 352 } 353 ``` 354 355### onProcess 356 357onProcess (bundleName: string, process: string) 358 359回调函数。应用备份/恢复过程中进度信息的回调，返回应用执行业务的进度信息和异常信息等。 360 361**系统能力**：SystemCapability.FileManagement.StorageService.Backup 362 363**返回值：** 364 365| 参数名 | 类型 | 必填 | 说明 | 366| ---------- | ------ | ---- | ------------------------------- | 367| bundleName | string | 是 | 应用包名 | 368| process | string | 是 | json格式返回应用备份/恢复的进度信息 | 369 370**示例：** 371 372 ```ts 373 import backup from '@ohos.file.backup'; 374 375 onProcess: (bundleName: string, process: string) => { 376 console.info('onProcess bundleName : ' + bundleName); 377 console.info('onProcess processInfo : ' + process); 378 } 379 ``` 380 381## backup.getLocalCapabilities 382 383getLocalCapabilities(callback: AsyncCallback<FileData>): void 384 385用于获取一个描述本地能力的Json文件。使用callback异步回调。 386 387**需要权限**：ohos.permission.BACKUP 388 389**系统能力**：SystemCapability.FileManagement.StorageService.Backup 390 391**参数：** 392 393| 参数名 | 类型 | 必填 | 说明 | 394| -------- | ------------------------------------------ | ---- | -------------------------------------------------- | 395| callback | AsyncCallback<[FileData](#filedata)> | 是 | 异步获取本地能力文件之后的回调。返回FileData对象。 | 396 397**错误码：** 398 399以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 400 401| 错误码ID | 错误信息 | 402| -------- | ----------------------- | 403| 13600001 | IPC error | 404| 13900005 | I/O error | 405| 13900011 | Out of memory | 406| 13900025 | No space left on device | 407| 13900042 | Unknown error | 408 409**示例：** 410 411 ```ts 412 import fs from '@ohos.file.fs'; 413 import { BusinessError } from '@ohos.base'; 414 415 try { 416 backup.getLocalCapabilities((err: BusinessError, fileData: backup.FileData) => { 417 if (err) { 418 console.error('getLocalCapabilities failed with err: ' + JSON.stringify(err)); 419 return; 420 } 421 console.info('getLocalCapabilities success'); 422 console.info('fileData info:' + fileData.fd); 423 fs.closeSync(fileData.fd); 424 }); 425 } catch (error) { 426 let err: BusinessError = error as BusinessError; 427 console.error('getLocalCapabilities failed with err: ' + JSON.stringify(err)); 428 } 429 ``` 430 431**能力文件可以通过[@ohos.file.fs](js-apis-file-fs.md)提供的[fs.stat](js-apis-file-fs.md#fsstat-1)等相关接口获取，能力文件内容示例：** 432 433 ```json 434 { 435 "bundleInfos" :[{ 436 "allToBackup" : true, 437 "extensionName" : "BackupExtensionAbility", 438 "name" : "com.example.hiworld", 439 "needToInstall" : false, 440 "spaceOccupied" : 0, 441 "versionCode" : 1000000, 442 "versionName" : "1.0.0" 443 }], 444 "deviceType" : "default", 445 "systemFullName" : "OpenHarmony-4.0.0.0" 446 } 447 ``` 448 449## backup.getLocalCapabilities 450 451getLocalCapabilities(): Promise<FileData> 452 453用于获取一个描述本地能力的Json文件。使用Promise异步回调。 454 455**需要权限**：ohos.permission.BACKUP 456 457**系统能力**：SystemCapability.FileManagement.StorageService.Backup 458 459**返回值：** 460 461| 类型 | 说明 | 462| ------------------------------------ | ------------------------------- | 463| Promise<[FileData](#filedata)> | Promise对象，返回FileData对象。 | 464 465**错误码：** 466 467以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 468 469| 错误码ID | 错误信息 | 470| -------- | ----------------------- | 471| 13600001 | IPC error | 472| 13900005 | I/O error | 473| 13900011 | Out of memory | 474| 13900025 | No space left on device | 475| 13900042 | Unknown error | 476 477**示例：** 478 479 ```ts 480 import fs from '@ohos.file.fs'; 481 import { BusinessError } from '@ohos.base'; 482 483 async function getLocalCapabilities() { 484 try { 485 let fileData = await backup.getLocalCapabilities(); 486 console.info('getLocalCapabilities success'); 487 console.info('fileData info:' + fileData.fd); 488 fs.closeSync(fileData.fd); 489 } catch (error) { 490 let err: BusinessError = error as BusinessError; 491 console.error('getLocalCapabilities failed with err: ' + JSON.stringify(err)); 492 } 493 } 494 ``` 495 496 **能力文件可以通过[@ohos.file.fs](js-apis-file-fs.md)提供的[fs.stat](js-apis-file-fs.md#fsstat)等相关接口获取，能力文件内容示例：** 497 498 ```json 499 { 500 "bundleInfos" :[{ 501 "allToBackup" : true, 502 "extensionName" : "BackupExtensionAbility", 503 "name" : "com.example.hiworld", 504 "needToInstall" : false, 505 "spaceOccupied" : 0, 506 "versionCode" : 1000000, 507 "versionName" : "1.0.0" 508 }], 509 "deviceType" : "default", 510 "systemFullName" : "OpenHarmony-4.0.0.0" 511 } 512 ``` 513 514## backup.getLocalCapabilities<sup>12+</sup> 515 516getLocalCapabilities(dataList:Array<IncrementalBackupTime>): Promise<FileData> 517 518用于获取一个描述本地能力的Json文件，根据dataList内传递的参数查询对应应用的本地能力数据。使用Promise异步回调。 519 520**需要权限**：ohos.permission.BACKUP 521 522**系统能力**：SystemCapability.FileManagement.StorageService.Backup 523 524**参数：** 525| 参数名 | 类型 | 必填 | 说明 | 526| -------- | -------------------------------------------------------------- | ---- | ---------------------------------------------- | 527| dataList | Array<[IncrementalBackupTime](#incrementalbackuptime12)> | 是 | 增量备份数据列表，用于描述增量备份的文件信息。 | 528 529**返回值：** 530 531| 类型 | 说明 | 532| ------------------------------------ | ------------------------------- | 533| Promise<[FileData](#filedata)> | Promise对象，返回FileData对象。 | 534 535**错误码：** 536 537以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 538 539| 错误码ID | 错误信息 | 540| -------- | ---------------------------------------------------------------------------------------------- | 541| 201 | Permission verification failed, usually the result returned by VerifyAccessToken. | 542| 202 | Permission verification failed, application which is not a system application uses system API. | 543| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verifcation faild| 544| 13600001 | IPC error | 545| 13900005 | I/O error | 546| 13900011 | Out of memory | 547| 13900020 | Invalid argument | 548| 13900025 | No space left on device | 549| 13900042 | Unknown error | 550 551**示例：** 552 553 ```ts 554 import fs from '@ohos.file.fs'; 555 import { BusinessError } from '@ohos.base'; 556 557 async function getLocalCapabilities() { 558 try { 559 let backupApps: backup.IncrementalBackupTime[] = [{ 560 bundleName: "com.example.hiworld", 561 lastIncrementalTime: 1700107870 //调用者根据上次记录的增量备份时间 562 }]; 563 let fileData = await backup.getLocalCapabilities(backupApps); 564 console.info('getLocalCapabilities success'); 565 console.info('fileData info:' + fileData.fd); 566 fs.closeSync(fileData.fd); 567 } catch (error) { 568 let err: BusinessError = error as BusinessError; 569 console.error('getLocalCapabilities failed with err: ' + JSON.stringify(err)); 570 } 571 } 572 ``` 573 574## backup.getBackupInfo 575 576getBackupInfo(bundleToBackup: string): string; 577 578获取需要备份的应用信息。 579 580**需要权限**：ohos.permission.BACKUP 581 582**系统能力**：SystemCapability.FileManagement.StorageService.Backup 583 584**参数：** 585 586| 参数名 | 类型 | 必填 | 说明 | 587| --------------- | -------- | ---- | -------------------------- | 588| bundleToBackup | string | 是 | 需要备份的应用名称。 | 589 590**返回值：** 591 592| 类型 | 说明 | 593| ------------------- | ----------------------- | 594| string | 返回应用上报的信息。 | 595 596**错误码：** 597 598以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 599 600| 错误码ID | 错误信息 | 601| -------- | ----------------------- | 602| 13600001 | IPC error | 603| 13900001 | Operation not permitted | 604| 13900005 | I/O error | 605| 13900011 | Out of memory | 606| 13900020 | Invalid argument | 607| 13900025 | No space left on device | 608| 13900042 | Unknown error | 609 610**示例：** 611 612 ```ts 613 import fs from '@ohos.file.fs'; 614 import { BusinessError } from '@ohos.base'; 615 import backup from '@ohos.file.backup'; 616 617 function getBackupInfo() { 618 try { 619 let backupApp = "com.example.hiworld"; 620 let result = backup.getBackupInfo(backupApp); 621 console.info('getBackupInfo success， result: ' + result); 622 } catch (error) { 623 let err: BusinessError = error as BusinessError; 624 console.error('getBackupInfo failed with err: ' + JSON.stringify(err)); 625 } 626 } 627 ``` 628 629## backup.updateTimer 630 631updateTimer(bundleName: string, timeout: number): void; 632 633调用时机为onBundleBegin之后，onBundleEnd之前 634 635**需要权限**：ohos.permission.BACKUP 636 637**系统能力**：SystemCapability.FileManagement.StorageService.Backup 638 639**参数：** 640 641| 参数名 | 类型 | 必填 | 说明 | 642| --------------- | -------- | ---- | -------------------------- | 643| bundleName | string | 是 | 需要设置备份或恢复时长的应用名称 | 644| timeout | number | 是 | 备份或恢复的限制时长，入参范围[0,14400000]，单位:ms | 645 646**返回值：** 647 648| 类型 | 说明 | 649| ------------------- | ----------------------- | 650| boolean | 超时时间是否设置成功 | 651 652**错误码：** 653 654| 错误码ID | 错误信息 | 655| -------- | ----------------------- | 656| 201 | Permission verification failed, usually the result returned by VerifyAccessToken. | 657| 202 | Permission verification failed, application which is not a system application uses system API. | 658| 401 | The input parameter is invalid. | 659 660**示例：** 661 662 ```ts 663 import { BusinessError } from '@ohos.base'; 664 import backup form '@ohos.file.backup'; 665 666 function updateTimer() { 667 try { 668 let timeout = 30000; 669 let bundleName = "com.example.hiworld"; 670 let result = backup.updateTimer(bundleName, timeout); 671 if (result) { 672 console.info('updateTimer success'); 673 } else { 674 console.info('updateTimer fail'); 675 } 676 } catch (error) { 677 let err: BusinessError = error as BusinessError; 678 console.error('updateTimer failed with err: ' + JSON.stringify(err)); 679 } 680 } 681 ``` 682 683## backup.updateSendRate 684 685updateSendRate(bundleName: string, sendRate: number): boolean; 686 687调用时机为onBundleBegin之后，onBundleEnd之前 688 689**需要权限**：ohos.permission.BACKUP 690 691**系统能力**：SystemCapability.FileManagement.StorageService.Backup 692 693**参数：** 694 695| 参数名 | 类型 | 必填 | 说明 | 696| --------------- | -------- | ---- | -------------------------- | 697| bundleName|string | 是 | 需要控制速率对应的应用名称 698| sendRate | number | 是 | 需要应用设置的fd发送速率大小，以秒为单位，范围0~800，默认60/秒，当为0时，表示停止发送，等到设置非0值时激活发送。如果设置值超过最大值800，按照800进行发送。 | 699 700**返回值：** 701 702| 类型 | 说明 | 703| ------------------- | ----------------------- | 704| boolean | 发送速率是否设置成功 | 705 706**错误码：** 707 708| 错误码ID | 错误信息 | 709| -------- | ----------------------- | 710| 201 | Permission verification failed, usually the result returned by VerifyAccessToken. | 711| 202 | Permission verification failed, application which is not a system application uses system API. | 712| 401 | The input parameter is invalid. | 713 714**示例：** 715 716 ```ts 717 import { BusinessError } from '@ohos.base'; 718 import backup form '@ohos.file.backup'; 719 720 function updateSendRate() { 721 try { 722 let bundleName = "com.example.myApp"; 723 let sendRate = 300; 724 let result = backup.updateSendRate(bundleName, sendRate); 725 if (result) { 726 console.info('updateSendRate success'); 727 } else { 728 console.info('updateSendRate fail'); 729 } 730 } catch (error) { 731 let err: BusinessError = error as BusinessError; 732 console.error('updateSendRate failed with err: ' + JSON.stringify(err)); 733 } 734 } 735 ``` 736 737## SessionBackup 738 739备份流程对象，用来支撑应用备份的流程。在使用前，需要先创建SessionBackup实例。 740 741### constructor 742 743constructor(callbacks: GeneralCallbacks); 744 745备份流程的构造函数，用于获取SessionBackup类的实例。 746 747**需要权限**：ohos.permission.BACKUP 748 749**系统能力**：SystemCapability.FileManagement.StorageService.Backup 750 751**参数：** 752 753| 参数名 | 类型 | 必填 | 说明 | 754| -------- | ------------------------------------- | ---- | -------------------- | 755| callback | [GeneralCallbacks](#generalcallbacks) | 是 | 备份流程所需的回调。 | 756 757**示例：** 758 759 ```ts 760 import fs from '@ohos.file.fs'; 761 import { BusinessError } from '@ohos.base'; 762 763 let generalCallbacks: backup.GeneralCallbacks = { 764 onFileReady: (err: BusinessError, file: backup.File) => { 765 if (err) { 766 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 767 return; 768 } 769 console.info('onFileReady success'); 770 fs.closeSync(file.fd); 771 }, 772 onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => { 773 if (err) { 774 console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data); 775 return; 776 } 777 console.info('onBundleBegin success'); 778 }, 779 onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => { 780 if (err) { 781 console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data); 782 return; 783 } 784 console.info('onBundleEnd success'); 785 }, 786 onAllBundlesEnd: (err: BusinessError) => { 787 if (err) { 788 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 789 return; 790 } 791 console.info('onAllBundlesEnd success'); 792 }, 793 onBackupServiceDied: () => { 794 console.info('service died'); 795 }, 796 onResultReport: (bundleName: string, result: string) => { 797 console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result); 798 }, 799 onProcess: (bundleName: string, process: string) => { 800 console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process); 801 } 802 }; 803 let sessionBackup = new backup.SessionBackup(generalCallbacks); // 创建备份流程 804 ``` 805 806### appendBundles 807 808appendBundles(bundlesToBackup: string[], callback: AsyncCallback<void>): void 809 810添加需要备份的应用。当前整个流程中，在获取SessionBackup类的实例后只能调用一次。使用callback异步回调。 811 812**需要权限**：ohos.permission.BACKUP 813 814**系统能力**：SystemCapability.FileManagement.StorageService.Backup 815 816**参数：** 817 818| 参数名 | 类型 | 必填 | 说明 | 819| --------------- | ------------------------- | ---- | ---------------------------- | 820| bundlesToBackup | string[] | 是 | 需要备份的应用名称的数组。 | 821| callback | AsyncCallback<void> | 是 | 异步添加备份应用之后的回调。 | 822 823**错误码：** 824 825以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 826 827| 错误码ID | 错误信息 | 828| -------- | ----------------------- | 829| 13600001 | IPC error | 830| 13900001 | Operation not permitted | 831| 13900005 | I/O error | 832| 13900011 | Out of memory | 833| 13900020 | Invalid argument | 834| 13900025 | No space left on device | 835| 13900042 | Unknown error | 836 837**示例：** 838 839 ```ts 840 import fs from '@ohos.file.fs'; 841 import { BusinessError } from '@ohos.base'; 842 843 let generalCallbacks: backup.GeneralCallbacks = { 844 onFileReady: (err: BusinessError, file: backup.File) => { 845 if (err) { 846 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 847 return; 848 } 849 console.info('onFileReady success'); 850 fs.closeSync(file.fd); 851 }, 852 onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => { 853 if (err) { 854 console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data); 855 return; 856 } 857 console.info('onBundleBegin success'); 858 }, 859 onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => { 860 if (err) { 861 console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data); 862 return; 863 } 864 console.info('onBundleEnd success'); 865 }, 866 onAllBundlesEnd: (err: BusinessError) => { 867 if (err) { 868 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 869 return; 870 } 871 console.info('onAllBundlesEnd success'); 872 }, 873 onBackupServiceDied: () => { 874 console.info('service died'); 875 }, 876 onResultReport: (bundleName: string, result: string) => { 877 console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result); 878 }, 879 onProcess: (bundleName: string, process: string) => { 880 console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process); 881 } 882 }; 883 let sessionBackup = new backup.SessionBackup(generalCallbacks); // 创建备份流程 884 try { 885 let backupApps: Array<string> = [ 886 "com.example.hiworld", 887 ]; 888 sessionBackup.appendBundles(backupApps, (err: BusinessError) => { 889 if (err) { 890 console.error('appendBundles failed with err: ' + JSON.stringify(err)); 891 return; 892 } 893 console.info('appendBundles success'); 894 }); 895 } catch (error) { 896 let err: BusinessError = error as BusinessError; 897 console.error('appendBundles failed with err: ' + JSON.stringify(err)); 898 } 899 ``` 900 901### appendBundles 902 903appendBundles(bundlesToBackup: string[], infos?: string[]): Promise<void> 904 905添加需要备份的应用。当前整个流程中，在获取SessionBackup类的实例后只能调用一次。使用Promise异步回调。 906 907从API version 12开始, 新增可选参数infos, 可携带备份时各应用所需要的扩展信息, infos和bundlesToBackup根据索引一一对应。 908 909**需要权限**：ohos.permission.BACKUP 910 911**系统能力**：SystemCapability.FileManagement.StorageService.Backup 912 913**参数：** 914 915| 参数名 | 类型 | 必填 | 说明 | 916| --------------- | -------- | ---- | -------------------------- | 917| bundlesToBackup | string[] | 是 | 需要备份的应用名称的数组。 | 918| infos | string[] | 否 | 备份时各应用所需扩展信息的数组, 与bundlesToBackup根据索引一一对应, 从API version 12开始支持。| 919 920**返回值：** 921 922| 类型 | 说明 | 923| ------------------- | ----------------------- | 924| Promise<void> | Promise对象。无返回值。 | 925 926**错误码：** 927 928以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 929 930| 错误码ID | 错误信息 | 931| -------- | ----------------------- | 932| 13600001 | IPC error | 933| 13900001 | Operation not permitted | 934| 13900005 | I/O error | 935| 13900011 | Out of memory | 936| 13900020 | Invalid argument | 937| 13900025 | No space left on device | 938| 13900042 | Unknown error | 939 940**示例：** 941 942 ```ts 943 import fs from '@ohos.file.fs'; 944 import { BusinessError } from '@ohos.base'; 945 946 let generalCallbacks: backup.GeneralCallbacks = { 947 onFileReady: (err: BusinessError, file: backup.File) => { 948 if (err) { 949 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 950 return; 951 } 952 console.info('onFileReady success'); 953 fs.closeSync(file.fd); 954 }, 955 onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => { 956 if (err) { 957 console.error('onBundleBegin failed with err: ' + JSON.stringify(err)); 958 return; 959 } 960 console.info('onBundleBegin success'); 961 }, 962 onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => { 963 if (err) { 964 console.error('onBundleEnd failed with err: ' + JSON.stringify(err)); 965 return; 966 } 967 console.info('onBundleEnd success'); 968 }, 969 onAllBundlesEnd: (err: BusinessError) => { 970 if (err) { 971 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 972 return; 973 } 974 console.info('onAllBundlesEnd success'); 975 }, 976 onBackupServiceDied: () => { 977 console.info('service died'); 978 }, 979 onResultReport: (bundleName: string, result: string) => { 980 console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result); 981 }, 982 onProcess: (bundleName: string, process: string) => { 983 console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process); 984 } 985 }; 986 let sessionBackup = new backup.SessionBackup(generalCallbacks); // 创建备份流程 987 async function appendBundles() { 988 try { 989 let backupApps: Array<string> = [ 990 "com.example.hiworld", 991 "com.example.myApp" 992 ]; 993 await sessionBackup.appendBundles(backupApps); 994 console.info('appendBundles success'); 995 // 携带扩展参数, 其中infos,details和外层的type节点为固定节点 996 let infos: Array<string> = [ 997 ` 998 { 999 "infos": [ 1000 { 1001 "details": [ 1002 { 1003 "detail": [ 1004 { 1005 "key1": "value1", 1006 "key2": "value2" 1007 } 1008 ] 1009 } 1010 ], 1011 "type": "unicast", 1012 "bundleName": "com.example.hiworld" 1013 } 1014 ] 1015 }, 1016 { 1017 "infos": [ 1018 { 1019 "details": [ 1020 { 1021 "detail": [ 1022 { 1023 "key1": "value1", 1024 "key2": "value2" 1025 } 1026 ] 1027 } 1028 ], 1029 "type": "unicast", 1030 "bundleName": "com.example.myApp" 1031 } 1032 ] 1033 } 1034 ` 1035 ] 1036 await sessionBackup.appendBundles(backupApps, infos); 1037 console.info('appendBundles success'); 1038 } catch (error) { 1039 let err: BusinessError = error as BusinessError; 1040 console.error('appendBundles failed with err: ' + JSON.stringify(err)); 1041 } 1042 } 1043 ``` 1044 1045### release<sup>12+</sup> 1046 1047release(): Promise<void> 1048 1049备份流程结束后，应用与服务断开连接，使备份恢复服务退出。使用Promise异步回调。 1050 1051**需要权限**：ohos.permission.BACKUP 1052 1053**系统能力**：SystemCapability.FileManagement.StorageService.Backup 1054 1055**返回值：** 1056 1057| 类型 | 说明 | 1058| ------------------- | ----------------------- | 1059| Promise<void> | Promise对象。无返回值。 | 1060 1061**错误码：** 1062 1063以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 1064 1065| 错误码ID | 错误信息 | 1066| -------- | ---------------------------------------------------------------------------------------------- | 1067| 201 | Permission verification failed, usually the result returned by VerifyAccessToken. | 1068| 202 | Permission verification failed, application which is not a system application uses system API. | 1069| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verifcation faild| 1070| 13600001 | IPC error | 1071| 13900001 | Operation not permitted | 1072| 13900005 | I/O error | 1073| 13900042 | Unknown error | 1074 1075**示例：** 1076 1077 ```ts 1078 import fs from '@ohos.file.fs'; 1079 import { BusinessError } from '@ohos.base'; 1080 1081 let generalCallbacks: backup.GeneralCallbacks = { 1082 onFileReady: (err: BusinessError, file: backup.File) => { 1083 if (err) { 1084 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 1085 return; 1086 } 1087 console.info('onFileReady success'); 1088 fs.closeSync(file.fd); 1089 }, 1090 onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => { 1091 if (err) { 1092 console.error('onBundleBegin failed with err: ' + JSON.stringify(err)); 1093 return; 1094 } 1095 console.info('onBundleBegin success'); 1096 }, 1097 onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => { 1098 if (err) { 1099 console.error('onBundleEnd failed with err: ' + JSON.stringify(err)); 1100 return; 1101 } 1102 console.info('onBundleEnd success'); 1103 }, 1104 onAllBundlesEnd: (err: BusinessError) => { 1105 if (err) { 1106 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 1107 return; 1108 } 1109 console.info('onAllBundlesEnd success'); 1110 }, 1111 onBackupServiceDied: () => { 1112 console.info('service died'); 1113 }, 1114 onResultReport: (bundleName: string, result: string) => { 1115 console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result); 1116 }, 1117 onProcess: (bundleName: string, process: string) => { 1118 console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process); 1119 } 1120 }; 1121 let sessionBackup = new backup.SessionBackup(generalCallbacks); // 创建备份流程 1122 async function release() { 1123 try { 1124 await sessionBackup.release(); 1125 console.info('release success'); 1126 } catch (error) { 1127 let err: BusinessError = error as BusinessError; 1128 console.error('release failed with err: ' + JSON.stringify(err)); 1129 } 1130 } 1131 ``` 1132 1133## SessionRestore 1134 1135恢复流程对象，用来支撑应用恢复的流程。在使用前，需要先创建SessionRestore实例。 1136 1137### constructor 1138 1139constructor(callbacks: GeneralCallbacks); 1140 1141恢复流程的构造函数，用于获取SessionRestore类的实例。 1142 1143**需要权限**：ohos.permission.BACKUP 1144 1145**系统能力**：SystemCapability.FileManagement.StorageService.Backup 1146 1147**参数：** 1148 1149| 参数名 | 类型 | 必填 | 说明 | 1150| -------- | ------------------------------------- | ---- | -------------------- | 1151| callback | [GeneralCallbacks](#generalcallbacks) | 是 | 恢复流程所需的回调。 | 1152 1153**示例：** 1154 1155 ```ts 1156 import fs from '@ohos.file.fs'; 1157 import { BusinessError } from '@ohos.base'; 1158 1159 let generalCallbacks: backup.GeneralCallbacks = { 1160 onFileReady: (err: BusinessError, file: backup.File) => { 1161 if (err) { 1162 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 1163 return; 1164 } 1165 console.info('onFileReady success'); 1166 fs.closeSync(file.fd); 1167 }, 1168 onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => { 1169 if (err) { 1170 console.error('onBundleBegin failed with err: ' + JSON.stringify(err)); 1171 return; 1172 } 1173 console.info('onBundleBegin success'); 1174 }, 1175 onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => { 1176 if (err) { 1177 console.error('onBundleEnd failed with err: ' + JSON.stringify(err)); 1178 return; 1179 } 1180 console.info('onBundleEnd success'); 1181 }, 1182 onAllBundlesEnd: (err: BusinessError) => { 1183 if (err) { 1184 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 1185 return; 1186 } 1187 console.info('onAllBundlesEnd success'); 1188 }, 1189 onBackupServiceDied: () => { 1190 console.info('service died'); 1191 }, 1192 onResultReport: (bundleName: string, result: string) => { 1193 console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result); 1194 }, 1195 onProcess: (bundleName: string, process: string) => { 1196 console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process); 1197 } 1198 }; 1199 let sessionRestore = new backup.SessionRestore(generalCallbacks); // 创建恢复流程 1200 ``` 1201 1202### appendBundles 1203 1204appendBundles(remoteCapabilitiesFd: number, bundlesToBackup: string[], callback: AsyncCallback<void>): void 1205 1206添加需要恢复的应用。当前整个流程中，在获取SessionRestore类的实例后只能调用一次，使用callback异步回调。 1207 1208> **说明：** 1209> 1210> - 服务在恢复时需要其能力文件进行相关校验。 1211> - 因此remoteCapabilitiesFd可通过备份端服务所提供的[getLocalCapabilities](#backupgetlocalcapabilities)接口获取，可对其内容根据恢复应用的实际状况修改参数。也可通过getLocalCapabilities提供的json示例自行生成能力文件。 1212 1213**需要权限**：ohos.permission.BACKUP 1214 1215**系统能力**：SystemCapability.FileManagement.StorageService.Backup 1216 1217**参数：** 1218 1219| 参数名 | 类型 | 必填 | 说明 | 1220| -------------------- | ------------------------- | ---- | ---------------------------------- | 1221| remoteCapabilitiesFd | number | 是 | 用于恢复所需能力文件的文件描述符。 | 1222| bundlesToBackup | string[] | 是 | 需要恢复的应用名称的数组。 | 1223| callback | AsyncCallback<void> | 是 | 异步添加需要恢复的应用之后的回调。 | 1224 1225**错误码：** 1226 1227以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 1228 1229| 错误码ID | 错误信息 | 1230| -------- | ----------------------- | 1231| 13600001 | IPC error | 1232| 13900001 | Operation not permitted | 1233| 13900005 | I/O error | 1234| 13900011 | Out of memory | 1235| 13900020 | Invalid argument | 1236| 13900025 | No space left on device | 1237| 13900042 | Unknown error | 1238 1239**示例：** 1240 1241 ```ts 1242 import fs from '@ohos.file.fs'; 1243 import { BusinessError } from '@ohos.base'; 1244 1245 let generalCallbacks: backup.GeneralCallbacks = { 1246 onFileReady: (err: BusinessError, file: backup.File) => { 1247 if (err) { 1248 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 1249 return; 1250 } 1251 console.info('onFileReady success'); 1252 fs.closeSync(file.fd); 1253 }, 1254 onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => { 1255 if (err) { 1256 console.error('onBundleBegin failed with err: ' + JSON.stringify(err)); 1257 return; 1258 } 1259 console.info('onBundleBegin success'); 1260 }, 1261 onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => { 1262 if (err) { 1263 console.error('onBundleEnd failed with err: ' + JSON.stringify(err)); 1264 return; 1265 } 1266 console.info('onBundleEnd success'); 1267 }, 1268 onAllBundlesEnd: (err: BusinessError) => { 1269 if (err) { 1270 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 1271 return; 1272 } 1273 console.info('onAllBundlesEnd success'); 1274 }, 1275 onBackupServiceDied: () => { 1276 console.info('service died'); 1277 }, 1278 onResultReport: (bundleName: string, result: string) => { 1279 console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result); 1280 }, 1281 onProcess: (bundleName: string, process: string) => { 1282 console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process); 1283 } 1284 }; 1285 let sessionRestore = new backup.SessionRestore(generalCallbacks); // 创建恢复流程 1286 async function appendBundles() { 1287 let fileData : backup.FileData = { 1288 fd : -1 1289 } 1290 try { 1291 fileData = await backup.getLocalCapabilities(); 1292 console.info('getLocalCapabilities success'); 1293 let restoreApps: Array<string> = [ 1294 "com.example.hiworld", 1295 ]; 1296 sessionRestore.appendBundles(fileData.fd, restoreApps, (err: BusinessError) => { 1297 if (err) { 1298 console.error('appendBundles failed with err: ' + JSON.stringify(err)); 1299 return; 1300 } 1301 console.info('appendBundles success'); 1302 }); 1303 } catch (error) { 1304 let err: BusinessError = error as BusinessError; 1305 console.error('getLocalCapabilities failed with err: ' + JSON.stringify(err)); 1306 } finally { 1307 fs.closeSync(fileData.fd); 1308 } 1309 } 1310 ``` 1311 1312### appendBundles 1313 1314appendBundles(remoteCapabilitiesFd: number, bundlesToBackup: string[], infos?: string[]): Promise<void> 1315 1316添加需要恢复的应用。从API version 12开始，新增可选参数infos，可携带应用恢复所需信息，infos和bundlesToBackup根据索引一一对应。 1317当前整个流程中，在获取SessionRestore类的实例后只能调用一次。使用Promise异步回调。 1318 1319> **说明：** 1320> 1321> - 服务在恢复时需要其能力文件进行相关校验。 1322> - 因此remoteCapabilitiesFd可通过备份端服务所提供的[getLocalCapabilities](#backupgetlocalcapabilities)接口获取， 1323 可对其内容根据恢复应用的实际状况修改参数。也可通过getLocalCapabilities提供的json示例自行生成能力文件。 1324 1325**需要权限**：ohos.permission.BACKUP 1326 1327**系统能力**：SystemCapability.FileManagement.StorageService.Backup 1328 1329**参数：** 1330 1331| 参数名 | 类型 | 必填 | 说明 | 1332| -------------------- | -------- | ---- | ---------------------------------- | 1333| remoteCapabilitiesFd | number | 是 | 用于恢复所需能力文件的文件描述符。 | 1334| bundlesToBackup | string[] | 是 | 需要恢复的应用包名称的数组。 | 1335| infos<sup>12+</sup> | string[] | 否 | 恢复时各应用所需要扩展信息的数组，与bundlesToBackup根据索引一一对应，从API version 12开始支持。 | 1336 1337**返回值：** 1338 1339| 类型 | 说明 | 1340| ------------------- | ----------------------- | 1341| Promise<void> | Promise对象。无返回值。 | 1342 1343**错误码：** 1344 1345以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 1346 1347| 错误码ID | 错误信息 | 1348| -------- | ----------------------- | 1349| 13600001 | IPC error | 1350| 13900001 | Operation not permitted | 1351| 13900005 | I/O error | 1352| 13900011 | Out of memory | 1353| 13900020 | Invalid argument | 1354| 13900025 | No space left on device | 1355| 13900042 | Unknown error | 1356 1357**示例：** 1358 1359 ```ts 1360 import fs from '@ohos.file.fs'; 1361 import { BusinessError } from '@ohos.base'; 1362 1363 let generalCallbacks: backup.GeneralCallbacks = { 1364 onFileReady: (err: BusinessError, file: backup.File) => { 1365 if (err) { 1366 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 1367 return; 1368 } 1369 console.info('onFileReady success'); 1370 fs.closeSync(file.fd); 1371 }, 1372 onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => { 1373 if (err) { 1374 console.error('onBundleBegin failed with err: ' + JSON.stringify(err)); 1375 return; 1376 } 1377 console.info('onBundleBegin success'); 1378 }, 1379 onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => { 1380 if (err) { 1381 console.error('onBundleEnd failed with err: ' + JSON.stringify(err)); 1382 return; 1383 } 1384 console.info('onBundleEnd success'); 1385 }, 1386 onAllBundlesEnd: (err: BusinessError) => { 1387 if (err) { 1388 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 1389 return; 1390 } 1391 console.info('onAllBundlesEnd success'); 1392 }, 1393 onBackupServiceDied: () => { 1394 console.info('service died'); 1395 }, 1396 onResultReport: (bundleName: string, result: string) => { 1397 console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result); 1398 }, 1399 onProcess: (bundleName: string, process: string) => { 1400 console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process); 1401 } 1402 }; 1403 let sessionRestore = new backup.SessionRestore(generalCallbacks); // 创建恢复流程 1404 async function appendBundles() { 1405 let fileData : backup.FileData = { 1406 fd : -1 1407 } 1408 try { 1409 fileData = await backup.getLocalCapabilities(); 1410 console.info('getLocalCapabilities success'); 1411 let restoreApps: Array<string> = [ 1412 "com.example.hiworld", 1413 ]; 1414 await sessionRestore.appendBundles(fileData.fd, restoreApps); 1415 console.info('appendBundles success'); 1416 // 携带扩展参数的调用 1417 let infos: Array<string> = [ 1418 ` 1419 { 1420 "infos":[ 1421 { 1422 "details": [ 1423 { 1424 "detail": [ 1425 { 1426 "source": "com.example.hiworld", // 应用旧系统包名 1427 "target": "com.example.helloworld" // 应用新系统包名 1428 } 1429 ]， 1430 "type": "app_mapping_relation" 1431 } 1432 ], 1433 "type":"broadcast" 1434 } 1435 ] 1436 } 1437 ` 1438 ] 1439 await sessionRestore.appendBundles(fileData.fd, restoreApps, infos); 1440 console.info('appendBundles success'); 1441 } catch (error) { 1442 let err: BusinessError = error as BusinessError; 1443 console.error('getLocalCapabilities failed with err: ' + JSON.stringify(err)); 1444 } finally { 1445 fs.closeSync(fileData.fd); 1446 } 1447 } 1448 ``` 1449 1450### getFileHandle 1451 1452getFileHandle(fileMeta: FileMeta, callback: AsyncCallback<void>): void 1453 1454用于请求从服务中获取共享文件。使用callback异步回调。 1455 1456> **说明：** 1457> 1458> - 这个接口是零拷贝特性（减少不必要的内存拷贝，实现了更高效率的传输）的一部分。零拷贝方法可参考由[@ohos.file.fs](js-apis-file-fs.md)提供的[fs.copyFile](js-apis-file-fs.md#fscopyfile)等相关零拷贝接口。 1459> - 使用getFileHandle前需要获取SessionRestore类的实例，并且成功通过appendBundles添加需要待恢复的应用。 1460> - 开发者可以通过onFileReady回调来获取文件句柄，当客户端完成文件操作时，需要使用publishFile来进行发布。 1461> - 根据所需要恢复的文件个数，可以多次调用getFileHandle。 1462 1463**需要权限**：ohos.permission.BACKUP 1464 1465**系统能力**：SystemCapability.FileManagement.StorageService.Backup 1466 1467**参数：** 1468 1469| 参数名 | 类型 | 必填 | 说明 | 1470| -------- | ------------------------- | ---- | -------------------------------- | 1471| fileMeta | [FileMeta](#filemeta) | 是 | 恢复文件的元数据。 | 1472| callback | AsyncCallback<void> | 是 | 异步请求文件句柄成功之后的回调。 | 1473 1474**错误码：** 1475 1476以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 1477 1478| 错误码ID | 错误信息 | 1479| -------- | ----------------------- | 1480| 13600001 | IPC error | 1481| 13900001 | Operation not permitted | 1482| 13900020 | Invalid argument | 1483| 13900042 | Unknown error | 1484 1485**示例：** 1486 1487 ```ts 1488 import fs from '@ohos.file.fs'; 1489 import { BusinessError } from '@ohos.base'; 1490 1491 let generalCallbacks: backup.GeneralCallbacks = { 1492 onFileReady: (err: BusinessError, file: backup.File) => { 1493 if (err) { 1494 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 1495 return; 1496 } 1497 console.info('onFileReady success'); 1498 fs.closeSync(file.fd); 1499 }, 1500 onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => { 1501 if (err) { 1502 console.error('onBundleBegin failed with err: ' + JSON.stringify(err)); 1503 return; 1504 } 1505 console.info('onBundleBegin success'); 1506 }, 1507 onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => { 1508 if (err) { 1509 console.error('onBundleEnd failed with err: ' + JSON.stringify(err)); 1510 return; 1511 } 1512 console.info('onBundleEnd success'); 1513 }, 1514 onAllBundlesEnd: (err: BusinessError) => { 1515 if (err) { 1516 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 1517 return; 1518 } 1519 console.info('onAllBundlesEnd success'); 1520 }, 1521 onBackupServiceDied: () => { 1522 console.info('service died'); 1523 }, 1524 onResultReport: (bundleName: string, result: string) => { 1525 console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result); 1526 }, 1527 onProcess: (bundleName: string, process: string) => { 1528 console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process); 1529 } 1530 }; 1531 let sessionRestore = new backup.SessionRestore(generalCallbacks); // 创建恢复流程 1532 let fileMeta: backup.FileMeta = { 1533 bundleName: "com.example.hiworld", 1534 uri: "test.txt" 1535 } 1536 sessionRestore.getFileHandle(fileMeta, (err: BusinessError) => { 1537 if (err) { 1538 console.error('getFileHandle failed with err: ' + JSON.stringify(err)); 1539 } 1540 console.info('getFileHandle success'); 1541 }); 1542 ``` 1543 1544### getFileHandle 1545 1546getFileHandle(fileMeta: FileMeta): Promise<void> 1547 1548用于请求从服务中获取共享文件。使用Promise异步回调。 1549 1550> **说明：** 1551> 1552> - 这个接口是零拷贝特性（减少不必要的内存拷贝，实现了更高效率的传输）的一部分。零拷贝方法可参考由[@ohos.file.fs](js-apis-file-fs.md)提供的[fs.copyFile](js-apis-file-fs.md#fscopyfile)等相关零拷贝接口。 1553> - 使用getFileHandle前需要获取SessionRestore类的实例，并且成功通过appendBundles添加需要待恢复的应用。 1554> - 开发者可以通过onFileReady回调来获取文件句柄，当客户端完成文件操作时，需要使用publishFile来进行发布。 1555> - 根据所需要恢复的文件个数，可以多次调用getFileHandle。 1556 1557**需要权限**：ohos.permission.BACKUP 1558 1559**系统能力**：SystemCapability.FileManagement.StorageService.Backup 1560 1561**参数：** 1562 1563| 参数名 | 类型 | 必填 | 说明 | 1564| -------- | --------------------- | ---- | ------------------ | 1565| fileMeta | [FileMeta](#filemeta) | 是 | 恢复文件的元数据。 | 1566 1567**返回值：** 1568 1569| 类型 | 说明 | 1570| ------------------- | ----------------------- | 1571| Promise<void> | Promise对象。无返回值。 | 1572 1573**错误码：** 1574 1575以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 1576 1577| 错误码ID | 错误信息 | 1578| -------- | ----------------------- | 1579| 13600001 | IPC error | 1580| 13900001 | Operation not permitted | 1581| 13900020 | Invalid argument | 1582| 13900042 | Unknown error | 1583 1584**示例：** 1585 1586 ```ts 1587 import fs from '@ohos.file.fs'; 1588 import { BusinessError } from '@ohos.base'; 1589 1590 let generalCallbacks: backup.GeneralCallbacks = { 1591 onFileReady: (err: BusinessError, file: backup.File) => { 1592 if (err) { 1593 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 1594 return; 1595 } 1596 console.info('onFileReady success'); 1597 fs.closeSync(file.fd); 1598 }, 1599 onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => { 1600 if (err) { 1601 console.error('onBundleBegin failed with err: ' + JSON.stringify(err)); 1602 return; 1603 } 1604 console.info('onBundleBegin success'); 1605 }, 1606 onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => { 1607 if (err) { 1608 console.error('onBundleEnd failed with err: ' + JSON.stringify(err)); 1609 return; 1610 } 1611 console.info('onBundleEnd success'); 1612 }, 1613 onAllBundlesEnd: (err: BusinessError) => { 1614 if (err) { 1615 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 1616 return; 1617 } 1618 console.info('onAllBundlesEnd success'); 1619 }, 1620 onBackupServiceDied: () => { 1621 console.info('service died'); 1622 }, 1623 onResultReport: (bundleName: string, result: string) => { 1624 console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result); 1625 }, 1626 onProcess: (bundleName: string, process: string) => { 1627 console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process); 1628 } 1629 }; 1630 let sessionRestore = new backup.SessionRestore(generalCallbacks); // 创建恢复流程 1631 async function getFileHandle() { 1632 try { 1633 let fileMeta: backup.FileMeta = { 1634 bundleName: "com.example.hiworld", 1635 uri: "test.txt" 1636 } 1637 await sessionRestore.getFileHandle(fileMeta); 1638 console.info('getFileHandle success'); 1639 } catch (error) { 1640 let err: BusinessError = error as BusinessError; 1641 console.error('getFileHandle failed with err: ' + JSON.stringify(err)); 1642 } 1643 } 1644 ``` 1645 1646### publishFile 1647 1648publishFile(fileMeta: FileMeta, callback: AsyncCallback<void>): void 1649 1650用于将FileMeta发布到备份服务，使服务知道文件的内容已经准备完成。使用callback异步回调。 1651 1652> **说明：** 1653> 1654> - 这个接口是零拷贝特性（减少不必要的内存拷贝，实现了更高效率的传输）的一部分。零拷贝方法可参考由[@ohos.file.fs](js-apis-file-fs.md)提供的[fs.copyFile](js-apis-file-fs.md#fscopyfile)等相关零拷贝接口。 1655> - 服务端通过onFileReady返回文件句柄后，客户端可通过零拷贝操作将其对应的文件内容拷贝到服务端提供的文件句柄中。 1656> - 这个接口仅在调用方完成所有待恢复数据的写入操作后才能调用，且调用方需要确保待写入恢复数据的一致性与完整性。 1657 1658**需要权限**：ohos.permission.BACKUP 1659 1660**系统能力**：SystemCapability.FileManagement.StorageService.Backup 1661 1662**参数：** 1663 1664| 参数名 | 类型 | 必填 | 说明 | 1665| -------- | ------------------------- | ---- | ---------------------------- | 1666| fileMeta | [FileMeta](#filemeta) | 是 | 恢复文件元数据。 | 1667| callback | AsyncCallback<void> | 是 | 异步发布文件成功之后的回调。 | 1668 1669**错误码：** 1670 1671以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 1672 1673| 错误码ID | 错误信息 | 1674| -------- | ----------------------- | 1675| 13600001 | IPC error | 1676| 13900001 | Operation not permitted | 1677| 13900020 | Invalid argument | 1678| 13900042 | Unknown error | 1679 1680**示例：** 1681 1682 ```ts 1683 import fs from '@ohos.file.fs'; 1684 import { BusinessError } from '@ohos.base'; 1685 1686 let g_session: backup.SessionRestore; 1687 let initMap = new Map<string, number>(); 1688 let testFileNum = 123; // 123: 恢复所需文件个数示例 1689 let testBundleName = 'com.example.myapplication'; // 测试包名 1690 initMap.set(testBundleName, testFileNum); 1691 let countMap = new Map<string, number>(); 1692 countMap.set(testBundleName, 0); // 实际写入文件个数初始化 1693 function createSessionRestore() { 1694 let generalCallbacks: backup.GeneralCallbacks = { 1695 onFileReady: (err: BusinessError, file: backup.File) => { 1696 if (err) { 1697 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 1698 return; 1699 } 1700 console.info('onFileReady success'); 1701 fs.closeSync(file.fd); 1702 countMap[file.bundleName]++; // 实际写入文件个数更新 1703 // 恢复所需文件个数与实际写入文件个数相等时调用，保证数据的一致性和完整性 1704 if (countMap[file.bundleName] == initMap[file.bundleName]) { // 每个包的所有文件收到后触发publishFile 1705 let fileMeta: backup.FileMeta = { 1706 bundleName: file.bundleName, 1707 uri: '' 1708 } 1709 g_session.publishFile(fileMeta, (err: BusinessError) => { 1710 if (err) { 1711 console.error('publishFile failed with err: ' + JSON.stringify(err)); 1712 return; 1713 } 1714 console.info('publishFile success'); 1715 }); 1716 } 1717 }, 1718 onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => { 1719 if (err) { 1720 console.error('onBundleBegin failed with err: ' + JSON.stringify(err)); 1721 return; 1722 } 1723 console.info('onBundleBegin success'); 1724 }, 1725 onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => { 1726 if (err) { 1727 console.error('onBundleEnd failed with err: ' + JSON.stringify(err)); 1728 return; 1729 } 1730 console.info('onBundleEnd success'); 1731 }, 1732 onAllBundlesEnd: (err: BusinessError) => { 1733 if (err) { 1734 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 1735 return; 1736 } 1737 console.info('onAllBundlesEnd success'); 1738 }, 1739 onBackupServiceDied: () => { 1740 console.info('service died'); 1741 }, 1742 onResultReport: (bundleName: string, result: string) => { 1743 console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result); 1744 }, 1745 onProcess: (bundleName: string, process: string) => { 1746 console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process); 1747 } 1748 }; 1749 let sessionRestore = new backup.SessionRestore(generalCallbacks); // 创建恢复流程 1750 return sessionRestore; 1751 } 1752 g_session = createSessionRestore(); 1753 ``` 1754 1755### publishFile 1756 1757publishFile(fileMeta: FileMeta): Promise<void> 1758 1759用于将FileMeta发布到备份服务，使服务知道文件的内容已经准备完成。使用Promise异步回调。 1760 1761> **说明：** 1762> 1763> - 这个接口是零拷贝特性（减少不必要的内存拷贝，实现了更高效率的传输）的一部分。零拷贝方法可参考由[@ohos.file.fs](js-apis-file-fs.md)提供的[fs.copyFile](js-apis-file-fs.md#fscopyfile)等相关零拷贝接口。 1764> - 服务端通过onFileReady返回文件句柄后，客户端可通过零拷贝操作将其对应的文件内容拷贝到服务端提供的文件句柄中。 1765> - 这个接口仅在调用方完成所有待恢复数据的写入操作后才能调用，且调用方需要确保待写入恢复数据的一致性与完整性。 1766 1767**需要权限**：ohos.permission.BACKUP 1768 1769**系统能力**：SystemCapability.FileManagement.StorageService.Backup 1770 1771**参数：** 1772 1773| 参数名 | 类型 | 必填 | 说明 | 1774| -------- | --------------------- | ---- | ---------------- | 1775| fileMeta | [FileMeta](#filemeta) | 是 | 恢复文件元数据。 | 1776 1777**返回值：** 1778 1779| 类型 | 说明 | 1780| ------------------- | ----------------------- | 1781| Promise<void> | Promise对象。无返回值。 | 1782 1783**错误码：** 1784 1785以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 1786 1787| 错误码ID | 错误信息 | 1788| -------- | ----------------------- | 1789| 13600001 | IPC error | 1790| 13900001 | Operation not permitted | 1791| 13900020 | Invalid argument | 1792| 13900042 | Unknown error | 1793 1794**示例：** 1795 1796 ```ts 1797 import fs from '@ohos.file.fs'; 1798 import { BusinessError } from '@ohos.base'; 1799 1800 let g_session: backup.SessionRestore; 1801 let initMap = new Map<string, number>(); 1802 let testFileNum = 123; // 123: 恢复所需文件个数示例 1803 let testBundleName = 'com.example.myapplication'; // 测试包名 1804 initMap.set(testBundleName, testFileNum); 1805 let countMap = new Map<string, number>(); 1806 countMap.set(testBundleName, 0); // 实际写入文件个数初始化 1807 async function publishFile(file: backup.FileMeta) { 1808 let fileMeta: backup.FileMeta = { 1809 bundleName: file.bundleName, 1810 uri: '' 1811 } 1812 await g_session.publishFile(fileMeta); 1813 } 1814 function createSessionRestore() { 1815 let generalCallbacks: backup.GeneralCallbacks = { 1816 onFileReady: (err: BusinessError, file: backup.File) => { 1817 if (err) { 1818 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 1819 return; 1820 } 1821 console.info('onFileReady success'); 1822 fs.closeSync(file.fd); 1823 countMap[file.bundleName]++; // 实际写入文件个数更新 1824 // 恢复所需文件个数与实际写入文件个数相等时调用，保证数据的一致性和完整性 1825 if (countMap[file.bundleName] == initMap[file.bundleName]) { // 每个包的所有文件收到后触发publishFile 1826 publishFile(file); 1827 } 1828 console.info('publishFile success'); 1829 }, 1830 onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => { 1831 if (err) { 1832 console.error('onBundleBegin failed with err: ' + JSON.stringify(err)); 1833 return; 1834 } 1835 console.info('onBundleBegin success'); 1836 }, 1837 onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => { 1838 if (err) { 1839 console.error('onBundleEnd failed with err: ' + JSON.stringify(err)); 1840 return; 1841 } 1842 console.info('onBundleEnd success'); 1843 }, 1844 onAllBundlesEnd: (err: BusinessError) => { 1845 if (err) { 1846 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 1847 return; 1848 } 1849 console.info('onAllBundlesEnd success'); 1850 }, 1851 onBackupServiceDied: () => { 1852 console.info('service died'); 1853 }, 1854 onResultReport: (bundleName: string, result: string) => { 1855 console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result); 1856 }, 1857 onProcess: (bundleName: string, process: string) => { 1858 console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process); 1859 } 1860 }; 1861 let sessionRestore = new backup.SessionRestore(generalCallbacks); // 创建恢复流程 1862 return sessionRestore; 1863 } 1864 g_session = createSessionRestore(); 1865 ``` 1866 1867### release<sup>12+</sup> 1868 1869release(): Promise<void> 1870 1871恢复流程结束后，应用与服务断开连接，使备份恢复服务退出。使用Promise异步回调。 1872 1873**需要权限**：ohos.permission.BACKUP 1874 1875**系统能力**：SystemCapability.FileManagement.StorageService.Backup 1876 1877**返回值：** 1878 1879| 类型 | 说明 | 1880| ------------------- | ----------------------- | 1881| Promise<void> | Promise对象。无返回值。 | 1882 1883**错误码：** 1884 1885以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 1886 1887| 错误码ID | 错误信息 | 1888| -------- | ---------------------------------------------------------------------------------------------- | 1889| 201 | Permission verification failed, usually the result returned by VerifyAccessToken. | 1890| 202 | Permission verification failed, application which is not a system application uses system API. | 1891| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verifcation faild| 1892| 13600001 | IPC error | 1893| 13900001 | Operation not permitted | 1894| 13900005 | I/O error | 1895| 13900042 | Unknown error | 1896 1897**示例：** 1898 1899 ```ts 1900 import fs from '@ohos.file.fs'; 1901 import { BusinessError } from '@ohos.base'; 1902 1903 let g_session: backup.SessionRestore; 1904 let initMap = new Map<string, number>(); 1905 let testFileNum = 123; // 123: 恢复所需文件个数示例 1906 let testBundleName = 'com.example.myapplication'; // 测试包名 1907 initMap.set(testBundleName, testFileNum); 1908 let countMap = new Map<string, number>(); 1909 countMap.set(testBundleName, 0); // 实际写入文件个数初始化 1910 function createSessionRestore() { 1911 let generalCallbacks: backup.GeneralCallbacks = { 1912 onFileReady: (err: BusinessError, file: backup.File) => { 1913 if (err) { 1914 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 1915 return; 1916 } 1917 console.info('onFileReady success'); 1918 fs.closeSync(file.fd); 1919 countMap[file.bundleName]++; // 实际写入文件个数更新 1920 // 恢复所需文件个数与实际写入文件个数相等时调用，保证数据的一致性和完整性 1921 if (countMap[file.bundleName] == initMap[file.bundleName]) { // 每个包的所有文件收到后触发publishFile 1922 let fileMeta: backup.FileMeta = { 1923 bundleName: file.bundleName, 1924 uri: '' 1925 } 1926 g_session.publishFile(fileMeta, (err: BusinessError) => { 1927 if (err) { 1928 console.error('publishFile failed with err: ' + JSON.stringify(err)); 1929 return; 1930 } 1931 console.info('publishFile success'); 1932 }); 1933 } 1934 }, 1935 onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => { 1936 if (err) { 1937 console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data); 1938 return; 1939 } 1940 console.info('onBundleBegin success'); 1941 }, 1942 onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => { 1943 if (err) { 1944 console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data); 1945 return; 1946 } 1947 console.info('onBundleEnd success'); 1948 }, 1949 onAllBundlesEnd: (err: BusinessError) => { 1950 if (err) { 1951 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 1952 return; 1953 } 1954 console.info('onAllBundlesEnd success'); 1955 }, 1956 onBackupServiceDied: () => { 1957 console.info('service died'); 1958 }, 1959 onResultReport: (bundleName: string, result: string) => { 1960 console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result); 1961 }, 1962 onProcess: (bundleName: string, process: string) => { 1963 console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process); 1964 } 1965 }; 1966 let sessionRestore = new backup.SessionRestore(generalCallbacks); // 创建恢复流程 1967 return sessionRestore; 1968 } 1969 g_session = createSessionRestore(); 1970 g_session.release(); 1971 console.info('release success'); 1972 ``` 1973 1974## IncrementalBackupSession<sup>12+</sup> 1975 1976增量备份流程对象，用来支撑应用增量备份的流程。在使用前，需要先创建IncrementalBackupSession实例。 1977 1978### constructor<sup>12+</sup> 1979 1980constructor(callbacks: GeneralCallbacks); 1981 1982增量备份流程的构造函数，用于获取IncrementalBackupSession类的实例。 1983 1984**需要权限**：ohos.permission.BACKUP 1985 1986**系统能力**：SystemCapability.FileManagement.StorageService.Backup 1987 1988**参数：** 1989 1990| 参数名 | 类型 | 必填 | 说明 | 1991| -------- | ------------------------------------- | ---- | ------------------------ | 1992| callback | [GeneralCallbacks](#generalcallbacks) | 是 | 增量备份流程所需的回调。 | 1993 1994**错误码：** 1995 1996以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 1997 1998| 错误码ID | 错误信息 | 1999| -------- | ---------------------------------------------------------------------------------------------- | 2000| 201 | Permission verification failed, usually the result returned by VerifyAccessToken. | 2001| 202 | Permission verification failed, application which is not a system application uses system API. | 2002| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verifcation faild| 2003 2004**示例：** 2005 2006 ```ts 2007 import fs from '@ohos.file.fs'; 2008 import { BusinessError } from '@ohos.base'; 2009 2010 let generalCallbacks: backup.GeneralCallbacks = { 2011 onFileReady: (err: BusinessError, file: backup.File) => { 2012 if (err) { 2013 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 2014 return; 2015 } 2016 console.info('onFileReady success'); 2017 fs.closeSync(file.fd); 2018 }, 2019 onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => { 2020 if (err) { 2021 console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data); 2022 return; 2023 } 2024 console.info('onBundleBegin success'); 2025 }, 2026 onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => { 2027 if (err) { 2028 console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data); 2029 return; 2030 } 2031 console.info('onBundleEnd success'); 2032 }, 2033 onAllBundlesEnd: (err: BusinessError) => { 2034 if (err) { 2035 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 2036 return; 2037 } 2038 console.info('onAllBundlesEnd success'); 2039 }, 2040 onBackupServiceDied: () => { 2041 console.info('service died'); 2042 }, 2043 onResultReport: (bundleName: string, result: string) => { 2044 console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result); 2045 }, 2046 onProcess: (bundleName: string, process: string) => { 2047 console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process); 2048 } 2049 }; 2050 let incrementalBackupSession = new backup.IncrementalBackupSession(generalCallbacks); // 创建增量备份流程 2051 ``` 2052 2053### appendBundles<sup>12+</sup> 2054 2055appendBundles(bundlesToBackup: Array<IncrementalBackupData>): Promise<void> 2056 2057添加需要增量备份的应用。当前整个流程中，触发Release接口之前都可以进行appendBundles的调用。使用Promise异步回调。 2058 2059**需要权限**：ohos.permission.BACKUP 2060 2061**系统能力**：SystemCapability.FileManagement.StorageService.Backup 2062 2063**参数：** 2064 2065| 参数名 | 类型 | 必填 | 说明 | 2066| --------------- | -------------------------------------------------------------- | ---- | -------------------------- | 2067| bundlesToBackup | Array<[IncrementalBackupData](#incrementalbackupdata12)> | 是 | 需要增量备份的应用的数组。 | 2068 2069**返回值：** 2070 2071| 类型 | 说明 | 2072| ------------------- | ----------------------- | 2073| Promise<void> | Promise对象。无返回值。 | 2074 2075**错误码：** 2076 2077以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 2078 2079| 错误码ID | 错误信息 | 2080| -------- | ---------------------------------------------------------------------------------------------- | 2081| 201 | Permission verification failed, usually the result returned by VerifyAccessToken. | 2082| 202 | Permission verification failed, application which is not a system application uses system API. | 2083| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verifcation faild| 2084| 13600001 | IPC error | 2085| 13900001 | Operation not permitted | 2086| 13900005 | I/O error | 2087| 13900011 | Out of memory | 2088| 13900020 | Invalid argument | 2089| 13900025 | No space left on device | 2090| 13900042 | Unknown error | 2091 2092**示例：** 2093 2094 ```ts 2095 import fs from '@ohos.file.fs'; 2096 import { BusinessError } from '@ohos.base'; 2097 2098 let generalCallbacks: backup.GeneralCallbacks = { 2099 onFileReady: (err: BusinessError, file: backup.File) => { 2100 if (err) { 2101 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 2102 return; 2103 } 2104 console.info('onFileReady success'); 2105 fs.closeSync(file.fd); 2106 }, 2107 onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => { 2108 if (err) { 2109 console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data); 2110 return; 2111 } 2112 console.info('onBundleBegin success'); 2113 }, 2114 onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => { 2115 if (err) { 2116 console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data); 2117 return; 2118 } 2119 console.info('onBundleEnd success'); 2120 }, 2121 onAllBundlesEnd: (err: BusinessError) => { 2122 if (err) { 2123 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 2124 return; 2125 } 2126 console.info('onAllBundlesEnd success'); 2127 }, 2128 onBackupServiceDied: () => { 2129 console.info('service died'); 2130 }, 2131 onResultReport: (bundleName: string, result: string) => { 2132 console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result); 2133 }, 2134 onProcess: (bundleName: string, process: string) => { 2135 console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process); 2136 } 2137 }; 2138 let incrementalBackupSession = new backup.IncrementalBackupSession(generalCallbacks); // 创建增量备份流程 2139 let incrementalBackupData: backup.IncrementalBackupData = { 2140 bundleName: "com.example.hiworld", 2141 lastIncrementalTime: 1700107870, // 调用者传递上一次备份的时间戳 2142 manifestFd:1 // 调用者传递上一次备份的manifest文件句柄 2143 } 2144 let incrementalBackupDataArray: backup.IncrementalBackupData[] = [incrementalBackupData]; 2145 incrementalBackupSession.appendBundles(incrementalBackupDataArray).then(() => { 2146 console.info('appendBundles success'); 2147 }).catch((err: BusinessError) => { 2148 console.error('appendBundles failed with err: ' + JSON.stringify(err)); 2149 }); // 添加需要增量备份的应用 2150 ``` 2151 2152### release<sup>12+</sup> 2153 2154release(): Promise<void> 2155 2156结束增量备份流程。使用Promise异步回调。 2157 2158**需要权限**：ohos.permission.BACKUP 2159 2160**系统能力**：SystemCapability.FileManagement.StorageService.Backup 2161 2162**返回值：** 2163 2164| 类型 | 说明 | 2165| ------------------- | ----------------------- | 2166| Promise<void> | Promise对象。无返回值。 | 2167 2168**错误码：** 2169 2170以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 2171 2172| 错误码ID | 错误信息 | 2173| -------- | ---------------------------------------------------------------------------------------------- | 2174| 201 | Permission verification failed, usually the result returned by VerifyAccessToken. | 2175| 202 | Permission verification failed, application which is not a system application uses system API. | 2176| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verifcation faild| 2177| 13600001 | IPC error | 2178| 13900001 | Operation not permitted | 2179| 13900005 | I/O error | 2180| 13900020 | Invalid argument | 2181| 13900042 | Unknown error | 2182 2183**示例：** 2184 2185 ```ts 2186 import fs from '@ohos.file.fs'; 2187 import { BusinessError } from '@ohos.base'; 2188 2189 let generalCallbacks: backup.GeneralCallbacks = { 2190 onFileReady: (err: BusinessError, file: backup.File) => { 2191 if (err) { 2192 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 2193 return; 2194 } 2195 console.info('onFileReady success'); 2196 fs.closeSync(file.fd); 2197 }, 2198 onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => { 2199 if (err) { 2200 console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data); 2201 return; 2202 } 2203 console.info('onBundleBegin success'); 2204 }, 2205 onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => { 2206 if (err) { 2207 console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data); 2208 return; 2209 } 2210 console.info('onBundleEnd success'); 2211 }, 2212 onAllBundlesEnd: (err: BusinessError) => { 2213 if (err) { 2214 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 2215 return; 2216 } 2217 console.info('onAllBundlesEnd success'); 2218 }, 2219 onBackupServiceDied: () => { 2220 console.info('service died'); 2221 }, 2222 onResultReport: (bundleName: string, result: string) => { 2223 console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result); 2224 }, 2225 onProcess: (bundleName: string, process: string) => { 2226 console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process); 2227 } 2228 }; 2229 let incrementalBackupSession = new backup.IncrementalBackupSession(generalCallbacks); // 创建增量备份流程 2230 incrementalBackupSession.release(); // 结束增量备份流程 2231 console.info('release success'); 2232 ``` 2233