1# @ohos.bundle.distributedBundleManager (distributedBundleManager模块)(系统接口)
2
3本模块提供分布式应用的管理能力。
4
5> **说明：**
6>
7> 本模块首批接口从API version 9 开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
8>
9> 本模块为系统接口。
10
11## 导入模块
12
13``` ts
14import distributedBundle from '@ohos.bundle.distributedBundleManager';
15```
16
17## 系统能力
18
19SystemCapability.BundleManager.DistributedBundleFramework
20
21## 权限列表
22
23| 权限                                       | 权限等级     | 说明               |
24| ------------------------------------------ | ------------ | ------------------ |
25| ohos.permission.GET_BUNDLE_INFO_PRIVILEGED | system_basic | 允许查询应用的基本信息和其他敏感信息。 |
26
27权限等级参考[权限APL等级说明](../../security/AccessToken/app-permission-mgmt-overview.md#权限机制中的基本概念)。
28
29## distributedBundle.getRemoteAbilityInfo
30
31getRemoteAbilityInfo(elementName: ElementName, callback: AsyncCallback\<RemoteAbilityInfo>): void
32
33以异步方法获取由elementName指定的远程设备上的应用的AbilityInfo信息。使用callback异步回调。
34
35**系统接口：** 此接口为系统接口。
36
37**需要权限：** ohos.permission.GET_BUNDLE_INFO_PRIVILEGED
38
39**系统能力：** SystemCapability.BundleManager.DistributedBundleFramework
40
41**参数：**
42
43| 参数名      | 类型                                                         | 必填 | 说明                                                         |
44| ----------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
45| elementName | [ElementName](js-apis-bundleManager-elementName.md)          | 是   | ElementName信息。                                            |
46| callback    | AsyncCallback<[RemoteAbilityInfo](js-apis-bundleManager-remoteAbilityInfo-sys.md)> | 是   | 回调函数，调用成功返回err为null，data为RemoteAbilityInfo对象；调用失败err为错误对象, data为undefined。 |
47
48**错误码：**
49
50以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.bundle错误码](errorcode-bundle.md)。
51
52| 错误码ID |    错误信息                   |
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**示例：**
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
93以异步方法获取由elementName指定的远程设备上的应用的AbilityInfo信息。使用Promise异步回调。
94
95**系统接口：** 此接口为系统接口。
96
97**需要权限：** ohos.permission.GET_BUNDLE_INFO_PRIVILEGED
98
99**系统能力：** SystemCapability.BundleManager.DistributedBundleFramework
100
101**参数：**
102
103| 参数名       | 类型                                         | 必填 | 说明                    |
104| ----------- | -------------------------------------------- | ---- | ----------------------- |
105| elementName | [ElementName](js-apis-bundleManager-elementName.md) | 是   | ElementName信息。 |
106
107**返回值：**
108
109| 类型                                                         | 说明                              |
110| ------------------------------------------------------------ | --------------------------------- |
111| Promise\<[RemoteAbilityInfo](js-apis-bundleManager-remoteAbilityInfo-sys.md)> | Promise对象，调用成功返回RemoteAbilityInfo对象；调用失败返回错误对象。 |
112
113**错误码：**
114
115以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.bundle错误码](errorcode-bundle.md)。
116
117| 错误码ID |    错误信息                   |
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**示例：**
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
156以异步方法获取由elementName指定的远程设备上的应用的AbilityInfo数组信息。使用callback异步回调。
157
158**系统接口：** 此接口为系统接口。
159
160**需要权限：** ohos.permission.GET_BUNDLE_INFO_PRIVILEGED
161
162**系统能力：** SystemCapability.BundleManager.DistributedBundleFramework
163
164**参数：**
165
166| 参数名       | 类型                                                         | 必填 | 说明                                                         |
167| ------------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
168| elementNames | Array<[ElementName](js-apis-bundleManager-elementName.md)>   | 是   | ElementName信息,最大数组长度为10。                             |
169| callback     | AsyncCallback\<Array\<[RemoteAbilityInfo](js-apis-bundleManager-remoteAbilityInfo-sys.md)>> | 是   | 回调函数，调用成功返回err为null，data为RemoteAbilityInfo数组对象；调用失败err为错误对象, data为undefined。 |
170
171**错误码：**
172
173以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.bundle错误码](errorcode-bundle.md)。
174
175| 错误码ID |    错误信息                   |
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**示例：**
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
223以异步方法获取由elementName指定的远程设备上的应用的AbilityInfo数组信息。使用Promise异步回调。
224
225**系统接口：** 此接口为系统接口。
226
227**需要权限：** ohos.permission.GET_BUNDLE_INFO_PRIVILEGED
228
229**系统能力：** SystemCapability.BundleManager.DistributedBundleFramework
230
231**参数：**
232
233| 参数名        | 类型                                                | 必填 | 说明                    |
234| ------------ | --------------------------------------------------- | ---- | ----------------------- |
235| elementNames | Array<[ElementName](js-apis-bundleManager-elementName.md)> | 是   | ElementName信息，最大数组长度为10。 |
236
237**返回值：**
238
239| 类型                                                         | 说明                              |
240| ------------------------------------------------------------ | --------------------------------- |
241| Promise\<Array<[RemoteAbilityInfo](js-apis-bundleManager-remoteAbilityInfo-sys.md)>> | Promise对象，调用成功返回RemoteAbilityInfo对象；调用失败返回错误对象。 |
242
243**错误码：**
244
245以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.bundle错误码](errorcode-bundle.md)。
246
247| 错误码ID |    错误信息                   |
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**示例：**
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
293以异步方法获取由elementName和locale指定的远程设备上的应用的AbilityInfo信息。使用callback异步回调。
294
295**系统接口：** 此接口为系统接口。
296
297**需要权限：** ohos.permission.GET_BUNDLE_INFO_PRIVILEGED
298
299**系统能力：** SystemCapability.BundleManager.DistributedBundleFramework
300
301**参数：**
302
303| 参数名       | 类型                                                         | 必填 | 说明                                               |
304| ----------- | ------------------------------------------------------------ | ---- | -------------------------------------------------- |
305| elementName | [ElementName](js-apis-bundleManager-elementName.md)                 | 是   | ElementName信息。                            |
306| locale  | string |是 | 语言地区。 |
307| callback    | AsyncCallback<[RemoteAbilityInfo](js-apis-bundleManager-remoteAbilityInfo-sys.md)> | 是   | 回调函数，调用成功返回err为null，data为RemoteAbilityInfo对象；调用失败err为错误对象, data为undefined。 |
308
309**错误码：**
310
311以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.bundle错误码](errorcode-bundle.md)。
312
313| 错误码ID |    错误信息                   |
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**示例：**
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
354以异步方法获取由elementName和locale指定的远程设备上的应用的AbilityInfo信息。使用Promise异步回调。
355
356**系统接口：** 此接口为系统接口。
357
358**需要权限：** ohos.permission.GET_BUNDLE_INFO_PRIVILEGED
359
360**系统能力：** SystemCapability.BundleManager.DistributedBundleFramework
361
362**参数：**
363
364| 参数名       | 类型                                         | 必填 | 说明                    |
365| ----------- | -------------------------------------------- | ---- | ----------------------- |
366| elementName | [ElementName](js-apis-bundleManager-elementName.md) | 是   | ElementName信息。 |
367| locale  | string |是 | 语言地区。 |
368
369**返回值：**
370
371| 类型                                                         | 说明                              |
372| ------------------------------------------------------------ | --------------------------------- |
373| Promise\<[RemoteAbilityInfo](js-apis-bundleManager-remoteAbilityInfo-sys.md)> | Promise对象，调用成功返回RemoteAbilityInfo对象；调用失败返回错误对象。 |
374
375**错误码：**
376
377以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.bundle错误码](errorcode-bundle.md)。
378
379| 错误码ID |    错误信息                   |
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**示例：**
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
418以异步方法获取由elementName和locale指定的远程设备上的应用的AbilityInfo数组信息。使用callback异步回调。
419
420**系统接口：** 此接口为系统接口。
421
422**需要权限：** ohos.permission.GET_BUNDLE_INFO_PRIVILEGED
423
424**系统能力：** SystemCapability.BundleManager.DistributedBundleFramework
425
426**参数：**
427
428| 参数名        | 类型                                                         | 必填 | 说明                                               |
429| ------------ | ------------------------------------------------------------ | ---- | -------------------------------------------------- |
430| elementNames | Array<[ElementName](js-apis-bundleManager-elementName.md)>          | 是   | ElementName信息,最大数组长度为10。                   |
431| locale  | string |是 | 语言地区。 |
432| callback     | AsyncCallback\<Array\<[RemoteAbilityInfo](js-apis-bundleManager-remoteAbilityInfo-sys.md)>> | 是   | 回调函数，调用成功返回err为null，data为RemoteAbilityInfo数组对象；调用失败err为错误对象, data为undefined。 |
433
434**错误码：**
435
436以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.bundle错误码](errorcode-bundle.md)。
437
438| 错误码ID        |    错误信息                   |
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**示例：**
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
486以异步方法获取由elementName和locale指定的远程设备上的应用的AbilityInfo数组信息。使用Promise异步回调。
487
488**系统接口：** 此接口为系统接口。
489
490**需要权限：** ohos.permission.GET_BUNDLE_INFO_PRIVILEGED
491
492**系统能力：** SystemCapability.BundleManager.DistributedBundleFramework
493
494**参数：**
495
496| 参数名        | 类型                                                | 必填 | 说明                    |
497| ------------ | --------------------------------------------------- | ---- | ----------------------- |
498| elementNames | Array<[ElementName](js-apis-bundleManager-elementName.md)> | 是   | ElementName信息,最大数组长度为10。 |
499| locale  | string |是 | 语言地区。 |
500
501**返回值：**
502
503| 类型                                                         | 说明                              |
504| ------------------------------------------------------------ | --------------------------------- |
505| Promise\<Array<[RemoteAbilityInfo](js-apis-bundleManager-remoteAbilityInfo-sys.md)>> | Promise对象，调用成功返回RemoteAbilityInfo对象；调用失败返回错误对象。 |
506
507**错误码：**
508
509以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.bundle错误码](errorcode-bundle.md)。
510
511| 错误码ID |    错误信息                   |
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**示例：**
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