• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# 订阅公共事件（C/C++）
2
3
4## 场景介绍
5
6通过[OH_CommonEvent_CreateSubscriber](../../reference/apis-basic-services-kit/capi-common-event.md#oh_commonevent_createsubscriber)创建的订阅者可以对某个公共事件进行订阅，如果有订阅的事件发布那么订阅了这个事件的订阅者将会收到该事件及其传递的参数，也可以通过订阅者对象进一步处理有序公共事件。
7
8## 接口说明
9
10详细的API说明请参考[CommonEvent API参考](../../reference/apis-basic-services-kit/capi-common-event.md)。
11
12| 接口名                               | 描述                                                             |
13| ------------------------------------ | ---------------------------------------------------------------- |
14|[CommonEvent_SubscribeInfo* OH_CommonEvent_CreateSubscribeInfo(const char* events[], int32_t eventsNum)](../../reference/apis-basic-services-kit/capi-common-event.md#oh_commonevent_createsubscribeinfo)|创建订阅者信息。|
15|[void OH_CommonEvent_DestroySubscribeInfo(CommonEvent_SubscribeInfo* info)](../../reference/apis-basic-services-kit/capi-common-event.md#oh_commonevent_destroysubscribeinfo)|销毁订阅者信息。|
16|[CommonEvent_Subscriber* OH_CommonEvent_CreateSubscriber(const CommonEvent_SubscribeInfo* info, CommonEvent_ReceiveCallback callback)](../../reference/apis-basic-services-kit/capi-common-event.md#oh_commonevent_createsubscriber)| 创建订阅者。|
17|[void OH_CommonEvent_DestroySubscriber(CommonEvent_Subscriber* subscriber)](../../reference/apis-basic-services-kit/capi-common-event.md#oh_commonevent_destroysubscriber)|销毁订阅者。|
18|[CommonEvent_ErrCode OH_CommonEvent_Subscribe(const CommonEvent_Subscriber* subscriber)](../../reference/apis-basic-services-kit/capi-common-event.md#oh_commonevent_subscribe)|订阅事件。|
19|[bool OH_CommonEvent_AbortCommonEvent(CommonEvent_Subscriber* subscriber)](../../reference/apis-basic-services-kit/capi-common-event.md#oh_commonevent_abortcommonevent)|中止当前的有序公共事件。|
20|[bool OH_CommonEvent_ClearAbortCommonEvent(CommonEvent_Subscriber* subscriber)](../../reference/apis-basic-services-kit/capi-common-event.md#oh_commonevent_clearabortcommonevent)|取消当前有序公共事件的中止状态。|
21|[bool OH_CommonEvent_FinishCommonEvent(CommonEvent_Subscriber* subscriber)](../../reference/apis-basic-services-kit/capi-common-event.md#oh_commonevent_finishcommonevent)|结束对当前有序公共事件的处理。|
22
23## 开发步骤
24
251. 引用头文件。
26
27   ```c++
28   #include <cstdint>
29   #include <cstdio>
30   #include <cwchar>
31   #include <string.h>
32   #include "hilog/log.h"
33   #include "BasicServicesKit/oh_commonevent.h"
34   ```
35
362. 在CMake脚本中添加动态链接库。
37
38   ```txt
39   target_link_libraries(entry PUBLIC
40       libace_napi.z.so
41       libhilog_ndk.z.so
42       libohcommonevent.so
43   )
44   ```
45
463. 创建订阅者信息。
47
48   通过[OH_CommonEvent_CreateSubscribeInfo](../../reference/apis-basic-services-kit/capi-common-event.md#oh_commonevent_createsubscribeinfo)创建订阅者信息。
49
50   ```c++
51   CommonEvent_SubscribeInfo* CreateSubscribeInfo(const char* events[], int32_t eventsNum, const char* permission, const char* bundleName) {
52       int32_t ret = -1;
53       // 创建订阅者信息
54       CommonEvent_SubscribeInfo* info = OH_CommonEvent_CreateSubscribeInfo(events, eventsNum);
55
56       // 设置订阅者权限
57       ret = OH_CommonEvent_SetPublisherPermission(info, permission);
58       OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "OH_CommonEvent_SetPublisherPermission ret <%{public}d>.", ret);
59
60       // 设置订阅者包名称
61       ret = OH_CommonEvent_SetPublisherBundleName(info, bundleName);
62       OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "OH_CommonEvent_SetPublisherBundleName ret <%{public}d>.", ret);
63       return info;
64   }
65
66   // 销毁订阅者信息
67   void DestroySubscribeInfo(CommonEvent_SubscribeInfo* info) {
68       OH_CommonEvent_DestroySubscribeInfo(info);
69       info = nullptr;
70   }
71   ```
72
734. 创建订阅者。
74
75   先创建订阅者时通过传入公共事件的回调函数[CommonEvent_ReceiveCallback](../../reference/apis-basic-services-kit/capi-common-event.md#commonevent_receivecallback)，事件发布时，订阅者会接收到回调数据[CommonEvent_RcvData](../../reference/apis-basic-services-kit/capi-common-event.md#commonevent_rcvdata)。
76
77   ```c++
78   // 公共事件回调函数
79   void OnReceive(const CommonEvent_RcvData *data) {
80       // 获取回调公共事件名称
81       const char *event = OH_CommonEvent_GetEventFromRcvData(data);
82
83       // 获取回调公共事件结果代码
84       int code = OH_CommonEvent_GetCodeFromRcvData(data);
85
86       // 获取回调公共事件自定义结果数据
87       const char *retData = OH_CommonEvent_GetDataStrFromRcvData(data);
88
89       // 获取回调公共事件包名称
90       const char *bundle = OH_CommonEvent_GetBundleNameFromRcvData(data);
91
92       // 获取回调公共事件附件信息
93       const CommonEvent_Parameters *parameters = OH_CommonEvent_GetParametersFromRcvData(data);
94       OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "event: %{public}s, code: %{public}d, data: %{public}s, bundle: %{public}s", event, code, retData, bundle);
95   }
96   ```
97
98   通过[CommonEvent_Parameters](../../reference/apis-basic-services-kit/capi-common-event.md#commonevent_parameters)传入key来获取附加信息内容。
99
100   ```c++
101   void GetParameters(const CommonEvent_RcvData *data) {
102       // 获取回调公共事件附件信息
103       bool exists = false;
104       const CommonEvent_Parameters *parameters = OH_CommonEvent_GetParametersFromRcvData(data);
105
106       // 检查公共事件附加信息中是否包含某个键值对信息
107       exists = OH_CommonEvent_HasKeyInParameters(parameters, "intKey");
108       // 获取公共事件附加信息中int数据信息
109       int intValue = OH_CommonEvent_GetIntFromParameters(parameters, "intKey", 10);
110       OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "exists = %{public}d, intValue = %{public}d", exists, intValue);
111
112       exists = OH_CommonEvent_HasKeyInParameters(parameters, "boolKey");
113       // 获取公共事件附加信息中bool数据信息
114       bool boolValue = OH_CommonEvent_GetBoolFromParameters(parameters, "boolKey", false);
115       OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "exists = %{public}d, boolValue = %{public}d", exists, boolValue);
116
117       exists = OH_CommonEvent_HasKeyInParameters(parameters, "longKey");
118       // 获取公共事件附加信息中long数据信息
119       long longValue = OH_CommonEvent_GetLongFromParameters(parameters, "longKey", 1111111111);
120       OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "exists = %{public}d, longValue = %{public}ld", exists, longValue);
121
122       exists = OH_CommonEvent_HasKeyInParameters(parameters, "doubleKey");
123       // 获取公共事件附加信息中double数据信息
124       double doubleValue = OH_CommonEvent_GetDoubleFromParameters(parameters, "doubleKey", 11.11);
125       OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "exists = %{public}d, doubleValue = %{public}f", exists, doubleValue);
126
127       exists = OH_CommonEvent_HasKeyInParameters(parameters, "charKey");
128       // 获取公共事件附加信息中char数据信息
129       char charValue = OH_CommonEvent_GetCharFromParameters(parameters, "charKey", 'A');
130       OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "exists = %{public}d, charValue = %{public}c", exists, charValue);
131
132       int** arr = new int*;
133       exists = OH_CommonEvent_HasKeyInParameters(parameters, "intArrayKey");
134       // 获取公共事件附加信息中int数组信息
135       int32_t intArraySize = OH_CommonEvent_GetIntArrayFromParameters(parameters, "intArrayKey", arr);
136       if (intArraySize <= 0 || *arr == nullptr) {
137           OH_LOG_Print(LOG_APP, LOG_ERROR, 1, "CES_TEST", "exists = %{public}d, Failed to get int array or invalid size: %{public}d", exists, intArraySize);
138       } else {
139           OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "exists = %{public}d, intArraySize = %{public}d", exists, intArraySize);
140           for (int i = 0; i < intArraySize; i++) {
141               OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "<%{public}d>", *((*arr) + i));
142           }
143       }
144
145       long** longArray = new long*;
146       exists = OH_CommonEvent_HasKeyInParameters(parameters, "longArrayKey");
147       // 获取公共事件附加信息中long数组信息
148       int32_t longArraySize = OH_CommonEvent_GetLongArrayFromParameters(parameters, "longArrayKey", longArray);
149       if (longArraySize <= 0 || *longArray == nullptr) {
150           OH_LOG_Print(LOG_APP, LOG_ERROR, 1, "CES_TEST", "exists = %{public}d, Failed to get long array or invalid size: %{public}d", exists, longArraySize);
151       } else {
152           OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "exists = %{public}d, longArraySize = %{public}d", exists, longArraySize);
153           for (int i = 0; i < longArraySize; i++) {
154               OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "<%{public}ld>", *((*longArray) + i));
155           }
156       }
157
158       double** doubleArray = new double*;
159       exists = OH_CommonEvent_HasKeyInParameters(parameters, "doubleArrayKey");
160       // 获取公共事件附加信息中double数组信息
161       int32_t doubleArraySize = OH_CommonEvent_GetDoubleArrayFromParameters(parameters, "doubleArrayKey", doubleArray);
162       if (doubleArraySize <= 0 || *doubleArray == nullptr) {
163          OH_LOG_Print(LOG_APP, LOG_ERROR, 1, "CES_TEST", "exists = %{public}d, Failed to get double array or invalid size: %{public}d", exists, doubleArraySize);
164       } else {
165           OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "exists = %{public}d, doubleArraySize = %{public}d", exists, doubleArraySize);
166           for (int i = 0; i < doubleArraySize; i++) {
167               OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "<%{public}f>", *((*doubleArray) + i));
168           }
169       }
170
171       char** charArray = new char*;
172       exists = OH_CommonEvent_HasKeyInParameters(parameters, "charArrayKey");
173       // 获取公共事件附加信息中char数组信息
174       int32_t charArraySize = OH_CommonEvent_GetCharArrayFromParameters(parameters, "charArrayKey", charArray);
175       if (charArraySize <= 0 || *charArray == nullptr) {
176           OH_LOG_Print(LOG_APP, LOG_ERROR, 1, "CES_TEST", "exists = %{public}d, Failed to get charArray or invalid size: %{public}d", exists, charArraySize);
177       } else {
178           OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "charArray as string: %{public}s", *charArray);
179       }
180
181       bool** boolArray = new bool*;
182       exists = OH_CommonEvent_HasKeyInParameters(parameters, "boolArrayKey");
183       // 获取公共事件附加信息中bool数组信息
184       int32_t boolArraySize = OH_CommonEvent_GetBoolArrayFromParameters(parameters, "boolArrayKey", boolArray);
185       if (boolArraySize <= 0 || *boolArray == nullptr) {
186          OH_LOG_Print(LOG_APP, LOG_ERROR, 1, "CES_TEST", "exists = %{public}d, Failed to get boolArray or invalid size: %{public}d", exists, boolArraySize);
187       } else {
188           OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "exists = %{public}d, boolArraySize = %{public}d", exists, boolArraySize);
189           for (int i = 0; i < boolArraySize; i++) {
190               OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "<%{public}d>", *((*boolArray) + i));
191           }
192       }
193   }
194   ```
195
196   通过[OH_CommonEvent_CreateSubscriber](../../reference/apis-basic-services-kit/capi-common-event.md#oh_commonevent_createsubscriber)创建订阅者，传入订阅者信息[CommonEvent_SubscribeInfo](../../reference/apis-basic-services-kit/capi-common-event.md#commonevent_subscribeinfo)和事件回调函数[OnReceive](../../reference/apis-basic-services-kit/capi-common-event.md#commonevent_receivecallback)。
197
198   ```c++
199   // 创建订阅者
200   CommonEvent_Subscriber* CreateSubscriber(CommonEvent_SubscribeInfo* info) {
201       return OH_CommonEvent_CreateSubscriber(info, OnReceive);
202   }
203
204   // 销毁订阅者
205   void DestroySubscriber(CommonEvent_Subscriber* Subscriber) {
206       OH_CommonEvent_DestroySubscriber(Subscriber);
207       Subscriber = nullptr;
208   }
209   ```
210
2115. 订阅事件。
212
213   通过[OH_CommonEvent_Subscribe](../../reference/apis-basic-services-kit/capi-common-event.md#oh_commonevent_subscribe)订阅事件。
214
215   ```c++
216   void Subscribe(CommonEvent_Subscriber* subscriber) {
217       // 通过传入订阅者来订阅事件
218       int32_t ret = OH_CommonEvent_Subscribe(subscriber);
219       OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "OH_CommonEvent_Subscribe ret <%{public}d>.", ret);
220   }
221   ```
222
2236. （可选）当订阅的事件为有序公共事件时，可以选择进一步处理有序公共事件。
224
225   根据订阅者设置的优先级等级，优先将公共事件发送给优先级较高的订阅者，等待其成功接收该公共事件之后再将事件发送给优先级较低的订阅者。如果有多个订阅者具有相同的优先级，则他们将随机接收到公共事件。
226
227   > **注意：**
228   >
229   > 在订阅者收到公共事件之后，才能通过以下接口进一步处理有序公共事件。
230
231   - 中止当前的有序公共事件。
232
233     通过[OH_CommonEvent_AbortCommonEvent](../../reference/apis-basic-services-kit/capi-common-event.md#oh_commonevent_abortcommonevent)与[OH_CommonEvent_FinishCommonEvent](../../reference/apis-basic-services-kit/capi-common-event.md#oh_commonevent_finishcommonevent)配合使用，可以中止当前的有序公共事件，使该公共事件不再向下一个订阅者传递。
234
235     ```c++
236     void AbortCommonEvent(CommonEvent_Subscriber* subscriber) {
237         // 判断是否为有序公共事件
238         if(!OH_CommonEvent_IsOrderedCommonEvent(subscriber)) {
239             OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "Not ordered common event.");
240             return;
241         }
242         // 中止有序事件
243         if(OH_CommonEvent_AbortCommonEvent(subscriber)) {
244             if(OH_CommonEvent_FinishCommonEvent(subscriber)) {
245                 // 获取当前有序公共事件是否处于中止状态
246                 OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "Abort common event success, Get abort <%{public}d>.",   OH_CommonEvent_GetAbortCommonEvent(subscriber));
247             }
248         } else {
249            OH_LOG_Print(LOG_APP, LOG_ERROR, 1, "CES_TEST", "Abort common event failed.");
250         }
251     }
252     ```
253
254   - 取消当前有序公共事件的中止状态。
255
256     通过[OH_CommonEvent_ClearAbortCommonEvent](../../reference/apis-basic-services-kit/capi-common-event.md#oh_commonevent_clearabortcommonevent)与[OH_CommonEvent_FinishCommonEvent](../../reference/apis-basic-services-kit/capi-common-event.md#oh_commonevent_finishcommonevent)配合使用，可以取消当前有序公共事件的中止状态，使该公共事件继续向下一个订阅者传递。
257
258     ```c++
259     void ClearAbortCommonEvent(CommonEvent_Subscriber* subscriber) {
260         // 判断是否为有序公共事件
261         if(!OH_CommonEvent_IsOrderedCommonEvent(subscriber)) {
262             OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "Not ordered common event.");
263             return;
264         }
265         // 中止有序事件
266         if(!OH_CommonEvent_AbortCommonEvent(subscriber)) {
267             OH_LOG_Print(LOG_APP, LOG_ERROR, 1, "CES_TEST", "Abort common event failed.");
268             return;
269         }
270         // 取消中止有序事件
271         if(OH_CommonEvent_ClearAbortCommonEvent(subscriber)) {
272             if(OH_CommonEvent_FinishCommonEvent(subscriber)) {
273                 // 获取当前有序公共事件是否处于中止状态
274                 OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "Clear abort common event success, Get abort <%{public}d>.",   OH_CommonEvent_GetAbortCommonEvent(subscriber));
275             }
276         } else {
277            OH_LOG_Print(LOG_APP, LOG_ERROR, 1, "CES_TEST", "Clear abort common event failed.");
278         }
279     }
280     ```
281
282   - 修改有序公共事件的内容。
283
284     通过[OH_CommonEvent_SetCodeToSubscriber](../../reference/apis-basic-services-kit/capi-common-event.md#oh_commonevent_setcodetosubscriber)与[OH_CommonEvent_SetDataToSubscriber](../../reference/apis-basic-services-kit/capi-common-event.md#oh_commonevent_setdatatosubscriber)设置有序公共事件的代码和数据。
285
286     ```c++
287     void SetToSubscriber(CommonEvent_Subscriber* subscriber, const int32_t code, const char* data) {
288         // 设置有序公共事件的代码
289         if(!OH_CommonEvent_SetCodeToSubscriber(subscriber, code)) {
290             OH_LOG_Print(LOG_APP, LOG_ERROR, 1, "CES_TEST", "OH_CommonEvent_SetCodeToSubscriber failed.");
291             return;
292         }
293         // 设置有序公共事件的数据
294         size_t dataLength = strlen(data);
295         if(!OH_CommonEvent_SetDataToSubscriber(subscriber, data, dataLength)) {
296             OH_LOG_Print(LOG_APP, LOG_ERROR, 1, "CES_TEST", "OH_CommonEvent_SetDataToSubscriber failed.");
297             return;
298         }
299     }
300
301     void GetFromSubscriber(CommonEvent_Subscriber* subscriber) {
302         // 获取有序公共事件的数据和代码
303         const char* data = OH_CommonEvent_GetDataFromSubscriber(subscriber);
304         int32_t code = OH_CommonEvent_GetCodeFromSubscriber(subscriber);
305         OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "Subscriber data <%{public}s>, code <%{public}d>.", data, code);
306     }
307     ```
308
309