1# ParticleAbility Module 2 3>  **NOTE** 4> The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version. 5 6## Constraints 7 8The ParticleAbility module is used to perform operations on abilities of the Data and Service types. 9 10## Modules to Import 11 12```js 13import particleAbility from '@ohos.ability.particleAbility' 14``` 15 16## particleAbility.startAbility 17 18startAbility(parameter: StartAbilityParameter, callback: AsyncCallback\<void>): void 19 20Starts a Particle ability. This API uses an asynchronous callback to return the result. 21 22**System capability**: SystemCapability.Ability.AbilityRuntime.FAModel 23 24**Parameters** 25 26 27| Name | Type | Mandatory| Description | 28| --------- | ----------------------------------------------- | ---- | ----------------- | 29| parameter | [StartAbilityParameter](js-apis-featureAbility.md#startabilityparameter) | Yes | Ability to start.| 30| callback | AsyncCallback\<void> | Yes | Callback used to return the result. | 31 32**Example** 33 34```js 35import particleAbility from '@ohos.ability.particleAbility' 36import wantConstant from '@ohos.ability.wantConstant' 37particleAbility.startAbility( 38 { 39 want: 40 { 41 action: "action.system.home", 42 entities: ["entity.system.home"], 43 type: "MIMETYPE", 44 flags: wantConstant.Flags.FLAG_AUTH_READ_URI_PERMISSION, 45 deviceId: "", 46 bundleName: "com.example.Data", 47 abilityName: "com.example.Data.MainAbility", 48 uri:"" 49 }, 50 }, 51 (error, result) => { 52 console.log('particleAbility startAbility errCode:' + error + 'result:' + result) 53 }, 54) 55``` 56 57 58 59## particleAbility.startAbility 60 61startAbility(parameter: StartAbilityParameter): Promise\<void>; 62 63Starts a Particle ability. This API uses a promise to return the result. 64 65**System capability**: SystemCapability.Ability.AbilityRuntime.FAModel 66 67**Parameters** 68 69 70| Name | Type | Mandatory| Description | 71| --------- | ----------------------------------------------- | ---- | ----------------- | 72| parameter | [StartAbilityParameter](js-apis-featureAbility.md#startabilityparameter) | Yes | Ability to start.| 73 74**Return value** 75 76| Type | Description | 77| -------------- | ------------------------- | 78| Promise\<void> | Promise used to return the result.| 79 80**Example** 81 82```js 83import particleAbility from '@ohos.ability.particleAbility' 84import wantConstant from '@ohos.ability.wantConstant' 85particleAbility.startAbility( 86 { 87 want: 88 { 89 action: "action.system.home", 90 entities: ["entity.system.home"], 91 type: "MIMETYPE", 92 flags: wantConstant.Flags.FLAG_AUTH_READ_URI_PERMISSION, 93 deviceId: "", 94 bundleName: "com.example.Data", 95 abilityName: "com.example. Data.MainAbility", 96 uri:"" 97 }, 98 }, 99).then((data) => { 100 console.info("particleAbility startAbility"); 101}); 102``` 103 104 105 106## particleAbility.terminateSelf 107 108terminateSelf(callback: AsyncCallback\<void>): void 109 110Terminates this Particle ability. This API uses an asynchronous callback to return the result. 111 112**System capability**: SystemCapability.Ability.AbilityRuntime.FAModel 113 114**Parameters** 115 116| Name | Type | Mandatory| Description | 117| -------- | -------------------- | ---- | -------------------- | 118| callback | AsyncCallback\<void> | Yes | Callback used to return the result.| 119 120**Example** 121 122```js 123import particleAbility from '@ohos.ability.particleAbility' 124particleAbility.terminateSelf( 125 (error, result) => { 126 console.log('particleAbility terminateSelf errCode:' + error + 'result:' + result) 127 } 128) 129``` 130 131 132 133## particleAbility.terminateSelf 134 135terminateSelf(): Promise\<void> 136 137Terminates this Particle ability. This API uses a promise to return the result. 138 139**System capability**: SystemCapability.Ability.AbilityRuntime.FAModel 140 141**Return value** 142 143| Type | Description | 144| -------------- | ------------------------- | 145| Promise\<void> | Promise used to return the result.| 146 147**Example** 148 149```js 150import particleAbility from '@ohos.ability.particleAbility' 151particleAbility.terminateSelf().then((data) => { 152 console.info("particleAbility terminateSelf"); 153}); 154``` 155 156 157 158## particleAbility.acquireDataAbilityHelper 159 160acquireDataAbilityHelper(uri: string): DataAbilityHelper 161 162Obtains a **dataAbilityHelper** object. 163 164**System capability**: SystemCapability.Ability.AbilityRuntime.FAModel 165 166**Parameters** 167 168| Name| Type | Mandatory| Description | 169| :--- | ------ | ---- | ------------------------ | 170| uri | string | Yes | URI of the file to open.| 171 172**Return value** 173 174| Type | Description | 175| ----------------- | -------------------------------------------- | 176| DataAbilityHelper | A utility class used to help other abilities access a Data ability.| 177 178**Example** 179 180```js 181import particleAbility from '@ohos.ability.particleAbility' 182var uri = ""; 183particleAbility.acquireDataAbilityHelper(uri) 184``` 185 186 187## particleAbility.startBackgroundRunning 188 189startBackgroundRunning(id: number, request: NotificationRequest, callback: AsyncCallback<void>): void; 190 191Requests a continuous task from the system. This API uses an asynchronous callback to return the result. You are advised to use the new API [backgroundTaskManager.startBackgroundRunning](js-apis-backgroundTaskManager.md#backgroundtaskmanagerstartbackgroundrunning8). 192 193**Required permissions**: ohos.permission.KEEP_BACKGROUND_RUNNING 194 195**System capability**: SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 196 197**Parameters** 198 199 | Name| Type| Mandatory| Description| 200 | -------- | -------- | -------- | -------- | 201 | id | number | Yes| Notification ID of a continuous task.| 202 | request | NotificationRequest | Yes| Notification parameter, which is used to display information in the notification bar.| 203 | callback | AsyncCallback<void> | Yes| Callback used to return the result.| 204 205 **Example** 206 207```js 208import notification from '@ohos.notification'; 209import particleAbility from '@ohos.ability.particleAbility'; 210import wantAgent from '@ohos.wantAgent'; 211 212function callback(err, data) { 213 if (err) { 214 console.error("Operation failed Cause: " + err); 215 } else { 216 console.info("Operation succeeded"); 217 } 218} 219 220let wantAgentInfo = { 221 wants: [ 222 { 223 bundleName: "com.example.myapplication", 224 abilityName: "com.example.myapplication.MainAbility" 225 } 226 ], 227 operationType: wantAgent.OperationType.START_ABILITY, 228 requestCode: 0, 229 wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESET_FLAG] 230}; 231 232wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => { 233 let basicContent = { 234 title: "title", 235 text: "text" 236 }; 237 let notificationContent = { 238 contentType: notification.ContentType.NOTIFICATION_CONTENT_TEXT, 239 normal: basicContent 240 }; 241 let request = { 242 content: notificatonContent, 243 wantAgent: wantAgentObj 244 }; 245 let id = 1; 246 particleAbility.startBackgroundRunning(id, request, callback); 247}); 248 249``` 250 251## particleAbility.startBackgroundRunning 252 253startBackgroundRunning(id: number, request: NotificationRequest): Promise<void> 254 255**Required permissions**: ohos.permission.KEEP_BACKGROUND_RUNNING 256 257**System capability**: SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 258 259Requests a continuous task from the system. This API uses a promise to return the result. You are advised to use the new API [backgroundTaskManager.startBackgroundRunning](js-apis-backgroundTaskManager.md#backgroundtaskmanagerstartbackgroundrunning8-1). 260 261**Parameters** 262 263| Name| Type| Mandatory| Description| 264| -------- | -------- | -------- | -------- | 265| id | number | Yes| Notification ID of a continuous task.| 266| request | NotificationRequest | Yes| Notification parameter, which is used to display information in the notification bar.| 267 268**Return value** 269 270| Type | Description | 271| -------------- | ------------------------- | 272| Promise\<void> | Promise used to return the result.| 273 274**Example** 275 276```js 277import notification from '@ohos.notification'; 278import particleAbility from '@ohos.ability.particleAbility'; 279import wantAgent from '@ohos.wantAgent'; 280 281let wantAgentInfo = { 282 wants: [ 283 { 284 bundleName: "com.example.myapplication", 285 abilityName: "com.example.myapplication.MainAbility" 286 } 287 ], 288 operationType: wantAgent.OperationType.START_ABILITY, 289 requestCode: 0, 290 wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESET_FLAG] 291}; 292 293wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => { 294 let basicContent = { 295 title: "title", 296 text: "text" 297 }; 298 let notificationContent = { 299 contentType: notification.ContentType.NOTIFICATION_CONTENT_TEXT, 300 normal: basicContent 301 }; 302 let request = { 303 content: notificatonContent, 304 wantAgent: wantAgentObj 305 }; 306 let id = 1; 307 particleAbility.startBackgroundRunning(id, request).then(() => { 308 console.info("Operation succeeded"); 309 }).catch((err) => { 310 console.error("Operation failed Cause: " + err); 311 }); 312}); 313 314``` 315 316## particleAbility.cancelBackgroundRunning 317 318cancelBackgroundRunning(callback: AsyncCallback<void>): void; 319 320Requests to cancel a continuous task from the system. This API uses an asynchronous callback to return the result. You are advised to use the new API [backgroundTaskManager.stopBackgroundRunning](js-apis-backgroundTaskManager.md#backgroundtaskmanagerstopbackgroundrunning8). 321 322**System capability**: SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 323 324 **Parameters** 325 326 | Name| Type| Mandatory| Description| 327 | -------- | -------- | -------- | -------- | 328 | callback | AsyncCallback<void> | Yes| Callback used to return the result.| 329 330 **Example** 331 332```js 333import particleAbility from '@ohos.ability.particleAbility'; 334 335function callback(err, data) { 336 if (err) { 337 console.error("Operation failed Cause: " + err); 338 } else { 339 console.info("Operation succeeded"); 340 } 341} 342 343particleAbility.cancelBackgroundRunning(callback); 344 345``` 346 347## particleAbility.cancelBackgroundRunning 348 349cancelBackgroundRunning(): Promise<void>; 350 351Requests a continuous task from the system. This API uses a promise to return the result. You are advised to use the new API [backgroundTaskManager.stopBackgroundRunning](js-apis-backgroundTaskManager.md#backgroundtaskmanagerstopbackgroundrunning8-1). 352 353**System capability**: SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 354 355**Return value** 356 357| Type | Description | 358| -------------- | ------------------------- | 359| Promise\<void> | Promise used to return the result.| 360 361 **Example** 362 363```js 364import particleAbility from '@ohos.ability.particleAbility'; 365 366particleAbility.cancelBackgroundRunning().then(() => { 367 console.info("Operation succeeded"); 368}).catch((err) => { 369 console.error("Operation failed Cause: " + err); 370}); 371 372``` 373 374 375## particleAbility.connectAbility 376 377connectAbility(request: Want, options:ConnectOptions): number 378 379Connects this ability to a specific Service ability. This API uses a callback to return the result. 380 381**System capability**: SystemCapability.Ability.AbilityRuntime.FAModel 382 383**Parameters** 384 385| Name | Type | Mandatory| Description | 386| ------- | -------------- | ---- | ---------------------------- | 387| request | [Want](js-apis-featureAbility.md#want) | Yes | Service ability to connect.| 388| options | ConnectOptions | Yes | Callback used to return the result. | 389 390 391ConnectOptions 392 393**System capability**: SystemCapability.Ability.AbilityRuntime.Core 394 395| Name | Readable/Writable| Type | Mandatory | Description | 396| ------------ | ---- | -------- | ---- | ------------------------- | 397| onConnect | Read only | function | Yes | Callback invoked when the connection is successful. | 398| onDisconnect | Read only | function | Yes | Callback invoked when the connection fails. | 399| onFailed | Read only | function | Yes | Callback invoked when **connectAbility** fails to be called.| 400 401**Example** 402 403```js 404 function onConnectCallback(element, remote){ 405 console.log('ConnectAbility onConnect remote is proxy:' + (remote instanceof rpc.RemoteProxy)); 406 } 407 function onDisconnectCallback(element){ 408 console.log('ConnectAbility onDisconnect element.deviceId : ' + element.deviceId) 409 } 410 function onFailedCallback(code){ 411 console.log('particleAbilityTest ConnectAbility onFailed errCode : ' + code) 412 } 413 var connId = particleAbility.connectAbility( 414 { 415 bundleName: "com.ix.ServiceAbility", 416 abilityName: "ServiceAbilityA", 417 }, 418 { 419 onConnect: onConnectCallback, 420 onDisconnect: onDisconnectCallback, 421 onFailed: onFailedCallback, 422 }, 423 ); 424 425 particleAbility.disconnectAbility(connId).then((error,data)=>{ 426 console.log('particleAbilityTest result errCode : ' + error.code + " data: " + data); 427 }); 428 429 430``` 431 432 433## particleAbility.disconnectAbility 434 435disconnectAbility(connection: number, callback:AsyncCallback\<void>): void; 436 437Disconnects this ability from the Service ability. This API uses a callback to return the result. 438 439**System capability**: SystemCapability.Ability.AbilityRuntime.FAModel 440 441**Parameters** 442 443 | Name| Type| Mandatory| Description| 444 | -------- | -------- | -------- | -------- | 445 | callback | AsyncCallback<void> | Yes| Callback used to return the result.| 446 447**Example** 448 449```js 450 function onConnectCallback(element, remote){ 451 console.log('ConnectAbility onConnect remote is proxy:' + (remote instanceof rpc.RemoteProxy)); 452 } 453 function onDisconnectCallback(element){ 454 console.log('ConnectAbility onDisconnect element.deviceId : ' + element.deviceId) 455 } 456 function onFailedCallback(code){ 457 console.log('particleAbilityTest ConnectAbility onFailed errCode : ' + code) 458 } 459 var connId = particleAbility.connectAbility( 460 { 461 bundleName: "com.ix.ServiceAbility", 462 abilityName: "ServiceAbilityA", 463 }, 464 { 465 onConnect: onConnectCallback, 466 onDisconnect: onDisconnectCallback, 467 onFailed: onFailedCallback, 468 }, 469 ); 470 var result = particleAbility.disconnectAbility(connId, 471 (error,data) => { 472 console.log('particleAbilityTest DisConnectJsSameBundleName result errCode : ' + error.code + " data: " + data) 473 }, 474 ); 475 476``` 477 478 479## particleAbility.disconnectAbility 480 481disconnectAbility(connection: number): Promise\<void>; 482 483Disconnects this ability from the Service ability. This API uses a promise to return the result. 484 485**System capability**: SystemCapability.Ability.AbilityRuntime.FAModel 486 487**Return value** 488 489| Type | Description | 490| -------------- | ------------------------- | 491| Promise\<void> | Promise used to return the result.| 492 493**Example** 494 495```js 496function onConnectCallback(element, remote){ 497 console.log('ConnectAbility onConnect remote is proxy:' + (remote instanceof rpc.RemoteProxy)); 498 } 499 function onDisconnectCallback(element){ 500 console.log('ConnectAbility onDisconnect element.deviceId : ' + element.deviceId) 501 } 502 function onFailedCallback(code){ 503 console.log('particleAbilityTest ConnectAbility onFailed errCode : ' + code) 504 } 505 var connId = particleAbility.connectAbility( 506 { 507 bundleName: "com.ix.ServiceAbility", 508 abilityName: "ServiceAbilityA", 509 }, 510 { 511 onConnect: onConnectCallback, 512 onDisconnect: onDisconnectCallback, 513 onFailed: onFailedCallback, 514 }, 515 ); 516 517 particleAbility.disconnectAbility(connId).then((error,data)=>{ 518 console.log('particleAbilityTest result errCode : ' + error.code + " data: " + data); 519 }); 520 521``` 522 523## ErrorCode 524 525Enumerates error codes. 526 527**System capability**: SystemCapability.Ability.AbilityRuntime.FAModel 528 529| Name | Value | Description | 530| ----------------------------- | ---- | ------------------------------------------------------------ | 531| INVALID_PARAMETER | -1 | Invalid parameter.| 532
