From e54251962b5380ef7d11f3a26cee9dd7d4523159 Mon Sep 17 00:00:00 2001
From: zmx <1029211721@qq.com>
Date: Tue, 28 Dec 2021 15:38:03 +0800
Subject: [PATCH] add connectRemoteAbility material
Signed-off-by: zmx <1029211721@qq.com>
Change-Id: Ic9a0907e7f9196f6529189e93f2691ac98a8c90a
Signed-off-by: zmx <1029211721@qq.com>
---
.../ability/service-ability.md | 89 ++++++++++++++++++-
.../reference/apis/js-apis-featureAbility.md | 9 ++
2 files changed, 94 insertions(+), 4 deletions(-)
diff --git a/zh-cn/application-dev/ability/service-ability.md b/zh-cn/application-dev/ability/service-ability.md
index 908875bb42..c07488af97 100644
--- a/zh-cn/application-dev/ability/service-ability.md
+++ b/zh-cn/application-dev/ability/service-ability.md
@@ -104,13 +104,13 @@ var promise = await featureAbility.startAbility(
-## 连接Service
+## 连接本地Service
如果Service需要与Page Ability或其他应用的Service Ability进行交互，则须创建用于连接的Connection。Service支持其他Ability通过connectAbility()方法与其进行连接。
在使用connectAbility()处理回调时，需要传入目标Service的Want与IAbilityConnection的实例。IAbilityConnection提供了以下方法供开发者实现：onConnect()是用来处理连接Service成功的回调，onDisconnect()是用来处理Service异常死亡的回调，onFailed()是用来处理连接Service失败的回调。
-创建连接Service回调实例的代码示例如下：
+创建连接本地Service回调实例的代码示例如下：
```javascript
var mRemote;
@@ -128,7 +128,7 @@ function onFailedCallback(code){
}
```
-连接Service的代码示例如下：
+连接本地Service的代码示例如下：
```javascript
import featureAbility from '@ohos.ability.featureability';
@@ -158,7 +158,7 @@ export default {
class MyStub extends rpc.RemoteObject{
constructor(des) {
if (typeof des === 'string') {
- super(des, des.length);
+ super(des);
}
return null;
}
@@ -183,3 +183,84 @@ export default {
}
```
+## 连接远程Service
+
+如果Service需要与Page Ability或其他应用的Service Ability进行跨设备交互，则须创建用于连接的Connection。Service支持其他Ability通过connectAbility()方法与其进行跨设备连接。
+
+在使用connectAbility()处理回调时，需要传入目标Service的Want与IAbilityConnection的实例。IAbilityConnection提供了以下方法供开发者实现：onConnect()是用来处理连接Service成功的回调，onDisconnect()是用来处理Service异常死亡的回调，onFailed()是用来处理连接Service失败的回调。
+
+创建连接远程Service回调实例的代码示例如下：
+
+```javascript
+var mRemote;
+function onConnectCallback(element, remote){
+ console.log('ConnectRemoteAbility onConnect Callback')
+ mRemote = remote;
+}
+
+function onDisconnectCallback(element){
+ console.log('ConnectRemoteAbility onDisconnect Callback')
+}
+
+function onFailedCallback(code){
+ console.log('ConnectRemoteAbility onFailed Callback')
+}
+```
+
+目标Service的Want需要包含远程deviceId，该远程deviceId可通过deviceManager获取。
+
+连接远程Service的代码示例如下：
+
+```javascript
+import featureAbility from '@ohos.ability.featureability';
+var connId = featureAbility.connectAbility(
+ {
+ deviceId: deviceId,
+ bundleName: "com.jstest.serviceability",
+ abilityName: "com.jstest.serviceability.MainAbility",
+ },
+ {
+ onConnect: onConnectCallback,
+ onDisconnect: onDisconnectCallback,
+ onFailed: onFailedCallback,
+ },
+);
+```
+
+同时，Service侧也需要在onConnect()时返回IRemoteObject，从而定义与Service进行通信的接口。onConnect()需要返回一个IRemoteObject对象，OpenHarmony提供了IRemoteObject的默认实现，用户可以通过继承rpc.RemoteObject来创建自定义的实现类。
+
+Service侧把自身的实例返回给调用侧的代码示例如下：
+
+```javascript
+import rpc from "@ohos.rpc";
+
+var mMyStub;
+export default {
+ onStart(want) {
+ class MyStub extends rpc.RemoteObject{
+ constructor(des) {
+ if (typeof des === 'string') {
+ super(des);
+ }
+ return null;
+ }
+ onRemoteRequest(code, message, reply, option) {
+ }
+ }
+ mMyStub = new MyStub("ServiceAbility-test");
+ },
+ onCommand(want, restart, startId) {
+ console.log('SerivceAbility onCommand');
+ },
+ onConnect(want) {
+ console.log('SerivceAbility OnConnect');
+ return mMyStub;
+ },
+ onDisconnect() {
+ console.log('SerivceAbility OnDisConnect');
+ },
+ onStop() {
+ console.log('SerivceAbility onStop');
+ },
+}
+```
\ No newline at end of file
diff --git a/zh-cn/application-dev/reference/apis/js-apis-featureAbility.md b/zh-cn/application-dev/reference/apis/js-apis-featureAbility.md
index 5938d6095e..b6bd8e8254 100644
--- a/zh-cn/application-dev/reference/apis/js-apis-featureAbility.md
+++ b/zh-cn/application-dev/reference/apis/js-apis-featureAbility.md
@@ -774,6 +774,14 @@ featureAbility.terminateSelf().then((void) => { console.info("=============
| request | 只读 | Want | 是 | 表示被连接的ServiceAbility |
| options | 只读 | ConnectOptions | 是 | 被指定的回调方法 |
+* Want参数描述
+
+| 名称 | 读写属性 | 类型 | 必填 | 描述 |
+| ------------ | -------- | -------- | ---- | ---------------------------------- |
+| deviceId | 只读 | string | 否 | 表示被连接的ServiceAbility的设备id，缺省表示连接本地的ServiceAbility |
+| bundleName | 只读 | string | 是 | 表示被连接的ServiceAbility的包名 |
+| abilityName | 只读 | string | 是 | 表示被连接的ServiceAbility的类名 |
+
- ConnectOptions类型说明
| 名称 | 读写属性 | 类型 | 必填 | 描述 |
@@ -804,6 +812,7 @@ function onFailedCallback(code){
}
var connId = featureAbility.connectAbility(
{
+ deviceId: deviceId,
bundleName: "com.ix.ServiceAbility",
abilityName: "ServiceAbilityA",
},
--
GitLab