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