Skip to content

D
Docs

OpenHarmony / Docs
大约 1 年 前同步成功

通知 159
Star 292
Fork 28
D
Docs

体验新版 GitCode，发现更多精彩内容 >>

切换分支/标签
查找文件 普通视图历史永久链接Permalink
js-apis-file-backup.md 23.7 KB
Newer Older
H
新增file.backup 备份恢复接口说明  
huaqingsimeng 已提交
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 
# @ohos.file.backup (备份恢复)

该模块为应用提供备份/恢复数据的能力。

> **说明：**
> - 本模块首批接口从API version 10开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
> - 本模块接口为系统接口。
> - 本模块支持对错误码进行处理，错误码及其适配方式[参考文档](../errorcodes/errorcode-filemanagement.md#错误码适配指导)。

## 导入模块

```js
import backup from '@ohos.file.backup';
```

## FileMeta

文件的元数据，包含一个应用名称以及文件uri。FileMeta在执行备份/恢复时是不可缺少的对象

**系统能力**：SystemCapability.FileManagement.StorageService.Backup
H
修改file.backup 备份恢复接口说明  
huaqingsimeng 已提交
22 23 24 
| 名称       | 类型   | 必填 | 说明                                                                                           |
| ---------- | ------ | ---- | ---------------------------------------------------------------------------------------------- |
| bundleName | string | 是   | 应用名称，可通过[bundle.BundleInfo](js-apis-bundle-BundleInfo.md)提供的获取方式获取。          |
H
新增file.backup 备份恢复接口说明  
huaqingsimeng 已提交
25 26 27 28 29 30 31 
| uri        | string | 是   | 应用沙箱内待传输文件的名称，当前uri尚未升级为标准格式，仅接受0-9a-zA-Z下划线(_)点(.)组成的名称 |

## FileData

文件的元数据，包含一个已经打开的文件描述符。FileData在执行备份/恢复时是不可缺少的对象

> **说明：**
H
修改备份恢复api接口描述错误  
huaqingsimeng 已提交
32 
> - FileData使用完成后必须关闭，如不关闭会出现内存泄露问题。关闭的方法可参考由[@ohos.file.fs](./js-apis-file-fs.md)提供的[fs.closeSync](js-apis-file-fs.md#fsclosesync)等相关关闭接口
H
新增file.backup 备份恢复接口说明  
huaqingsimeng 已提交
33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 

**系统能力**：SystemCapability.FileManagement.StorageService.Backup

| 名称 | 类型   | 必填 | 说明                                     |
| ---- | ------ | ---- | ---------------------------------------- |
| fd   | number | 是   | 已经打开的文件描述符，通过备份服务获取。 |

## File

一个文件对象。
继承[FileMeta](#filemeta)和[FileData](#filedata)

> **说明：**
> - file.backup.File与@ohos.file.fs中的提供的[File](js-apis-file-fs.md#file)是带有不同的涵义，前者是继承[FileMeta](#filemeta)和[FileData](#filedata)的对象而后者只有一个文件描述符的对象。请注意做区分，不要混淆。

**系统能力**：SystemCapability.FileManagement.StorageService.Backup

## GeneralCallbacks

备份/恢复过程中的通用回调，备份服务将通过这些回调通知客户端其应用的备份/恢复阶段。

**系统能力**：SystemCapability.FileManagement.StorageService.Backup

### onFileReady

onFileReady : AsyncCallback<File>

回调函数。当服务端返向客户端发送文件成功，err为undefined，否则为错误对象。

> **说明：**
> - AsyncCallback回调中返回的File 所属file.backup.[File](#file)类型，返回的文件归备份服务所有，一旦文件关闭，备份服务将选择合适的实际去清理，但客户端必须关闭文件句柄。

**系统能力**：SystemCapability.FileManagement.StorageService.Backup

**示例：**

  ```js
  import fs from '@ohos.file.fs';
  onFileReady: (err, file) => {
    if (err) {
      console.error('onFileReady failed with err: ' + err);
    }
    console.info('onFileReady success with file: ' + file.bundleName + ' ' + file.uri);
    fs.closeSync(file.fd);
  }
  ```

### onBundleBegin

onBundleBegin : AsyncCallback<string>

 回调函数。当应用备份/恢复开始时返回bundle名称成功，err为undefined，否则为错误对象。

> **说明：**
> - 回调函数。当应用备份/恢复开始时，err为undefined，否则为错误对象。

**系统能力**：SystemCapability.FileManagement.StorageService.Backup

**示例：**

  ```js
  onBundleBegin: (err, bundleName) => {
    if (err) {
H
修改file.backup 备份恢复接口说明  
huaqingsimeng 已提交
96 
      console.error('onBundleBegin failed with err: ' + err);
H
新增file.backup 备份恢复接口说明  
huaqingsimeng 已提交
97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 
    }
    console.info('onBundleBegin success with bundleName: ' + bundleName);
  }
  ```

### onBundleEnd

onBundleEnd : AsyncCallback<string>

回调函数。当应用备份/恢复结束后返回bundle名称成功，err为undefined，否则为错误对象。

**系统能力**：SystemCapability.FileManagement.StorageService.Backup

**示例：**

  ```js
  onBundleEnd: (err, bundleName) => {
    if (err) {
      console.error('onBundleEnd failed with err: ' + err);
    }
    console.info('onBundleEnd success with bundleName: ' + bundleName);
  }
  ```

### onAllBundlesEnd

onAllBundlesEnd : AsyncCallback<undefined>

回调函数。当所有bundle的备份/恢复过程结束成功，err为undefined，否则为错误对象。

**系统能力**：SystemCapability.FileManagement.StorageService.Backup

**示例：**

  ```js
  onAllBundlesEnd: (err) => {
    if (err) {
      console.error('onAllBundlesEnd failed with err: ' + err);
    }
    console.info('onAllBundlesEnd success');
  }
  ```

### onBackupServiceDied

onBackupServiceDied : Callback<undefined>

回调函数，返回备份服务死亡。

**系统能力**：SystemCapability.FileManagement.StorageService.Backup

**示例：**

  ```js
  onBackupServiceDied: () => {
    console.info('onBackupServiceDied success');
  }
  ```

## getLocalCapabilities

getLocalCapabilities(callback: AsyncCallback<FileData>): void;

用于获取一个描述本地能力的Json文件。使用callback异步回调。

**需要权限**：ohos.permission.BACKUP

**系统能力**：SystemCapability.FileManagement.StorageService.Backup

**参数：**
| 参数名   | 类型                                       | 必填 | 说明                                                   |
| -------- | ------------------------------------------ | ---- | ------------------------------------------------------ |
| callback | AsyncCallback<[FileData](#filedata)> | 是   | 回调函数。当获取成功，err为undefined，否则为错误对象。 |

**示例：**

  ```js
  import fs from '@ohos.file.fs';
  try {
    backup.getLocalCapabilities((err, fileData) => {
      if (err) {
        console.error('getLocalCapabilities failed with err: ' + err);
      }
      console.info('getLocalCapabilities success');
      fs.closeSync(fileData.fd);
    });
  } catch (err) {
    console.error('getLocalCapabilities failed with err: ' + err);
  }
  ```
H
修改file.backup 备份恢复接口说明  
huaqingsimeng 已提交
188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 
  
**返回的能力文件内容示例：**

 ```json
 {
  "bundleInfos" :[{
    "allToBackup" : true,
    "extensionName" : "BackupExtensionAbility",
    "name" : "com.example.hiworld",
    "needToInstall" : false,
    "spaceOccupied" : 0,
    "versionCode" : 1000000,
    "versionName" : "1.0.0"
    }],
  "deviceType" : "phone",
  "systemFullName" : "OpenHarmony-4.0.0.0"
 }
 ```
H
新增file.backup 备份恢复接口说明  
huaqingsimeng 已提交
207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 
## getLocalCapabilities

getLocalCapabilities(): Promise<FileData>;

用于获取一个描述本地能力的Json文件。使用Promise异步回调。

**需要权限**：ohos.permission.BACKUP

**系统能力**：SystemCapability.FileManagement.StorageService.Backup

**返回值：**

| 类型                                 | 说明                                                |
| ------------------------------------ | --------------------------------------------------- |
| Promise<[FileData](#filedata)> | Promise对象，返回描述本地能力的Json文件的FileData。 |
H
修改file.backup 备份恢复接口说明  
huaqingsimeng 已提交
223 224 225 226 227 228 229 230 231 232 233 234 235 236 
**示例：**

  ```js
  import fs from '@ohos.file.fs';
  try {
    let fileData = await backup.getLocalCapabilities();
    console.info('getLocalCapabilities success');
    fs.closeSync(fileData.fd);
  } catch (err) {
    console.error('getLocalCapabilities failed with err: ' + err);
  }
  ```

  **返回的能力文件内容示例：**
H
新增file.backup 备份恢复接口说明  
huaqingsimeng 已提交
237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 

 ```json
 {
  "bundleInfos" :[{
    "allToBackup" : true,
    "extensionName" : "BackupExtensionAbility",
    "name" : "com.example.hiworld",
    "needToInstall" : false,
    "spaceOccupied" : 0,
    "versionCode" : 1000000,
    "versionName" : "1.0.0"
    }],
  "deviceType" : "phone",
  "systemFullName" : "OpenHarmony-4.0.0.0"
 }
 ```

## SessionBackup

备份流程对象，用来支撑应用备份的流程。在使用前，需要先创建SessionBackup实例。

### constructor

constructor(callbacks: GeneralCallbacks);

备份流程的构造函数，用于获取SessionBackup类的实例。

**需要权限**：ohos.permission.BACKUP

**系统能力**：SystemCapability.FileManagement.StorageService.Backup

**参数：**

| 参数名   | 类型                                  | 必填 | 说明                 |
| -------- | ------------------------------------- | ---- | -------------------- |
| callback | [GeneralCallbacks](#generalcallbacks) | 是   | 备份流程所需的回调。 |

**示例：**

  ```js
  import fs from '@ohos.file.fs';
  let sessionBackup = new backup.SessionBackup({
    onFileReady: (err, file) => {
      if (err) {
        console.error('onFileReady failed with err: ' + err);
      }
      console.info('onFileReady success');
      fs.closeSync(file.fd);
    },
    onBundleBegin: (err, bundleName) => {
      if (err) {
        console.error('onBundleBegin failed with err: ' + err);
      }
      console.info('onBundleBegin success');
    },
    onBundleEnd: (err, bundleName) => {
      if (err) {
        console.error('onBundleEnd failed with err: ' + err);
      }
      console.info('onBundleEnd success');
    },
    onAllBundlesEnd: (err) => {
      if (err) {
        console.error('onAllBundlesEnd failed with err: ' + err);
      }
      console.info('onAllBundlesEnd success');
    },
    onBackupServiceDied: () => {
      console.info('service died');
    }
  });
  ```

### appendBundles

appendBundles(bundlesToBackup: string[], callback: AsyncCallback<void>): void;

添加需要备份的应用。当前整个流程中，在获取SessionBackup类的实例后只能调用一次。使用callback异步回调。

**需要权限**：ohos.permission.BACKUP

**系统能力**：SystemCapability.FileManagement.StorageService.Backup

**参数：**

| 参数名          | 类型                      | 必填 | 说明                                                           |
| --------------- | ------------------------- | ---- | -------------------------------------------------------------- |
| bundlesToBackup | string[]                  | 是   | 需要备份的应用名称的数组。                                     |
| callback        | AsyncCallback<void> | 是   | 回调函数。当添加备份应用成功，err为undefined，否则为错误对象。 |

**示例：**

  ```js
  try {
    sessionBackup.appendBundles(['com.example.hiworld'], (err) => {
      if (err) {
        console.error('appendBundles failed with err: ' + err);
      }
      console.info('appendBundles success');
    });
  } catch (err) {
    console.error('appendBundles failed with err: ' + err);
  }
  ```

### appendBundles

appendBundles(bundlesToBackup: string[]): Promise<void>;

添加需要备份的应用。当前整个流程中，在获取SessionBackup类的实例后只能调用一次。使用Promise异步回调。

**需要权限**：ohos.permission.BACKUP

**系统能力**：SystemCapability.FileManagement.StorageService.Backup

**参数：**

| 参数名          | 类型     | 必填 | 说明                       |
| --------------- | -------- | ---- | -------------------------- |
| bundlesToBackup | string[] | 是   | 需要备份的应用名称的数组。 |

**返回值：**

| 类型                | 说明                                   |
| ------------------- | -------------------------------------- |
| Promise<void> | Promise对象。无返回结果的Promise对象。 |

**示例：**

  ```js
  try {
    await sessionBackup.appendBundles(['com.example.hiworld']);
    console.info('appendBundles success');
  } catch (err) {
    console.error('appendBundles failed with err: ' + err);
  }
  ```

## SessionRestore

恢复流程对象，用来支撑应用恢复的流程。在使用前，需要先创建SessionRestore实例。

### constructor

constructor(callbacks: GeneralCallbacks);

恢复流程的构造函数，用于获取SessionRestore类的实例。

**需要权限**：ohos.permission.BACKUP

**系统能力**：SystemCapability.FileManagement.StorageService.Backup

**参数：**

| 参数名   | 类型                                  | 必填 | 说明                 |
| -------- | ------------------------------------- | ---- | -------------------- |
| callback | [GeneralCallbacks](#generalcallbacks) | 是   | 恢复流程所需的回调。 |

**示例：**

  ```js
  import fs from '@ohos.file.fs';
  let sessionRestore = new backup.SessionRestore({
    onFileReady: (err, file) => {
      if (err) {
        console.error('onFileReady failed with err: ' + err);
      }
      console.info('onFileReady success');
      fs.closeSync(file.fd);
    },
    onBundleBegin: (err, bundleName) => {
      if (err) {
        console.error('onBundleBegin failed with err: ' + err);
      }
      console.info('onBundleBegin success');
    },
    onBundleEnd: (err, bundleName) => {
      if (err) {
        console.error('onBundleEnd failed with err: ' + err);
      }
      console.info('onBundleEnd success');
    },
    onAllBundlesEnd: (err) => {
      if (err) {
        console.error('onAllBundlesEnd failed with err: ' + err);
      }
      console.info('onAllBundlesEnd success');
    },
    onRestoreServiceDied: () => {
      console.info('service died');
    }
  });
  ```

### appendBundles

appendBundles(remoteCapabilitiesFd: number, bundlesToBackup: string[], callback: AsyncCallback<void>): void;

添加需要恢复的应用。当前整个流程中，在获取SessionRestore类的实例后只能调用一次。使用callback异步回调。

> **说明：**
> - 服务在恢复时需要其能力文件进行相关校验。
> - 因此remoteCapabilitiesFd可通过备份端服务所提供的[getLocalCapabilities](#getlocalcapabilities)接口获取，可对其内容根据恢复应用的实际状况修改参数。也可通过getLocalCapabilities提供的json示例自行生成能力文件。

**需要权限**：ohos.permission.BACKUP

**系统能力**：SystemCapability.FileManagement.StorageService.Backup

**参数：**

| 参数名               | 类型                      | 必填 | 说明                                                           |
| -------------------- | ------------------------- | ---- | -------------------------------------------------------------- |
| remoteCapabilitiesFd | number                    | 是   | 用于恢复所需能力文件的文件描述符。                             |
| bundlesToBackup      | string[]                  | 是   | 需要恢复的应用名称的数组。                                     |
| callback             | AsyncCallback<void> | 是   | 回调函数。当添加恢复应用成功，err为undefined，否则为错误对象。 |

**示例：**

  ```js
  try {
    let fileData = await backup.getLocalCapabilities();
    console.info('getLocalCapabilities success');
    sessionRestore.appendBundles(fileData.fd, ['com.example.hiworld'], (err) => {
      if (err) {
        console.error('appendBundles failed with err: ' + err);
      }
      console.info('appendBundles success');
    });
  } catch (err) {
    console.error('appendBundles failed with err: ' + err);
  }
  ```

### appendBundles

appendBundles(remoteCapabilitiesFd: number, bundlesToBackup: string[]): Promise<void>;

添加需要恢复的应用。当前整个流程中，在获取SessionRestore类的实例后只能调用一次。使用Promise异步回调。

> **说明：**
> - 服务在恢复时需要其能力文件进行相关校验。
> - 因此remoteCapabilitiesFd可通过备份端服务所提供的[getLocalCapabilities](#getlocalcapabilities)接口获取，可对其内容根据恢复应用的实际状况修改参数。也可通过getLocalCapabilities提供的json示例自行生成能力文件。

**需要权限**：ohos.permission.BACKUP

**系统能力**：SystemCapability.FileManagement.StorageService.Backup

**参数：**

| 参数名               | 类型     | 必填 | 说明                               |
| -------------------- | -------- | ---- | ---------------------------------- |
| remoteCapabilitiesFd | number   | 是   | 用于恢复所需能力文件的文件描述符。 |
| bundlesToBackup      | string[] | 是   | 需要恢复的应用包名称的数组。       |

**返回值：**

| 类型                | 说明                                   |
| ------------------- | -------------------------------------- |
| Promise<void> | Promise对象。无返回结果的Promise对象。 |

**示例：**

  ```js
  try {
    let fileData = await backup.getLocalCapabilities();
    console.info('getLocalCapabilities success');
    await sessionRestore.appendBundles(fileData.fd, ['com.example.hiworld']);
    console.info('appendBundles success');
  } catch (err) {
    console.error('appendBundles failed with err: ' + err);
  }
  ```

### getFileHandle

getFileHandle(fileMeta: FileMeta, callback: AsyncCallback<void>): void;

用于请求从服务中获取共享文件。使用callback异步回调。

> **说明：**
> - 这个接口是零拷贝特性（减少不必要的内存拷贝，实现了更高效率的传输）的一部分。零拷贝方法可参考由[@ohos.file.fs](./js-apis-file-fs.md)提供的[fs.copyFile](js-apis-file-fs.md#fscopyfile)等相关零拷贝接口。
> - 使用getFileHandle前需要获取SessionRestore类的实例，并且成功通过appendBundles添加需要待恢复的应用。
> - 开发者可以通过onFileReady回调来获取文件句柄，当客户端完成文件操作时，需要使用publishFile来进行发布。
> - 根据所需要恢复的文件个数，可以多次调用getFileHandle。

**需要权限**：ohos.permission.BACKUP

**系统能力**：SystemCapability.FileManagement.StorageService.Backup

**参数：**

| 参数名   | 类型                      | 必填 | 说明                                                           |
| -------- | ------------------------- | ---- | -------------------------------------------------------------- |
| fileMeta | [FileMeta](#filemeta)     | 是   | 恢复文件的元数据。                                             |
| callback | AsyncCallback<void> | 是   | 回调函数。当请求文件句柄成功，err为undefined，否则为错误对象。 |

**示例：**

  ```js
  try {
    sessionRestore.getFileHandle({
      bundleName: "com.example.hiworld",
      uri: "test.txt"
      }, (err, file) => {
      if (err) {
        console.error('getFileHandle failed with err: ' + err);
      }
      console.info('getFileHandle success');
    });
  } catch (err) {
    console.error('getFileHandle failed with err: ' + err);
  }
  ```

### getFileHandle

getFileHandle(fileMeta: FileMeta): Promise<void>;

用于请求从服务中获取共享文件。使用Promise异步回调。

> **说明：**
> - 这个接口是零拷贝特性（减少不必要的内存拷贝，实现了更高效率的传输）的一部分。零拷贝方法可参考由[@ohos.file.fs](./js-apis-file-fs.md)提供的[fs.copyFile](js-apis-file-fs.md#fscopyfile)等相关零拷贝接口。
> - 使用getFileHandle前需要获取SessionRestore类的实例，并且成功通过appendBundles添加需要待恢复的应用。
> - 开发者可以通过onFileReady回调来获取文件句柄，当客户端完成文件操作时，需要使用publishFile来进行发布。
> - 根据所需要恢复的文件个数，可以多次调用getFileHandle。

**需要权限**：ohos.permission.BACKUP

**系统能力**：SystemCapability.FileManagement.StorageService.Backup

**参数：**

| 参数名   | 类型                  | 必填 | 说明               |
| -------- | --------------------- | ---- | ------------------ |
| fileMeta | [FileMeta](#filemeta) | 是   | 恢复文件的元数据。 |

**返回值：**

| 类型                | 说明                                   |
| ------------------- | -------------------------------------- |
| Promise<void> | Promise对象。无返回结果的Promise对象。 |

**示例：**

  ```js
  try {
    await sessionRestore.getFileHandle({
      bundleName: "com.example.hiworld",
      uri: "test.txt"
      });
    console.info('getFileHandle success');
  } catch (err) {
    console.error('getFileHandle failed with err: ' + err);
  }
  ```

### publishFile

publishFile(fileMeta: FileMeta, callback: AsyncCallback<void>): void;

用于将FileMeta发布到备份服务，使服务知道文件的内容已经准备完成。使用callback异步回调。

> **说明：**
> - 这个接口是零拷贝特性（减少不必要的内存拷贝，实现了更高效率的传输）的一部分。零拷贝方法可参考由[@ohos.file.fs](./js-apis-file-fs.md)提供的[fs.copyFile](js-apis-file-fs.md#fscopyfile)等相关零拷贝接口。
> - 服务端通过onFileReady返回文件句柄后，客户端可通过零拷贝操作将其对应的文件内容拷贝到服务端提供的文件句柄中。
> - 在完成拷贝操作后可使用publishFile通知备份服务文件已经准备完成。

**需要权限**：ohos.permission.BACKUP

**系统能力**：SystemCapability.FileManagement.StorageService.Backup

**参数：**

| 参数名   | 类型                      | 必填 | 说明                                                       |
| -------- | ------------------------- | ---- | ---------------------------------------------------------- |
| fileMeta | [FileMeta](#filemeta)     | 是   | 恢复文件元数据。                                           |
| callback | AsyncCallback<void> | 是   | 回调函数。当发布文件成功，err为undefined，否则为错误对象。 |

**示例：**

  ```js
  try {
    onFileReady: (err, file) => {
      if (err) {
        console.error('onFileReady failed with err: ' + err);
      }
      console.info('onFileReady success');
      fs.closeSync(file.fd);
      sessionRestore.publishFile({
      bundleName: file.bundleName,
      uri: file.uri
      }, (err) => {
        if (err) {
          console.error('publishFile failed with err: ' + err);
        }
        console.info('publishFile success');
      });
    }
  } catch (err) {
    console.error('publishFile failed with err: ' + err);
  }
  ```

### publishFile

publishFile(fileMeta: FileMeta): Promise<void>;

用于将FileMeta发布到备份服务，使服务知道文件的内容已经准备完成。使用Promise异步回调。

> **说明：**
> - 这个接口是零拷贝特性（减少不必要的内存拷贝，实现了更高效率的传输）的一部分。零拷贝方法可参考由[@ohos.file.fs](./js-apis-file-fs.md)提供的[fs.copyFile](js-apis-file-fs.md#fscopyfile)等相关零拷贝接口。
> - 服务端通过onFileReady返回文件句柄后，客户端可通过零拷贝操作将其对应的文件内容拷贝到服务端提供的文件句柄中。
> - 在完成拷贝操作后可使用publishFile通知备份服务文件已经准备完成。

**需要权限**：ohos.permission.BACKUP

**系统能力**：SystemCapability.FileManagement.StorageService.Backup

**参数：**

| 参数名   | 类型                  | 必填 | 说明             |
| -------- | --------------------- | ---- | ---------------- |
| fileMeta | [FileMeta](#filemeta) | 是   | 恢复文件元数据。 |

**返回值：**

| 类型                | 说明                                   |
| ------------------- | -------------------------------------- |
| Promise<void> | Promise对象。无返回结果的Promise对象。 |

**示例：**

  ```js
  try {
    onFileReady: (err, file) => {
      if (err) {
        console.error('onFileReady failed with err: ' + err);
      }
      console.info('onFileReady success');
      fs.closeSync(file.fd);
      await sessionRestore.publishFile({
      bundleName: file.bundleName,
      uri: file.uri
      });
      console.info('publishFile success');
    },
  } catch (err) {
    console.error('publishFile failed with err: ' + err);
  }
  ```