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 and cannot be called by third-party applications.

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 bundle from '@ohos.bundle';
let hapFilePaths = ['/data/storage/el2/base/haps/entry/files/'];
let installParam = {
    userId: 100,
    isKeepData: false,
    installFlag: 1,
};

bundle.getBundleInstaller().then(installer => {
    installer.install(hapFilePaths, installParam, err => {
        if (err) {
            console.error('install failed:' + JSON.stringify(err));
        } else {
            console.info('install successfully.');
        }
    });
}).catch(error => {
    console.error('getBundleInstaller failed. Cause: ' + error.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 and cannot be called by third-party applications.

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 bundle from '@ohos.bundle';
let bundleName = 'com.example.myapplication';
let installParam = {
    userId: 100,
    isKeepData: false,
    installFlag: 1,
};

bundle.getBundleInstaller().then(installer => {
    installer.uninstall(bundleName, installParam, err => {
        if (err) {
            console.error('uninstall failed:' + JSON.stringify(err));
        } else {
            console.info('uninstall successfully.');
        }
    });
}).catch(error => {
    console.error('getBundleInstaller failed. Cause: ' + error.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 and cannot be called by third-party applications.

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 bundle from '@ohos.bundle';

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

bundle.getBundleInstaller().then(installer => {
    installer.recover(bundleName, installParam, err => {
        if (err) {
            console.error('recover failed:' + JSON.stringify(err));
        } else {
            console.info('recover successfully.');
        }
    });
}).catch(error => {
    console.error('getBundleInstaller failed. Cause: ' + error.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 and cannot be called by third-party applications.

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 and cannot be called by third-party applications.

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: Uninstallation failed. (The application to be uninstalled is not found.)
STATUS_UNINSTALL_FAILURE_ABORTED: Uninstallation aborted. (This error code is not in use.)
STATUS_UNINSTALL_FAILURE_ABORTED: Uninstallation 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 uninstallation 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);
});