README.md
1# IPC通信示例
2
3## 一、介绍
4
5本示例展示了如何使用[@ohos.rpc](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/apis-ipc-kit/js-apis-rpc.md) 相关接口，开发一个IPC客户端与服务端通信的完整示例，并在此示例中演示如何使用Parcelable/ArrayBuffer对象传递字符串信息。
6
7### 1.1、示例界面：
8|客户端|服务端|
9|-----------------|----------------------|
10|||
11
12### 1.2、使用说明：
13
141. 点击“获取服务端代理”进行连接服务端，在“发送Parcelable”和“发送ArrayBuffer”底下的输入框中输入发送内容，点击对应按钮即可发送字符串信息至服务端；
15
162. 在服务端的“显示接收到的Parcelable”、“显示接收到的ArrayBuffer”文本下显示从客户端发来的对应信息；
17
18
19## 二、工程目录
20### 客户端-IPC_Client
21```
22entry/src/main/ets/
23|---entryability
24| |---EntryAbility.ets // 入口文件
25|---pages
26| |---Index.ets // 页面布局
27|---service/cnn
28| |---IPC_Client.ets // 客户端能力，连接服务端，发送Parcelable和ArrayBuffer
29```
30
31### 服务端-IPC_Service
32```
33entry/src/main/ets/
34|---entryability
35| |---EntryAbility.ets // 入口文件
36|---pages
37| |---Index.ets // 页面布局
38|---serviceextability
39| |---IPC_Service.ets // 服务端能力，接收、处理数据
40| |---ServiceExtAbility.ets // Service通用能力
41```
42
43## 三、具体实现
44
45* 本示例分为两大模块
46
47 ### 3.1、客户端与服务端的连接和断开模块
48
49 * 3.1.1、获取服务端代理：按下按钮后，通过connectIpc()中的connectServiceExtensionAbility()进行连接服务端;
50 ```
51 let connect: common.ConnectOptions = {
52 //回调获取请求结果
53 onConnect: (elementName, remoteProxy) => {
54 hilog.info(DOMAIN, TAG, 'IpcClient:onConnect.callend(server),elementName:'+
55 JSON.stringify(elementName))
56 proxy = remoteProxy
57 ObtainResult.Result = 'success'
58 callback()
59 },
60 onDisconnect: (elementName) => {
61 hilog.info(DOMAIN, TAG, 'IpcClient onDisconnect:' + elementName)
62 },
63 onFailed: (code: number) => {
64 ObtainResult.Result = 'error '+code
65 hilog.info(DOMAIN, TAG, 'IpcClient onFailed,code:' + code)
66 callback()
67 },
68 }
69
70 //连接至服务端扩展功能
71 connectid = context.connectServiceExtensionAbility(want, connect)
72 hilog.info(DOMAIN, TAG, 'IpcClient connectid:' + connectid)
73 ```
74 * 3.1.2、断开服务端代理：按下按钮后，通过disConnectIpc()disconnectServiceExtensionAbility()进行断开连接;
75 ```
76 function disConnectIpc(context: common.UIAbilityContext) {
77 if (connectid != undefined) {
78 context.disconnectServiceExtensionAbility(connectid);
79 proxy = undefined;
80 }
81 }
82 ```
83
84 源码参考：[IPC_Client.ets](entry/src/main/ets/client/cnn/IPC_Client.ets);
85
86 接口参考：[@ohos.rpc](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/apis-ipc-kit/js-apis-rpc.md);
87
88 [IPC与RPC通信开发指南](https://docs.openharmony.cn/pages/v5.0/zh-cn/application-dev/ipc/ipc-rpc-development-guideline.md)
89
90
91 ### 3.2、客户端发送数据与服务端接收数据
92
93 * 3.2.1、通过Parcelable对象发送数据：
94
95 (1).在客户端的IPC_Client.ets中的sendParcelable()中通过rpc.MessageSequence.create()创建MessageSequence对象；
96 ```
97 let data = rpc.MessageSequence.create()
98 ```
99 (2).通过MessageSequence.writeParcelable()将封装字符串信息的Parcelable对象写入MessageSequence对象中；
100 ```
101 //取决于MyParcelable类如何定义，或需要序列化时准备传递什么数据类型;
102 //本示例中MyParcelable是以number和string为例，且服务端接收string
103 let parcelable = new MyParcelable(1, str);
104 data.writeParcelable(parcelable);
105 ```
106 (3).通过sendData()中的rpc.RemoteObject.sendMessageRequest()将包裹待发送字符串的Parcelable对象发送到服务端进程中；
107 ```
108 //用连接服务成功后返回的对象proxy，进行消息发送
109 proxy.sendMessageRequest(code, data, reply, options)
110 .then((result: rpc.RequestResult) => {
111 if (result.errCode === 0) {
112 hilog.info(DOMAIN, TAG, 'sendMessageRequest got result');
113 try {
114 let rsp = result.reply.readString()
115 hilog.info(DOMAIN, TAG, 'IpcClient result.' + rsp);
116 } catch (error) {
117 let e: BusinessError = error as BusinessError;
118 hilog.error(DOMAIN, TAG, 'rpc read exception fail, error is ' + e);
119 }
120 } else {
121 hilog.error(DOMAIN, TAG, 'RPCTest: sendMessageRequest failed, errCode: ' + result.errCode);
122 }
123 }).catch((e: Error) => {
124 hilog.error(DOMAIN, TAG, 'RPCTest: sendMessageRequest got exception: ' + e);
125 }).finally (() => {
126 hilog.info(DOMAIN, TAG, 'RPCTest: sendMessageRequest ends, reclaim parcel');
127 data.reclaim();
128 reply.reclaim();
129 });
130 ```
131
132 * 3.2.2、通过ArrayBuffer对象发送数据：
133
134 (1).在客户端的IPC_Client.ets中的sendArrayBuffer()中通过rpc.MessageSequence.create()创建MessageSequence对象；
135 ```
136 let data = rpc.MessageSequence.create()
137 ```
138
139 (2).然后将待发送字符串转为ArrayBuffer，之后通过MessageSequence.writeArrayBuffer()将ArrayBuffer对象写入MessageSequence对象中；
140 ```
141 let buffer = new ArrayBuffer(str.length);
142 let Uint8View = new Uint8Array(buffer);
143 for (let i = 0; i < str.length; i++) {
144 Uint8View[i] = str.charCodeAt(i);
145 }
146 //进行校验
147 data.writeInterfaceToken(proxy.getDescriptor())
148 //写入ArrayBuffer
149 data.writeArrayBuffer(buffer, rpc.TypeCode.UINT8_ARRAY);
150 ```
151
152 (3).通过sendData()中的rpc.RemoteObject.sendMessageRequest()将包裹待发送字符串的ArrayBuffer对象发送到服务端进程中；
153 ```
154 //用连接服务成功后返回的对象proxy，进行消息发送
155 proxy.sendMessageRequest(code, data, reply, options)
156 .then((result: rpc.RequestResult) => {
157 if (result.errCode === 0) {
158 hilog.info(DOMAIN, TAG, 'sendMessageRequest got result');
159 try {
160 let rsp = result.reply.readString()
161 hilog.info(DOMAIN, TAG, 'IpcClient result.' + rsp);
162 } catch (error) {
163 let e: BusinessError = error as BusinessError;
164 hilog.error(DOMAIN, TAG, 'rpc read exception fail, error is ' + e);
165 }
166 } else {
167 hilog.error(DOMAIN, TAG, 'RPCTest: sendMessageRequest failed, errCode: ' + result.errCode);
168 }
169 }).catch((e: Error) => {
170 hilog.error(DOMAIN, TAG, 'RPCTest: sendMessageRequest got exception: ' + e);
171 }).finally (() => {
172 hilog.info(DOMAIN, TAG, 'RPCTest: sendMessageRequest ends, reclaim parcel');
173 data.reclaim();
174 reply.reclaim();
175 });
176 ```
177 源码参考：[IPC_Client.ets](entry/src/main/ets/client/cnn/IPC_Client.ets);
178
179 接口参考：[@ohos.rpc](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/apis-ipc-kit/js-apis-rpc.md);
180
181 [IPC与RPC通信开发指南](https://docs.openharmony.cn/pages/v5.0/zh-cn/application-dev/ipc/ipc-rpc-development-guideline.md);
182
183 * 3.2.3、服务端读取数据：
184
185 (1).创建一个ServiceExtensionAbility，并在onConnect回调中返回一个StubServer对象；
186 ```
187 let globalStubServer: StubServer | undefined
188
189 function getInstance(): StubServer {
190 if (globalStubServer == undefined) {
191 globalStubServer = new StubServer('serverStub_App2')
192 }
193 return globalStubServer
194 }
195
196 export default class ServiceExtension extends ServiceExtensionAbility {
197 onCreate(want: Want) {
198 hilog.info(DOMAIN, TAG, 'ServiceExtensionAbility onCreate,want param:' + JSON.stringify(want) ?? ' ')
199 }
200
201 onRequest(want: Want, startId: number) {
202 hilog.info(DOMAIN, TAG,
203 'ServiceExtensionAbility onRequest,want param:' + JSON.stringify(want) ?? "+,startId:" + JSON.stringify(startId))
204 }
205
206 onConnect(want: Want): rpc.RemoteObject | Promise<rpc.RemoteObject> {
207 hilog.info(DOMAIN, TAG, 'ServiceExtensionAbility onConnect,want param:' + JSON.stringify(want) ?? "")
208 return getInstance()
209 }
210
211 onDisconnect(want: Want) {
212 hilog.info(DOMAIN, TAG, 'ServiceExtensionAbility onDisconnect,want param::' + JSON.stringify(want))
213 }
214
215 onDestroy() {
216 hilog.info(DOMAIN, TAG, 'ServiceExtensionAbility onDestroy')
217 }
218 }
219 ```
220
221 (2).处理MessageRequest请求的接口封装在StubServer里面，在这里接收传递来的数据；
222 ```
223 onRemoteMessageRequest(code: number, data: rpc.MessageSequence, reply: rpc.MessageSequence,
224 options: rpc.MessageOption): boolean | Promise<boolean> {
225 hilog.info(DOMAIN, TAG, 'Client Send code:' + code)
226 let descriptor = this.getDescriptor()
227 // 进行校验
228 if (descriptor != data.readInterfaceToken()) {
229 hilog.info(DOMAIN, TAG, 'VERIFICATION FAILED');
230 return false;
231 }
232
233 onHandleClientReq(code, data, reply)
234 return true
235 }
236 ```
237
238 (3).然后经过onHandleClientReq()处理接收的MessageSequence信息，通过不同的code值（Parcelable：1001，ArrayBuffer：1002），分别使用rpc.RemoteObject.readParcelable()和rpc.RemoteObject.readArrayBuffer()获取传递来的对象，通过解析该对象获得客户端传递来的字符串；
239 ```
240 function onHandleClientReq(code: number, data: rpc.MessageSequence, reply: rpc.MessageSequence) {
241 hilog.info(DOMAIN, TAG, 'onHandle Client,code:' + code)
242 switch (code) {
243 //接收Parcelable对象
244 case 1001:
245 let parcelable = new MyParcelable(0, '');
246 data.readParcelable(parcelable);
247 dataStatus.updataParcelable(parcelable.str)
248 hilog.info(DOMAIN, TAG, 'read parcelable: ' + parcelable.str);
249 break
250 //接收ArrayBuffer对象
251 case 1002:
252 let result = data.readArrayBuffer(rpc.TypeCode.UINT8_ARRAY);
253 let decoder = util.TextDecoder.create('utf-8');
254 let stringData = decoder.decodeToString(new Uint8Array(result));
255 dataStatus.updataArrayBuffer(stringData)
256 hilog.info(DOMAIN, TAG, 'read arraybuffer: ' + stringData);
257 break
258 default:
259 hilog.info(DOMAIN, TAG, 'onHandleClient-default,code: ' + 1001);
260 break
261 }
262 }
263 ```
264 源码参考：[IPC_Service.ets](../IPC_Service/entry/src/main/ets/serviceextability/IPC_Service.ets);
265
266 接口参考：[@ohos.rpc](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/apis-ipc-kit/js-apis-rpc.md);
267
268 [IPC与RPC通信开发指南](https://docs.openharmony.cn/pages/v5.0/zh-cn/application-dev/ipc/ipc-rpc-development-guideline.md);
269
270
271## 四、相关权限
272
273由于Service Ability（服务端所在应用）只能被系统应用调用，所以IPC通信机制在单框架上不对普通应用开放，故服务端需要申请系统应用权限。
274(服务端需提供ohos-sdk-full)
275
2764.1、配置权限：在服务端entry下的module中配置如下权限：[module.json5](IPC_Service/entry/src/main/module.json5),参考第38-45行。
277 ```
278 "extensionAbilities": [
279 //配置IpcServiceExtAbility能力
280 {
281 "name": "IpcServiceExtAbility",
282 "srcEntry": "./ets/serviceextability/ServiceExtAbility.ets",
283 "type": "service",
284 "exported": true,
285 "description": "service"
286 }
287 ]
288 ```
289
2904.2、将“4.1.配置权限”中添加的权限注释起来，然后运行工程，在设备上推送服务端hap。
291
2924.3、将服务端需要的系统应用权限注册到设备：
293
294 4.3.1、 获取签名指纹，及获取install_list_capability.json文件
295
296 
297
298 4.3.2、 在拉取到本地的install_list_capability.json文件中添加如下权限信息：
299
300
301 {
302 "bundleName": "应用包名",
303 "app_signature": ["4.3.1获取到的签名指纹"],
304 //添加系统应用权限
305 "allowAppUsePrivilegeExtension": true
306 },
307
308
309
310 4.3.3、 将添加权限后的install_list_capability.json文件推送至设备原路径，并重启设备
311
312 ```
313 hdc shell mount -o rw,remount /
314 hdc file send install_list_capability.json /system/etc/app/install_list_capability.json
315 hdc shell chmod 777 /system/etc/app/install_list_capability.json
316 hdc shell reboot
317 ```
318
319
3204.4、将“4.1.配置权限”中添加的权限取消注释，然后运行工程，此时的hap具有IpcServiceExtAbility。
321
322## 五、依赖
323
324本应用需依赖[IPC_Service](../IPC_Service/)端来进行IPC通信。
325
326## 六、约束与限制
327
3286.1、本示例仅支持在标准系统上运行，支持RK3568；
329
3306.2、本示例涉及使用系统接口：UIAbilityContext.connectServiceExtensionAbility，需要手动替换Full SDK才能编译通过，推荐使用最新版本Full SDK。[Full SDK下载链接](https://ci.openharmony.cn/workbench/cicd/dailybuild/dailylist)；
331
3326.3、本示例推荐使用DevEco Studio 5.0.2 Beta1 (Build Version: 5.0.7.100 构建 2025年1月16日)及以上版本编译运行。
333
3346.4、本示例推荐使用API version 16版本SDK，版本号：5.1.0.46。
335
336## 七、下载
337
338如需单独下载本工程及服务端，执行如下命令：
339
340```
341git init
342git config core.sparsecheckout true
343echo code/BasicFeature/Connectivity/IPC/ObjectTransfer/ > .git/info/sparse-checkout
344git remote add origin https://gitee.com/openharmony/applications_app_samples.git
345git pull origin master
346```
