BundleInstaller

The BundleInstaller module provides APIs for you to install, uninstall, and recover bundles on devices.

NOTE

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

BundleInstaller.install(deprecated)

This API is deprecated since API version 9. You are advised to use @ohos.bundle.installer.install instead.

install(bundleFilePaths: Array<string>, param: InstallParam, callback: AsyncCallback<InstallStatus>): void;

Installs a bundle. Multiple HAP files can be installed. This API uses an asynchronous callback to return the result.

Required permissions

ohos.permission.INSTALL_BUNDLE

System capability

SystemCapability.BundleManager.BundleFramework

System API: This is a system API.

Parameters

Name Type Mandatory Description
bundleFilePaths Array<string> Yes Sandbox path where the HAP files of the bundle are stored. For details about how to obtain the sandbox path, see Obtaining the Sandbox Path.
param InstallParam Yes Parameters required for bundle installation.
callback AsyncCallback<InstallStatus> Yes Callback used to return the installation status.

Example

import bundleInstall from '@ohos.bundle.installer';
import { BusinessError } from '@ohos.base';

let hapFilePaths: Array<string> = ['/data/storage/el2/base/haps/entry/files/'];
let installParam: bundleInstall.InstallParam = {
  userId: 100,
  isKeepData: false,
  installFlag: 1,
};

bundleInstall.getBundleInstaller().then(installer => {
  installer.install(hapFilePaths, installParam, err => {
    if (err) {
      console.error('install failed:' + JSON.stringify(err));
    } else {
      console.info('install successfully.');
    }
  });
}).catch((error: BusinessError)=> {
  let message = (error as BusinessError).message;
  console.error('getBundleInstaller failed. Cause: ' + message);
});

BundleInstaller.uninstall(deprecated)

This API is deprecated since API version 9. You are advised to use uninstall instead.

uninstall(bundleName: string, param: InstallParam, callback: AsyncCallback<InstallStatus>): void;

Uninstalls a bundle. This API uses an asynchronous callback to return the result.

Required permissions

ohos.permission.INSTALL_BUNDLE

System capability

SystemCapability.BundleManager.BundleFramework

System API: This is a system API.

Parameters

Name Type Mandatory Description
bundleName string Yes Bundle name.
param InstallParam Yes Parameters required for bundle uninstall.
callback AsyncCallback<InstallStatus> Yes Callback used to return the installation status.

Example

import bundleInstall from '@ohos.bundle.installer';
import { BusinessError } from '@ohos.base';

let bundleName: string = 'com.example.myapplication';
let installParam: bundleInstall.InstallParam = {
  userId: 100,
  isKeepData: false,
  installFlag: 1,
};

bundleInstall.getBundleInstaller().then(installer => {
  installer.uninstall(bundleName, installParam, err => {
    if (err) {
      console.error('uninstall failed:' + JSON.stringify(err));
    } else {
      console.info('uninstall successfully.');
    }
  });
}).catch((error: BusinessError) => {
  let message = (error as BusinessError).message;
  console.error('getBundleInstaller failed. Cause: ' + message);
});

BundleInstaller.recover(deprecated)

This API is deprecated since API version 9. You are advised to use recover instead.

recover(bundleName: string, param: InstallParam, callback: AsyncCallback<InstallStatus>): void;

Recovers a bundle. This API uses an asynchronous callback to return the result. After a pre-installed bundle is uninstalled, you can call this API to recover it.

Required permissions

ohos.permission.INSTALL_BUNDLE

System capability

SystemCapability.BundleManager.BundleFramework

System API: This is a system API.

Parameters

Name Type Mandatory Description
bundleName string Yes Bundle name.
param InstallParam Yes Parameters required for bundle recovery.
callback AsyncCallback<InstallStatus> Yes Callback used to return the recovery status.

Example

import bundleInstall from '@ohos.bundle.installer';
import { BusinessError } from '@ohos.base';

let bundleName: string = 'com.example.myapplication';
let installParam: bundleInstall.InstallParam = {
  userId: 100,
  isKeepData: false,
  installFlag: 1,
};

bundleInstall.getBundleInstaller().then(installer => {
  installer.uninstall(bundleName, installParam, err => {
    if (err) {
      console.error('uninstall failed:' + JSON.stringify(err));
    } else {
      console.info('uninstall successfully.');
    }
  });
}).catch((error: BusinessError) => {
  let message = (error as BusinessError).message;
  console.error('getBundleInstaller failed. Cause: ' + message);
});

InstallParam(deprecated)

Describes the parameters required for bundle installation, recovery, or uninstall.

System capability: SystemCapability.BundleManager.BundleFramework

System API: This is a system API.

Name Type Readable Writable Description
userId number Yes Yes User ID. The default value is the user ID of the caller.
installFlag number Yes Yes Installation flag.
1 (default): overwrite installation.
16: installation-free.
isKeepData boolean Yes Yes Whether data is kept. The default value is false.

InstallStatus(deprecated)

Describes the bundle installation or uninstall status.

System capability: SystemCapability.BundleManager.BundleFramework

System API: This is a system API.

Name Type Readable Writable Description
status bundle.InstallErrorCode Yes No Installation or uninstall error code. The value must be defined in InstallErrorCode.
statusMessage string Yes No Installation or uninstall status message.
SUCCESS: install_succeed
STATUS_INSTALL_FAILURE: Installation failed (no installation file exists).
STATUS_INSTALL_FAILURE_ABORTED: Installation aborted.
STATUS_INSTALL_FAILURE_INVALID: Invalid installation parameter.
STATUS_INSTALL_FAILURE_CONFLICT: Installation conflict. (The basic information of the application to update is inconsistent with that of the existing application.)
STATUS_INSTALL_FAILURE_STORAGE: Failed to store the bundle information.
STATUS_INSTALL_FAILURE_INCOMPATIBLE: Installation incompatibility. (A downgrade occurs or the signature information is incorrect.)
STATUS_UNINSTALL_FAILURE: Uninstall failed. (The application to be uninstalled is not found.)
STATUS_UNINSTALL_FAILURE_ABORTED: Uninstall aborted. (This error code is not in use.)
STATUS_UNINSTALL_FAILURE_ABORTED: Uninstall conflict. (Failed to uninstall a system application or end the application process.)
STATUS_INSTALL_FAILURE_DOWNLOAD_TIMEOUT: Installation failed. (Download timed out.)
STATUS_INSTALL_FAILURE_DOWNLOAD_FAILED: Installation failed. (Download failed.)
STATUS_RECOVER_FAILURE_INVALID: Failed to restore the pre-installed application.
STATUS_ABILITY_NOT_FOUND: Ability not found.
STATUS_BMS_SERVICE_ERROR: BMS service error.
STATUS_FAILED_NO_SPACE_LEFT: Insufficient device space.
STATUS_GRANT_REQUEST_PERMISSIONS_FAILED: Application authorization failed.
STATUS_INSTALL_PERMISSION_DENIED: No installation permission.
STATUS_UNINSTALL_PERMISSION_DENIED: No uninstall permission.

Obtaining the Sandbox Path

For the FA model, the sandbox path of a bundle can be obtained using the APIs in Context. For the stage model, the sandbox path can be obtained using the attribute in Context. The following describes how to obtain the sandbox path.

Example

// Stage model
import UIAbility from '@ohos.app.ability.UIAbility';
import window from '@ohos.window';
export default class EntryAbility extends UIAbility {
    onWindowStageCreate(windowStage: window.WindowStage) {
        let context = this.context;
        let pathDir = context.filesDir;
        console.info('sandbox path is ' + pathDir);
    }
}

// FA model
import featureAbility from '@ohos.ability.featureAbility';
let context = featureAbility.getContext();
context.getFilesDir().then((data: string) => {
    let pathDir = data;
    console.info('sandbox path is ' + pathDir);
});