@ohos.bundle.launcherBundleManager (launcherBundleManager Module) (System API)

The module providers APIs for launcher applications (applications with icons on the home screen) to obtain the launcher ability information and shortcut information.

NOTE

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

The APIs provided by this module are system APIs.

Modules to Import

import { launcherBundleManager } from '@kit.AbilityKit';

launcherBundleManager.getLauncherAbilityInfo

getLauncherAbilityInfo(bundleName: string, userId: number, callback: AsyncCallback<Array<LauncherAbilityInfo>>) : void

Obtains the launcher ability information based on the given bundle name and user ID. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED

System API: This is a system API.

System capability: SystemCapability.BundleManager.BundleFramework.Launcher

Parameters

Name	Type	Mandatory	Description
bundleName	string	Yes	Bundle name.
userId	number	Yes	User ID, which can be obtained by calling getOsAccountLocalId.
callback	AsyncCallback<Array<LauncherAbilityInfo>>	Yes	Callback used to return the result. If the operation is successful, err is null, and data is the array of LauncherAbilityInfo objects obtained. Otherwise, err is an error object.

Error codes

For details about the error codes, see Universal Error Codes and Bundle Error Codes.

ID	Error Message
201	Verify permission denied.
202	Permission denied, non-system app called system api.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
801	Capability not support.
17700001	The specified bundle name is not found.
17700004	The specified user ID is not found.

Example

import { launcherBundleManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  launcherBundleManager.getLauncherAbilityInfo('com.example.demo', 100,
    (errData: BusinessError, data: launcherBundleManager.LauncherAbilityInfo[]) => {
      if (errData !== null) {
        console.error(`errData is errCode:${errData.code}  message:${errData.message}`);
      } else {
        console.info('data is ' + JSON.stringify(data));
      }
    })
} catch (errData) {
  let code = (errData as BusinessError).code;
  let message = (errData as BusinessError).message;
  console.error(`errData is errCode:${code}  message:${message}`);
}

launcherBundleManager.getLauncherAbilityInfo

getLauncherAbilityInfo(bundleName: string, userId: number) : Promise<Array<LauncherAbilityInfo>>

Obtains the launcher ability information based on the given bundle name and user ID. This API uses a promise to return the result.

Required permissions: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED

System API: This is a system API.

System capability: SystemCapability.BundleManager.BundleFramework.Launcher

Parameters

Name	Type	Mandatory	Description
bundleName	string	Yes	Bundle name.
userId	number	Yes	User ID, which can be obtained by calling getOsAccountLocalId.

Return value

Type	Description
Promise<Array<LauncherAbilityInfo>>	Promise used to return the array of LauncherAbilityInfo objects obtained.

Error codes

For details about the error codes, see Universal Error Codes and Bundle Error Codes.

ID	Error Message
201	Verify permission denied.
202	Permission denied, non-system app called system api.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
801	Capability not support.
17700001	The specified bundle name is not found.
17700004	The specified user ID is not found.

Example

import { launcherBundleManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  launcherBundleManager.getLauncherAbilityInfo("com.example.demo", 100)
    .then((data: launcherBundleManager.LauncherAbilityInfo[]) => {
      console.info('data is ' + JSON.stringify(data));
    }).catch((errData: BusinessError) => {
    console.error(`errData is errCode:${errData.code}  message:${errData.message}`);
  })
} catch (errData) {
  let code = (errData as BusinessError).code;
  let message = (errData as BusinessError).message;
  console.error(`errData is errCode:${code}  message:${message}`);
}

launcherBundleManager.getAllLauncherAbilityInfo

getAllLauncherAbilityInfo(userId: number, callback: AsyncCallback<Array<LauncherAbilityInfo>>) : void

Obtains the launcher ability information of all applications based on the given user ID. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED

System API: This is a system API.

System capability: SystemCapability.BundleManager.BundleFramework.Launcher

Parameters

Name	Type	Mandatory	Description
userId	number	Yes	User ID, which can be obtained by calling getOsAccountLocalId.
callback	AsyncCallback<Array<LauncherAbilityInfo>>	Yes	Callback used to return the result. If the operation is successful, err is null, and data is the array of LauncherAbilityInfo objects obtained. Otherwise, err is an error object.

Error codes

For details about the error codes, see Universal Error Codes and Bundle Error Codes.

ID	Error Message
201	Verify permission denied.
202	Permission denied, non-system app called system api.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
801	Capability not support.
17700004	The specified user ID is not found.

Example

import { launcherBundleManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  launcherBundleManager.getAllLauncherAbilityInfo(100,
    (errData: BusinessError, data: launcherBundleManager.LauncherAbilityInfo[]) => {
      if (errData !== null) {
        console.error(`errData is errCode:${errData.code}  message:${errData.message}`);
      } else {
        console.info('data is ' + JSON.stringify(data));
      }
    });
} catch (errData) {
  let code = (errData as BusinessError).code;
  let message = (errData as BusinessError).message;
  console.error(`errData is errCode:${code}  message:${message}`);
}

launcherBundleManager.getAllLauncherAbilityInfo

getAllLauncherAbilityInfo(userId: number) : Promise<Array<LauncherAbilityInfo>>

Obtains the launcher ability information of all applications based on the given user ID. This API uses a promise to return the result.

Required permissions: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED

System API: This is a system API.

System capability: SystemCapability.BundleManager.BundleFramework.Launcher

Parameters

Name	Type	Mandatory	Description
userId	number	Yes	User ID, which can be obtained by calling getOsAccountLocalId.

Return value

Type	Description
Promise<Array<LauncherAbilityInfo>>	Promise used to return the array of LauncherAbilityInfo objects obtained.

Error codes

For details about the error codes, see Universal Error Codes and Bundle Error Codes.

ID	Error Message
201	Verify permission denied.
202	Permission denied, non-system app called system api.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
801	Capability not support.
17700004	The specified user ID is not found.

Example

import { launcherBundleManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  launcherBundleManager.getAllLauncherAbilityInfo(100)
    .then((data: launcherBundleManager.LauncherAbilityInfo[]) => {
      console.info('data is ' + JSON.stringify(data));
    }).catch((errData: BusinessError) => {
    console.error(`errData is errCode:${errData.code}  message:${errData.message}`);
  });
} catch (errData) {
  let code = (errData as BusinessError).code;
  let message = (errData as BusinessError).message;
  console.error(`errData is errCode:${code}  message:${message}`);
}

launcherBundleManager.getShortcutInfo

getShortcutInfo(bundleName :string, callback: AsyncCallback<Array<ShortcutInfo>>) : void

Obtains the shortcut information of the current user based on the given bundle name of a main application. To obtain shortcut information about an application clone, use getShortcutInfoByAppIndex. This API uses an asynchronous callback to return the result.

No permission is required for obtaining the caller's own information.

Required permissions: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED or ohos.permission.GET_BUNDLE_INFO

System API: This is a system API.

System capability: SystemCapability.BundleManager.BundleFramework.Launcher

Parameters

Name	Type	Mandatory	Description
bundleName	string	Yes	Bundle name.
callback	AsyncCallback<Array<ShortcutInfo>>	Yes	Callback used to return the result. If the operation is successful, err is null, and data is the array of ShortcutInfo objects obtained. Otherwise, err is an error object.

Error codes

For details about the error codes, see Universal Error Codes and Bundle Error Codes.

ID	Error Message
201	Verify permission denied.
202	Permission denied, non-system app called system api.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
801	Capability not support.
17700001	The specified bundle name is not found.
17700026	The specified bundle is disabled.

Example

import { launcherBundleManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  launcherBundleManager.getShortcutInfo("com.example.demo",
    (errData: BusinessError, data: launcherBundleManager.ShortcutInfo[]) => {
      if (errData !== null) {
        console.error(`errData is errCode:${errData.code}  message:${errData.message}`);
      } else {
        console.info('data is ' + JSON.stringify(data));
      }
    });
} catch (errData) {
  let code = (errData as BusinessError).code;
  let message = (errData as BusinessError).message;
  console.error(`errData is errCode:${code}  message:${message}`);
}

launcherBundleManager.getShortcutInfo

getShortcutInfo(bundleName : string) : Promise<Array<ShortcutInfo>>

Obtains the shortcut information of the current user based on the given bundle name of a main application. To obtain shortcut information about an application clone, use getShortcutInfoByAppIndex. This API uses a promise to return the result.

No permission is required for obtaining the caller's own information.

Required permissions: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED or ohos.permission.GET_BUNDLE_INFO

System API: This is a system API.

System capability: SystemCapability.BundleManager.BundleFramework.Launcher

Parameters

Name	Type	Mandatory	Description
bundleName	string	Yes	Bundle name.

Return value

Type	Description
Promise<Array<ShortcutInfo>>	Promise used to return the array of ShortcutInfo objects obtained.

Error codes

For details about the error codes, see Universal Error Codes and Bundle Error Codes.

ID	Error Message
201	Verify permission denied.
202	Permission denied, non-system app called system api.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
801	Capability not support.
17700001	The specified bundle name is not found.
17700026	The specified bundle is disabled.

Example

import { launcherBundleManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  launcherBundleManager.getShortcutInfo("com.example.demo")
    .then((data: launcherBundleManager.ShortcutInfo[]) => {
      console.info('data is ' + JSON.stringify(data));
    }).catch((errData: BusinessError) => {
    console.error(`errData is errCode:${errData.code}  message:${errData.message}`);
  });
} catch (errData) {
  let code = (errData as BusinessError).code;
  let message = (errData as BusinessError).message;
  console.error(`errData is errCode:${code}  message:${message}`);
}

launcherBundleManager.getShortcutInfoSync¹⁰⁺

getShortcutInfoSync(bundleName : string) : Array<ShortcutInfo>

Obtains the shortcut information of the current user based on the given bundle name of a main application. To obtain shortcut information about an application clone, use getShortcutInfoByAppIndex.

No permission is required for obtaining the caller's own information.

Required permissions: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED or ohos.permission.GET_BUNDLE_INFO

System API: This is a system API.

System capability: SystemCapability.BundleManager.BundleFramework.Launcher

Parameters

Name	Type	Mandatory	Description
bundleName	string	Yes	Bundle name.

Return value

Type	Description
Array<ShortcutInfo>	Array of the ShortcutInfo objects obtained.

Error codes

For details about the error codes, see Universal Error Codes and Bundle Error Codes.

ID	Error Message
201	Verify permission denied.
202	Permission denied, non-system app called system api.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
801	Capability not support.
17700001	The specified bundle name is not found.
17700026	The specified bundle is disabled.

Example

import { launcherBundleManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  let data = launcherBundleManager.getShortcutInfoSync("com.example.demo");
  console.info('data is ' + JSON.stringify(data));
} catch (errData) {
  let code = (errData as BusinessError).code;
  let message = (errData as BusinessError).message;
  console.error(`errData is errCode:${code}  message:${message}`);
}

launcherBundleManager.getShortcutInfoSync¹³⁺

getShortcutInfoSync(bundleName: string, userId: number) : Array<ShortcutInfo>

Obtains the shortcut information of the specified user based on the given bundle name of a main application. To obtain shortcut information about an application clone, use getShortcutInfoByAppIndex.

No permission is required for obtaining the caller's own information.

Required permissions: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED or ohos.permission.GET_BUNDLE_INFO

System API: This is a system API.

System capability: SystemCapability.BundleManager.BundleFramework.Launcher

Parameters

Name	Type	Mandatory	Description
bundleName	string	Yes	Bundle name.
userId	number	Yes	User ID, which can be obtained by calling getOsAccountLocalId.

Return value

Type	Description
Array<ShortcutInfo>	Array of the ShortcutInfo objects obtained.

Error codes

For details about the error codes, see Universal Error Codes and Bundle Error Codes.

ID	Error Message
201	Verify permission denied.
202	Permission denied, non-system app called system api.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
801	Capability not support.
17700001	The specified bundle name is not found.
17700004	The specified user ID is not found.
17700026	The specified bundle is disabled.

Example

import { launcherBundleManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  let data = launcherBundleManager.getShortcutInfoSync("com.example.demo", 100);
  console.info('data is ' + JSON.stringify(data));
} catch (errData) {
  let code = (errData as BusinessError).code;
  let message = (errData as BusinessError).message;
  console.error(`errData is errCode:${code}  message:${message}`);
}

launcherBundleManager.startShortcut¹²⁺

startShortcut(shortcutInfo: ShortcutInfo, options?: StartOptions): Promise<void>

Starts an ability based on the specified shortcut information. This API uses a promise to return the result.

Required permissions: ohos.permission.START_SHORTCUT

System API: This is a system API.

System capability: SystemCapability.BundleManager.BundleFramework.Launcher

Parameters

Name	Type	Mandatory	Description
shortcutInfo	ShortcutInfo	Yes	Shortcut information of the application.
options	StartOptions	No	Startup parameters, which are used to specify the window mode and device ID for switching the mission to the foreground.

Return value

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

Error codes

For details about the error codes, see Universal Error Codes and Bundle Error Codes.

ID	Error Message
201	Verify permission denied.
202	Permission denied, non-system app called system api.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
801	Capability not support.
17700065	The specified shortcut want in shortcut info is not supported to be started.

Example

import { launcherBundleManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  let data: Array<launcherBundleManager.ShortcutInfo> = launcherBundleManager.getShortcutInfoSync("com.example.demo");
  console.info('data is ' + JSON.stringify(data));
  if (data) {
    try {
      launcherBundleManager.startShortcut(data[0])
        .then(() => {
          console.info('startShortcut success');
        }).catch((err: BusinessError) => {
        console.error(`errData is errCode:${err.code}  message:${err.message}`);
      });
    } catch (error) {
      let code = (error as BusinessError).code;
      let message = (error as BusinessError).message;
      console.error(`error is errCode:${code}  message:${message}`);
    }
  }
} catch (errData) {
  let code = (errData as BusinessError).code;
  let message = (errData as BusinessError).message;
  console.error(`errData is errCode:${code}  message:${message}`);
}

launcherBundleManager.startShortcutWithReason²⁰⁺

startShortcutWithReason(shortcutInfo: ShortcutInfo, startReason: string, options?: StartOptions): Promise<void>

Starts an ability based on the specified shortcut information, and carries the reason for the shortcut launch. This API uses a promise to return the result.

The launched ability can obtain the launch reason through the launchReasonMessage field of LaunchParam and handle service logic accordingly.

Required permissions: ohos.permission.START_SHORTCUT and ohos.permission.SET_LAUNCH_REASON_MESSAGE (If the caller has the ohos.permission.START_SHORTCUT permission but not the ohos.permission.SET_LAUNCH_REASON_MESSAGE permission, the ability can be started, but the shortcut launch reason carried is invalid.)

System API: This is a system API.

System capability: SystemCapability.BundleManager.BundleFramework.Launcher

Parameters

Name	Type	Mandatory	Description
shortcutInfo	ShortcutInfo	Yes	Shortcut information of the application.
startReason	string	Yes	Reason for launching the shortcut. The value can be AbilityConstant.REASON_MESSAGE_DESKTOP_SHORTCUT, indicating a home screen shortcut launch.
options	StartOptions	No	Parameters used to specify the window mode of the target ability.

Return value

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

Error codes

For details about the error codes, see Universal Error Codes and Bundle Error Codes.

ID	Error Message
201	Verify permission denied.
202	Permission denied, non-system app called system api.
801	Capability not support.
17700065	The specified shortcut want in shortcut info is not supported to be started.

Example

import { launcherBundleManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { AbilityConstant } from '@kit.AbilityKit';

try {
  let data: Array<launcherBundleManager.ShortcutInfo> =
    launcherBundleManager.getShortcutInfoSync("com.example.myapplication");
  console.info('startShortcutWithReason data is ' + JSON.stringify(data));
  let startReason = AbilityConstant.REASON_MESSAGE_DESKTOP_SHORTCUT;
  if (data) {
    try {
      launcherBundleManager.startShortcutWithReason(data[0], startReason)
        .then(() => {
          console.info('startShortcutWithReason success');
        }).catch((err: BusinessError) => {
        console.error(`startShortcutWithReason errData is errCode:${err.code}  message:${err.message}`);
      });
    } catch (error) {
      let code = (error as BusinessError).code;
      let message = (error as BusinessError).message;
      console.error(`startShortcutWithReason error is errCode:${code}  message:${message}`);
    }
  }
} catch (errData) {
  let code = (errData as BusinessError).code;
  let message = (errData as BusinessError).message;
  console.error(`startShortcutWithReason errData is errCode:${code}  message:${message}`);
}

launcherBundleManager.getShortcutInfoByAppIndex²⁰⁺

getShortcutInfoByAppIndex(bundleName: string, appIndex: number): Array<ShortcutInfo>

Obtains the shortcut information of the current user based on the index of an application clone.

No permission is required for obtaining the caller's own information.

Required permissions: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED

System API: This is a system API.

System capability: SystemCapability.BundleManager.BundleFramework.Launcher

Parameters

Name	Type	Mandatory	Description
bundleName	string	Yes	Bundle name.
appIndex	number	Yes	Index of the application clone.

Return value

Type	Description
Array<ShortcutInfo>	Array of the ShortcutInfo objects obtained.

Error codes

For details about the error codes, see Universal Error Codes and Bundle Error Codes.

ID	Error Message
201	Verify permission denied.
202	Permission denied, non-system app called system api.
801	Capability not support.
17700001	The specified bundle name is not found.
17700061	The specified app index is invalid.

Example

import { launcherBundleManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  let data = launcherBundleManager.getShortcutInfoByAppIndex("com.example.demo", 1);
  console.info('getShortcutInfoByAppIndex successfully, data is ' + JSON.stringify(data));
} catch (errData) {
  let code = (errData as BusinessError).code;
  let message = (errData as BusinessError).message;
  console.error(`Failed to getShortcutInfoByAppIndex. Code: ${code}, message: ${message}`);
}