• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# @ohos.bundle.distributedBundleManager (distributedBundleManager模块)(系统接口)
2<!--Kit: Ability Kit-->
3<!--Subsystem: BundleManager-->
4<!--Owner: @wanghang904-->
5<!--Designer: @hanfeng6-->
6<!--Tester: @kongjing2-->
7<!--Adviser: @Brilliantry_Rui-->
8
9本模块提供分布式应用的管理能力。
10
11> **说明：**
12>
13> 本模块首批接口从API version 9 开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
14>
15> 本模块为系统接口。
16
17## 导入模块
18
19``` ts
20import distributedBundle from '@ohos.bundle.distributedBundleManager';
21```
22
23## 系统能力
24
25SystemCapability.BundleManager.DistributedBundleFramework
26
27## 权限列表
28
29| 权限                                       | 权限等级     | 说明               |
30| ------------------------------------------ | ------------ | ------------------ |
31| ohos.permission.GET_BUNDLE_INFO_PRIVILEGED | system_basic | 允许查询应用的基本信息和其他敏感信息。 |
32
33权限等级参考[权限APL等级说明](../../security/AccessToken/app-permission-mgmt-overview.md#权限机制中的基本概念)。
34
35## distributedBundle.getRemoteAbilityInfo
36
37getRemoteAbilityInfo(elementName: ElementName, callback: AsyncCallback\<RemoteAbilityInfo>): void
38
39获取由elementName指定的远程设备上的应用的AbilityInfo信息。使用callback异步回调。
40
41**系统接口：** 此接口为系统接口。
42
43**需要权限：** ohos.permission.GET_BUNDLE_INFO_PRIVILEGED
44
45**系统能力：** SystemCapability.BundleManager.DistributedBundleFramework
46
47**参数：**
48
49| 参数名      | 类型                                                         | 必填 | 说明                                                         |
50| ----------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
51| elementName | [ElementName](js-apis-bundleManager-elementName.md)          | 是   | ElementName信息。                                            |
52| callback    | AsyncCallback<[RemoteAbilityInfo](js-apis-bundleManager-remoteAbilityInfo-sys.md)> | 是   | [回调函数](../apis-basic-services-kit/js-apis-base.md#asynccallback)，调用成功返回err为null，data为RemoteAbilityInfo对象；调用失败err为错误对象, data为undefined。 |
53
54**错误码：**
55
56以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.bundle错误码](errorcode-bundle.md)。
57
58| 错误码ID |    错误信息                   |
59|----------|--------------------------------------|
60| 201 | Permission denied. |
61| 202 | Permission denied, non-system app called system api. |
62| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.|
63| 801 | Capability not supported. |
64| 17700001 | The specified bundle name is not found. |
65| 17700003 | The specified ability name is not found. |
66| 17700007 | The specified device ID is not found. |
67| 17700027 | The distributed service is not running. |
68
69**示例：**
70
71```ts
72import distributedBundle from '@ohos.bundle.distributedBundleManager';
73import { BusinessError } from '@ohos.base';
74
75try {
76    distributedBundle.getRemoteAbilityInfo(
77        {
78            deviceId: '1',
79            bundleName: 'com.example.application',
80            abilityName: 'EntryAbility'
81        }, (err: BusinessError, data: distributedBundle.RemoteAbilityInfo) => {
82            if (err) {
83                console.error(`Operation failed: error code is ${err.code}  and error message is ${err.message}`);
84            } else {
85                console.info('Operation succeed:' + JSON.stringify(data));
86            }
87        });
88} catch (err) {
89    let code = (err as BusinessError).code;
90    let message = (err as BusinessError).message;
91    console.error(`Operation failed: error code is ${code}  and error message is ${message}`);
92}
93```
94
95## distributedBundle.getRemoteAbilityInfo
96
97getRemoteAbilityInfo(elementName: ElementName): Promise\<RemoteAbilityInfo>
98
99获取由elementName指定的远程设备上的应用的AbilityInfo信息。使用Promise异步回调。
100
101**系统接口：** 此接口为系统接口。
102
103**需要权限：** ohos.permission.GET_BUNDLE_INFO_PRIVILEGED
104
105**系统能力：** SystemCapability.BundleManager.DistributedBundleFramework
106
107**参数：**
108
109| 参数名       | 类型                                         | 必填 | 说明                    |
110| ----------- | -------------------------------------------- | ---- | ----------------------- |
111| elementName | [ElementName](js-apis-bundleManager-elementName.md) | 是   | ElementName信息。 |
112
113**返回值：**
114
115| 类型                                                         | 说明                              |
116| ------------------------------------------------------------ | --------------------------------- |
117| Promise\<[RemoteAbilityInfo](js-apis-bundleManager-remoteAbilityInfo-sys.md)> | Promise对象，调用成功返回RemoteAbilityInfo对象；调用失败返回错误对象。 |
118
119**错误码：**
120
121以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.bundle错误码](errorcode-bundle.md)。
122
123| 错误码ID |    错误信息                   |
124|----------|-------------------------|
125| 201 | Permission denied. |
126| 202 | Permission denied, non-system app called system api. |
127| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.|
128| 801 | Capability not supported. |
129| 17700001 | The specified bundle name is not found. |
130| 17700003 | The specified ability name is not found. |
131| 17700007 | The specified device ID is not found. |
132| 17700027 | The distributed service is not running. |
133
134**示例：**
135
136```ts
137import distributedBundle from '@ohos.bundle.distributedBundleManager';
138import { BusinessError } from '@ohos.base';
139
140try {
141    distributedBundle.getRemoteAbilityInfo(
142        {
143            deviceId: '1',
144            bundleName: 'com.example.application',
145            abilityName: 'EntryAbility'
146        }).then((data: distributedBundle.RemoteAbilityInfo) => {
147            console.info('Operation succeed:' + JSON.stringify(data));
148        }).catch((err: BusinessError) => {
149            console.error(`Operation failed: error code is ${err.code}  and error message is ${err.message}`);
150        });
151} catch (err) {
152    let code = (err as BusinessError).code;
153    let message = (err as BusinessError).message;
154    console.error(`Operation failed: error code is ${code}  and error message is ${message}`);
155}
156```
157
158## distributedBundle.getRemoteAbilityInfo
159
160getRemoteAbilityInfo(elementNames: Array\<ElementName>, callback: AsyncCallback\<Array\<RemoteAbilityInfo>>): void
161
162获取由elementName指定的远程设备上的应用的AbilityInfo数组信息。使用callback异步回调。
163
164**系统接口：** 此接口为系统接口。
165
166**需要权限：** ohos.permission.GET_BUNDLE_INFO_PRIVILEGED
167
168**系统能力：** SystemCapability.BundleManager.DistributedBundleFramework
169
170**参数：**
171
172| 参数名       | 类型                                                         | 必填 | 说明                                                         |
173| ------------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
174| elementNames | Array<[ElementName](js-apis-bundleManager-elementName.md)>   | 是   | ElementName信息,最大数组长度为10。                             |
175| callback     | AsyncCallback\<Array\<[RemoteAbilityInfo](js-apis-bundleManager-remoteAbilityInfo-sys.md)>> | 是   | [回调函数](../apis-basic-services-kit/js-apis-base.md#asynccallback)，调用成功返回err为null，data为RemoteAbilityInfo数组对象；调用失败err为错误对象, data为undefined。 |
176
177**错误码：**
178
179以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.bundle错误码](errorcode-bundle.md)。
180
181| 错误码ID |    错误信息                   |
182|----------|-------------------------|
183| 201 | Permission denied. |
184| 202 | Permission denied, non-system app called system api. |
185| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.|
186| 801 | Capability not supported. |
187| 17700001 | The specified bundle name is not found. |
188| 17700003 | The specified ability name is not found. |
189| 17700007 | The specified device ID is not found. |
190| 17700027 | The distributed service is not running. |
191
192**示例：**
193
194```ts
195import distributedBundle from '@ohos.bundle.distributedBundleManager';
196import { BusinessError } from '@ohos.base';
197
198try {
199    distributedBundle.getRemoteAbilityInfo(
200        [
201            {
202                deviceId: '1',
203                bundleName: 'com.example.application1',
204                abilityName: 'EntryAbility1'
205            },
206            {
207                deviceId: '1',
208                bundleName: 'com.example.application2',
209                abilityName: 'EntryAbility'
210            }
211        ], (err: BusinessError, data: distributedBundle.RemoteAbilityInfo[]) => {
212          if (err) {
213            console.error(`Operation failed: error code is ${err.code}  and error message is ${err.message}`);
214          } else {
215            console.info('Operation succeed:' + JSON.stringify(data));
216          }
217        });
218} catch (err) {
219    let code = (err as BusinessError).code;
220    let message = (err as BusinessError).message;
221    console.error(`Operation failed: error code is ${code}  and error message is ${message}`);
222}
223```
224
225## distributedBundle.getRemoteAbilityInfo
226
227getRemoteAbilityInfo(elementNames: Array\<ElementName>): Promise\<Array\<RemoteAbilityInfo>>
228
229获取由elementName指定的远程设备上的应用的AbilityInfo数组信息。使用Promise异步回调。
230
231**系统接口：** 此接口为系统接口。
232
233**需要权限：** ohos.permission.GET_BUNDLE_INFO_PRIVILEGED
234
235**系统能力：** SystemCapability.BundleManager.DistributedBundleFramework
236
237**参数：**
238
239| 参数名        | 类型                                                | 必填 | 说明                    |
240| ------------ | --------------------------------------------------- | ---- | ----------------------- |
241| elementNames | Array<[ElementName](js-apis-bundleManager-elementName.md)> | 是   | ElementName信息，最大数组长度为10。 |
242
243**返回值：**
244
245| 类型                                                         | 说明                              |
246| ------------------------------------------------------------ | --------------------------------- |
247| Promise\<Array<[RemoteAbilityInfo](js-apis-bundleManager-remoteAbilityInfo-sys.md)>> | Promise对象，调用成功返回RemoteAbilityInfo对象；调用失败返回错误对象。 |
248
249**错误码：**
250
251以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.bundle错误码](errorcode-bundle.md)。
252
253| 错误码ID |    错误信息                   |
254|----------|-------------------------|
255| 201 | Permission denied. |
256| 202 | Permission denied, non-system app called system api. |
257| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.|
258| 801 | Capability not supported. |
259| 17700001 | The specified bundle name is not found. |
260| 17700003 | The specified ability name is not found. |
261| 17700007 | The specified device ID is not found. |
262| 17700027 | The distributed service is not running. |
263
264**示例：**
265
266```ts
267import distributedBundle from '@ohos.bundle.distributedBundleManager';
268import { BusinessError } from '@ohos.base';
269
270try {
271    distributedBundle.getRemoteAbilityInfo(
272        [
273            {
274                deviceId: '1',
275                bundleName: 'com.example.application',
276                abilityName: 'EntryAbility'
277            },
278            {
279                deviceId: '1',
280                bundleName: 'com.example.application2',
281                abilityName: 'EntryAbility'
282            }
283        ]).then((data: distributedBundle.RemoteAbilityInfo[]) => {
284            console.info('Operation succeed:' + JSON.stringify(data));
285        }).catch((err: BusinessError) => {
286            console.error(`Operation failed: error code is ${err.code}  and error message is ${err.message}`);
287        });
288} catch (err) {
289    let code = (err as BusinessError).code;
290    let message = (err as BusinessError).message;
291    console.error(`Operation failed: error code is ${code}  and error message is ${message}`);
292}
293```
294
295## distributedBundle.getRemoteAbilityInfo
296
297getRemoteAbilityInfo(elementName: ElementName, locale: string, callback: AsyncCallback\<RemoteAbilityInfo>): void
298
299获取由elementName和locale指定的远程设备上的应用的AbilityInfo信息。使用callback异步回调。
300
301**系统接口：** 此接口为系统接口。
302
303**需要权限：** ohos.permission.GET_BUNDLE_INFO_PRIVILEGED
304
305**系统能力：** SystemCapability.BundleManager.DistributedBundleFramework
306
307**参数：**
308
309| 参数名       | 类型                                                         | 必填 | 说明                                               |
310| ----------- | ------------------------------------------------------------ | ---- | -------------------------------------------------- |
311| elementName | [ElementName](js-apis-bundleManager-elementName.md)                 | 是   | ElementName信息。                            |
312| locale  | string |是 | 语言地区。 |
313| callback    | AsyncCallback<[RemoteAbilityInfo](js-apis-bundleManager-remoteAbilityInfo-sys.md)> | 是   | [回调函数](../apis-basic-services-kit/js-apis-base.md#asynccallback)，调用成功返回err为null，data为RemoteAbilityInfo对象；调用失败err为错误对象, data为undefined。 |
314
315**错误码：**
316
317以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.bundle错误码](errorcode-bundle.md)。
318
319| 错误码ID |    错误信息                   |
320|----------|-------------------------|
321| 201 | Permission denied. |
322| 202 | Permission denied, non-system app called system api. |
323| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.|
324| 801 | Capability not supported. |
325| 17700001 | The specified bundle name is not found. |
326| 17700003 | The specified ability name is not found. |
327| 17700007 | The specified device ID is not found. |
328| 17700027 | The distributed service is not running. |
329
330**示例：**
331
332```ts
333import distributedBundle from '@ohos.bundle.distributedBundleManager';
334import { BusinessError } from '@ohos.base';
335
336try {
337    distributedBundle.getRemoteAbilityInfo(
338        {
339            deviceId: '1',
340            bundleName: 'com.example.application',
341            abilityName: 'EntryAbility'
342        }, 'zh-Hans-CN', (err: BusinessError, data: distributedBundle.RemoteAbilityInfo) => {
343          if (err) {
344            console.error(`Operation failed: error code is ${err.code}  and error message is ${err.message}`);
345          } else {
346            console.info('Operation succeed:' + JSON.stringify(data));
347          }
348        });
349} catch (err) {
350    let code = (err as BusinessError).code;
351    let message = (err as BusinessError).message;
352    console.error(`Operation failed: error code is ${code}  and error message is ${message}`);
353}
354```
355
356## distributedBundle.getRemoteAbilityInfo
357
358getRemoteAbilityInfo(elementName: ElementName, locale: string): Promise\<RemoteAbilityInfo>
359
360获取由elementName和locale指定的远程设备上的应用的AbilityInfo信息。使用Promise异步回调。
361
362**系统接口：** 此接口为系统接口。
363
364**需要权限：** ohos.permission.GET_BUNDLE_INFO_PRIVILEGED
365
366**系统能力：** SystemCapability.BundleManager.DistributedBundleFramework
367
368**参数：**
369
370| 参数名       | 类型                                         | 必填 | 说明                    |
371| ----------- | -------------------------------------------- | ---- | ----------------------- |
372| elementName | [ElementName](js-apis-bundleManager-elementName.md) | 是   | ElementName信息。 |
373| locale  | string |是 | 语言地区。 |
374
375**返回值：**
376
377| 类型                                                         | 说明                              |
378| ------------------------------------------------------------ | --------------------------------- |
379| Promise\<[RemoteAbilityInfo](js-apis-bundleManager-remoteAbilityInfo-sys.md)> | Promise对象，调用成功返回RemoteAbilityInfo对象；调用失败返回错误对象。 |
380
381**错误码：**
382
383以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.bundle错误码](errorcode-bundle.md)。
384
385| 错误码ID |    错误信息                   |
386|----------|-------------------------|
387| 201 | Permission denied. |
388| 202 | Permission denied, non-system app called system api. |
389| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.|
390| 801 | Capability not supported. |
391| 17700001 | The specified bundle name is not found. |
392| 17700003 | The specified ability name is not found. |
393| 17700007 | The specified device ID is not found. |
394| 17700027 | The distributed service is not running. |
395
396**示例：**
397
398```ts
399import distributedBundle from '@ohos.bundle.distributedBundleManager';
400import { BusinessError } from '@ohos.base';
401
402try {
403    distributedBundle.getRemoteAbilityInfo(
404        {
405            deviceId: '1',
406            bundleName: 'com.example.application',
407            abilityName: 'EntryAbility'
408        }, 'zh-Hans-CN').then((data: distributedBundle.RemoteAbilityInfo) => {
409            console.info('Operation succeed:' + JSON.stringify(data));
410        }).catch((err: BusinessError) => {
411            console.error(`Operation failed: error code is ${err.code}  and error message is ${err.message}`);
412        });
413} catch (err) {
414    let code = (err as BusinessError).code;
415    let message = (err as BusinessError).message;
416    console.error(`Operation failed: error code is ${code}  and error message is ${message}`);
417}
418```
419
420## distributedBundle.getRemoteAbilityInfo
421
422getRemoteAbilityInfo(elementNames: Array\<ElementName>, locale: string, callback: AsyncCallback\<Array\<RemoteAbilityInfo>>): void
423
424获取由elementName和locale指定的远程设备上的应用的AbilityInfo数组信息。使用callback异步回调。
425
426**系统接口：** 此接口为系统接口。
427
428**需要权限：** ohos.permission.GET_BUNDLE_INFO_PRIVILEGED
429
430**系统能力：** SystemCapability.BundleManager.DistributedBundleFramework
431
432**参数：**
433
434| 参数名        | 类型                                                         | 必填 | 说明                                               |
435| ------------ | ------------------------------------------------------------ | ---- | -------------------------------------------------- |
436| elementNames | Array<[ElementName](js-apis-bundleManager-elementName.md)>          | 是   | ElementName信息,最大数组长度为10。                   |
437| locale  | string |是 | 语言地区。 |
438| callback     | AsyncCallback\<Array\<[RemoteAbilityInfo](js-apis-bundleManager-remoteAbilityInfo-sys.md)>> | 是   | [回调函数](../apis-basic-services-kit/js-apis-base.md#asynccallback)，调用成功返回err为null，data为RemoteAbilityInfo数组对象；调用失败err为错误对象, data为undefined。 |
439
440**错误码：**
441
442以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.bundle错误码](errorcode-bundle.md)。
443
444| 错误码ID        |    错误信息                   |
445|---------------|-------------------------|
446| 201 | Permission denied. |
447| 202 | Permission denied, non-system app called system api. |
448| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.|
449| 801 | Capability not supported. |
450| 17700001 | The specified bundle name is not found. |
451| 17700003 | The specified ability name is not found. |
452| 17700007 | The specified device ID is not found. |
453| 17700027 | The distributed service is not running. |
454
455**示例：**
456
457```ts
458import distributedBundle from '@ohos.bundle.distributedBundleManager';
459import { BusinessError } from '@ohos.base';
460
461try {
462    distributedBundle.getRemoteAbilityInfo(
463        [
464            {
465                deviceId: '1',
466                bundleName: 'com.example.application1',
467                abilityName: 'EntryAbility1'
468            },
469            {
470                deviceId: '1',
471                bundleName: 'com.example.application2',
472                abilityName: 'EntryAbility'
473            }
474        ], 'zh-Hans-CN', (err: BusinessError, data: distributedBundle.RemoteAbilityInfo[]) => {
475          if (err) {
476           console.error(`Operation failed: error code is ${err.code}  and error message is ${err.message}`);
477          } else {
478            console.info('Operation succeed:' + JSON.stringify(data));
479          }
480        });
481} catch (err) {
482    let code = (err as BusinessError).code;
483    let message = (err as BusinessError).message;
484    console.error(`Operation failed: error code is ${code}  and error message is ${message}`);
485}
486```
487
488## distributedBundle.getRemoteAbilityInfo
489
490getRemoteAbilityInfo(elementNames: Array\<ElementName>, locale: string): Promise\<Array\<RemoteAbilityInfo>>
491
492获取由elementName和locale指定的远程设备上的应用的AbilityInfo数组信息。使用Promise异步回调。
493
494**系统接口：** 此接口为系统接口。
495
496**需要权限：** ohos.permission.GET_BUNDLE_INFO_PRIVILEGED
497
498**系统能力：** SystemCapability.BundleManager.DistributedBundleFramework
499
500**参数：**
501
502| 参数名        | 类型                                                | 必填 | 说明                    |
503| ------------ | --------------------------------------------------- | ---- | ----------------------- |
504| elementNames | Array<[ElementName](js-apis-bundleManager-elementName.md)> | 是   | ElementName信息,最大数组长度为10。 |
505| locale  | string |是 | 语言地区。 |
506
507**返回值：**
508
509| 类型                                                         | 说明                              |
510| ------------------------------------------------------------ | --------------------------------- |
511| Promise\<Array<[RemoteAbilityInfo](js-apis-bundleManager-remoteAbilityInfo-sys.md)>> | Promise对象，调用成功返回RemoteAbilityInfo对象；调用失败返回错误对象。 |
512
513**错误码：**
514
515以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.bundle错误码](errorcode-bundle.md)。
516
517| 错误码ID |    错误信息                   |
518|----------|-------------------------|
519| 201 | Permission denied. |
520| 202 | Permission denied, non-system app called system api. |
521| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.|
522| 801 | Capability not supported. |
523| 17700001 | The specified bundle name is not found. |
524| 17700003 | The specified ability name is not found. |
525| 17700007 | The specified device ID is not found. |
526| 17700027 | The distributed service is not running. |
527
528**示例：**
529
530```ts
531import distributedBundle from '@ohos.bundle.distributedBundleManager';
532import { BusinessError } from '@ohos.base';
533
534try {
535    distributedBundle.getRemoteAbilityInfo(
536        [
537            {
538                deviceId: '1',
539                bundleName: 'com.example.application',
540                abilityName: 'EntryAbility'
541            },
542            {
543                deviceId: '1',
544                bundleName: 'com.example.application2',
545                abilityName: 'EntryAbility'
546            }
547        ], 'zh-Hans-CN').then((data: distributedBundle.RemoteAbilityInfo[]) => {
548            console.info('Operation succeed:' + JSON.stringify(data));
549        }).catch((err: BusinessError) => {
550            console.error(`Operation failed: error code is ${err.code}  and error message is ${err.message}`);
551        });
552} catch (err) {
553    let code = (err as BusinessError).code;
554    let message = (err as BusinessError).message;
555    console.error(`Operation failed: error code is ${code}  and error message is ${message}`);
556}
557```
558
559## RemoteAbilityInfo
560
561type RemoteAbilityInfo = _RemoteAbilityInfo
562
563包含远程的ability信息。
564
565**系统接口：** 此接口为系统接口。
566
567**系统能力：** SystemCapability.BundleManager.DistributedBundleFramework
568
569| 类型                                                         | 说明           |
570| ------------------------------------------------------------ | -------------- |
571| [_RemoteAbilityInfo](js-apis-bundleManager-remoteAbilityInfo-sys.md#remoteabilityinfo) |包含远程的ability信息。 |