js-apis-particleAbility.md 16.6 KB
Newer Older
W
wusongqing 已提交
1 2
# ParticleAbility Module

W
wusongqing 已提交
3 4 5
> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE**
> 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.

W
wusongqing 已提交
6 7 8 9 10 11 12 13 14 15
## Constraints

The ParticleAbility module is used to perform operations on abilities of the Data and Service types.

## Modules to Import

```js
import particleAbility from '@ohos.ability.particleAbility'
```

W
wusongqing 已提交
16
## particleAbility.startAbility
W
wusongqing 已提交
17

W
wusongqing 已提交
18
startAbility(parameter: StartAbilityParameter, callback: AsyncCallback\<void>): void
W
wusongqing 已提交
19

W
wusongqing 已提交
20
Starts a Particle ability. This API uses an asynchronous callback to return the result.
W
wusongqing 已提交
21

W
wusongqing 已提交
22
**System capability**: SystemCapability.Ability.AbilityRuntime.FAModel
W
wusongqing 已提交
23

W
wusongqing 已提交
24
**Parameters**
W
wusongqing 已提交
25 26


W
wusongqing 已提交
27
| Name     | Type                                           | Mandatory| Description             |
W
wusongqing 已提交
28
| --------- | ----------------------------------------------- | ---- | ----------------- |
29
| parameter | [StartAbilityParameter](js-apis-featureAbility.md#startabilityparameter) | Yes  | Ability to start.|
W
wusongqing 已提交
30
| callback  | AsyncCallback\<void>                            | Yes  | Callback used to return the result. |
W
wusongqing 已提交
31

W
wusongqing 已提交
32
**Example**
W
wusongqing 已提交
33 34 35

```js
import particleAbility from '@ohos.ability.particleAbility'
W
wusongqing 已提交
36
import wantConstant from '@ohos.ability.wantConstant'
W
wusongqing 已提交
37 38 39 40 41 42 43
particleAbility.startAbility(
	{
        want:
        {
            action: "action.system.home",
            entities: ["entity.system.home"],
            type: "MIMETYPE",
W
wusongqing 已提交
44
            flags: wantConstant.Flags.FLAG_AUTH_READ_URI_PERMISSION,
W
wusongqing 已提交
45 46 47 48 49 50 51 52 53 54 55 56 57 58
            deviceId: "",
            bundleName: "com.example.Data",
            abilityName: "com.example.Data.MainAbility",
            uri:""
        },
    },
    (error, result) => {
		console.log('particleAbility startAbility errCode:' + error + 'result:' + result)
    },
)
```



W
wusongqing 已提交
59
## particleAbility.startAbility
W
wusongqing 已提交
60

61
startAbility(parameter: StartAbilityParameter): Promise\<void>;
W
wusongqing 已提交
62

W
wusongqing 已提交
63
Starts a Particle ability. This API uses a promise to return the result.
W
wusongqing 已提交
64

W
wusongqing 已提交
65
**System capability**: SystemCapability.Ability.AbilityRuntime.FAModel
W
wusongqing 已提交
66

W
wusongqing 已提交
67
**Parameters**
W
wusongqing 已提交
68 69


W
wusongqing 已提交
70
| Name     | Type                                           | Mandatory| Description             |
W
wusongqing 已提交
71
| --------- | ----------------------------------------------- | ---- | ----------------- |
72
| parameter | [StartAbilityParameter](js-apis-featureAbility.md#startabilityparameter) | Yes  | Ability to start.|
W
wusongqing 已提交
73

W
wusongqing 已提交
74
**Return value**
W
wusongqing 已提交
75

W
wusongqing 已提交
76
| Type          | Description                     |
W
wusongqing 已提交
77
| -------------- | ------------------------- |
W
wusongqing 已提交
78
| Promise\<void> | Promise used to return the result.|
W
wusongqing 已提交
79

W
wusongqing 已提交
80
**Example**
W
wusongqing 已提交
81 82 83

```js
import particleAbility from '@ohos.ability.particleAbility'
W
wusongqing 已提交
84
import wantConstant from '@ohos.ability.wantConstant'
W
wusongqing 已提交
85 86 87 88 89 90 91
particleAbility.startAbility(
	{
        want:
        {
            action: "action.system.home",
            entities: ["entity.system.home"],
            type: "MIMETYPE",
W
wusongqing 已提交
92
            flags: wantConstant.Flags.FLAG_AUTH_READ_URI_PERMISSION,
W
wusongqing 已提交
93 94
            deviceId: "",
            bundleName: "com.example.Data",
W
wusongqing 已提交
95
            abilityName: "com.example. Data.MainAbility",
W
wusongqing 已提交
96 97 98
            uri:""
        },
    },
W
wusongqing 已提交
99
).then((data) => {
W
wusongqing 已提交
100 101 102 103 104 105
    console.info("particleAbility startAbility");
});
```



W
wusongqing 已提交
106
## particleAbility.terminateSelf
W
wusongqing 已提交
107

W
wusongqing 已提交
108
terminateSelf(callback: AsyncCallback\<void>): void
W
wusongqing 已提交
109

W
wusongqing 已提交
110
Terminates this Particle ability. This API uses an asynchronous callback to return the result.
W
wusongqing 已提交
111

W
wusongqing 已提交
112
**System capability**: SystemCapability.Ability.AbilityRuntime.FAModel
W
wusongqing 已提交
113

W
wusongqing 已提交
114
**Parameters**
W
wusongqing 已提交
115

W
wusongqing 已提交
116
| Name    | Type                | Mandatory| Description                |
W
wusongqing 已提交
117
| -------- | -------------------- | ---- | -------------------- |
W
wusongqing 已提交
118
| callback | AsyncCallback\<void> | Yes  | Callback used to return the result.|
W
wusongqing 已提交
119

W
wusongqing 已提交
120
**Example**
W
wusongqing 已提交
121 122 123 124 125 126 127 128 129 130 131 132

```js
import particleAbility from '@ohos.ability.particleAbility'
particleAbility.terminateSelf(
    (error, result) => {
		console.log('particleAbility terminateSelf errCode:' + error + 'result:' + result)
    }
)
```



W
wusongqing 已提交
133
## particleAbility.terminateSelf
W
wusongqing 已提交
134

W
wusongqing 已提交
135
terminateSelf(): Promise\<void>
W
wusongqing 已提交
136

W
wusongqing 已提交
137
Terminates this Particle ability. This API uses a promise to return the result.
W
wusongqing 已提交
138

W
wusongqing 已提交
139
**System capability**: SystemCapability.Ability.AbilityRuntime.FAModel
W
wusongqing 已提交
140

W
wusongqing 已提交
141
**Return value**
W
wusongqing 已提交
142

W
wusongqing 已提交
143
| Type          | Description                     |
W
wusongqing 已提交
144
| -------------- | ------------------------- |
W
wusongqing 已提交
145
| Promise\<void> | Promise used to return the result.|
W
wusongqing 已提交
146

W
wusongqing 已提交
147
**Example**
W
wusongqing 已提交
148 149 150

```js
import particleAbility from '@ohos.ability.particleAbility'
W
wusongqing 已提交
151
particleAbility.terminateSelf().then((data) => {
W
wusongqing 已提交
152 153 154 155 156 157
	console.info("particleAbility terminateSelf");
});
```



W
wusongqing 已提交
158
## particleAbility.acquireDataAbilityHelper
W
wusongqing 已提交
159

W
wusongqing 已提交
160
acquireDataAbilityHelper(uri: string): DataAbilityHelper
W
wusongqing 已提交
161

W
wusongqing 已提交
162
Obtains a **dataAbilityHelper** object.
W
wusongqing 已提交
163

W
wusongqing 已提交
164
**System capability**: SystemCapability.Ability.AbilityRuntime.FAModel
W
wusongqing 已提交
165

W
wusongqing 已提交
166
**Parameters**
W
wusongqing 已提交
167

W
wusongqing 已提交
168
| Name| Type  | Mandatory| Description                    |
W
wusongqing 已提交
169
| :--- | ------ | ---- | ------------------------ |
W
wusongqing 已提交
170
| uri  | string | Yes  | URI of the file to open.|
W
wusongqing 已提交
171

W
wusongqing 已提交
172
**Return value**
W
wusongqing 已提交
173

W
wusongqing 已提交
174
| Type             | Description                                        |
W
wusongqing 已提交
175
| ----------------- | -------------------------------------------- |
W
wusongqing 已提交
176 177
| DataAbilityHelper | A utility class used to help other abilities access a Data ability.|

W
wusongqing 已提交
178
**Example**
W
wusongqing 已提交
179 180 181 182 183 184 185

```js
import particleAbility from '@ohos.ability.particleAbility'     
var uri = "";
particleAbility.acquireDataAbilityHelper(uri)
```

W
wusongqing 已提交
186 187 188 189 190

## particleAbility.startBackgroundRunning

startBackgroundRunning(id: number, request: NotificationRequest, callback: AsyncCallback&lt;void&gt;): void;

W
wusongqing 已提交
191 192 193
Requests 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).

**Required permissions**: ohos.permission.KEEP_BACKGROUND_RUNNING
W
wusongqing 已提交
194

W
wusongqing 已提交
195
**System capability**: SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask
W
wusongqing 已提交
196

W
wusongqing 已提交
197
**Parameters**
W
wusongqing 已提交
198

W
wusongqing 已提交
199 200 201 202
  | Name| Type| Mandatory| Description|
  | -------- | -------- | -------- | -------- |
  | id | number | Yes| Notification ID of a continuous task.|
  | request | NotificationRequest | Yes| Notification parameter, which is used to display information in the notification bar.|
W
wusongqing 已提交
203 204 205
  | callback | AsyncCallback&lt;void&gt; | Yes| Callback used to return the result.|

 **Example**
W
wusongqing 已提交
206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254

```js
import notification from '@ohos.notification';
import particleAbility from '@ohos.ability.particleAbility';
import wantAgent from '@ohos.wantAgent';

function callback(err, data) {
    if (err) {
        console.error("Operation failed Cause: " + err);
    } else {
        console.info("Operation succeeded");
    }
}

let wantAgentInfo = {
    wants: [
        {
            bundleName: "com.example.myapplication",
            abilityName: "com.example.myapplication.MainAbility"
        }
    ],
    operationType: wantAgent.OperationType.START_ABILITY,
    requestCode: 0,
    wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESET_FLAG]
};

wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => {
    let basicContent = {
        title: "title",
        text: "text"
    };
    let notificationContent = {
        contentType: notification.ContentType.NOTIFICATION_CONTENT_TEXT,
        normal: basicContent
    };
    let request = {
        content: notificatonContent,
        wantAgent: wantAgentObj
    };
    let id = 1;
    particleAbility.startBackgroundRunning(id, request, callback);
});

```

## particleAbility.startBackgroundRunning

startBackgroundRunning(id: number, request: NotificationRequest): Promise&lt;void&gt;

W
wusongqing 已提交
255 256
**Required permissions**: ohos.permission.KEEP_BACKGROUND_RUNNING

W
wusongqing 已提交
257
**System capability**: SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask
W
wusongqing 已提交
258

W
wusongqing 已提交
259
Requests 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).
W
wusongqing 已提交
260 261

**Parameters**
W
wusongqing 已提交
262

W
wusongqing 已提交
263 264 265 266 267 268
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| id | number | Yes| Notification ID of a continuous task.|
| request | NotificationRequest | Yes| Notification parameter, which is used to display information in the notification bar.|

**Return value**
W
wusongqing 已提交
269

W
wusongqing 已提交
270
| Type          | Description                     |
W
wusongqing 已提交
271 272 273
| -------------- | ------------------------- |
| Promise\<void> | Promise used to return the result.|

W
wusongqing 已提交
274 275
**Example**

W
wusongqing 已提交
276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319
```js
import notification from '@ohos.notification';
import particleAbility from '@ohos.ability.particleAbility';
import wantAgent from '@ohos.wantAgent';

let wantAgentInfo = {
    wants: [
        {
            bundleName: "com.example.myapplication",
            abilityName: "com.example.myapplication.MainAbility"
        }
    ],
    operationType: wantAgent.OperationType.START_ABILITY,
    requestCode: 0,
    wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESET_FLAG]
};

wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => {
    let basicContent = {
        title: "title",
        text: "text"
    };
    let notificationContent = {
        contentType: notification.ContentType.NOTIFICATION_CONTENT_TEXT,
        normal: basicContent
    };
    let request = {
        content: notificatonContent,
        wantAgent: wantAgentObj
    };
    let id = 1;
    particleAbility.startBackgroundRunning(id, request).then(() => {
        console.info("Operation succeeded");
    }).catch((err) => {
        console.error("Operation failed Cause: " + err);
    });
});

```

## particleAbility.cancelBackgroundRunning

cancelBackgroundRunning(callback: AsyncCallback&lt;void&gt;): void;

W
wusongqing 已提交
320
Requests 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).
W
wusongqing 已提交
321

W
wusongqing 已提交
322
**System capability**: SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask
W
wusongqing 已提交
323

W
wusongqing 已提交
324
 **Parameters**
W
wusongqing 已提交
325

W
wusongqing 已提交
326 327
  | Name| Type| Mandatory| Description|
  | -------- | -------- | -------- | -------- |
W
wusongqing 已提交
328 329 330
  | callback | AsyncCallback&lt;void&gt; | Yes| Callback used to return the result.|

 **Example**
W
wusongqing 已提交
331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350

```js
import particleAbility from '@ohos.ability.particleAbility';

function callback(err, data) {
    if (err) {
        console.error("Operation failed Cause: " + err);
    } else {
        console.info("Operation succeeded");
    }
}

particleAbility.cancelBackgroundRunning(callback);

```

## particleAbility.cancelBackgroundRunning

cancelBackgroundRunning(): Promise&lt;void&gt;;

W
wusongqing 已提交
351
Requests 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).
W
wusongqing 已提交
352

W
wusongqing 已提交
353
**System capability**: SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask
W
wusongqing 已提交
354

W
wusongqing 已提交
355
**Return value**
W
wusongqing 已提交
356

W
wusongqing 已提交
357
| Type          | Description                     |
W
wusongqing 已提交
358 359 360
| -------------- | ------------------------- |
| Promise\<void> | Promise used to return the result.|

W
wusongqing 已提交
361 362
 **Example**

W
wusongqing 已提交
363 364 365 366 367 368 369 370 371 372
```js
import particleAbility from '@ohos.ability.particleAbility';

particleAbility.cancelBackgroundRunning().then(() => {
    console.info("Operation succeeded");
}).catch((err) => {
    console.error("Operation failed Cause: " + err);
});

```
W
wusongqing 已提交
373 374 375 376 377 378 379 380 381 382 383 384 385 386


## particleAbility.connectAbility

connectAbility(request: Want, options:ConnectOptions): number

Connects this ability to a specific Service ability. This API uses a callback to return the result.

**System capability**: SystemCapability.Ability.AbilityRuntime.FAModel

**Parameters**

| Name   | Type          | Mandatory| Description                        |
| ------- | -------------- | ---- | ---------------------------- |
W
wusongqing 已提交
387
| request | [Want](js-apis-featureAbility.md#want)           | Yes  | Service ability to connect.|
W
wusongqing 已提交
388 389
| options | ConnectOptions | Yes  | Callback used to return the result.          |

W
wusongqing 已提交
390 391 392 393 394 395 396 397 398 399 400

ConnectOptions

**System capability**: SystemCapability.Ability.AbilityRuntime.Core

| Name          | Readable/Writable| Type      | Mandatory  | Description                       |
| ------------ | ---- | -------- | ---- | ------------------------- |
| onConnect    | Read only  | function | Yes   | Callback invoked when the connection is successful.              |
| onDisconnect | Read only  | function | Yes   | Callback invoked when the connection fails.              |
| onFailed     | Read only  | function | Yes   | Callback invoked when **connectAbility** fails to be called.|

W
wusongqing 已提交
401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434
**Example**

```js
        function onConnectCallback(element, remote){
            console.log('ConnectAbility onConnect remote is proxy:' + (remote instanceof rpc.RemoteProxy));
        }
        function onDisconnectCallback(element){
            console.log('ConnectAbility onDisconnect element.deviceId : ' + element.deviceId)
        }
        function onFailedCallback(code){
            console.log('particleAbilityTest ConnectAbility onFailed errCode : ' + code)
        }
        var connId = particleAbility.connectAbility(
            {
                bundleName: "com.ix.ServiceAbility",
                abilityName: "ServiceAbilityA",
            },
            {
                onConnect: onConnectCallback,
                onDisconnect: onDisconnectCallback,
                onFailed: onFailedCallback,
            },
        );

        particleAbility.disconnectAbility(connId).then((error,data)=>{
            console.log('particleAbilityTest result errCode : ' + error.code + " data: " + data);
        });
    

```


## particleAbility.disconnectAbility

W
wusongqing 已提交
435
disconnectAbility(connection: number, callback:AsyncCallback\<void>): void;
W
wusongqing 已提交
436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480

Disconnects this ability from the Service ability. This API uses a callback to return the result.

**System capability**: SystemCapability.Ability.AbilityRuntime.FAModel

**Parameters**

  | Name| Type| Mandatory| Description|
  | -------- | -------- | -------- | -------- |
  | callback | AsyncCallback&lt;void&gt; | Yes| Callback used to return the result.|

**Example**

```js
 function onConnectCallback(element, remote){
            console.log('ConnectAbility onConnect remote is proxy:' + (remote instanceof rpc.RemoteProxy));
        }
        function onDisconnectCallback(element){
            console.log('ConnectAbility onDisconnect element.deviceId : ' + element.deviceId)
        }
        function onFailedCallback(code){
            console.log('particleAbilityTest ConnectAbility onFailed errCode : ' + code)
        }
        var connId = particleAbility.connectAbility(
            {
                bundleName: "com.ix.ServiceAbility",
                abilityName: "ServiceAbilityA",
            },
            {
                onConnect: onConnectCallback,
                onDisconnect: onDisconnectCallback,
                onFailed: onFailedCallback,
            },
        );
        var result = particleAbility.disconnectAbility(connId,
            (error,data) => {
                console.log('particleAbilityTest DisConnectJsSameBundleName result errCode : ' + error.code + " data: " + data)
            },
        );

```


## particleAbility.disconnectAbility

W
wusongqing 已提交
481
disconnectAbility(connection: number): Promise\<void>;
W
wusongqing 已提交
482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526

Disconnects this ability from the Service ability. This API uses a promise to return the result.

**System capability**: SystemCapability.Ability.AbilityRuntime.FAModel

**Return value**

| Type          | Description                     |
| -------------- | ------------------------- |
| Promise\<void> | Promise used to return the result.|

**Example**

```js
function onConnectCallback(element, remote){
            console.log('ConnectAbility onConnect remote is proxy:' + (remote instanceof rpc.RemoteProxy));
        }
        function onDisconnectCallback(element){
            console.log('ConnectAbility onDisconnect element.deviceId : ' + element.deviceId)
        }
        function onFailedCallback(code){
            console.log('particleAbilityTest ConnectAbility onFailed errCode : ' + code)
        }
        var connId = particleAbility.connectAbility(
            {
                bundleName: "com.ix.ServiceAbility",
                abilityName: "ServiceAbilityA",
            },
            {
                onConnect: onConnectCallback,
                onDisconnect: onDisconnectCallback,
                onFailed: onFailedCallback,
            },
        );

        particleAbility.disconnectAbility(connId).then((error,data)=>{
            console.log('particleAbilityTest result errCode : ' + error.code + " data: " + data);
        });

```

## ErrorCode

Enumerates error codes.

W
wusongqing 已提交
527 528
**System capability**: SystemCapability.Ability.AbilityRuntime.FAModel

W
wusongqing 已提交
529 530
| Name                         | Value  | Description                                                        |
| ----------------------------- | ---- | ------------------------------------------------------------ |
W
wusongqing 已提交
531
| INVALID_PARAMETER         | -1    | Invalid parameter.|