1# IPC/RPC组件<a name="ZH-CN_TOPIC_0000001103602398"></a> 2 3- [简介](#section11660541593) 4- [系统架构](#section1950291414611) 5- [目录](#section161941989596) 6- [约束](#section119744591305) 7- [编译构建](#section137768191623) 8- [说明](#section1312121216216) 9 - [接口说明](#section1551164914237) 10 - [使用说明](#section129654513264) 11 12- [相关仓](#section1371113476307) 13 14## 简介<a name="section11660541593"></a> 15 16IPC（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表示服务提供方。 17 18## 系统架构<a name="section1950291414611"></a> 19 20**图 1** IPC通信机制架构图<a name="fig312319321710"></a> 21 22 23## 目录<a name="section161941989596"></a> 24 25``` 26/foundation/communication/ipc 27├── interfaces # 对外接口存放目录 28│ └── innerkits # 对内部子系统暴露的头文件存放目录 29│ ├── ipc_core # ipc 接口存放目录 30│ └── libdbinder # dbinder 接口存放目录 31├── ipc # ipc 框架代码 32│ ├── native # ipc native 实现存放目录 33│ ├── src # ipc native 源代码存放目录 34│ └── test # ipc native 单元测试用例存放目录 35│ └── test # ipc native 模块测试用例存放目录 36├── service # dbinder 实现存放目录 37│ └── dbinder # dbinder 源代码存放目录 38``` 39 40## 约束<a name="section119744591305"></a> 41 421. 单个设备上跨进程通信时，传输的数据量最大约为1MB，过大的数据量请使用匿名共享内存。 432. 不支持把跨设备的Proxy对象传递回该Proxy对象所指向的Stub对象所在的设备。 44 45## 编译构建<a name="section137768191623"></a> 46 47**JS侧依赖** 48 49``` 50import rpc from "@ohos.rpc" 51``` 52 53**Native侧编译依赖** 54 55sdk依赖： 56 57``` 58external_deps = [ 59 "ipc:ipc_core", 60] 61``` 62 63此外， IPC/RPC依赖的refbase实现在公共基础库下，请增加对utils的依赖： 64 65``` 66external_deps = [ 67 "c_utils:utils", 68] 69``` 70 71## 说明<a name="section1312121216216"></a> 72 73**JS侧实现跨进程通信基本步骤：** 74 751. 获取代理 76 77 使用ohos.app.ability.UIAbility提供的globalThis.context.connectServiceExtensionAbility方法绑定Ability，在参数里指定要绑定的Ability所在应用的包名、组件名，如果是跨设备的情况，还需要指定所在设备的NetworkId。用户需要在服务端的onConnect方法里返回一个继承自ohos.rpc.RemoteObject的对象，此对象会在其onRemoteMessageRequest方法里接收到请求。 78 792. 发送请求 80 81 客户端在globalThis.context.connectServiceExtensionAbility参数指定的回调函数接收到代理对象后，使用ohos.rpc模块提供的方法完成RPC通信，其中MessageParcel提供了读写各种类型数据的方法，IRemoteObject提供了发送请求的方法，RemoteObject提供了处理请求的方法onRemoteRequest，用户需要重写。 82 83**Native侧实现跨进程通信的基本步骤：** 84 851. 定义接口类 86 87 接口类继承IRemoteBroker，定义描述符、业务函数和消息码。 88 892. 实现服务提供端\(Stub\) 90 91 Stub继承IRemoteStub\(Native\)，除了接口类中未实现方法外，还需要实现AsObject方法及OnRemoteRequest方法。 92 933. 实现服务请求端\(Proxy\) 94 95 Proxy继承IRemoteProxy\(Native\)，封装业务函数，调用SendRequest将请求发送到Stub。 96 974. 注册SA 98 99 服务提供方所在进程启动后，申请SA的唯一标识，将Stub注册到SAMgr。 100 1015. 获取SA 102 1036. 通过SA的标识和设备NetworkId，从SAMgr获取Proxy，通过Proxy实现与Stub的跨进程通信。 104 105### 接口说明<a name="section1551164914237"></a> 106 107**表 1** JS侧IPC关键API 108 109| 模块 | 方法 | 功能说明 | 110| -------------------------- | ------------------------------------------------------------ | ------------------------------------------- | 111| ohos.app.ability.UIAbility | globalThis.context.connectServiceExtensionAbility(want: Want, options:ConnectOptions ): number | 绑定指定的Ability，在回调函数里接收代理对象 | 112| ohos.rpc.RemoteObject | onRemoteMessageRequest(code: number, data: MessageParcel, reply: MessageParcel, options: MessageOption): boolean \| Promise<boolean> | 服务端处理请求，返回结果 | 113| ohos.rpc.IRemoteObject | sendRequest(code: number, data: MessageParcel, reply: MessageParcel, options: MessageOption): Promise<SendRequestResult> | 发送请求，在期约里接收结果 | 114| ohos.rpc.IRemoteObject | sendRequest(code: number, data: MessageParcel, reply: MessageParcel, options: MessageOption, callback: AsyncCallback<SendRequestResult>): void | 发送请求，在回调函数里接收结果 | 115| ohos.rpc.MessageParcel | writeRemoteObject(object: IRemoteObject): boolean | 序列化IRemoteObject对象 | 116| ohos.rpc.MessageParcel | readRemoteObject(): IRemoteObject | 反序列化IRemoteObject对象 | 117 118 119 120**表 2** Native侧IPC接口 121 122<a name="table178849240013"></a> 123 124<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> 125</th> 126<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> 127</th> 128<th class="cellrowborder" valign="top" width="33.33333333333333%" id="mcps1.2.4.1.3"><p id="p388516244016"><a name="p388516244016"></a><a name="p388516244016"></a>功能说明</p> 129</th> 130</tr> 131</thead> 132<tbody><tr id="row15885824402"><td class="cellrowborder" valign="top" width="14.12141214121412%" headers="mcps1.2.4.1.1 "><p id="p08859241008"><a name="p08859241008"></a><a name="p08859241008"></a>IRemoteBroker</p> 133</td> 134<td class="cellrowborder" valign="top" width="52.54525452545254%" headers="mcps1.2.4.1.2 "><p id="p388572412010"><a name="p388572412010"></a><a name="p388572412010"></a>sptr<IRemoteObject> AsObject()</p> 135</td> 136<td class="cellrowborder" valign="top" width="33.33333333333333%" headers="mcps1.2.4.1.3 "><p id="p13885724405"><a name="p13885724405"></a><a name="p13885724405"></a>返回通信对象。派生类需要实现，Stub端返回RemoteObject对象本身，Proxy端返回代理对象。</p> 137</td> 138</tr> 139<tr id="row138859241808"><td class="cellrowborder" valign="top" width="14.12141214121412%" headers="mcps1.2.4.1.1 "><p id="p1888515245012"><a name="p1888515245012"></a><a name="p1888515245012"></a>IRemoteStub</p> 140</td> 141<td class="cellrowborder" valign="top" width="52.54525452545254%" headers="mcps1.2.4.1.2 "><p id="p1388516240011"><a name="p1388516240011"></a><a name="p1388516240011"></a>virtual int OnRemoteRequest(uint32_t code, MessageParcel &data, MessageParcel &reply, MessageOption &option)</p> 142</td> 143<td class="cellrowborder" valign="top" width="33.33333333333333%" headers="mcps1.2.4.1.3 "><p id="p1188582414016"><a name="p1188582414016"></a><a name="p1188582414016"></a>请求处理方法，派生类需要重写，处理Proxy的请求并返回结果。</p> 144</td> 145</tr> 146<tr id="row108856241904"><td class="cellrowborder" valign="top" width="14.12141214121412%" headers="mcps1.2.4.1.1 "><p id="p6885924609"><a name="p6885924609"></a><a name="p6885924609"></a>IRemoteProxy</p> 147</td> 148<td class="cellrowborder" valign="top" width="52.54525452545254%" headers="mcps1.2.4.1.2 "> </td> 149<td class="cellrowborder" valign="top" width="33.33333333333333%" headers="mcps1.2.4.1.3 "><p id="p688592413018"><a name="p688592413018"></a><a name="p688592413018"></a>业务Proxy类派生自IRemoteProxy类。</p> 150</td> 151</tr> 152</tbody> 153</table> 154 155### 使用说明<a name="section129654513264"></a> 156 157**JS侧使用说明** 158 1591. 客户端构造变量want，指定要绑定的Ability所在应用的包名、组件名，如果是跨设备的场景，还需要目标设备NetworkId。构造变量connect，指定绑定成功、绑定失败、断开连接时的回调函数。使用UIAbility提供的接口绑定Ability。 160 161 ``` 162 import rpc from "@ohos.rpc" 163 164 let proxy = null 165 let connectId = null 166 167 // 单个设备 168 let want = { 169 // 包名和组件名写实际的值 170 "bundleName": "ohos.rpc.test.server", 171 "abilityName": "ohos.rpc.test.server.ServiceAbility", 172 } 173 let connect = { 174 onConnect:function(elementName, remote) { 175 proxy = remote 176 }, 177 onDisconnect:function(elementName) { 178 }, 179 onFailed:function() { 180 proxy = null 181 } 182 } 183 connectId = globalThis.context.connectServiceExtensionAbility(want, connect) 184 185 // 如果是跨设备绑定，可以使用deviceManager获取目标设备NetworkId 186 import deviceManager from '@ohos.distributedHardware.deviceManager' 187 function deviceManagerCallback(deviceManager) { 188 let deviceList = deviceManager.getTrustedDeviceListSync() 189 let deviceId = deviceList[0].deviceId 190 let want = { 191 "bundleName": "ohos.rpc.test.server", 192 "abilityName": "ohos.rpc.test.service.ServiceAbility", 193 "deviceId": deviceId, 194 "flags": 256 195 } 196 connectId = globalThis.context.connectServiceExtensionAbility(want, connect) 197 } 198 // 第一个参数是本应用的包名，第二个参数是接收deviceManager的回调函数 199 deviceManager.createDeviceManager("ohos.rpc.test", deviceManagerCallback) 200 ``` 201 202 203 2042. 服务端被绑定的Ability在onConnect方法里返回继承自rpc.RemoteObject的对象，该对象需要实现onRemoteMessageRequest方法，处理客户端的请求。 205 206 ``` 207 import rpc from "@ohos.rpc" 208 onConnect(want: Want) { 209 var robj:rpc.RemoteObject = new Stub("rpcTestAbility") 210 return robj 211 } 212 class Stub extends rpc.RemoteObject { 213 constructor(descriptor) { 214 super(descriptor) 215 } 216 onRemoteMessageRequest(code, data, reply, option) { 217 // 根据code处理客户端的请求 218 return true 219 } 220 } 221 ``` 222 223 224 2253. 客户端在onConnect回调里接收到代理对象，调用sendRequest方法发起请求，在期约或者回调函数里接收结果。 226 227 ``` 228 import rpc from "@ohos.rpc" 229 // 使用期约 230 let option = new rpc.MessageOption() 231 let data = rpc.MessageParcel.create() 232 let reply = rpc.MessageParcel.create() 233 // 往data里写入参数 234 proxy.sendRequest(1, data, reply, option) 235 .then(function(result) { 236 if (result.errCode != 0) { 237 console.error("send request failed, errCode: " + result.errCode) 238 return 239 } 240 // 从result.reply里读取结果 241 }) 242 .catch(function(e) { 243 console.error("send request got exception: " + e) 244 } 245 .finally(() => { 246 data.reclaim() 247 reply.reclaim() 248 }) 249 250 // 使用回调函数 251 function sendRequestCallback(result) { 252 try { 253 if (result.errCode != 0) { 254 console.error("send request failed, errCode: " + result.errCode) 255 return 256 } 257 // 从result.reply里读取结果 258 } finally { 259 result.data.reclaim() 260 result.reply.reclaim() 261 } 262 } 263 let option = new rpc.MessageOption() 264 let data = rpc.MessageParcel.create() 265 let reply = rpc.MessageParcel.create() 266 // 往data里写入参数 267 proxy.sendRequest(1, data, reply, option, sendRequestCallback) 268 ``` 269 270 271 2724. IPC通信结束后，使用UIAbility的接口断开连接。 273 274 ``` 275 import rpc from "@ohos.rpc" 276 globalThis.context.disconnectServiceExtensionAbility(connectionId).then((data) => { 277 console.info('disconnectServiceExtensionAbility success'); 278 }).catch((error) => { 279 console.error('disconnectServiceExtensionAbility failed'); 280 }) 281 ``` 282 283 284 285**Native侧使用说明** 286 2871. 定义IPC接口ITestAbility 288 289 IPC接口继承IPC基类接口IRemoteBroker，接口里定义描述符、业务函数和消息码，其中业务函数在Proxy端和Stub端都需要实现。 290 291 ``` 292 class ITestAbility : public IRemoteBroker { 293 public: 294 // DECLARE_INTERFACE_DESCRIPTOR是必须的， 入参需使用std::u16string； 295 DECLARE_INTERFACE_DESCRIPTOR(u"test.ITestAbility"); // DESCRIPTOR接口描述符建议使用"组件名.类名"的格式 296 int TRANS_ID_PING_ABILITY = 1; // 定义消息码 297 virtual int TestPingAbility(const std::u16string &dummy) = 0; // 定义业务函数 298 }; 299 ``` 300 301 302 3032. 定义和实现服务端TestAbilityStub 304 305 该类是和IPC框架相关的实现，需要继承自IRemoteStub<ITestAbility\>。Stub端作为接收请求的一端，需重写OnRemoteRequest方法用于接收客户端调用。 306 307 ``` 308 class TestAbilityStub : public IRemoteStub<ITestAbility> { 309 public: 310 virtual int OnRemoteRequest(uint32_t code, MessageParcel &data, MessageParcel &reply, MessageOption &option) override; 311 int TestPingAbility(const std::u16string &dummy) override; 312 }; 313 314 int TestServiceStub::OnRemoteRequest(uint32_t code, 315 MessageParcel &data, MessageParcel &reply, MessageOption &option) 316 { 317 if (data.ReadInterfaceToken() != GetDescriptor()) { //校验是否为本服务的接口描述符，避免中继攻击 318 return -1; 319 } 320 switch (code) { 321 case TRANS_ID_PING_ABILITY: { 322 std::u16string dummy = data.ReadString16(); 323 int result = TestPingAbility(dummy); 324 reply.WriteInt32(result); 325 return 0; 326 } 327 default: 328 return IPCObjectStub::OnRemoteRequest(code, data, reply, option); 329 } 330 } 331 ``` 332 333 334 3353. 定义服务端业务函数具体实现类TestAbility 336 337 ``` 338 class TestAbility : public TestAbilityStub { 339 public: 340 int TestPingAbility(const std::u16string &dummy); 341 } 342 343 int TestAbility::TestPingAbility(const std::u16string &dummy) { 344 return 0; 345 } 346 ``` 347 348 349 3504. 定义和实现客户端TestAbilityProxy 351 352 该类是Proxy端实现，继承自IRemoteProxy<ITestAbility\>，调用SendRequest接口向Stub端发送请求，对外暴露服务端提供的能力。 353 354 ``` 355 class TestAbilityProxy : public IRemoteProxy<ITestAbility> { 356 public: 357 explicit TestAbilityProxy(const sptr<IRemoteObject> &impl); 358 int TestPingService(const std::u16string &dummy) override; 359 private: 360 static inline BrokerDelegator<TestAbilityProxy> delegator_; // 方便使用iface_cast宏 361 } 362 363 TestAbilityProxy::TestAbilityProxy(const sptr<IRemoteObject> &impl) 364 : IRemoteProxy<ITestAbility>(impl) 365 { 366 } 367 368 int TestAbilityProxy::TestPingService(const std::u16string &dummy) { 369 MessageOption option; 370 MessageParcel dataParcel, replyParcel; 371 if(!dataParcel.WriteInterfaceToken(GetDescriptor())) { //所有对外接口的proxy实现都要写入接口描述符，用于stub端检验 372 return -1; 373 } 374 if(!dataParcel.WriteString16(dummy)) { 375 return -1; 376 } 377 int error = Remote()->SendRequest(TRANS_ID_PING_ABILITY, dataParcel, replyParcel, option); 378 int result = (error == ERR_NONE) ? replyParcel.ReadInt32() : -1; 379 return result; 380 } 381 ``` 382 383 384 3855. 同步调用与异步调用 386 387 MessageOption作为发送接口（原型如下）的入参，可设定同步（TF\_SYNC）、异步（TF\_ASYNC），默认情况下设定为同步，其余可通过MessageOption构造方法或void SetFlags\(int flags\)设定。 388 389 ``` 390 int SendRequest(uint32_t code, MessageParcel &data, 391 MessageParcel &reply, MessageOption &option) override; 392 MessageOption option; 393 option.setFlags(option.TF_ASYNC); 394 ``` 395 396 397 3986. SA注册与启动 399 400 SA需要将自己的TestAbilityStub实例通过AddSystemAbility接口注册到SystemAbilityManager，设备内与分布式的注册参数不同。 401 402 ``` 403 // 注册到本设备内 404 auto samgr = SystemAbilityManagerClient::GetInstance().GetSystemAbilityManager(); 405 samgr->AddSystemAbility(said, new TestAbility()); 406 407 // 在组网场景下，会被同步到其他设备上 408 auto samgr = SystemAbilityManagerClient::GetInstance().GetSystemAbilityManager(); 409 ISystemAbilityManager::SAExtraProp saExtra; 410 saExtra.isDistributed = true; // 设置为分布式SA 411 int result = samgr->AddSystemAbility(said, new TestAbility(), saExtra); 412 ``` 413 414 415 4167. SA获取与调用 417 418 通过SystemAbilityManager的GetSystemAbility方法可获取到对应SA的代理IRemoteObject，然后构造TestAbilityProxy即可。 419 420 ``` 421 // 获取本设备内注册的SA的proxy 422 sptr<ISystemAbilityManager> samgr = SystemAbilityManagerClient::GetInstance().GetSystemAbilityManager(); 423 sptr<IRemoteObject> remoteObject = samgr->GetSystemAbility(said); 424 sptr<ITestAbility> testAbility = iface_cast<ITestAbility>(remoteObject); // 使用iface_cast宏转换成具体类型 425 426 // 获取其他设备注册的SA的Proxy 427 sptr<ISystemAbilityManager> samgr = SystemAbilityManagerClient::GetInstance().GetSystemAbilityManager(); 428 sptr<IRemoteObject> remoteObject = samgr->GetSystemAbility(sdid, deviceId); // deviceId是指定设备的标识符 429 sptr<TestAbilityProxy> proxy(new TestAbilityProxy(remoteObject)); // 直接构造具体Proxy 430 ``` 431 432 433 434## 相关仓<a name="section1371113476307"></a> 435 436分布式软总线子系统 437 438**communication\_ipc** 439 440[commonlibrary\_c\_utils](https://gitee.com/openharmony/commonlibrary_c_utils) 441 442[distributedschedule\_samgr](https://gitee.com/openharmony/distributedschedule_samgr) 443 444
