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