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