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