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';
export default class EntryAbility extends UIAbility {
    onWindowStageCreate(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) => {
    let pathDir = data;
    console.info('sandbox path is ' + pathDir);
});