From 1135af6110ba99319d5067d6c006912dfaa49b92 Mon Sep 17 00:00:00 2001 From: wusongqing Date: Tue, 21 Jun 2022 17:43:27 +0800 Subject: [PATCH] updated docs against 4159 Signed-off-by: wusongqing --- .../ability/fa-serviceability.md | 53 ++++++++++--------- 1 file changed, 29 insertions(+), 24 deletions(-) diff --git a/en/application-dev/ability/fa-serviceability.md b/en/application-dev/ability/fa-serviceability.md index 131d8ec6e0..b00796a80d 100644 --- a/en/application-dev/ability/fa-serviceability.md +++ b/en/application-dev/ability/fa-serviceability.md @@ -8,8 +8,8 @@ A Service ability is used to run tasks in the background, such as playing music **Table 1** Service ability lifecycle callbacks |API|Description| |:------|:------| -|onStart|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. The **Want** object passed to this callback must be null.| -|onCommand|Called every time a Service ability is created on a client. You can calculate calling statistics and perform initialization operations in this callback.| +|onStart|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.| +|onCommand|Called every time a Service ability is created on a client. You can collect calling statistics and perform initialization operations in this callback.| |onConnect|Called when another ability is connected to the Service ability.| |onDisconnect|Called when another ability is disconnected from the Service ability.| |onStop|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.| @@ -18,9 +18,7 @@ A Service ability is used to run tasks in the background, such as playing music ### Creating a Service Ability -1. Create a child class of the **Ability** class and override the following Service ability-related lifecycle callbacks to implement your own logic for processing requests to interact with your Service ability: - - The following code snippet shows how to create a Service ability: +1. Create a child class of the **Ability** class and override the following Service ability-related lifecycle callbacks to implement your own logic for processing interaction requests: ```javascript export default { @@ -32,6 +30,7 @@ A Service ability is used to run tasks in the background, such as playing music }, onConnect(want) { console.log('ServiceAbility OnConnect'); + return null; }, onDisconnect(want) { console.log('ServiceAbility OnDisConnect'); @@ -41,7 +40,7 @@ A Service ability is used to run tasks in the background, such as playing music }, } ``` - + 2. Register a Service ability. You must declare your Service ability in the **config.json** file by setting its **type** attribute to **service**. @@ -65,7 +64,7 @@ A Service ability is used to run tasks in the background, such as playing music -### Starting a Service ability +### Starting a Service Ability The **Ability** class provides the **startAbility()** API for you to start another Service ability by passing a **Want** object. @@ -78,12 +77,12 @@ The following code snippet shows how to start a Service ability running on the l ```javascript import featureAbility from '@ohos.ability.featureAbility'; -let promise = await featureAbility.startAbility( +let promise = featureAbility.startAbility( { want: { - bundleName: "com.jstest.serviceability", - abilityName: "com.jstest.serviceability.MainAbility", + bundleName: "com.jstest.service", + abilityName: "com.jstest.service.ServiceAbility", }, } ); @@ -95,9 +94,9 @@ After the preceding code is executed, the **startAbility()** API is called to st -### Stopping a Service ability +### Stopping a 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. You can call **terminateSelf()** on a Service ability to stop it. +Once created, the Service ability keeps running in the background. The system does not stop or destroy it unless memory resources must be reclaimed. You can call **terminateSelf()** on a Service ability to stop it. @@ -110,6 +109,8 @@ When calling **connectAbility()**, you should pass a **Want** object containing The following code snippet shows how to implement the callbacks: ```javascript +import prompt from '@system.prompt' + let mRemote; function onConnectCallback(element, remote){ console.log('onConnectLocalService onConnectDone element: ' + element); @@ -154,8 +155,8 @@ The following code snippet shows how to connect to a local Service ability: import featureAbility from '@ohos.ability.featureAbility'; let connId = featureAbility.connectAbility( { - bundleName: "com.jstest.serviceability", - abilityName: "com.jstest.serviceability.MainAbility", + bundleName: "com.jstest.service", + abilityName: "com.jstest.service.ServiceAbility", }, { onConnect: onConnectCallback, @@ -165,7 +166,7 @@ let connId = featureAbility.connectAbility( ); ``` -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 the **IRemoteObject** interface. You can inherit **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 a default implementation of the **IRemoteObject** interface. You can extend **rpc.RemoteObject** to implement your own class of **IRemoteObject**. The following code snippet shows how the Service ability instance returns itself to the calling ability: @@ -213,16 +214,20 @@ export default { } ``` -### Connecting to a Remote Service Ability (Applying only to System Applications) ->Note: The **getTrustedDeviceListSync** API of the **DeviceManager** class is open only to system applications. Therefore, remote Service ability startup applies only to system applications. +### Connecting to a Remote Service Ability (Applying only to System Applications) +>NOTE +> +>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 on another device or to a Service ability in another application on another device, you must first implement the **IAbilityConnection** interface for the connection. A Service ability allows other abilities on another device to connect to it through **connectAbility()**. +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: ```ts +import prompt from '@system.prompt' + let mRemote; function onConnectCallback(element, remote){ console.log('onConnectRemoteService onConnectDone element: ' + element); @@ -264,7 +269,10 @@ The **Want** of the target Service ability must contain the remote **deviceId**, ```ts import deviceManager from '@ohos.distributedHardware.deviceManager'; + +// For details about the implementation of dmClass, see the implementation in Distributed Demo in Samples. let dmClass; + function getRemoteDeviceId() { if (typeof dmClass === 'object' && dmClass != null) { let list = dmClass.getTrustedDeviceListSync(); @@ -327,15 +335,12 @@ async function RequestPermission() { let context = featureAbility.getContext(); context.requestPermissionsFromUser(requestPermissions, 1, (data)=>{ console.info("data:" + JSON.stringify(data)); - console.info("data requestCode:" + data.requestCode); - console.info("data permissions:" + data.permissions); - console.info("data authResults:" + data.authResults); }); console.info('RequestPermission end'); } ``` -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 the **IRemoteObject** interface. You can inherit **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 a default implementation of the **IRemoteObject** interface. You can extend **rpc.RemoteObject** to implement your own class of **IRemoteObject**. The following code snippet shows how the Service ability instance returns itself to the calling ability: @@ -398,5 +403,5 @@ export default { ## Samples The following samples are provided to help you better understand how to develop a Service ability: -- [`ServiceAbility`: Service Ability Creation and Use (eTS) (API8)](https://gitee.com/openharmony/app_samples/tree/master/ability/ServiceAbility) -- [`DMS`: Distributed Demo (eTS) (API7)](https://gitee.com/openharmony/app_samples/tree/master/ability/DMS) +- [`ServiceAbility`: Service Ability Creation and Use (eTS, API version 8)](https://gitee.com/openharmony/app_samples/tree/master/ability/ServiceAbility) +- [`DMS`: Distributed Demo (eTS, API version 8)](https://gitee.com/openharmony/app_samples/tree/master/ability/DMS) -- GitLab