1# @ohos.bundle.distributedBundleManager (distributedBundleManager) (System API) 2<!--Kit: Ability Kit--> 3<!--Subsystem: BundleManager--> 4<!--Owner: @wanghang904--> 5<!--Designer: @hanfeng6--> 6<!--Tester: @kongjing2--> 7<!--Adviser: @Brilliantry_Rui--> 8 9The module provides APIs for managing distributed bundles. 10 11> **NOTE** 12> 13> 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. 14> 15> The APIs provided by this module are system APIs. 16 17## Modules to Import 18 19``` ts 20import distributedBundle from '@ohos.bundle.distributedBundleManager'; 21``` 22 23## System Capabilities 24 25SystemCapability.BundleManager.DistributedBundleFramework 26 27## Required Permissions 28 29| Permission | APL | Description | 30| ------------------------------------------ | ------------ | ------------------ | 31| ohos.permission.GET_BUNDLE_INFO_PRIVILEGED | system_basic | Permission to obtain basic information and other sensitive information about a bundle.| 32 33For details about the APL, see [Basic Concepts in the Permission Mechanism](../../security/AccessToken/app-permission-mgmt-overview.md#basic-concepts-in-the-permission-mechanism). 34 35## distributedBundle.getRemoteAbilityInfo 36 37getRemoteAbilityInfo(elementName: ElementName, callback: AsyncCallback\<RemoteAbilityInfo>): void 38 39Obtains information about the remote ability that matches the given element name. This API uses an asynchronous callback to return the result. 40 41**System API**: This is a system API. 42 43**Required permissions**: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED 44 45**System capability**: SystemCapability.BundleManager.DistributedBundleFramework 46 47**Parameters** 48 49| Name | Type | Mandatory| Description | 50| ----------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 51| elementName | [ElementName](js-apis-bundleManager-elementName.md) | Yes | Target element name. | 52| callback | AsyncCallback<[RemoteAbilityInfo](js-apis-bundleManager-remoteAbilityInfo-sys.md)> | Yes | [Callback](../apis-basic-services-kit/js-apis-base.md#asynccallback) 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**.| 53 54**Error codes** 55 56For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Bundle Error Codes](errorcode-bundle.md). 57 58| ID| Error Message | 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**Example** 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 99Obtains information about the remote ability that matches the given element name. This API uses a promise to return the result. 100 101**System API**: This is a system API. 102 103**Required permissions**: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED 104 105**System capability**: SystemCapability.BundleManager.DistributedBundleFramework 106 107**Parameters** 108 109| Name | Type | Mandatory| Description | 110| ----------- | -------------------------------------------- | ---- | ----------------------- | 111| elementName | [ElementName](js-apis-bundleManager-elementName.md) | Yes | Target element name.| 112 113**Return value** 114 115| Type | Description | 116| ------------------------------------------------------------ | --------------------------------- | 117| 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.| 118 119**Error codes** 120 121For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Bundle Error Codes](errorcode-bundle.md). 122 123| ID| Error Message | 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**Example** 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 162Obtains information about the remote abilities that match the given element names. This API uses an asynchronous callback to return the result. 163 164**System API**: This is a system API. 165 166**Required permissions**: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED 167 168**System capability**: SystemCapability.BundleManager.DistributedBundleFramework 169 170**Parameters** 171 172| Name | Type | Mandatory| Description | 173| ------------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 174| elementNames | Array<[ElementName](js-apis-bundleManager-elementName.md)> | Yes | **ElementName** array, whose maximum length is 10. | 175| callback | AsyncCallback\<Array\<[RemoteAbilityInfo](js-apis-bundleManager-remoteAbilityInfo-sys.md)>> | Yes | [Callback](../apis-basic-services-kit/js-apis-base.md#asynccallback) 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**.| 176 177**Error codes** 178 179For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Bundle Error Codes](errorcode-bundle.md). 180 181| ID| Error Message | 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**Example** 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 229Obtains information about the remote abilities that match the given element names. This API uses a promise to return the result. 230 231**System API**: This is a system API. 232 233**Required permissions**: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED 234 235**System capability**: SystemCapability.BundleManager.DistributedBundleFramework 236 237**Parameters** 238 239| Name | Type | Mandatory| Description | 240| ------------ | --------------------------------------------------- | ---- | ----------------------- | 241| elementNames | Array<[ElementName](js-apis-bundleManager-elementName.md)> | Yes | **ElementName** array, whose maximum length is 10.| 242 243**Return value** 244 245| Type | Description | 246| ------------------------------------------------------------ | --------------------------------- | 247| 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.| 248 249**Error codes** 250 251For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Bundle Error Codes](errorcode-bundle.md). 252 253| ID| Error Message | 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**Example** 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 299Obtains information about the remote ability that matches the given element name and locale. This API uses an asynchronous callback to return the result. 300 301**System API**: This is a system API. 302 303**Required permissions**: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED 304 305**System capability**: SystemCapability.BundleManager.DistributedBundleFramework 306 307**Parameters** 308 309| Name | Type | Mandatory| Description | 310| ----------- | ------------------------------------------------------------ | ---- | -------------------------------------------------- | 311| elementName | [ElementName](js-apis-bundleManager-elementName.md) | Yes | Target element name. | 312| locale | string |Yes| Target locale.| 313| callback | AsyncCallback<[RemoteAbilityInfo](js-apis-bundleManager-remoteAbilityInfo-sys.md)> | Yes | [Callback](../apis-basic-services-kit/js-apis-base.md#asynccallback) 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**.| 314 315**Error codes** 316 317For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Bundle Error Codes](errorcode-bundle.md). 318 319| ID| Error Message | 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**Example** 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 360Obtains information about the remote ability that matches the given element name and locale. This API uses a promise to return the result. 361 362**System API**: This is a system API. 363 364**Required permissions**: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED 365 366**System capability**: SystemCapability.BundleManager.DistributedBundleFramework 367 368**Parameters** 369 370| Name | Type | Mandatory| Description | 371| ----------- | -------------------------------------------- | ---- | ----------------------- | 372| elementName | [ElementName](js-apis-bundleManager-elementName.md) | Yes | Target element name.| 373| locale | string |Yes| Target locale.| 374 375**Return value** 376 377| Type | Description | 378| ------------------------------------------------------------ | --------------------------------- | 379| 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.| 380 381**Error codes** 382 383For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Bundle Error Codes](errorcode-bundle.md). 384 385| ID| Error Message | 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**Example** 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 424Obtains information about the remote abilities that match the given element names and locale. This API uses an asynchronous callback to return the result. 425 426**System API**: This is a system API. 427 428**Required permissions**: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED 429 430**System capability**: SystemCapability.BundleManager.DistributedBundleFramework 431 432**Parameters** 433 434| Name | Type | Mandatory| Description | 435| ------------ | ------------------------------------------------------------ | ---- | -------------------------------------------------- | 436| elementNames | Array<[ElementName](js-apis-bundleManager-elementName.md)> | Yes | **ElementName** array, whose maximum length is 10. | 437| locale | string |Yes| Target locale.| 438| callback | AsyncCallback\<Array\<[RemoteAbilityInfo](js-apis-bundleManager-remoteAbilityInfo-sys.md)>> | Yes | [Callback](../apis-basic-services-kit/js-apis-base.md#asynccallback) 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**.| 439 440**Error codes** 441 442For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Bundle Error Codes](errorcode-bundle.md). 443 444| ID | Error Message | 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**Example** 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 492Obtains information about the remote abilities that match the given element names and locale. This API uses a promise to return the result. 493 494**System API**: This is a system API. 495 496**Required permissions**: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED 497 498**System capability**: SystemCapability.BundleManager.DistributedBundleFramework 499 500**Parameters** 501 502| Name | Type | Mandatory| Description | 503| ------------ | --------------------------------------------------- | ---- | ----------------------- | 504| elementNames | Array<[ElementName](js-apis-bundleManager-elementName.md)> | Yes | **ElementName** array, whose maximum length is 10.| 505| locale | string |Yes| Target locale.| 506 507**Return value** 508 509| Type | Description | 510| ------------------------------------------------------------ | --------------------------------- | 511| 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.| 512 513**Error codes** 514 515For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Bundle Error Codes](errorcode-bundle.md). 516 517| ID| Error Message | 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**Example** 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 563Defines the remote ability information. 564 565**System API**: This is a system API. 566 567**System capability**: SystemCapability.BundleManager.DistributedBundleFramework 568 569| Type | Description | 570| ------------------------------------------------------------ | -------------- | 571| [_RemoteAbilityInfo](js-apis-bundleManager-remoteAbilityInfo-sys.md#remoteabilityinfo) |Remote ability information.| 572