A Service ability is used to run tasks in the background, such as playing music or downloading files. It does not provide a UI for user interaction. Service abilities can be started by other applications or abilities and can remain running in the background even after the user switches to another application.
A Service ability is used to run tasks in the background, such as playing music or downloading files. It does not provide a UI for user interaction. Service abilities can be started by other applications or abilities and can keep running in the background even after the user switches to another application.
## Available APIs
## Lifecycle APIs
**Table 1** Service ability lifecycle APIs
**Table 1** Service ability lifecycle APIs
|API|Description|
|API|Description|
|:------|:------|
|:------|:------|
|onStart?(): void|Called to initialize a Service ability being created. This callback is invoked only once in the entire lifecycle of a Service ability. The **Want** object passed to this callback must be null.|
|onStart?(): void|Called to initialize a Service ability when the Service ability is being created. This callback is invoked only once in the entire lifecycle of a Service ability.|
|onCommand?(want: Want, startId: number): void|Called every time a Service ability is created on a client. You can collect calling statistics and perform initialization operations in this callback.|
|onCommand?(want: Want, startId: number): void|Called every time a Service ability is created on the client. You can collect calling statistics and perform initialization operations in this callback.|
|onConnect?(want: Want): rpc.RemoteObject|Called when another ability is connected to the Service ability.|
|onConnect?(want: Want): rpc.RemoteObject|Called when another ability is connected to the Service ability.|
|onDisconnect?(want: Want): void|Called when another ability is disconnected from the Service ability.|
|onDisconnect?(want: Want): void|Called when another ability is disconnected from the Service ability.|
|onStop?(): void|Called when the Service ability is being destroyed. You should override this callback for your Service ability to clear its resources, such as threads and registered listeners.|
|onStop?(): void|Called when the Service ability is being destroyed. You should override this callback for your Service ability to clear its resources, such as threads and registered listeners.|
The differences between **onCommand()** and **onConnect()** are as follows:
- The **onCommand()** callback is triggered each time the client starts the Service ability by calling **startAbility** or **startAbilityForResult**.
- The **onConnect()** callback is triggered each time the client establishes a new connection with the Service ability by calling **connectAbility**.
## How to Develop
## How to Develop
### Creating and Registering a Service Ability
### Creating and Registering a Service Ability
1. Override the Service ability-related lifecycle callbacks to implement your own logic for processing interaction requests.
1. Override the Service ability-related lifecycle callbacks to implement your own logic for processing interaction requests.
```javascript
```ts
exportdefault{
exportdefault{
onStart(){
onStart(){
console.log('ServiceAbility onStart');
console.log('ServiceAbility onStart');
...
@@ -30,14 +34,15 @@ A Service ability is used to run tasks in the background, such as playing music
...
@@ -30,14 +34,15 @@ A Service ability is used to run tasks in the background, such as playing music
},
},
onConnect(want){
onConnect(want){
console.log('ServiceAbility OnConnect');
console.log('ServiceAbility OnConnect');
returnnewFirstServiceAbilityStub('test');
// Below lists the implementation of ServiceAbilityStub.
returnnewServiceAbilityStub('test');
},
},
onDisconnect(want){
onDisconnect(want){
console.log('ServiceAbility OnDisConnect');
console.log('ServiceAbility OnDisConnect');
},
},
onStop(){
onStop(){
console.log('ServiceAbility onStop');
console.log('ServiceAbility onStop');
},
}
}
}
```
```
...
@@ -45,7 +50,7 @@ A Service ability is used to run tasks in the background, such as playing music
...
@@ -45,7 +50,7 @@ A Service ability is used to run tasks in the background, such as playing music
Declare the Service ability in the **config.json** file by setting its **type** attribute to **service**.
Declare the Service ability in the **config.json** file by setting its **type** attribute to **service**.
```javascript
```json
{
{
"module":{
"module":{
"abilities":[
"abilities":[
...
@@ -68,245 +73,219 @@ A Service ability is used to run tasks in the background, such as playing music
...
@@ -68,245 +73,219 @@ A Service ability is used to run tasks in the background, such as playing music
The **Ability** class provides the **startAbility()** API for you to start another Service ability by passing a **Want** object.
The **Ability** class provides the **startAbility()** API for you to start another Service ability by passing a **Want** object.
To set information about the target Service ability, you can first construct a **Want** object with the **bundleName** and **abilityName** parameters specified. The meanings of the parameters are as follows:
To set information about the target Service ability, you can first construct a **Want** object with the **bundleName** and **abilityName** parameters specified.
-**bundleName**indicates the name of the bundle to which the target ability belongs.
-**bundleName**specifies the bundle name of the target application.
-**abilityName**indicates the target ability name.
-**abilityName**specifies the target ability name.
The following code snippet shows how to start a Service ability running on the local device:
The following code snippet shows how to start a Service ability running on the local device:
After the preceding code is executed, the **startAbility()** API is called to start the Service ability.
In the preceding code, the **startAbility()** API is used to start the Service ability.
- If the Service ability is not running, the system calls **onStart()** to initialize the Service ability, and then calls **onCommand()** on the Service ability.
- If the Service ability is not running, the system initializes the Service ability, and calls **onStart()** and **onCommand()** on the Service ability in sequence.
- If the Service ability is running, the system directly calls **onCommand()** on the Service ability.
- If the Service ability is running, the system directly calls **onCommand()** on the Service ability.
The following code snippet shows how to start a Service ability running on the remote device. For details about **getRemoteDeviceId()**, see [Connecting to a Remote Service Ability](#connecting-to-a-remote-service-ability).
The following code snippet shows how to start a Service ability running on the remote device. For details, see [Connecting to a Remote Service Ability](#connecting-to-a-remote-service-ability).
Once created, the Service ability keeps running in the background. The system does not stop or destroy it unless memory resources must be reclaimed.
In normal cases, a Service ability can be stopped by itself or by the system.
- The Service ability can call **particleAbility.terminateSelf()** to stop itself.
- If the application process where the Service ability is located exits, the Service ability is reclaimed along with the process.
- If the Service ability is only accessed through **connectAbility()** (the **onCommand()** callback has never been triggered), the system stops the Service ability when the last connection to the Service ability is disconnected.
### Connecting to a Local Service Ability
### Connecting to a Local Service Ability
If you need to connect a Service ability to a Page ability or to a Service ability in another application, you must first implement the **IAbilityConnection** API for the connection. A Service ability allows other abilities to connect to it through **connectAbility()**.
If a Service ability wants to interact with a Page ability or a Service ability in another application, you must first create a connection. A Service ability allows other abilities to connect to it through **connectAbility()**.
You can use either of the following methods to connect to a Service ability:
You can use either of the following methods to connect to a Service ability:
1. Using the IDL to automatically generate code
1. Using the IDL to automatically generate code
Use OpenHarmony Interface Definition Language (IDL) to automatically generate the corresponding client, server, and **IRemoteObject** code. For details, see “Development Using TS" in [OpenHarmony IDL Specifications and User Guide](../IDL/idl-guidelines.md).
Use OpenHarmony Interface Definition Language (IDL) to automatically generate the corresponding client, server, and **IRemoteObject** code. For details, see [Development Using TS](../IDL/idl-guidelines.md#development-using-ts).
2. Writing code in the corresponding file
2. Writing code in the corresponding file
When calling **connectAbility()**, you should pass a **Want** object containing information about the target Service ability and an **IAbilityConnection** object to the API. **IAbilityConnection** provides the following callbacks that you should implement: **onConnect()**, **onDisconnect()**, and **onFailed()**. The **onConnect()** callback is invoked when a Service ability is connected, **onDisconnect()** is invoked when a Service ability is unexpectedly disconnected, and **onFailed()** is invoked when a connection to a Service ability fails.
When using **connectAbility()**, pass the **Want** and **ConnectOptions** objects of the target Service ability, where **ConnectOptions** encapsulates the following three callbacks that need to be implemented.
- **onConnect()**: callback used for processing when the Service ability is connected.
- **onDisconnect()**: callback used for processing when the Service ability is disconnected.
- **onFailed()**: callback used for processing when the connection to the Service ability fails.
The following code snippet shows how to implement the callbacks:
The following code snippet shows how to implement the callbacks:
```javascript
```ts
import prompt from '@system.prompt'
import prompt from '@system.prompt'
var option = {
var option = {
onConnect: function onConnectCallback(element, proxy) {
onConnect: function onConnectCallback(element, proxy) {
The following code snippet shows how to connect to a local Service ability:
The following code snippet shows how to connect to a local Service ability:
```javascript
```ts
import featureAbility from '@ohos.ability.featureAbility';
import featureAbility from '@ohos.ability.featureAbility'
let connId = featureAbility.connectAbility(
{
let want = {
bundleName: "com.jstest.service",
bundleName: "com.jstest.service",
abilityName: "com.jstest.service.ServiceAbility",
abilityName: "com.jstest.service.ServiceAbility"
},
};
{
let connectId = featureAbility.connectAbility(want, option);
onConnect: onConnectCallback,
onDisconnect: onDisconnectCallback,
onFailed: onFailedCallback,
},
);
```
```
When a Service ability is connected, the **onConnect()** callback is invoked and returns an **IRemoteObject** defining the proxy used for communicating with the Service ability. OpenHarmony provides a default implementation of **IRemoteObject**. You can extend **rpc.RemoteObject** to implement your own class of **IRemoteObject**.
When a Service ability is connected, the **onConnect()** callback is invoked and returns an **IRemoteObject** defining the proxy used for communicating with the Service ability. OpenHarmony provides the default implementation of **IRemoteObject**. You can inherit **rpc.RemoteObject** to create a custom implementation class for interaction with the Service ability. For details, see the [RPC API Reference](..\reference\apis\js-apis-rpc.md).
The following code snippet shows how the Service ability instance returns itself to the calling ability:
The following code snippet shows how the Service ability returns itself to the calling ability:
```javascript
```ts
import rpc from "@ohos.rpc";
import rpc from "@ohos.rpc"
class FirstServiceAbilityStub extends rpc.RemoteObject {
class ServiceAbilityStub extends rpc.RemoteObject {
constructor(des: any) {
constructor(des: any) {
if (typeof des === 'string') {
if (typeof des === 'string') {
super(des)
super(des);
} else {
} else {
return
console.log("Error, the input param is not string");
>This feature applies only to system applications, since the **getTrustedDeviceListSync** API of the **DeviceManager** class is open only to system applications.
If you need to connect a Service ability to a Page ability or another Service ability on a remote device, you must first implement the **IAbilityConnection** interface for the connection. A Service ability allows abilities on another device to connect to it through **connectAbility()**.
When calling **connectAbility()**, you should pass a **Want** object containing information about the target Service ability and an **IAbilityConnection** object to the API. **IAbilityConnection** provides the following callbacks that you should implement: **onConnect()**, **onDisconnect()**, and **onFailed()**. The **onConnect()** callback is invoked when a Service ability is connected, **onDisconnect()** is invoked when a Service ability is unexpectedly disconnected, and **onFailed()** is invoked when a connection to a Service ability fails.
The following code snippet shows how to implement the callbacks:
return new ServiceAbilityStub('ServiceAbilityRemoteObject');
message:"Connect local service onFailed"
},
})
onDisconnect(want) {
console.log('ServiceAbility OnDisConnect');
},
onStop() {
console.log('ServiceAbility onStop');
}
}
}
}
```
```
The **Want** of the target Service ability must contain the remote **deviceId**, which can be obtained from **DeviceManager**. The sample code is as follows:
### Connecting to a Remote Service Ability
```ts
This feature applies only to system applications. The method of creating a **ConnectOptions** object for connecting to a remote Service ability is similar to that for connecting to a local Service ability. The differences are as follows:
- The application must apply for the data synchronization permission from the user.
-**Want** of the target Service ability must contain the remote device ID.
// For details about the implementation of dmClass, see the implementation in Distributed Demo in Samples.
> **NOTE**
letdmClass;
>
> The **getTrustedDeviceList** API of **DeviceManager** is open only to system applications. Currently, only system applications can connect to a remote Service ability.
>
> For details about the API definition, see [Device Management](..\reference\apis\js-apis-device-manager.md).
functiongetRemoteDeviceId(){
The data synchronization permission is required in the cross-device scenario. Configure the permission in the **config.json** file.
console.log("MainAbility onButtonClick getRemoteDeviceId err: dmClass is null");
}
}
}
}
```
```
The following code snippet shows how to connect to a remote Service ability:
The **DISTRIBUTED_DATASYNC** permission is user granted. Therefore, your application, when being started, must display a dialog box to request the permission. The sample code is as follows:
@@ -337,64 +315,19 @@ async function RequestPermission() {
...
@@ -337,64 +315,19 @@ async function RequestPermission() {
}
}
```
```
When a Service ability is connected, the **onConnect()** callback is invoked and returns an **IRemoteObject** defining the proxy used for communicating with the Service ability. OpenHarmony provides a default implementation of **IRemoteObject**. You can extend **rpc.RemoteObject** to implement your own class of **IRemoteObject**.
To obtain the device ID, import the **@ohos.distributedHardware.deviceManager** module, which provides **getTrustedDeviceList** to obtain the remote device ID. For details about how to use the API, see [Device Management](..\reference\apis\js-apis-device-manager.md).
The following code snippet shows how the Service ability instance returns itself to the calling ability:
To connect to a remote Service ability, you only need to define **deviceId** in **Want**. The sample code is as follows:
The other implementations are the same as those for the connection to a local Service ability. For details, see the sample code provided under [Connecting to a Local Service Ability](#connecting-to-a-local-service-ability).
