!92 【轻量级 PR】：update ipc readme

Merge pull request !92 from liangshenglin1/N/A

README_zh.md

@@ -13,7 +13,7 @@
 
 ## 简介<a name="section11660541593"></a>
 
-IPC（Inter-Process Communication）与RPC（Remote Procedure Call）机制用于实现跨进程通信，不同的是前者使用Binder驱动，用于设备内的跨进程通信，而后者使用软总线驱动，用于跨设备跨进程通信。IPC和RPC通常采用客户端-服务器（Client-Server）模型，服务请求方（Client）可获取提供服务提供方（Server）的代理 （Proxy），并通过此代理读写数据来实现进程间的数据通信。通常，Server会先注册系统能力（System Ability）到系统能力管理者（System Ability Manager，缩写SAMgr）中，SAMgr负责管理这些SA并向Client提供相关的接口。Client要和某个具体的SA通信，必须先从SAMgr中获取该SA的代理，然后使用代理和SA通信。下文使用Proxy表示服务请求方，Stub表示服务提供方。
+IPC（Inter-Process Communication）与RPC（Remote Procedure Call）机制用于实现跨进程通信，不同的是前者使用Binder驱动，用于设备内的跨进程通信，而后者使用软总线驱动，用于跨设备跨进程通信。IPC和RPC通常采用客户端-服务器（Client-Server）模型，服务请求方（Client）可获取提供服务提供方（Server）的代理 （Proxy），并通过此代理读写数据来实现进程间的数据通信。通常，系统能力（System Ability）Server侧会先注册到系统能力管理者（System Ability Manager，缩写SAMgr）中，SAMgr负责管理这些SA并向Client提供相关的接口。Client要和某个具体的SA通信，必须先从SAMgr中获取该SA的代理，然后使用代理和SA通信。三方应用可以使用FA提供的接口绑定服务提供方的Ability，获取代理，进行通信。下文使用Proxy表示服务请求方，Stub表示服务提供方。
 
 ## 系统架构<a name="section1950291414611"></a>
 
@@ -39,12 +39,18 @@ IPC（Inter-Process Communication）与RPC（Remote Procedure Call）机制用
 
 ## 约束<a name="section119744591305"></a>
 
-目前暂不支持的场景：
-
-跨设备RPC调用
+1. 单个设备上跨进程通信时，传输的数据量最大约为1MB，过大的数据量请使用匿名共享内存。
+2. 不支持把跨设备的Proxy对象传递回该Proxy对象所指向的Stub对象所在的设备。
 
 ## 编译构建<a name="section137768191623"></a>
 
+**JS侧依赖**
+
+```
+import rpc from "@ohos.rpc"
+import featureAbility from "@ohos.ability.featureAbility"
+```
+
 **Native侧编译依赖**
 
 sdk依赖：
@@ -65,7 +71,17 @@ deps = [
 
 ## 说明<a name="section1312121216216"></a>
 
-Native侧和Java侧实现跨进程通信的步骤基本相同。
+**JS侧实现跨进程通信基本步骤：**
+
+1. 获取代理
+
+   使用ohos.ability.featureAbility提供的connectAbility方法绑定Ability，在参数里指定要绑定的Ability所在应用的包名、组件名，如果是跨设备的情况，还需要指定所在设备的ID。用户需要在服务端的onConnect方法里返回一个继承自ohos.rpc.RemoteObject的对象，此对象会在onRemoteRequest方法里接收到请求。
+
+2. 发送请求
+
+   客户端在connectAbility参数指定的回调函数接收到代理对象后，使用ohos.rpc模块提供的方法完成RPC通信，其中MessageParcel提供了读写各种类型数据的方法，IRemoteObject提供了发送请求的方法，RemoteObject提供了处理请求的方法onRemoteRequest，用户需要重写。
+
+**Native侧实现跨进程通信的基本步骤：**
 
 1. 定义接口类
 
@@ -73,24 +89,39 @@ Native侧和Java侧实现跨进程通信的步骤基本相同。
 
 2. 实现服务提供端\(Stub\)
 
-    Stub继承IRemoteStub\(Native\)或者RemoteObject\(Java\)，除了接口类中未实现方法外，还需要实现AsObject方法及OnRemoteRequest方法。
+   Stub继承IRemoteStub\(Native\)，除了接口类中未实现方法外，还需要实现AsObject方法及OnRemoteRequest方法。
 
 3. 实现服务请求端\(Proxy\)
 
-    Proxy继承IRemoteProxy\(Native\)或者RemoteProxy\(Java\)，封装业务函数，调用SendRequest将请求发送到Stub。
+   Proxy继承IRemoteProxy\(Native\)，封装业务函数，调用SendRequest将请求发送到Stub。
 
 4. 注册SA
 
    服务提供方所在进程启动后，申请SA的唯一标识，将Stub注册到SAMgr。
 
 5. 获取SA
+
 6. 通过SA的标识和设备标识，从SAMgr获取Proxy，通过Proxy实现与Stub的跨进程通信。
 
 ### 接口说明<a name="section1551164914237"></a>
 
-**表 1**  Native侧IPC接口
+**表 1**  JS侧IPC关键API
+
+| 模块                        | 方法                                                         | 功能说明                                    |
+| --------------------------- | ------------------------------------------------------------ | ------------------------------------------- |
+| ohos.ability.featureAbility | connectAbility(request: Want, options:ConnectOptions ): number | 绑定指定的Ability，在回调函数里接收代理对象 |
+| ohos.rpc.RemoteObject       | onRemoteRequest(code: number, data: MessageParcel, reply: MessageParcel, options: MessageOption): boolean | 服务端处理请求，返回结果                    |
+| ohos.rpc.IRemoteObject      | sendRequest(code: number, data: MessageParcel, reply: MessageParcel, options: MessageOption): Promise<SendRequestResult> | 发送请求，在期约里接收结果                  |
+| ohos.rpc.IRemoteObject      | sendRequest(code: number, data: MessageParcel, reply: MessageParcel, options: MessageOption, callback: AsyncCallback<SendRequestResult>): void | 发送请求，在回调函数里接收结果              |
+| ohos.rpc.MessageParcel      | writeRemoteObject(object: IRemoteObject): boolean            | 序列化IRemoteObject对象                     |
+| ohos.rpc.MessageParcel      | readRemoteObject(): IRemoteObject                            | 反序列化IRemoteObject对象                   |
+
+
+
+**表 2**  Native侧IPC接口
 
 <a name="table178849240013"></a>
+
 <table><thead align="left"><tr id="row6884924608"><th class="cellrowborder" valign="top" width="14.12141214121412%" id="mcps1.2.4.1.1"><p id="p98846241706"><a name="p98846241706"></a><a name="p98846241706"></a>类/接口</p>
 </th>
 <th class="cellrowborder" valign="top" width="52.54525452545254%" id="mcps1.2.4.1.2"><p id="p1488482414020"><a name="p1488482414020"></a><a name="p1488482414020"></a>方法</p>
@@ -124,36 +155,166 @@ Native侧和Java侧实现跨进程通信的步骤基本相同。
 
 ### 使用说明<a name="section129654513264"></a>
 
+**JS侧使用说明**
+
+1. 客户端构造变量want，指定要绑定的Ability所在应用的包名、组件名，如果是跨设备的场景，还需要目标设备ID。构造变量connect，指定绑定成功、绑定失败、断开连接时的回调函数。使用featureAbility提供的接口绑定Ability。
+
+   ```
+   import rpc from "@ohos.rpc"
+   import featureAbility from "@ohos.ability.featureAbility"
+   
+   let proxy = null
+   let connectId = null
+   
+   // 单个设备
+   let want = {
+       // 包名和组件名写实际的值
+       "bundleName": "ohos.rpc.test.server",
+       "abilityName": "ohos.rpc.test.server.ServiceAbility",
+   }
+   let connect = {
+       onConnect:function(elementName, remote) {
+           proxy = remote
+       },
+       onDisconnect:function(elementName) {
+       },
+       onFailed:function() {
+           proxy = null
+       }
+   }
+   connectId = featureAbility.connectAbility(want, connect)
+   
+   // 如果是跨设备绑定，可以使用deviceManager获取目标设备ID
+   import deviceManager from '@ohos.distributedHardware.deviceManager'
+   function deviceManagerCallback(deviceManager) {
+       let deviceList = deviceManager.getTrustedDeviceListSync()
+       let deviceId = deviceList[0].deviceId
+       let want = {
+           "bundleName": "ohos.rpc.test.server",
+           "abilityName": "ohos.rpc.test.service.ServiceAbility",
+           "deviceId": deviceId,
+           "flags": 256
+       }
+       connectId = featureAbility.connectAbility(want, connect)
+   }
+   // 第一个参数是本应用的包名，第二个参数是接收deviceManager的回调函数
+   deviceManager.createDeviceManager("ohos.rpc.test", deviceManagerCallback)
+   ```
+
+   
+
+2. 服务端被绑定的Ability在onConnect方法里返回继承自rpc.RemoteObject的对象，该对象需要实现onRemoteRequest方法，处理客户端的请求。
+
+   ```
+   import rpc from "@ohos.rpc"
+   onConnect(want) {
+       return new Stub("rpcTestAbility")
+   }
+   class Stub extends rpc.RemoteObject {
+       constructor(descriptor) {
+           super(descriptor)
+       }
+       onRemoteRequest(code, data, reply, option) {
+           // 根据code处理客户端的请求
+           return true
+       }
+   }
+   ```
+
+   
+
+3. 客户端在onConnect回调里接收到代理对象，调用sendRequest方法发起请求，在期约或者回调函数里接收结果。
+
+   ```
+   import rpc from "@ohos.rpc"
+   // 使用期约
+   let option = new rpc.MessageOption()
+   let data = rpc.MessageParcel.create()
+   let reply = rpc.MessageParcel.create()
+   // 往data里写入参数
+   proxy.sendRequest(1, data, reply, option)
+       .then(function(result) {
+           if (result.errCode != 0) {
+               console.error("send request failed, errCode: " + result.errCode)
+               return
+           }
+           // 从result.reply里读取结果
+       })
+       .catch(function(e) {
+           console.error("send request got exception: " + e)
+       }
+       .finally(() => {
+           data.reclaim()
+           reply.reclaim()
+       }
+   
+   // 使用回调函数
+   function sendRequestCallback(result) {
+       try {
+           if (result.errCode != 0) {
+               console.error("send request failed, errCode: " + result.errCode)
+               return
+           }
+           // 从result.reply里读取结果
+       } finally {
+           result.data.reclaim()
+           result.reply.reclaim()
+       }
+   }
+   let option = new rpc.MessageOption()
+   let data = rpc.MessageParcel.create()
+   let reply = rpc.MessageParcel.create()
+   // 往data里写入参数
+   proxy.sendRequest(1, data, reply, option, sendRequestCallback)
+   ```
+
+   
+
+4. IPC通信结束后，使用featureAbility的接口断开连接。
+
+   ```
+   import rpc from "@ohos.rpc"
+   import featureAbility from "@ohos.ability.featureAbility"
+   function disconnectCallback() {
+       console.info("disconnect ability done")
+   }
+   featureAbility.disconnectAbility(connectId, disconnectCallback)
+   ```
+
+   
+
 **Native侧使用说明**
 
-定义IPC接口ITestAbility
+1. 定义IPC接口ITestAbility
 
-IPC接口继承IPC基类接口IRemoteBroker，接口里定义描述符、业务函数和消息码，其中业务函数在Proxy端和Stub端都需要实现。
+   IPC接口继承IPC基类接口IRemoteBroker，接口里定义描述符、业务函数和消息码，其中业务函数在Proxy端和Stub端都需要实现。
 
-```
-class ITestAbility : public IRemoteBroker {
-public:
-// DECLARE_INTERFACE_DESCRIPTOR是必须的， 入参需使用std::u16string；
-DECLARE_INTERFACE_DESCRIPTOR(u"test.ITestAbility");
-int TRANS_ID_PING_ABILITY = 1; // 定义消息码
-virtual int TestPingAbility(const std::u16string &dummy) = 0; // 定义业务函数
-};
-```
+   ```
+   class ITestAbility : public IRemoteBroker {
+   public:
+   // DECLARE_INTERFACE_DESCRIPTOR是必须的， 入参需使用std::u16string；
+   DECLARE_INTERFACE_DESCRIPTOR(u"test.ITestAbility");
+   int TRANS_ID_PING_ABILITY = 1; // 定义消息码
+   virtual int TestPingAbility(const std::u16string &dummy) = 0; // 定义业务函数
+   };
+   ```
 
-定义和实现服务端TestAbilityStub
    
-该类是和IPC框架相关的实现，需要继承 IRemoteStub<ITestAbility\>。Stub端作为接收请求的一端，需重写OnRemoteRequest方法用于接收客户端调用。
 
-```
-class TestAbilityStub : public IRemoteStub<ITestAbility> {
-public:
+2. 定义和实现服务端TestAbilityStub
+
+   该类是和IPC框架相关的实现，需要继承 IRemoteStub<ITestAbility\>。Stub端作为接收请求的一端，需重写OnRemoteRequest方法用于接收客户端调用。
+
+   ```
+   class TestAbilityStub : public IRemoteStub<ITestAbility> {
+   public:
        virtual int OnRemoteRequest(uint32_t code, MessageParcel &data, MessageParcel &reply, MessageOption &option) override;
        int TestPingAbility(const std::u16string &dummy) override;
-};
+   };
     
-int TestServiceStub::OnRemoteRequest(uint32_t code,
+   int TestServiceStub::OnRemoteRequest(uint32_t code,
        MessageParcel &data, MessageParcel &reply, MessageOption &option)
-{
+   {
        switch (code) {
            case TRANS_ID_PING_ABILITY: {
                std::u16string dummy = data.ReadString16();
@@ -164,91 +325,103 @@ int TestServiceStub::OnRemoteRequest(uint32_t code,
            default:
                return IPCObjectStub::OnRemoteRequest(code, data, reply, option);
        }
-}
-```
+   }
+   ```
 
-定义服务端业务函数具体实现类TestAbility
    
-```
-class TestAbility : public TestAbilityStub {
-public:
+
+3. 定义服务端业务函数具体实现类TestAbility
+
+   ```
+   class TestAbility : public TestAbilityStub {
+   public:
        int TestPingAbility(const std::u16string &dummy);
-}
+   }
    
-int TestAbility::TestPingAbility(const std::u16string &dummy) {
+   int TestAbility::TestPingAbility(const std::u16string &dummy) {
        return 0;
-}
-```
+   }
+   ```
 
-定义和实现客户端TestAbilityProxy
    
-该类是Proxy端实现，继承IRemoteProxy<ITestAbility\>，调用SendRequest接口向Stub端发送请求，对外暴露服务端提供的能力。
 
-```
-class TestAbilityProxy : public IRemoteProxy<ITestAbility> {
-public:
+4. 定义和实现客户端TestAbilityProxy
+
+   该类是Proxy端实现，继承IRemoteProxy<ITestAbility\>，调用SendRequest接口向Stub端发送请求，对外暴露服务端提供的能力。
+
+   ```
+   class TestAbilityProxy : public IRemoteProxy<ITestAbility> {
+   public:
        explicit TestAbilityProxy(const sptr<IRemoteObject> &impl);
        int TestPingService(const std::u16string &dummy) override;
-private:
+   private:
        static inline BrokerDelegator<TestAbilityProxy> delegator_; // 方便使用iface_cast宏
-}
+   }
    
-TestAbilityProxy::TestAbilityProxy(const sptr<IRemoteObject> &impl)
+   TestAbilityProxy::TestAbilityProxy(const sptr<IRemoteObject> &impl)
        : IRemoteProxy<ITestAbility>(impl)
-{
-}
+   {
+   }
    
-int TestAbilityProxy::TestPingService(const std::u16string &dummy) {
+   int TestAbilityProxy::TestPingService(const std::u16string &dummy) {
        MessageOption option;
        MessageParcel dataParcel, replyParcel;
        dataParcel.WriteString16(dummy);
        int error = Remote()->SendRequest(TRANS_ID_PING_ABILITY, dataParcel, replyParcel, option);
        int result = (error == ERR_NONE) ? replyParcel.ReadInt32() : -1;
        return result;
-}
-```
+   }
+   ```
 
-同步调用与异步调用
    
-MessageOption作为发送接口（原型如下）的入参，可设定同步（TF\_SYNC）、异步（TF\_ASYNC）、接收FD（TF\_ACCEPT\_FDS），默认情况下设定为同步，其余可通过MessageOption构造方法或void SetFlags\(int flags\)设定。
 
-```
-int SendRequest(uint32_t code, MessageParcel &data,
+5. 同步调用与异步调用
+
+   essageOption作为发送接口（原型如下）的入参，可设定同步（TF\_SYNC）、异步（TF\_ASYNC）、接收FD（TF\_ACCEPT\_FDS），默认情况下设定为同步，其余可通过MessageOption构造方法或void SetFlags\(int flags\)设定。
+
+   ```
+   int SendRequest(uint32_t code, MessageParcel &data,
        MessageParcel &reply, MessageOption &option) override;
-MessageOption option = { MessageOption::TF_ASYNC };
-```
+   MessageOption option = { MessageOption::TF_ASYNC };
+   ```
 
-SA注册与启动
    
-SA需要将自己的TestAbilityStub实例通过AddSystemAbility接口注册到SystemAbilityManager，设备内与分布式的注册参数不同。
 
-```
-// 注册到本设备内
-auto samgr = SystemAbilityManagerClient::GetInstance().GetSystemAbilityManager();
-samgr->AddSystemAbility(said, new TestAbility());
-
-// 在组网场景下，会被同步到其他设备上
-auto samgr = SystemAbilityManagerClient::GetInstance().GetSystemAbilityManager();
-ISystemAbilityManager::SAExtraProp saExtra;
-saExtra.isDistributed = true; // 设置为分布式SA
-int result = samgr->AddSystemAbility(said, new TestAbility(), saExtra);
-```
+6. SA注册与启动
 
-SA获取与调用
+   SA需要将自己的TestAbilityStub实例通过AddSystemAbility接口注册到SystemAbilityManager，设备内与分布式的注册参数不同。
+
+   ```
+   // 注册到本设备内
+   auto samgr = SystemAbilityManagerClient::GetInstance().GetSystemAbilityManager();
+   samgr->AddSystemAbility(said, new TestAbility());
+   
+   // 在组网场景下，会被同步到其他设备上
+   auto samgr = SystemAbilityManagerClient::GetInstance().GetSystemAbilityManager();
+   ISystemAbilityManager::SAExtraProp saExtra;
+   saExtra.isDistributed = true; // 设置为分布式SA
+   int result = samgr->AddSystemAbility(said, new TestAbility(), saExtra);
+   ```
+
+   
+
+7. SA获取与调用
+
+   通过SystemAbilityManager的GetSystemAbility方法可获取到对应SA的代理IRemoteObject，然后构造TestAbilityProxy即可。
+
+   ```
+   // 获取本设备内注册的SA的proxy
+   sptr<ISystemAbilityManager> samgr = SystemAbilityManagerClient::GetInstance().GetSystemAbilityManager();
+   sptr<IRemoteObject> remoteObject = samgr->GetSystemAbility(said);
+   sptr<ITestAbility> testAbility = iface_cast<ITestAbility>(remoteObject); // 使用iface_cast宏转换成具体类型
+   
+   // 获取其他设备注册的SA的Proxy
+   sptr<ISystemAbilityManager> samgr = SystemAbilityManagerClient::GetInstance().GetSystemAbilityManager();
+   sptr<IRemoteObject> remoteObject = samgr->GetSystemAbility(sdid, deviceId); // deviceId是指定设备的标识符
+   sptr<TestAbilityProxy> proxy(new TestAbilityProxy(remoteObject)); // 直接构造具体Proxy
+   ```
 
-通过SystemAbilityManager的GetSystemAbility方法可获取到对应SA的代理IRemoteObject，然后构造TestAbilityProxy即可。
 
-```
-// 获取本设备内注册的SA的proxy
-sptr<ISystemAbilityManager> samgr = SystemAbilityManagerClient::GetInstance().GetSystemAbilityManager();
-sptr<IRemoteObject> remoteObject = samgr->GetSystemAbility(said);
-sptr<ITestAbility> testAbility = iface_cast<ITestAbility>(remoteObject); // 使用iface_cast宏转换成具体类型
-
-// 获取其他设备注册的SA的Proxy
-sptr<ISystemAbilityManager> samgr = SystemAbilityManagerClient::GetInstance().GetSystemAbilityManager();
-sptr<IRemoteObject> remoteObject = samgr->GetSystemAbility(sdid, deviceId); // deviceId是指定设备的标识符
-sptr<TestAbilityProxy> proxy(new TestAbilityProxy(remoteObject)); // 直接构造具体Proxy
-```
 
 ## 相关仓<a name="section1371113476307"></a>