@ohos.application.BackupExtensionAbility (BackupExtensionAbility)

The BackupExtensionAbility module provides extended backup and restore capabilities for applications.

NOTE

• The initial APIs of this module are supported since API version 10. Newly added APIs will be marked with a superscript to indicate their earliest API version.

• The APIs of this module can be used only in the stage model.

Modules to Import

import { BackupExtensionAbility, BundleVersion } from '@kit.CoreFileKit';

BundleVersion

Defines the version information required for data restore. You can determine the application data to be restored based on the version information.

System capability: SystemCapability.FileManagement.StorageService.Backup

BackupExtensionAbility

Implements backup and restore for application access data. You can use onBackup and onRestore to implement custom backup and restore operations.

Properties

System capability: SystemCapability.FileManagement.StorageService.Backup

onBackup

onBackup(): void

Called when data is being backed up. You need to implement extended data backup operations.

System capability: SystemCapability.FileManagement.StorageService.Backup

Example

  class BackupExt extends BackupExtensionAbility {
    async onBackup() {
      console.log('onBackup');
    }
  }

onBackupEx¹²⁺

onBackupEx(backupInfo: string): string|Promise<string>

Called to pass parameters to the application during the application backup or restore process. It uses a promise to return the result.
onBackupEx and onBackup are mutually exclusive. Call onBackupEx preferentially if it is overridden.
The return value of onBackupEx cannot be an empty string. If an empty string is returned, onBackup will be called.

System capability: SystemCapability.FileManagement.StorageService.Backup

Parameters

Return value

NOTE

The following shows the sample code for synchronous implementation.

Example

import { BackupExtensionAbility, BundleVersion } from '@kit.CoreFileKit';

interface ErrorInfo {
  type: string,
  errorCode: number,
  errorInfo: string
}
class BackupExt extends BackupExtensionAbility {
  onBackupEx(backupInfo: string): string {
    try {
      if (backupInfo == "") {
        // When backupInfo is empty, you need to handle this based on the service logic of the application.
        console.info("backupInfo is empty");
      }
      console.log(`onBackupEx ok`);
      let errorInfo: ErrorInfo = {
        type: "ErrorInfo",
        errorCode: 0,
        errorInfo: "app customized error info"
      }
      return JSON.stringify(errorInfo);
    } catch (err) {
      console.error(`BackupExt error. Code:${err.code}, message:${err.message}`);
    }
    return "";
  }
} 

NOTE

The following shows the sample code for asynchronous implementation.

Example

import { BackupExtensionAbility, BundleVersion } from '@kit.CoreFileKit';

interface ErrorInfo {
  type: string,
  errorCode: number,
  errorInfo: string
}
class BackupExt extends BackupExtensionAbility {
  // Asynchronous implementation.
  async onBackupEx(backupInfo: string): Promise<string> {
    try {
      if (backupInfo == "") {
        // When backupInfo is empty, you need to handle this based on the service logic of the application.
        console.info("backupInfo is empty");
      }
      console.log(`onBackupEx ok`);
      let errorInfo: ErrorInfo = {
        type: "ErrorInfo",
        errorCode: 0,
        errorInfo: "app customized error info"
      }
      return JSON.stringify(errorInfo);
    } catch (err) {
      console.error(`BackupExt error. Code:${err.code}, message:${err.message}`);
    }
    return "";
  }
} 

onRestore

onRestore(bundleVersion: BundleVersion): void

Called when data is being restored. You need to implement the extended data restore operation.

System capability: SystemCapability.FileManagement.StorageService.Backup

Parameters

Example

  import { BackupExtensionAbility, BundleVersion } from '@kit.CoreFileKit';

  class BackupExt extends BackupExtensionAbility {
    async onRestore(bundleVersion : BundleVersion) {
      console.log(`onRestore ok ${JSON.stringify(bundleVersion)}`);
    }
  }

onRestoreEx¹²⁺

onRestoreEx(bundleVersion: BundleVersion, restoreInfo: string): string|Promise<string>

Called when data is being restored. You need to implement the extended data restore operation. It uses a promise to return the result.
onRestoreEx and onRestore are mutually exclusive. Call onRestoreEx preferentially if it is overridden.
The return value of onRestoreEx cannot be an empty string. If an empty string is returned, the system will attempt to call onRestore.
The return value of onRestoreEx is in JSON format. For details, see the sample code.

System capability: SystemCapability.FileManagement.StorageService.Backup

Parameters

Return value

NOTE

The following shows the sample code for asynchronous implementation.

Example

import { BackupExtensionAbility, BundleVersion } from '@kit.CoreFileKit';
interface ErrorInfo {
  type: string,
  errorCode: number,
  errorInfo: string
}
class BackupExt extends BackupExtensionAbility {
  // Asynchronous implementation
  async onRestoreEx(bundleVersion : BundleVersion, restoreInfo: string): Promise<string> {
    try {
      if (restoreInfo == "") {
        // When restoreInfo is empty, you need to handle this based on the service logic of the application.
        console.info("restoreInfo is empty");
      }
      console.log(`onRestoreEx ok ${JSON.stringify(bundleVersion)}`);
      let errorInfo: ErrorInfo = {
        type: "ErrorInfo",
        errorCode: 0,
        errorInfo: "app customized error info"
      }
      return JSON.stringify(errorInfo);
    } catch (err) {
      console.error(`onRestoreEx error. Code:${err.code}, message:${err.message}`);
    }
    return "";
  }
}

NOTE

The following shows the sample code for synchronous implementation.

Example

import { BackupExtensionAbility, BundleVersion } from '@kit.CoreFileKit';
interface ErrorInfo {
  type: string,
  errorCode: number,
  errorInfo: string
}

class BackupExt extends BackupExtensionAbility {
  // Synchronous implementation
  onRestoreEx(bundleVersion : BundleVersion, restoreInfo: string): string {
    try {
      if (restoreInfo == "") {
        // When restoreInfo is empty, you need to handle this based on the service logic of the application.
        console.info("restoreInfo is empty");
      }
      console.log(`onRestoreEx ok ${JSON.stringify(bundleVersion)}`);
      let errorInfo: ErrorInfo = {
        type: "ErrorInfo",
        errorCode: 0,
        errorInfo: "app customized error info"
      }
      return JSON.stringify(errorInfo);
    } catch (err) {
      console.error(`onRestoreEx error. Code:${err.code}, message:${err.message}`);
    }
    return "";
  }
}

onProcess¹²⁺

onProcess(): string

Called to return the progress information. This callback is executed synchronously and implemented during the execution of onBackup/onBackupEx or onRestore/onRestoreEx. This callback returns the service processing progress of the application. The return value is in JSON format. For details, see the sample code.

System capability: SystemCapability.FileManagement.StorageService.Backup

Return value

NOTE

• The system provides the default processing mechanism if onProcess is not implemented. If onProcess is used, the return value must strictly comply with that in the sample code.
• If onProcess is used, onBackup/onBackupEx and onRestore/onRestoreEx must be asynchronously executed in a dedicated thread. Otherwise, onProcess cannot run properly. For details, see the sample code.
• The following example shows the recommended use of onProcess().

Example

  import { BackupExtensionAbility, BundleVersion } from '@kit.CoreFileKit';
  import { taskpool } from '@kit.ArkTS';

  interface ProgressInfo {
    name: string, // appName
    processed: number, // Processed data records.
    total: number, // Total count.
    isPercentage: boolean // (Optional) The value true means to display the progress in percentage; the value false or not implemented means to display the progress by the number of items.
  }

  class BackupExt extends BackupExtensionAbility {
    // In the following code, the appJob method is the simulated service code, and args specifies the parameters of appJob(). This method is used to start a worker thread in the task pool.
    async onBackup() {
      console.log(`onBackup begin`);
      let args = 100; // args is a parameter of appJob().
      let jobTask: taskpool.Task = new taskpool.LongTask(appJob, args);
      try {
        await taskpool.execute(jobTask, taskpool.Priority.LOW);
      } catch (error) {
        console.error("onBackup error." + error.message);
      }
      taskpool.terminateTask(jobTask); // Manually destroy the task.
      console.log(`onBackup end`);
    }

    async onRestore() {
      console.log(`onRestore begin`);
      let args = 100; // args is a parameter of appJob().
      let jobTask: taskpool.Task = new taskpool.LongTask(appJob, args);
      try {
        await taskpool.execute(jobTask, taskpool.Priority.LOW);
      } catch (error) {
        console.error("onRestore error." + error.message);
      }
      taskpool.terminateTask(jobTask); // Manually destroy the task.
      console.log(`onRestore end`);
    }
 

    onProcess(): string {
      console.log(`onProcess begin`);
      let process: string = `{
       "progressInfo":[
         {
          "name": "callact", // appName
          "processed": 100, // Processed data records.
          "total": 1000, // Total count.
          "isPercentage", true // (Optional) The value true means to display the progress in percentage; the value false or not implemented means to display the progress by the number of items.
         }
       ]
      }`;
      console.log(`onProcess end`);
      return JSON.stringify(process);
    }
  }

  @Concurrent
  function appJob(args: number) : string {
    // Service logic.
    console.log(`appJob begin, args is: ` + args);
    return "ok";
  }

你可能感兴趣的鸿蒙文章

harmony 鸿蒙Core File Kit

harmony 鸿蒙Environment

harmony 鸿蒙FileIO

harmony 鸿蒙FileShare_PolicyErrorResult

harmony 鸿蒙FileShare_PolicyInfo

harmony 鸿蒙error_code.h

harmony 鸿蒙File Management Error Codes

harmony 鸿蒙FileShare

harmony 鸿蒙FileUri

harmony 鸿蒙@ohos.application.BackupExtensionAbility (Backup and Restore Extension Capability) (System API)