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 1464**需要权限**：ohos.permission.BACKUP 1465 1466**系统能力**：SystemCapability.FileManagement.StorageService.Backup 1467 1468**参数：** 1469 1470| 参数名 | 类型 | 必填 | 说明 | 1471| -------- | ------------------------- | ---- | -------------------------------- | 1472| fileMeta | [FileMeta](#filemeta) | 是 | 恢复文件的元数据。 | 1473| callback | AsyncCallback<void> | 是 | 异步请求文件句柄成功之后的回调。 | 1474 1475**错误码：** 1476 1477以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 1478 1479| 错误码ID | 错误信息 | 1480| -------- | ----------------------- | 1481| 13600001 | IPC error | 1482| 13900001 | Operation not permitted | 1483| 13900020 | Invalid argument | 1484| 13900042 | Unknown error | 1485 1486**示例：** 1487 1488 ```ts 1489 import fs from '@ohos.file.fs'; 1490 import { BusinessError } from '@ohos.base'; 1491 1492 let generalCallbacks: backup.GeneralCallbacks = { 1493 onFileReady: (err: BusinessError, file: backup.File) => { 1494 if (err) { 1495 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 1496 return; 1497 } 1498 console.info('onFileReady success'); 1499 fs.closeSync(file.fd); 1500 }, 1501 onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => { 1502 if (err) { 1503 console.error('onBundleBegin failed with err: ' + JSON.stringify(err)); 1504 return; 1505 } 1506 console.info('onBundleBegin success'); 1507 }, 1508 onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => { 1509 if (err) { 1510 console.error('onBundleEnd failed with err: ' + JSON.stringify(err)); 1511 return; 1512 } 1513 console.info('onBundleEnd success'); 1514 }, 1515 onAllBundlesEnd: (err: BusinessError) => { 1516 if (err) { 1517 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 1518 return; 1519 } 1520 console.info('onAllBundlesEnd success'); 1521 }, 1522 onBackupServiceDied: () => { 1523 console.info('service died'); 1524 }, 1525 onResultReport: (bundleName: string, result: string) => { 1526 console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result); 1527 }, 1528 onProcess: (bundleName: string, process: string) => { 1529 console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process); 1530 } 1531 }; 1532 let sessionRestore = new backup.SessionRestore(generalCallbacks); // 创建恢复流程 1533 let fileMeta: backup.FileMeta = { 1534 bundleName: "com.example.hiworld", 1535 uri: "test.txt" 1536 } 1537 sessionRestore.getFileHandle(fileMeta, (err: BusinessError) => { 1538 if (err) { 1539 console.error('getFileHandle failed with err: ' + JSON.stringify(err)); 1540 } 1541 console.info('getFileHandle success'); 1542 }); 1543 ``` 1544 1545### getFileHandle 1546 1547getFileHandle(fileMeta: FileMeta): Promise<void> 1548 1549用于请求从服务中获取共享文件。使用Promise异步回调。 1550 1551> **说明：** 1552> 1553> - 这个接口是零拷贝特性（减少不必要的内存拷贝，实现了更高效率的传输）的一部分。零拷贝方法可参考由[@ohos.file.fs](js-apis-file-fs.md)提供的[fs.copyFile](js-apis-file-fs.md#fscopyfile)等相关零拷贝接口。 1554> - 使用getFileHandle前需要获取SessionRestore类的实例，并且成功通过appendBundles添加需要待恢复的应用。 1555> - 开发者可以通过onFileReady回调来获取文件句柄，当客户端完成文件操作时，需要使用publishFile来进行发布。 1556> - 根据所需要恢复的文件个数，可以多次调用getFileHandle。 1557> - 所需恢复的文件，不支持使用相对路径(../)和软链接。 1558 1559**需要权限**：ohos.permission.BACKUP 1560 1561**系统能力**：SystemCapability.FileManagement.StorageService.Backup 1562 1563**参数：** 1564 1565| 参数名 | 类型 | 必填 | 说明 | 1566| -------- | --------------------- | ---- | ------------------ | 1567| fileMeta | [FileMeta](#filemeta) | 是 | 恢复文件的元数据。 | 1568 1569**返回值：** 1570 1571| 类型 | 说明 | 1572| ------------------- | ----------------------- | 1573| Promise<void> | Promise对象。无返回值。 | 1574 1575**错误码：** 1576 1577以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 1578 1579| 错误码ID | 错误信息 | 1580| -------- | ----------------------- | 1581| 13600001 | IPC error | 1582| 13900001 | Operation not permitted | 1583| 13900020 | Invalid argument | 1584| 13900042 | Unknown error | 1585 1586**示例：** 1587 1588 ```ts 1589 import fs from '@ohos.file.fs'; 1590 import { BusinessError } from '@ohos.base'; 1591 1592 let generalCallbacks: backup.GeneralCallbacks = { 1593 onFileReady: (err: BusinessError, file: backup.File) => { 1594 if (err) { 1595 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 1596 return; 1597 } 1598 console.info('onFileReady success'); 1599 fs.closeSync(file.fd); 1600 }, 1601 onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => { 1602 if (err) { 1603 console.error('onBundleBegin failed with err: ' + JSON.stringify(err)); 1604 return; 1605 } 1606 console.info('onBundleBegin success'); 1607 }, 1608 onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => { 1609 if (err) { 1610 console.error('onBundleEnd failed with err: ' + JSON.stringify(err)); 1611 return; 1612 } 1613 console.info('onBundleEnd success'); 1614 }, 1615 onAllBundlesEnd: (err: BusinessError) => { 1616 if (err) { 1617 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 1618 return; 1619 } 1620 console.info('onAllBundlesEnd success'); 1621 }, 1622 onBackupServiceDied: () => { 1623 console.info('service died'); 1624 }, 1625 onResultReport: (bundleName: string, result: string) => { 1626 console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result); 1627 }, 1628 onProcess: (bundleName: string, process: string) => { 1629 console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process); 1630 } 1631 }; 1632 let sessionRestore = new backup.SessionRestore(generalCallbacks); // 创建恢复流程 1633 async function getFileHandle() { 1634 try { 1635 let fileMeta: backup.FileMeta = { 1636 bundleName: "com.example.hiworld", 1637 uri: "test.txt" 1638 } 1639 await sessionRestore.getFileHandle(fileMeta); 1640 console.info('getFileHandle success'); 1641 } catch (error) { 1642 let err: BusinessError = error as BusinessError; 1643 console.error('getFileHandle failed with err: ' + JSON.stringify(err)); 1644 } 1645 } 1646 ``` 1647 1648### publishFile 1649 1650publishFile(fileMeta: FileMeta, callback: AsyncCallback<void>): void 1651 1652用于将FileMeta发布到备份服务，使服务知道文件的内容已经准备完成。使用callback异步回调。 1653 1654> **说明：** 1655> 1656> - 这个接口是零拷贝特性（减少不必要的内存拷贝，实现了更高效率的传输）的一部分。零拷贝方法可参考由[@ohos.file.fs](js-apis-file-fs.md)提供的[fs.copyFile](js-apis-file-fs.md#fscopyfile)等相关零拷贝接口。 1657> - 服务端通过onFileReady返回文件句柄后，客户端可通过零拷贝操作将其对应的文件内容拷贝到服务端提供的文件句柄中。 1658> - 这个接口仅在调用方完成所有待恢复数据的写入操作后才能调用，且调用方需要确保待写入恢复数据的一致性与完整性。 1659 1660**需要权限**：ohos.permission.BACKUP 1661 1662**系统能力**：SystemCapability.FileManagement.StorageService.Backup 1663 1664**参数：** 1665 1666| 参数名 | 类型 | 必填 | 说明 | 1667| -------- | ------------------------- | ---- | ---------------------------- | 1668| fileMeta | [FileMeta](#filemeta) | 是 | 恢复文件元数据。 | 1669| callback | AsyncCallback<void> | 是 | 异步发布文件成功之后的回调。 | 1670 1671**错误码：** 1672 1673以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 1674 1675| 错误码ID | 错误信息 | 1676| -------- | ----------------------- | 1677| 13600001 | IPC error | 1678| 13900001 | Operation not permitted | 1679| 13900020 | Invalid argument | 1680| 13900042 | Unknown error | 1681 1682**示例：** 1683 1684 ```ts 1685 import fs from '@ohos.file.fs'; 1686 import { BusinessError } from '@ohos.base'; 1687 1688 let g_session: backup.SessionRestore; 1689 let initMap = new Map<string, number>(); 1690 let testFileNum = 123; // 123: 恢复所需文件个数示例 1691 let testBundleName = 'com.example.myapplication'; // 测试包名 1692 initMap.set(testBundleName, testFileNum); 1693 let countMap = new Map<string, number>(); 1694 countMap.set(testBundleName, 0); // 实际写入文件个数初始化 1695 function createSessionRestore() { 1696 let generalCallbacks: backup.GeneralCallbacks = { 1697 onFileReady: (err: BusinessError, file: backup.File) => { 1698 if (err) { 1699 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 1700 return; 1701 } 1702 console.info('onFileReady success'); 1703 fs.closeSync(file.fd); 1704 countMap[file.bundleName]++; // 实际写入文件个数更新 1705 // 恢复所需文件个数与实际写入文件个数相等时调用，保证数据的一致性和完整性 1706 if (countMap[file.bundleName] == initMap[file.bundleName]) { // 每个包的所有文件收到后触发publishFile 1707 let fileMeta: backup.FileMeta = { 1708 bundleName: file.bundleName, 1709 uri: '' 1710 } 1711 g_session.publishFile(fileMeta, (err: BusinessError) => { 1712 if (err) { 1713 console.error('publishFile failed with err: ' + JSON.stringify(err)); 1714 return; 1715 } 1716 console.info('publishFile success'); 1717 }); 1718 } 1719 }, 1720 onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => { 1721 if (err) { 1722 console.error('onBundleBegin failed with err: ' + JSON.stringify(err)); 1723 return; 1724 } 1725 console.info('onBundleBegin success'); 1726 }, 1727 onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => { 1728 if (err) { 1729 console.error('onBundleEnd failed with err: ' + JSON.stringify(err)); 1730 return; 1731 } 1732 console.info('onBundleEnd success'); 1733 }, 1734 onAllBundlesEnd: (err: BusinessError) => { 1735 if (err) { 1736 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 1737 return; 1738 } 1739 console.info('onAllBundlesEnd success'); 1740 }, 1741 onBackupServiceDied: () => { 1742 console.info('service died'); 1743 }, 1744 onResultReport: (bundleName: string, result: string) => { 1745 console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result); 1746 }, 1747 onProcess: (bundleName: string, process: string) => { 1748 console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process); 1749 } 1750 }; 1751 let sessionRestore = new backup.SessionRestore(generalCallbacks); // 创建恢复流程 1752 return sessionRestore; 1753 } 1754 g_session = createSessionRestore(); 1755 ``` 1756 1757### publishFile 1758 1759publishFile(fileMeta: FileMeta): Promise<void> 1760 1761用于将FileMeta发布到备份服务，使服务知道文件的内容已经准备完成。使用Promise异步回调。 1762 1763> **说明：** 1764> 1765> - 这个接口是零拷贝特性（减少不必要的内存拷贝，实现了更高效率的传输）的一部分。零拷贝方法可参考由[@ohos.file.fs](js-apis-file-fs.md)提供的[fs.copyFile](js-apis-file-fs.md#fscopyfile)等相关零拷贝接口。 1766> - 服务端通过onFileReady返回文件句柄后，客户端可通过零拷贝操作将其对应的文件内容拷贝到服务端提供的文件句柄中。 1767> - 这个接口仅在调用方完成所有待恢复数据的写入操作后才能调用，且调用方需要确保待写入恢复数据的一致性与完整性。 1768 1769**需要权限**：ohos.permission.BACKUP 1770 1771**系统能力**：SystemCapability.FileManagement.StorageService.Backup 1772 1773**参数：** 1774 1775| 参数名 | 类型 | 必填 | 说明 | 1776| -------- | --------------------- | ---- | ---------------- | 1777| fileMeta | [FileMeta](#filemeta) | 是 | 恢复文件元数据。 | 1778 1779**返回值：** 1780 1781| 类型 | 说明 | 1782| ------------------- | ----------------------- | 1783| Promise<void> | Promise对象。无返回值。 | 1784 1785**错误码：** 1786 1787以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 1788 1789| 错误码ID | 错误信息 | 1790| -------- | ----------------------- | 1791| 13600001 | IPC error | 1792| 13900001 | Operation not permitted | 1793| 13900020 | Invalid argument | 1794| 13900042 | Unknown error | 1795 1796**示例：** 1797 1798 ```ts 1799 import fs from '@ohos.file.fs'; 1800 import { BusinessError } from '@ohos.base'; 1801 1802 let g_session: backup.SessionRestore; 1803 let initMap = new Map<string, number>(); 1804 let testFileNum = 123; // 123: 恢复所需文件个数示例 1805 let testBundleName = 'com.example.myapplication'; // 测试包名 1806 initMap.set(testBundleName, testFileNum); 1807 let countMap = new Map<string, number>(); 1808 countMap.set(testBundleName, 0); // 实际写入文件个数初始化 1809 async function publishFile(file: backup.FileMeta) { 1810 let fileMeta: backup.FileMeta = { 1811 bundleName: file.bundleName, 1812 uri: '' 1813 } 1814 await g_session.publishFile(fileMeta); 1815 } 1816 function createSessionRestore() { 1817 let generalCallbacks: backup.GeneralCallbacks = { 1818 onFileReady: (err: BusinessError, file: backup.File) => { 1819 if (err) { 1820 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 1821 return; 1822 } 1823 console.info('onFileReady success'); 1824 fs.closeSync(file.fd); 1825 countMap[file.bundleName]++; // 实际写入文件个数更新 1826 // 恢复所需文件个数与实际写入文件个数相等时调用，保证数据的一致性和完整性 1827 if (countMap[file.bundleName] == initMap[file.bundleName]) { // 每个包的所有文件收到后触发publishFile 1828 publishFile(file); 1829 } 1830 console.info('publishFile success'); 1831 }, 1832 onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => { 1833 if (err) { 1834 console.error('onBundleBegin failed with err: ' + JSON.stringify(err)); 1835 return; 1836 } 1837 console.info('onBundleBegin success'); 1838 }, 1839 onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => { 1840 if (err) { 1841 console.error('onBundleEnd failed with err: ' + JSON.stringify(err)); 1842 return; 1843 } 1844 console.info('onBundleEnd success'); 1845 }, 1846 onAllBundlesEnd: (err: BusinessError) => { 1847 if (err) { 1848 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 1849 return; 1850 } 1851 console.info('onAllBundlesEnd success'); 1852 }, 1853 onBackupServiceDied: () => { 1854 console.info('service died'); 1855 }, 1856 onResultReport: (bundleName: string, result: string) => { 1857 console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result); 1858 }, 1859 onProcess: (bundleName: string, process: string) => { 1860 console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process); 1861 } 1862 }; 1863 let sessionRestore = new backup.SessionRestore(generalCallbacks); // 创建恢复流程 1864 return sessionRestore; 1865 } 1866 g_session = createSessionRestore(); 1867 ``` 1868 1869### release<sup>12+</sup> 1870 1871release(): Promise<void> 1872 1873恢复流程结束后，应用与服务断开连接，使备份恢复服务退出。使用Promise异步回调。 1874 1875**需要权限**：ohos.permission.BACKUP 1876 1877**系统能力**：SystemCapability.FileManagement.StorageService.Backup 1878 1879**返回值：** 1880 1881| 类型 | 说明 | 1882| ------------------- | ----------------------- | 1883| Promise<void> | Promise对象。无返回值。 | 1884 1885**错误码：** 1886 1887以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 1888 1889| 错误码ID | 错误信息 | 1890| -------- | ---------------------------------------------------------------------------------------------- | 1891| 201 | Permission verification failed, usually the result returned by VerifyAccessToken. | 1892| 202 | Permission verification failed, application which is not a system application uses system API. | 1893| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verifcation faild| 1894| 13600001 | IPC error | 1895| 13900001 | Operation not permitted | 1896| 13900005 | I/O error | 1897| 13900042 | Unknown error | 1898 1899**示例：** 1900 1901 ```ts 1902 import fs from '@ohos.file.fs'; 1903 import { BusinessError } from '@ohos.base'; 1904 1905 let g_session: backup.SessionRestore; 1906 let initMap = new Map<string, number>(); 1907 let testFileNum = 123; // 123: 恢复所需文件个数示例 1908 let testBundleName = 'com.example.myapplication'; // 测试包名 1909 initMap.set(testBundleName, testFileNum); 1910 let countMap = new Map<string, number>(); 1911 countMap.set(testBundleName, 0); // 实际写入文件个数初始化 1912 function createSessionRestore() { 1913 let generalCallbacks: backup.GeneralCallbacks = { 1914 onFileReady: (err: BusinessError, file: backup.File) => { 1915 if (err) { 1916 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 1917 return; 1918 } 1919 console.info('onFileReady success'); 1920 fs.closeSync(file.fd); 1921 countMap[file.bundleName]++; // 实际写入文件个数更新 1922 // 恢复所需文件个数与实际写入文件个数相等时调用，保证数据的一致性和完整性 1923 if (countMap[file.bundleName] == initMap[file.bundleName]) { // 每个包的所有文件收到后触发publishFile 1924 let fileMeta: backup.FileMeta = { 1925 bundleName: file.bundleName, 1926 uri: '' 1927 } 1928 g_session.publishFile(fileMeta, (err: BusinessError) => { 1929 if (err) { 1930 console.error('publishFile failed with err: ' + JSON.stringify(err)); 1931 return; 1932 } 1933 console.info('publishFile success'); 1934 }); 1935 } 1936 }, 1937 onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => { 1938 if (err) { 1939 console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data); 1940 return; 1941 } 1942 console.info('onBundleBegin success'); 1943 }, 1944 onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => { 1945 if (err) { 1946 console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data); 1947 return; 1948 } 1949 console.info('onBundleEnd success'); 1950 }, 1951 onAllBundlesEnd: (err: BusinessError) => { 1952 if (err) { 1953 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 1954 return; 1955 } 1956 console.info('onAllBundlesEnd success'); 1957 }, 1958 onBackupServiceDied: () => { 1959 console.info('service died'); 1960 }, 1961 onResultReport: (bundleName: string, result: string) => { 1962 console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result); 1963 }, 1964 onProcess: (bundleName: string, process: string) => { 1965 console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process); 1966 } 1967 }; 1968 let sessionRestore = new backup.SessionRestore(generalCallbacks); // 创建恢复流程 1969 return sessionRestore; 1970 } 1971 g_session = createSessionRestore(); 1972 g_session.release(); 1973 console.info('release success'); 1974 ``` 1975 1976## IncrementalBackupSession<sup>12+</sup> 1977 1978增量备份流程对象，用来支撑应用增量备份的流程。在使用前，需要先创建IncrementalBackupSession实例。 1979 1980### constructor<sup>12+</sup> 1981 1982constructor(callbacks: GeneralCallbacks); 1983 1984增量备份流程的构造函数，用于获取IncrementalBackupSession类的实例。 1985 1986**需要权限**：ohos.permission.BACKUP 1987 1988**系统能力**：SystemCapability.FileManagement.StorageService.Backup 1989 1990**参数：** 1991 1992| 参数名 | 类型 | 必填 | 说明 | 1993| -------- | ------------------------------------- | ---- | ------------------------ | 1994| callback | [GeneralCallbacks](#generalcallbacks) | 是 | 增量备份流程所需的回调。 | 1995 1996**错误码：** 1997 1998以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 1999 2000| 错误码ID | 错误信息 | 2001| -------- | ---------------------------------------------------------------------------------------------- | 2002| 201 | Permission verification failed, usually the result returned by VerifyAccessToken. | 2003| 202 | Permission verification failed, application which is not a system application uses system API. | 2004| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verifcation faild| 2005 2006**示例：** 2007 2008 ```ts 2009 import fs from '@ohos.file.fs'; 2010 import { BusinessError } from '@ohos.base'; 2011 2012 let generalCallbacks: backup.GeneralCallbacks = { 2013 onFileReady: (err: BusinessError, file: backup.File) => { 2014 if (err) { 2015 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 2016 return; 2017 } 2018 console.info('onFileReady success'); 2019 fs.closeSync(file.fd); 2020 }, 2021 onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => { 2022 if (err) { 2023 console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data); 2024 return; 2025 } 2026 console.info('onBundleBegin success'); 2027 }, 2028 onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => { 2029 if (err) { 2030 console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data); 2031 return; 2032 } 2033 console.info('onBundleEnd success'); 2034 }, 2035 onAllBundlesEnd: (err: BusinessError) => { 2036 if (err) { 2037 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 2038 return; 2039 } 2040 console.info('onAllBundlesEnd success'); 2041 }, 2042 onBackupServiceDied: () => { 2043 console.info('service died'); 2044 }, 2045 onResultReport: (bundleName: string, result: string) => { 2046 console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result); 2047 }, 2048 onProcess: (bundleName: string, process: string) => { 2049 console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process); 2050 } 2051 }; 2052 let incrementalBackupSession = new backup.IncrementalBackupSession(generalCallbacks); // 创建增量备份流程 2053 ``` 2054 2055### appendBundles<sup>12+</sup> 2056 2057appendBundles(bundlesToBackup: Array<IncrementalBackupData>): Promise<void> 2058 2059添加需要增量备份的应用。当前整个流程中，触发Release接口之前都可以进行appendBundles的调用。使用Promise异步回调。 2060 2061**需要权限**：ohos.permission.BACKUP 2062 2063**系统能力**：SystemCapability.FileManagement.StorageService.Backup 2064 2065**参数：** 2066 2067| 参数名 | 类型 | 必填 | 说明 | 2068| --------------- | -------------------------------------------------------------- | ---- | -------------------------- | 2069| bundlesToBackup | Array<[IncrementalBackupData](#incrementalbackupdata12)> | 是 | 需要增量备份的应用的数组。 | 2070 2071**返回值：** 2072 2073| 类型 | 说明 | 2074| ------------------- | ----------------------- | 2075| Promise<void> | Promise对象。无返回值。 | 2076 2077**错误码：** 2078 2079以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 2080 2081| 错误码ID | 错误信息 | 2082| -------- | ---------------------------------------------------------------------------------------------- | 2083| 201 | Permission verification failed, usually the result returned by VerifyAccessToken. | 2084| 202 | Permission verification failed, application which is not a system application uses system API. | 2085| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verifcation faild| 2086| 13600001 | IPC error | 2087| 13900001 | Operation not permitted | 2088| 13900005 | I/O error | 2089| 13900011 | Out of memory | 2090| 13900020 | Invalid argument | 2091| 13900025 | No space left on device | 2092| 13900042 | Unknown error | 2093 2094**示例：** 2095 2096 ```ts 2097 import fs from '@ohos.file.fs'; 2098 import { BusinessError } from '@ohos.base'; 2099 2100 let generalCallbacks: backup.GeneralCallbacks = { 2101 onFileReady: (err: BusinessError, file: backup.File) => { 2102 if (err) { 2103 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 2104 return; 2105 } 2106 console.info('onFileReady success'); 2107 fs.closeSync(file.fd); 2108 }, 2109 onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => { 2110 if (err) { 2111 console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data); 2112 return; 2113 } 2114 console.info('onBundleBegin success'); 2115 }, 2116 onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => { 2117 if (err) { 2118 console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data); 2119 return; 2120 } 2121 console.info('onBundleEnd success'); 2122 }, 2123 onAllBundlesEnd: (err: BusinessError) => { 2124 if (err) { 2125 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 2126 return; 2127 } 2128 console.info('onAllBundlesEnd success'); 2129 }, 2130 onBackupServiceDied: () => { 2131 console.info('service died'); 2132 }, 2133 onResultReport: (bundleName: string, result: string) => { 2134 console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result); 2135 }, 2136 onProcess: (bundleName: string, process: string) => { 2137 console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process); 2138 } 2139 }; 2140 let incrementalBackupSession = new backup.IncrementalBackupSession(generalCallbacks); // 创建增量备份流程 2141 let incrementalBackupData: backup.IncrementalBackupData = { 2142 bundleName: "com.example.hiworld", 2143 lastIncrementalTime: 1700107870, // 调用者传递上一次备份的时间戳 2144 manifestFd:1 // 调用者传递上一次备份的manifest文件句柄 2145 } 2146 let incrementalBackupDataArray: backup.IncrementalBackupData[] = [incrementalBackupData]; 2147 incrementalBackupSession.appendBundles(incrementalBackupDataArray).then(() => { 2148 console.info('appendBundles success'); 2149 }).catch((err: BusinessError) => { 2150 console.error('appendBundles failed with err: ' + JSON.stringify(err)); 2151 }); // 添加需要增量备份的应用 2152 ``` 2153 2154### appendBundles<sup>12+</sup> 2155 2156appendBundles(bundlesToBackup: Array<IncrementalBackupData>, infos: string[]): Promise<void> 2157 2158添加需要增量备份的应用。当前整个流程中，触发Release接口之前都可以进行appendBundles的调用。使用Promise异步回调。 2159 2160**需要权限**：ohos.permission.BACKUP 2161 2162**系统能力**：SystemCapability.FileManagement.StorageService.Backup 2163 2164**参数：** 2165 2166| 参数名 | 类型 | 必填 | 说明 | 2167| --------------- | -------------------------------------------------------------- | ---- | -------------------------- | 2168| bundlesToBackup | Array<[IncrementalBackupData](#incrementalbackupdata12)> | 是 | 需要增量备份的应用的数组。 | 2169| infos | string[] | 是 | 备份时各应用所需要扩展信息的数组, 与bundlesToBackup根据索引一一对应, 从API version 12开始支持。 | 2170 2171**返回值：** 2172 2173| 类型 | 说明 | 2174| ------------------- | ----------------------- | 2175| Promise<void> | Promise对象。无返回值。 | 2176 2177**错误码：** 2178 2179以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 2180 2181| 错误码ID | 错误信息 | 2182| -------- | ---------------------------------------------------------------------------------------------- | 2183| 201 | Permission verification failed, usually the result returned by VerifyAccessToken. | 2184| 202 | Permission verification failed, application which is not a system application uses system API. | 2185| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verifcation faild| 2186| 13600001 | IPC error | 2187| 13900001 | Operation not permitted | 2188| 13900005 | I/O error | 2189| 13900011 | Out of memory | 2190| 13900020 | Invalid argument | 2191| 13900025 | No space left on device | 2192| 13900042 | Unknown error | 2193 2194**示例：** 2195 2196 ```ts 2197 import fs from '@ohos.file.fs'; 2198 import { BusinessError } from '@ohos.base'; 2199 2200 let generalCallbacks: backup.GeneralCallbacks = { 2201 onFileReady: (err: BusinessError, file: backup.File) => { 2202 if (err) { 2203 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 2204 return; 2205 } 2206 console.info('onFileReady success'); 2207 fs.closeSync(file.fd); 2208 }, 2209 onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => { 2210 if (err) { 2211 console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data); 2212 return; 2213 } 2214 console.info('onBundleBegin success'); 2215 }, 2216 onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => { 2217 if (err) { 2218 console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data); 2219 return; 2220 } 2221 console.info('onBundleEnd success'); 2222 }, 2223 onAllBundlesEnd: (err: BusinessError) => { 2224 if (err) { 2225 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 2226 return; 2227 } 2228 console.info('onAllBundlesEnd success'); 2229 }, 2230 onBackupServiceDied: () => { 2231 console.info('service died'); 2232 }, 2233 onResultReport: (bundleName: string, result: string) => { 2234 console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result); 2235 }, 2236 onProcess: (bundleName: string, process: string) => { 2237 console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process); 2238 } 2239 }; 2240 let incrementalBackupSession = new backup.IncrementalBackupSession(generalCallbacks); // 创建增量备份流程 2241 let incrementalBackupData: backup.IncrementalBackupData = { 2242 bundleName: "com.example.hiworld", 2243 lastIncrementalTime: 1700107870, // 调用者传递上一次备份的时间戳 2244 manifestFd:1 // 调用者传递上一次备份的manifest文件句柄 2245 } 2246 let infos: Array<string> = [ 2247 ` 2248 { 2249 "infos": [ 2250 { 2251 "details": [ 2252 { 2253 "detail": [ 2254 { 2255 "key1": "value1", 2256 "key2": "value2" 2257 } 2258 ] 2259 } 2260 ], 2261 "type": "unicast", 2262 "bundleName": "com.example.hiworld" 2263 } 2264 ] 2265 }, 2266 { 2267 "infos": [ 2268 { 2269 "details": [ 2270 { 2271 "detail": [ 2272 { 2273 "key1": "value1", 2274 "key2": "value2" 2275 } 2276 ] 2277 } 2278 ], 2279 "type": "unicast", 2280 "bundleName": "com.example.myApp" 2281 } 2282 ] 2283 } 2284 ` 2285 ] 2286 let incrementalBackupDataArray: backup.IncrementalBackupData[] = [incrementalBackupData]; 2287 // 添加需要增量备份的应用 2288 incrementalBackupSession.appendBundles(incrementalBackupDataArray, infos).then(() => { 2289 console.info('appendBundles success'); 2290 }).catch((err: BusinessError) => { 2291 console.error('appendBundles failed with err: ' + JSON.stringify(err)); 2292 }); 2293 ``` 2294### release<sup>12+</sup> 2295 2296release(): Promise<void> 2297 2298结束增量备份流程。使用Promise异步回调。 2299 2300**需要权限**：ohos.permission.BACKUP 2301 2302**系统能力**：SystemCapability.FileManagement.StorageService.Backup 2303 2304**返回值：** 2305 2306| 类型 | 说明 | 2307| ------------------- | ----------------------- | 2308| Promise<void> | Promise对象。无返回值。 | 2309 2310**错误码：** 2311 2312以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 2313 2314| 错误码ID | 错误信息 | 2315| -------- | ---------------------------------------------------------------------------------------------- | 2316| 201 | Permission verification failed, usually the result returned by VerifyAccessToken. | 2317| 202 | Permission verification failed, application which is not a system application uses system API. | 2318| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verifcation faild| 2319| 13600001 | IPC error | 2320| 13900001 | Operation not permitted | 2321| 13900005 | I/O error | 2322| 13900020 | Invalid argument | 2323| 13900042 | Unknown error | 2324 2325**示例：** 2326 2327 ```ts 2328 import fs from '@ohos.file.fs'; 2329 import { BusinessError } from '@ohos.base'; 2330 2331 let generalCallbacks: backup.GeneralCallbacks = { 2332 onFileReady: (err: BusinessError, file: backup.File) => { 2333 if (err) { 2334 console.error('onFileReady failed with err: ' + JSON.stringify(err)); 2335 return; 2336 } 2337 console.info('onFileReady success'); 2338 fs.closeSync(file.fd); 2339 }, 2340 onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => { 2341 if (err) { 2342 console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data); 2343 return; 2344 } 2345 console.info('onBundleBegin success'); 2346 }, 2347 onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => { 2348 if (err) { 2349 console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data); 2350 return; 2351 } 2352 console.info('onBundleEnd success'); 2353 }, 2354 onAllBundlesEnd: (err: BusinessError) => { 2355 if (err) { 2356 console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err)); 2357 return; 2358 } 2359 console.info('onAllBundlesEnd success'); 2360 }, 2361 onBackupServiceDied: () => { 2362 console.info('service died'); 2363 }, 2364 onResultReport: (bundleName: string, result: string) => { 2365 console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result); 2366 }, 2367 onProcess: (bundleName: string, process: string) => { 2368 console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process); 2369 } 2370 }; 2371 let incrementalBackupSession = new backup.IncrementalBackupSession(generalCallbacks); // 创建增量备份流程 2372 incrementalBackupSession.release(); // 结束增量备份流程 2373 console.info('release success'); 2374 ``` 2375