1# @ohos.bundle.launcherBundleManager (launcherBundleManager) (System API)
2
3The **bundle.launcherBundleManager** module providers APIs for the **Home Screen** application to obtain the [launcher ability information](js-apis-bundleManager-launcherAbilityInfo-sys.md) and [shortcut information](js-apis-bundleManager-shortcutInfo-sys.md).
4
5> **NOTE**
6>
7> 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.
8>
9> The APIs provided by this module are system APIs.
10
11## Modules to Import
12
13```ts
14import launcherBundleManager from '@ohos.bundle.launcherBundleManager';
15```
16
17
18## launcherBundleManager.getLauncherAbilityInfo<sup>9+</sup>
19
20getLauncherAbilityInfo(bundleName: string, userId: number, callback: AsyncCallback\<Array\<[LauncherAbilityInfo](js-apis-bundleManager-launcherAbilityInfo-sys.md)\>\>) : void
21
22Obtains the launcher ability information based on the given bundle name and user ID. This API uses an asynchronous callback to return the result.
23
24**Required permissions**: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED
25
26**System API**: This is a system API.
27
28**System capability**: SystemCapability.BundleManager.BundleFramework.Launcher
29
30**Parameters**
31
32| Name    | Type  | Mandatory| Description        |
33| ---------- | ------ | ---- | -------------- |
34| bundleName | string | Yes  | Bundle name.|
35| userId     | number | Yes  | User ID.|
36| callback | AsyncCallback\<Array\<[LauncherAbilityInfo](js-apis-bundleManager-launcherAbilityInfo-sys.md)\>\> | Yes| Callback used to return the **LauncherAbilityInfo** object obtained.|
37
38**Error codes**
39
40For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Bundle Error Codes](errorcode-bundle.md).
41
42| ID| Error Message                                |
43| -------- | ---------------------------------------- |
44| 201 | Permission denied. |
45| 202 | Permission denied, non-system app called system api. |
46| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.|
47| 801 | Capability not support. |
48| 17700001 | The specified bundle name is not found.  |
49| 17700004 | The specified user ID is not found.      |
50
51**Example**
52
53```ts
54import launcherBundleManager from '@ohos.bundle.launcherBundleManager';
55import { BusinessError } from '@ohos.base';
56
57try {
58    launcherBundleManager.getLauncherAbilityInfo('com.example.demo', 100,
59        (errData: BusinessError, data: launcherBundleManager.LauncherAbilityInfo[]) => {
60        if (errData !== null) {
61            console.error(`errData is errCode:${errData.code}  message:${errData.message}`);
62        } else {
63            console.log("data is " + JSON.stringify(data));
64        }
65    })
66} catch (errData) {
67    let code = (errData as BusinessError).code;
68    let message = (errData as BusinessError).message;
69    console.error(`errData is errCode:${code}  message:${message}`);
70}
71```
72
73## launcherBundleManager.getLauncherAbilityInfo<sup>9+</sup>
74
75getLauncherAbilityInfo(bundleName: string, userId: number) : Promise\<Array\<[LauncherAbilityInfo](js-apis-bundleManager-launcherAbilityInfo-sys.md)\>\>
76
77Obtains the launcher ability information based on the given bundle name and user ID. This API uses a promise to return the result.
78
79**Required permissions**: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED
80
81**System API**: This is a system API.
82
83**System capability**: SystemCapability.BundleManager.BundleFramework.Launcher
84
85**Parameters**
86
87| Name    | Type  | Mandatory| Description        |
88| ---------- | ------ | ---- | -------------- |
89| bundleName | string | Yes  | Bundle name.|
90| userId     | number | Yes  | User ID.|
91
92**Return value**
93
94| Type                         | Description                                              |
95| ----------------------------- | -------------------------------------------------- |
96| Promise\<Array\<[LauncherAbilityInfo](js-apis-bundleManager-launcherAbilityInfo-sys.md)\>\> | Promise used to return the **LauncherAbilityInfo** object obtained.|
97
98**Error codes**
99
100For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Bundle Error Codes](errorcode-bundle.md).
101
102| ID| Error Message                                |
103| -------- | ---------------------------------------- |
104| 201 | Permission denied. |
105| 202 | Permission denied, non-system app called system api. |
106| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.|
107| 801 | Capability not support. |
108| 17700001 | The specified bundle name is not found.  |
109| 17700004 | The specified user ID is not found.       |
110
111**Example**
112
113```ts
114import launcherBundleManager from '@ohos.bundle.launcherBundleManager';
115import { BusinessError } from '@ohos.base';
116
117try {
118    launcherBundleManager.getLauncherAbilityInfo("com.example.demo", 100)
119        .then((data: launcherBundleManager.LauncherAbilityInfo[]) => {
120        console.log("data is " + JSON.stringify(data));
121    }).catch ((errData: BusinessError) => {
122        console.error(`errData is errCode:${errData.code}  message:${errData.message}`);
123    })
124} catch (errData) {
125    let code = (errData as BusinessError).code;
126    let message = (errData as BusinessError).message;
127    console.error(`errData is errCode:${code}  message:${message}`);
128}
129```
130
131## launcherBundleManager.getLauncherAbilityInfoSync<sup>10+</sup>
132
133getLauncherAbilityInfoSync(bundleName: string, userId: number) : Array\<[LauncherAbilityInfo](js-apis-bundleManager-launcherAbilityInfo-sys.md)\>
134
135Obtains the launcher ability information based on the given bundle name and user ID. This API returns the result synchronously.
136
137**Required permissions**: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED
138
139**System API**: This is a system API.
140
141**System capability**: SystemCapability.BundleManager.BundleFramework.Launcher
142
143**Parameters**
144
145| Name    | Type  | Mandatory| Description        |
146| ---------- | ------ | ---- | -------------- |
147| bundleName | string | Yes  | Bundle name.|
148| userId     | number | Yes  | User ID.|
149
150**Return value**
151
152| Type                         | Description                                              |
153| ----------------------------- | -------------------------------------------------- |
154| Array\<[LauncherAbilityInfo](js-apis-bundleManager-launcherAbilityInfo-sys.md)\> | Array of the **LauncherAbilityInfo** objects obtained.|
155
156**Error codes**
157
158For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Bundle Error Codes](errorcode-bundle.md).
159
160| ID| Error Message                                |
161| -------- | ---------------------------------------- |
162| 201 | Permission denied. |
163| 202 | Permission denied, non-system app called system api. |
164| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.|
165| 801 | Capability not support. |
166| 17700001 | The specified bundle name is not found.  |
167| 17700004 | The specified user ID is not found.       |
168
169**Example**
170
171```ts
172import launcherBundleManager from '@ohos.bundle.launcherBundleManager';
173import { BusinessError } from '@ohos.base';
174
175try {
176    let data = launcherBundleManager.getLauncherAbilityInfoSync("com.example.demo", 100);
177    console.log("data is " + JSON.stringify(data));
178} catch (errData) {
179    let code = (errData as BusinessError).code;
180    let message = (errData as BusinessError).message;
181    console.error(`errData is errCode:${code}  message:${message}`);
182}
183```
184
185## launcherBundleManager.getAllLauncherAbilityInfo<sup>9+</sup>
186
187getAllLauncherAbilityInfo(userId: number, callback: AsyncCallback\<Array\<[LauncherAbilityInfo](js-apis-bundleManager-launcherAbilityInfo-sys.md)\>\>) : void
188
189Obtains the launcher ability information of all applications based on the given user ID. This API uses an asynchronous callback to return the result.
190
191**Required permissions**: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED
192
193**System API**: This is a system API.
194
195**System capability**: SystemCapability.BundleManager.BundleFramework.Launcher
196
197**Parameters**
198
199| Name| Type  | Mandatory| Description        |
200| ------ | ------ | ---- | -------------- |
201| userId | number | Yes  | User ID.|
202| callback | AsyncCallback\<Array\<[LauncherAbilityInfo](js-apis-bundleManager-launcherAbilityInfo-sys.md)\>\> | Yes| Callback used to return the array of **LauncherAbilityInfo** objects obtained.|
203
204**Error codes**
205
206For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Bundle Error Codes](errorcode-bundle.md).
207
208| ID| Error Message                               |
209| -------- | ---------------------------------------- |
210| 201 | Permission denied. |
211| 202 | Permission denied, non-system app called system api. |
212| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.|
213| 801 | Capability not support. |
214| 17700004 | The specified user ID is not found.      |
215
216Example
217
218```ts
219import launcherBundleManager from '@ohos.bundle.launcherBundleManager';
220import { BusinessError } from '@ohos.base';
221
222try {
223    launcherBundleManager.getAllLauncherAbilityInfo(100,
224        (errData: BusinessError, data: launcherBundleManager.LauncherAbilityInfo[]) => {
225        if (errData !== null) {
226            console.error(`errData is errCode:${errData.code}  message:${errData.message}`);
227        } else {
228            console.log("data is " + JSON.stringify(data));
229        }
230    });
231} catch (errData) {
232    let code = (errData as BusinessError).code;
233    let message = (errData as BusinessError).message;
234    console.error(`errData is errCode:${code}  message:${message}`);
235}
236```
237## launcherBundleManager.getAllLauncherAbilityInfo<sup>9+</sup>
238
239getAllLauncherAbilityInfo(userId: number) : Promise\<Array\<[LauncherAbilityInfo](js-apis-bundleManager-launcherAbilityInfo-sys.md)\>\>
240
241Obtains the launcher ability information of all applications based on the given user ID. This API uses a promise to return the result.
242
243**Required permissions**: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED
244
245**System API**: This is a system API.
246
247**System capability**: SystemCapability.BundleManager.BundleFramework.Launcher
248
249**Parameters**
250
251| Name| Type  | Mandatory| Description        |
252| ------ | ------ | ---- | -------------- |
253| userId | number | Yes  | User ID.|
254
255**Return value**
256
257| Type                         | Description                                                  |
258| ----------------------------- | ------------------------------------------------------ |
259| Promise\<Array\<[LauncherAbilityInfo](js-apis-bundleManager-launcherAbilityInfo-sys.md)\>\> | Promise used to return the array of **LauncherAbilityInfo** objects obtained.|
260
261**Error codes**
262
263For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Bundle Error Codes](errorcode-bundle.md).
264
265| ID| Error Message                               |
266| -------- | ---------------------------------------- |
267| 201 | Permission denied. |
268| 202 | Permission denied, non-system app called system api. |
269| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.|
270| 801 | Capability not support. |
271| 17700004 | The specified user ID is not found.      |
272
273**Example**
274
275```ts
276import launcherBundleManager from '@ohos.bundle.launcherBundleManager';
277import { BusinessError } from '@ohos.base';
278
279try {
280    launcherBundleManager.getAllLauncherAbilityInfo(100)
281        .then((data: launcherBundleManager.LauncherAbilityInfo[]) => {
282        console.log("data is " + JSON.stringify(data));
283    }).catch ((errData: BusinessError) => {
284        console.error(`errData is errCode:${errData.code}  message:${errData.message}`);
285    });
286} catch (errData) {
287    let code = (errData as BusinessError).code;
288    let message = (errData as BusinessError).message;
289    console.error(`errData is errCode:${code}  message:${message}`);
290}
291```
292
293## launcherBundleManager.getShortcutInfo<sup>9+</sup>
294
295getShortcutInfo(bundleName :string, callback: AsyncCallback\<Array\<[ShortcutInfo](js-apis-bundleManager-shortcutInfo-sys.md)\>\>) : void
296
297Obtains the shortcut information of the current user based on the given bundle name. This API uses an asynchronous callback to return the result.
298
299**Required permissions**: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED
300
301**System API**: This is a system API.
302
303**System capability**: SystemCapability.BundleManager.BundleFramework.Launcher
304
305**Parameters**
306
307| Name    | Type  | Mandatory| Description        |
308| ---------- | ------ | ---- | -------------- |
309| bundleName | string | Yes  | Bundle name.|
310| callback | AsyncCallback\<Array\<[ShortcutInfo](js-apis-bundleManager-shortcutInfo-sys.md)\>\> | Yes| Callback used to return the **ShortcutInfo** object obtained.|
311
312**Error codes**
313
314For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Bundle Error Codes](errorcode-bundle.md).
315
316| ID| Error Message                               |
317| -------- | ---------------------------------------- |
318| 201 | Permission denied. |
319| 202 | Permission denied, non-system app called system api. |
320| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.|
321| 801 | Capability not support. |
322| 17700001 | The specified bundle name is not found.  |
323
324**Example**
325
326```ts
327import launcherBundleManager from '@ohos.bundle.launcherBundleManager';
328import { BusinessError } from '@ohos.base';
329
330try {
331    launcherBundleManager.getShortcutInfo("com.example.demo",
332        (errData: BusinessError, data: launcherBundleManager.ShortcutInfo[]) => {
333        if (errData !== null) {
334            console.error(`errData is errCode:${errData.code}  message:${errData.message}`);
335        } else {
336            console.log("data is " + JSON.stringify(data));
337        }
338    });
339} catch (errData) {
340    let code = (errData as BusinessError).code;
341    let message = (errData as BusinessError).message;
342    console.error(`errData is errCode:${code}  message:${message}`);
343}
344```
345
346## launcherBundleManager.getShortcutInfo<sup>9+</sup>
347
348getShortcutInfo(bundleName : string) : Promise\<Array\<[ShortcutInfo](js-apis-bundleManager-shortcutInfo-sys.md)\>\>
349
350Obtains the shortcut information of the current user based on the given bundle name. This API uses a promise to return the result.
351
352**Required permissions**: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED
353
354**System API**: This is a system API.
355
356**System capability**: SystemCapability.BundleManager.BundleFramework.Launcher
357
358**Parameters**
359
360| Name    | Type  | Mandatory| Description        |
361| ---------- | ------ | ---- | -------------- |
362| bundleName | string | Yes  | Bundle name.|
363
364**Return value**
365
366| Type                  | Description                                           |
367| ---------------------- | ----------------------------------------------- |
368| Promise\<Array\<[ShortcutInfo](js-apis-bundleManager-shortcutInfo-sys.md)\>\> | Promise used to return the **ShortcutInfo** object obtained.|
369
370**Error codes**
371
372For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Bundle Error Codes](errorcode-bundle.md).
373
374| ID| Error Message                               |
375| -------- | ---------------------------------------- |
376| 201 | Permission denied. |
377| 202 | Permission denied, non-system app called system api. |
378| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.|
379| 801 | Capability not support. |
380| 17700001 | The specified bundle name is not found.  |
381
382**Example**
383
384```ts
385import launcherBundleManager from '@ohos.bundle.launcherBundleManager';
386import { BusinessError } from '@ohos.base';
387
388try {
389    launcherBundleManager.getShortcutInfo("com.example.demo")
390        .then((data: launcherBundleManager.ShortcutInfo[]) => {
391        console.log("data is " + JSON.stringify(data));
392    }).catch ((errData: BusinessError) => {
393        console.error(`errData is errCode:${errData.code}  message:${errData.message}`);
394    });
395} catch (errData) {
396    let code = (errData as BusinessError).code;
397    let message = (errData as BusinessError).message;
398    console.error(`errData is errCode:${code}  message:${message}`);
399}
400```
401
402## launcherBundleManager.getShortcutInfoSync<sup>10+</sup>
403
404getShortcutInfoSync(bundleName : string) : Array\<[ShortcutInfo](js-apis-bundleManager-shortcutInfo-sys.md)\>
405
406Obtains the shortcut information of the current user based on the given bundle name. This API returns the result synchronously.
407
408**Required permissions**: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED
409
410**System API**: This is a system API.
411
412**System capability**: SystemCapability.BundleManager.BundleFramework.Launcher
413
414**Parameters**
415
416| Name    | Type  | Mandatory| Description        |
417| ---------- | ------ | ---- | -------------- |
418| bundleName | string | Yes  | Bundle name.|
419
420**Return value**
421
422| Type                  | Description                                           |
423| ---------------------- | ----------------------------------------------- |
424| Array\<[ShortcutInfo](js-apis-bundleManager-shortcutInfo-sys.md)\> | Array of the **ShortcutInfo** objects obtained.|
425
426**Error codes**
427
428For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Bundle Error Codes](errorcode-bundle.md).
429
430| ID| Error Message                               |
431| -------- | ---------------------------------------- |
432| 201 | Permission denied. |
433| 202 | Permission denied, non-system app called system api. |
434| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.|
435| 801 | Capability not support. |
436| 17700001 | The specified bundle name is not found.  |
437
438**Example**
439
440```ts
441import launcherBundleManager from '@ohos.bundle.launcherBundleManager';
442import { BusinessError } from '@ohos.base';
443
444try {
445    let data = launcherBundleManager.getShortcutInfoSync("com.example.demo");
446    console.log("data is " + JSON.stringify(data));
447} catch (errData) {
448    let code = (errData as BusinessError).code;
449    let message = (errData as BusinessError).message;
450    console.error(`errData is errCode:${code}  message:${message}`);
451}
452```
453
454## launcherBundleManager.getShortcutInfoSync<sup>13+</sup>
455
456getShortcutInfoSync(bundleName: string, userId: number) : Array\<[ShortcutInfo](js-apis-bundleManager-shortcutInfo-sys.md)\>
457
458Obtains the shortcut information of the specified user based on the given bundle name.
459
460**Required permissions**: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED
461
462**System API**: This is a system API.
463
464**System capability**: SystemCapability.BundleManager.BundleFramework.Launcher
465
466**Parameters**
467
468| Name    | Type  | Mandatory| Description        |
469| ---------- | ------ | ---- | -------------- |
470| bundleName | string | Yes  | Bundle name.|
471| userId     | number | Yes  | User ID. |
472
473**Return value**
474
475| Type                  | Description                                           |
476| ---------------------- | ----------------------------------------------- |
477| Array\<[ShortcutInfo](js-apis-bundleManager-shortcutInfo-sys.md)\> | Array of the **ShortcutInfo** objects obtained.|
478
479**Error codes**
480
481For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Bundle Error Codes](errorcode-bundle.md).
482
483| ID| Error Message                               |
484| -------- | ---------------------------------------- |
485| 201 | Permission denied. |
486| 202 | Permission denied, non-system app called system api. |
487| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.|
488| 801 | Capability not support. |
489| 17700001 | The specified bundle name is not found.  |
490| 17700004 | The specified user ID is not found.     |
491
492**Example**
493
494```ts
495import launcherBundleManager from '@ohos.bundle.launcherBundleManager';
496import { BusinessError } from '@ohos.base';
497
498try {
499    let data = launcherBundleManager.getShortcutInfoSync("com.example.demo", 100);
500    console.log("data is " + JSON.stringify(data));
501} catch (errData) {
502    let code = (errData as BusinessError).code;
503    let message = (errData as BusinessError).message;
504    console.error(`errData is errCode:${code}  message:${message}`);
505}
506```
507
508## launcherBundleManager.startShortcut<sup>12+</sup>
509
510startShortcut(shortcutInfo: ShortcutInfo, options?: StartOptions): Promise\<void\>;
511
512Starts the ability in the specified [ShortcutInfo](js-apis-bundleManager-shortcutInfo-sys.md).
513
514**Required permissions**: ohos.permission.START_SHORTCUT
515
516**System API**: This is a system API.
517
518**System capability**: SystemCapability.BundleManager.BundleFramework.Launcher
519
520**Parameters**
521
522| Name       | Type  | Mandatory| Description        |
523| ------------ | ------ | ---- | -------------- |
524| shortcutInfo | [ShortcutInfo](js-apis-bundleManager-shortcutInfo-sys.md) | Yes  | Shortcut information of the application.|
525| options      | [StartOptions](js-apis-app-ability-startOptions-sys.md)   | No  | Startup parameters, which are used to specify the window mode and device ID for switching the mission to the foreground.|
526
527**Error codes**
528
529For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Bundle Error Codes](errorcode-bundle.md).
530
531| ID| Error Message                               |
532| -------- | ---------------------------------------- |
533| 201 | Permission denied. |
534| 202 | Permission denied, non-system app called system api. |
535| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.|
536| 801 | Capability not support. |
537| 17700065 | The ability specified by want in the ShortcutInfo struct cannot be started.  |
538
539**Example**
540
541```ts
542import launcherBundleManager from '@ohos.bundle.launcherBundleManager';
543import { BusinessError } from '@ohos.base';
544
545try {
546    let data : Array<launcherBundleManager.ShortcutInfo> = launcherBundleManager.getShortcutInfoSync("com.example.demo");
547    console.log("data is " + JSON.stringify(data));
548    if (data) {
549        try {
550            launcherBundleManager.startShortcut(data[0])
551                .then(() => {
552                console.log("startShortcut success");
553            }).catch ((err: BusinessError) => {
554                console.error(`errData is errCode:${err.code}  message:${err.message}`);
555            });
556        } catch (error) {
557            let code = (error as BusinessError).code;
558            let message = (error as BusinessError).message;
559            console.error(`error is errCode:${code}  message:${message}`);
560        }
561    }
562} catch (errData) {
563    let code = (errData as BusinessError).code;
564    let message = (errData as BusinessError).message;
565    console.error(`errData is errCode:${code}  message:${message}`);
566}
567```
568