目录

@ohos.application.BackupExtensionAbility (Backup and Restore Extension Capability)

The BackupExtensionAbility module provides the extension capability for the backup and restoration service. After an app integrates this capability, the system backup and restoration framework can schedule the backup, restoration, progress reporting, and secure exit logic to meet the requirements of app data migration, version compatibility processing, and temporary file cleanup. This improves data migration continuity and simplifies management of the backup and restoration process.

  • 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.

Constraints

To ensure system security and stability and prevent BackupExtensionAbility from abusing system resources, the system restricts its capabilities. Referencing certain modules is not supported. For details, please refer to the Appendix.

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

Name Type Read-Only Optional Description
code number No No Internal version number of the application.
name string No No Version name of the application.

BackupExtensionAbility

You can use BackupExtensionAbility to enable an app to access the backup and restore framework. You can use onBackup or onBackupEx to implement custom backup, onRestore or onRestoreEx to implement custom restoration, onProcess to report the app processing progress, and onRelease to execute the cleanup logic before the backup or restoration is complete. If onBackup and onBackupEx are rewritten at the same time, the framework preferentially calls onBackupEx. If onRestore and onRestoreEx are rewritten at the same time, the framework preferentially calls onRestoreEx.

[h2]Properties

System capability: SystemCapability.FileManagement.StorageService.Backup

Name Type Read-Only Optional Description
context11+ BackupExtensionContext No No Context of the BackupExtensionAbility. This context is inherited from ExtensionContext.

[h2]onBackup

onBackup(): void

Defines an extension lifecycle callback, which is called when data is being backed up. You can customize the backup data processing logic.

System capability: SystemCapability.FileManagement.StorageService.Backup

Example

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

[h2]onBackupEx12+

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

The backup and restoration framework passes extended parameters to the app during backup, allowing the app to perform custom backup processing based on the parameters. Compared with onBackup, onBackupEx can receive extended parameters, return processing results, and support asynchronous operations. Use onBackupEx when you need to process extended parameters from the caller or return the backup result. Use onBackup when you only need to execute the basic backup logic. This API 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

Name Type Mandatory Description
backupInfo string Yes Extended information transferred by the framework to the app during backup. The value is a string in JSON format.

Return value

Type Description
string | Promise<string>

Information about the app's custom backup operation. The return value is a JSON format string containing the type, errorCode, and errorInfo fields, which are filled in by the app based on the business processing result.

Promise<string> is returned asynchronously.

A string is returned for synchronous operations.

The following shows the sample code for synchronous implementation.

Example

import { BackupExtensionAbility } from '@kit.CoreFileKit';
import { BusinessError } from '@kit.BasicServicesKit';

interface ErrorInfo {
  type: string,
  errorCode: number,
  errorInfo: string
}
class BackupExt extends BackupExtensionAbility {
  onBackupEx(backupInfo: string): string {
    try {
      if (backupInfo == '') {
        // If backupInfo is empty, the application processes the data based on the service.
        console.info('backupInfo is empty');
      }
      console.info(`onBackupEx ok`);
      let errorInfo: ErrorInfo = {
        type: 'ErrorInfo',
        errorCode: 0,
        errorInfo: 'app customized error info'
      }
      return JSON.stringify(errorInfo);
    } catch (err) {
      let error: BusinessError = err as BusinessError;
      console.error(`BackupExt error. Code:${error.code}, message:${error.message}`);
      let errorInfo: ErrorInfo = {
        type: 'ErrorInfo',
        errorCode: error.code,
        errorInfo: error.message
      }
      return JSON.stringify(errorInfo);
    }
  }
}

The following shows the sample code for asynchronous implementation.

Example

import { BackupExtensionAbility } from '@kit.CoreFileKit';
import { BusinessError } from '@kit.BasicServicesKit';

interface ErrorInfo {
  type: string,
  errorCode: number,
  errorInfo: string
}
class BackupExt extends BackupExtensionAbility {
  // Asynchronous implementation
  async onBackupEx(backupInfo: string): Promise<string> {
    try {
      if (backupInfo == '') {
        // If backupInfo is empty, the application processes the data based on the service.
        console.info('backupInfo is empty');
      }
      console.info(`onBackupEx ok`);
      let errorInfo: ErrorInfo = {
        type: 'ErrorInfo',
        errorCode: 0,
        errorInfo: 'app customized error info'
      }
      return JSON.stringify(errorInfo);
    } catch (err) {
      let error: BusinessError = err as BusinessError;
      console.error(`BackupExt error. Code:${error.code}, message:${error.message}`);
      let errorInfo: ErrorInfo = {
        type: 'ErrorInfo',
        errorCode: error.code,
        errorInfo: error.message
      }
      return JSON.stringify(errorInfo);
    }
  }
}

[h2]onRestore

onRestore(bundleVersion: BundleVersion): void

Defines an extension lifecycle callback, which is called when data is being restored. You need to implement the extended data restore operation.

System capability: SystemCapability.FileManagement.StorageService.Backup

Parameters

Name Type Mandatory Description
bundleVersion BundleVersion Yes Version information of the application data to be restored.

Example

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

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

[h2]onRestoreEx12+

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

Defines an extension lifecycle callback, which is called when data is being restored. You need to implement the custom data restore operation. Compared with onRestore, onRestoreEx can receive extended parameters, return processing results, and support asynchronous operations. Use onRestoreEx when you need to process extended parameters from the caller or return the restore result. Use onRestore when you only need to execute the basic restore logic. This API 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

Name Type Mandatory Description
bundleVersion BundleVersion Yes Version information of the app data to be restored.
restoreInfo string Yes Extended information transferred by the framework to the app during restoration. The value is a string in JSON format.

Return value

Type Description
string | Promise<string>

Information about the app's custom restore operation. The return value is a JSON format string containing the type, errorCode, and errorInfo fields, which are filled in by the app based on the business processing result.

Promise<string> is returned asynchronously.

A string is returned for synchronous operations.

The following shows the sample code for asynchronous implementation.

Example

import { BackupExtensionAbility, BundleVersion } from '@kit.CoreFileKit';
import { BusinessError } from '@kit.BasicServicesKit';
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 == '') {
        // If restoreInfo is empty, the application processes the data based on the service.
        console.info('restoreInfo is empty');
      }
      console.info(`onRestoreEx ok ${JSON.stringify(bundleVersion)}`);
      let errorInfo: ErrorInfo = {
        type: 'ErrorInfo',
        errorCode: 0,
        errorInfo: 'app customized error info'
      }
      return JSON.stringify(errorInfo);
    } catch (err) {
      let error: BusinessError = err as BusinessError;
      console.error(`onRestoreEx error. Code:${error.code}, message:${error.message}`);
      let errorInfo: ErrorInfo = {
        type: 'ErrorInfo',
        errorCode: error.code,
        errorInfo: error.message
      }
      return JSON.stringify(errorInfo);
    }
  }
}

The following shows the sample code for synchronous implementation.

Example

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

class BackupExt extends BackupExtensionAbility {
  // Synchronous implementation
  onRestoreEx(bundleVersion : BundleVersion, restoreInfo: string): string {
    try {
      if (restoreInfo == '') {
        // If restoreInfo is empty, the application processes the data based on the service.
        console.info('restoreInfo is empty');
      }
      console.info(`onRestoreEx ok ${JSON.stringify(bundleVersion)}`);
      let errorInfo: ErrorInfo = {
        type: 'ErrorInfo',
        errorCode: 0,
        errorInfo: 'app customized error info'
      }
      return JSON.stringify(errorInfo);
    } catch (err) {
      let error: BusinessError = err as BusinessError;
      console.error(`onRestoreEx error. Code:${error.code}, message:${error.message}`);
      let errorInfo: ErrorInfo = {
        type: 'ErrorInfo',
        errorCode: error.code,
        errorInfo: error.message
      }
      return JSON.stringify(errorInfo);
    }
  }
}

[h2]onProcess12+

onProcess(): string

Adds an API to the backup and restoration framework 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

Type Description
string Progress information during the execution of onBackup or onRestore. The return value is in JSON format. The JSON structure contains the name, processed, total, and isPercentage fields. For details, see the sample code.
  • If it is not implemented, the system reports only the backup and restoration progress that can be obtained on the framework, excluding the custom service processing progress of the app. If onProcess is used, the return value must strictly comply with that in the sample code.
  • The execution of onProcess cannot exceed 1 second. The system calls onProcess every 5 seconds. If the execution times out for three consecutive times, the current backup or restoration task of the application is terminated.
  • 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 } from '@kit.CoreFileKit';
import { taskpool } from '@kit.ArkTS';
import { BusinessError } from '@kit.BasicServicesKit';

@Sendable
class MigrateProgressInfo {
  private migrateProgress: string = '';
  private name: string = 'test'; // appName
  private processed: number = 0; // Processed data
  private total: number = 100; // Total number
  private isPercentage: boolean = true // (Optional) The value true means to display the progress in percentage; the value false or an unimplemented field means to display the progress by the number of items.

  getMigrateProgress(): string {
    this.migrateProgress = `{"progressInfo": [{"name": ${this.name}, "processed": ${this.processed}, "total": ${
      this.total}, "isPercentage": ${this.isPercentage}}]}`;
    return this.migrateProgress;
  }

  updateProcessed(processed: number) {
    this.processed = processed;
  }
}

class BackupExt extends BackupExtensionAbility {
  private progressInfo: MigrateProgressInfo = new MigrateProgressInfo();

  // 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.info(`onBackup begin`);
    let args = 100; // args is a parameter of appJob().
    let jobTask: taskpool.Task = new taskpool.LongTask(appJob, this.progressInfo, args);
    try {
      await taskpool.execute(jobTask, taskpool.Priority.LOW);
    } catch (error) {
      let err: BusinessError = error as BusinessError;
      console.error(`onBackup error. Code: ${err.code}, message: ${err.message}`);
    }
    taskpool.terminateTask(jobTask); // Manually destroy the task.
    console.info(`onBackup end`);
  }

  async onRestore() {
    console.info(`onRestore begin`);
    let args = 100; // args is a parameter of appJob().
    let jobTask: taskpool.Task = new taskpool.LongTask(appJob, this.progressInfo, args);
    try {
      await taskpool.execute(jobTask, taskpool.Priority.LOW);
    } catch (error) {
      let err: BusinessError = error as BusinessError;
      console.error(`onRestore error. Code: ${err.code}, message: ${err.message}`);
    }
    taskpool.terminateTask(jobTask); // Manually destroy the task.
    console.info(`onRestore end`);
  }
 

  onProcess(): string {
    console.info(`onProcess begin`);
    return this.progressInfo.getMigrateProgress();
  }
}

@Concurrent
function appJob(progressInfo: MigrateProgressInfo, args: number) : string {
  console.info(`appJob begin, args is: ` + args);
  // Update the processing progress during service execution.
  let currentProcessed: number = 0;
  // Simulate the actual service logic.
  for (let i = 0; i < args; i++) {
    currentProcessed = i;
    progressInfo.updateProcessed(currentProcessed);
  }
  return 'ok';
}

[h2]onRelease20+

onRelease(scenario: number): Promise<void>

Provides secure exit APIs of the backup and restore framework. It is triggered when the application backup or restore is complete, allowing the application to perform special processing afterward, such as removing temporary files generated during these operations. This API uses a promise to return the result.

onRelease has a timeout mechanism. If the onRelease operation is not completed within 5 seconds, the application process exits when the backup and restoration are complete.

System capability: SystemCapability.FileManagement.StorageService.Backup

Parameters

Name Type Mandatory Description
scenario number Yes

The system passes this parameter based on the current operation scenario. Developers execute the corresponding cleanup logic based on the parameter value.

The value 1 indicates the backup scenario.

The value 2 indicates the restore scenario.

Return value

Type Description
Promise<void> Promise that returns no value.

Example

// The following describes an example of removing files.
import { BackupExtensionAbility, fileIo } from '@kit.CoreFileKit';
import { BusinessError } from '@kit.BasicServicesKit';

const SCENARIO_BACKUP: number = 1;
const SCENARIO_RESTORE: number = 2;
// Temporary directory to be removed.
let filePath: string = '/data/storage/el2/base/.temp/';

class BackupExt extends BackupExtensionAbility {
  async onRelease(scenario: number): Promise<void> {
    try {
      if (scenario == SCENARIO_BACKUP) {
        // In the backup scenario, the application implements the processing. The following describes how to remove temporary files generated during backup.
        console.info(`onRelease begin`);
        await fileIo.rmdir(filePath);
        console.info(`onRelease end, rmdir succeed`);
      }
      if (scenario == SCENARIO_RESTORE) {
        // In the restore scenario, the application implements the processing. The following describes how to remove temporary files generated during restoration.
        console.info(`onRelease begin`);
        await fileIo.rmdir(filePath);
        console.info(`onRelease end, rmdir succeed`);
      }
    } catch (error) {
      let err: BusinessError = error as BusinessError;
      console.error(`onRelease failed with error. Code: ${err.code}, message: ${err.message}`);
    }
  }
}

Appendix

BackupExtensionAbility does not support referencing the following modules.

Kit Module
Ability Kit @ohos.abilityAccessCtrl (Application Access Control)
Ability Kit @ohos.app.ability.appManager (Application Management)
Ability Kit @ohos.bundle.defaultAppManager (Default Application Management)
Ability Kit @ohos.bundle.launcherBundleManager (launcherBundleManager Module)
Ability Kit UIAbilityContext
ArkUI @ohos.screenshot (Screenshot)
Background Tasks Kit @ohos.bundleState (Device Usage Statistics)
Background Tasks Kit @ohos.reminderAgent (Agent-powered Reminder)
Background Tasks Kit @ohos.reminderAgentManager (Agent-powered Reminder)
Basic Services Kit @ohos.power (System Power Management)
Connectivity Kit @ohos.nfc.cardEmulation (Standard NFC Card Emulation)
Form Kit @ohos.application.formError (formError)
IME Kit @ohos.inputMethod (Input Method Framework)
Location Kit @ohos.geolocation (Geolocation)
MDM Kit @ohos.enterprise.adminManager (Administrator Permission Management)
Sensor Service Kit @ohos.sensor (Sensor)