1# Subscribing to Common Events in C 2 3 4## When to Use 5 6A subscriber created using [OH_CommonEvent_CreateSubscriber](../../reference/apis-basic-services-kit/capi-common-event.md#oh_commonevent_createsubscriber) can subscribe to a common event. If a subscribed event is published, the subscriber will receive the event and its parameters. Also, the subscriber object can be used to further process ordered common events. 7 8## Available APIs 9 10For details about the APIs, see [CommonEvent](../../reference/apis-basic-services-kit/capi-common-event.md). 11 12| API | Description | 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)|Creates the subscriber information.| 15|[void OH_CommonEvent_DestroySubscribeInfo(CommonEvent_SubscribeInfo* info)](../../reference/apis-basic-services-kit/capi-common-event.md#oh_commonevent_destroysubscribeinfo)|Destroys the subscriber information.| 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)| Creates a subscriber.| 17|[void OH_CommonEvent_DestroySubscriber(CommonEvent_Subscriber* subscriber)](../../reference/apis-basic-services-kit/capi-common-event.md#oh_commonevent_destroysubscriber)|Destroys a subscriber.| 18|[CommonEvent_ErrCode OH_CommonEvent_Subscribe(const CommonEvent_Subscriber* subscriber)](../../reference/apis-basic-services-kit/capi-common-event.md#oh_commonevent_subscribe)|Subscribes to an event.| 19|[bool OH_CommonEvent_AbortCommonEvent(CommonEvent_Subscriber* subscriber)](../../reference/apis-basic-services-kit/capi-common-event.md#oh_commonevent_abortcommonevent)|Whether to abort an ordered common event.| 20|[bool OH_CommonEvent_ClearAbortCommonEvent(CommonEvent_Subscriber* subscriber)](../../reference/apis-basic-services-kit/capi-common-event.md#oh_commonevent_clearabortcommonevent)|Whether to clear the aborted state of an ordered common event.| 21|[bool OH_CommonEvent_FinishCommonEvent(CommonEvent_Subscriber* subscriber)](../../reference/apis-basic-services-kit/capi-common-event.md#oh_commonevent_finishcommonevent)|Whether to finish processing an ordered common event.| 22 23## How to Develop 24 251. Reference header files. 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. Add dynamic link libraries to the CMake script. 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. Create the subscriber information. 47 48 Use [OH_CommonEvent_CreateSubscribeInfo](../../reference/apis-basic-services-kit/capi-common-event.md#oh_commonevent_createsubscribeinfo) to create subscriber information. 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 // Create the subscriber information. 54 CommonEvent_SubscribeInfo* info = OH_CommonEvent_CreateSubscribeInfo(events, eventsNum); 55 56 // Set the subscriber permission. 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 // Set a bundle name of the subscriber. 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 // Destroy the subscriber information. 67 void DestroySubscribeInfo(CommonEvent_SubscribeInfo* info) { 68 OH_CommonEvent_DestroySubscribeInfo(info); 69 info = nullptr; 70 } 71 ``` 72 734. Create a subscriber. 74 75 Pass in the callback function [CommonEvent_ReceiveCallback](../../reference/apis-basic-services-kit/capi-common-event.md#commonevent_receivecallback) of the common event when a subscriber is created. When the event is published, the subscriber receives the callback data [CommonEvent_RcvData](../../reference/apis-basic-services-kit/capi-common-event.md#commonevent_rcvdata). 76 77 ```c++ 78 // Common event callback. 79 void OnReceive(const CommonEvent_RcvData *data) { 80 // Obtain the name of a common event. 81 const char *event = OH_CommonEvent_GetEventFromRcvData(data); 82 83 // Obtain the result code of a common event. 84 int code = OH_CommonEvent_GetCodeFromRcvData(data); 85 86 // Obtain the custom result data of a common event. 87 const char *retData = OH_CommonEvent_GetDataStrFromRcvData(data); 88 89 // Obtain the bundle name of a common event. 90 const char *bundle = OH_CommonEvent_GetBundleNameFromRcvData(data); 91 92 // Obtain the additional information of a common event. 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 Use [CommonEvent_Parameters](../../reference/apis-basic-services-kit/capi-common-event.md#commonevent_parameters) to pass in a key to obtain the additional information. 99 100 ```c++ 101 void GetParameters(const CommonEvent_RcvData *data) { 102 // Obtain the additional information of a common event. 103 bool exists = false; 104 const CommonEvent_Parameters *parameters = OH_CommonEvent_GetParametersFromRcvData(data); 105 106 // Check whether the additional information of a common event contains a KV pair. 107 exists = OH_CommonEvent_HasKeyInParameters(parameters, "intKey"); 108 // Obtain the int data from the additional information of a common event. 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 // Obtain the Boolean data from the additional information of a common event. 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 // Obtain the long data from the additional information of a common event. 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 // Obtain the double data from the additional information of a common event. 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 // Obtain the char data from the additional information of a common event. 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 // Obtain the int array from the additional information of a common event. 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 // Obtain the long array from the additional information of a common event. 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 // Obtain the double array from the additional information of a common event. 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 // Obtain the char array from the additional information of a common event. 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 // Obtain the Boolean array from the additional information of a common event. 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 Use [OH_CommonEvent_CreateSubscriber](../../reference/apis-basic-services-kit/capi-common-event.md#oh_commonevent_createsubscriber) to create a subscriber and pass in the subscriber information [CommonEvent_SubscribeInfo](../../reference/apis-basic-services-kit/capi-common-event.md#commonevent_subscribeinfo) and event callback function [OnReceive](../../reference/apis-basic-services-kit/capi-common-event.md#commonevent_receivecallback). 197 198 ```c++ 199 // Create a subscriber. 200 CommonEvent_Subscriber* CreateSubscriber(CommonEvent_SubscribeInfo* info) { 201 return OH_CommonEvent_CreateSubscriber(info, OnReceive); 202 } 203 204 // Destroy a subscriber. 205 void DestroySubscriber(CommonEvent_Subscriber* Subscriber) { 206 OH_CommonEvent_DestroySubscriber(Subscriber); 207 Subscriber = nullptr; 208 } 209 ``` 210 2115. Subscribe to an event. 212 213 Subscribe to events through [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 // Subscribe to an event by passing a subscriber. 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. (Optional) Further process the subscribed event if this event is an ordered common event. 224 225 Based on the priority set by the subscriber, the common event is preferentially sent to the subscriber with a higher priority. After the subscriber successfully receives the event, the public event is sent to the subscriber with a lower priority. Subscribers with the same priority receive common events in a random order. 226 227 > **NOTE** 228 > 229 > After receiving a common event, the subscriber can further process the ordered common event through the following API. 230 231 - Abort an ordered common event. 232 233 Use [OH_CommonEvent_AbortCommonEvent](../../reference/apis-basic-services-kit/capi-common-event.md#oh_commonevent_abortcommonevent) and [OH_CommonEvent_FinishCommonEvent](../../reference/apis-basic-services-kit/capi-common-event.md#oh_commonevent_finishcommonevent) together to abort an ordered common event so that this event is not published to the next subscriber. 234 235 ```c++ 236 void AbortCommonEvent(CommonEvent_Subscriber* subscriber) { 237 // Check whether the event is an ordered common event. 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 // Abort an ordered common event. 243 if(OH_CommonEvent_AbortCommonEvent(subscriber)) { 244 if(OH_CommonEvent_FinishCommonEvent(subscriber)) { 245 // Obtain the result of the abort state of an ordered common event. 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 - Clear the aborted state of an ordered common event. 255 256 Use [OH_CommonEvent_ClearAbortCommonEvent](../../reference/apis-basic-services-kit/capi-common-event.md#oh_commonevent_clearabortcommonevent) and [OH_CommonEvent_FinishCommonEvent](../../reference/apis-basic-services-kit/capi-common-event.md#oh_commonevent_finishcommonevent) together to clear the aborted state of an ordered common event so that this event is published to the next subscriber. 257 258 ```c++ 259 void ClearAbortCommonEvent(CommonEvent_Subscriber* subscriber) { 260 // Check whether the event is an ordered common event. 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 // Abort an ordered common event. 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 // Clear the aborted state of an ordered event. 271 if(OH_CommonEvent_ClearAbortCommonEvent(subscriber)) { 272 if(OH_CommonEvent_FinishCommonEvent(subscriber)) { 273 // Obtain the result of the abort state of an ordered common event. 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 - Modify the content of an ordered common event. 283 284 Use [OH_CommonEvent_SetCodeToSubscriber](../../reference/apis-basic-services-kit/capi-common-event.md#oh_commonevent_setcodetosubscriber) and [OH_CommonEvent_SetDataToSubscriber](../../reference/apis-basic-services-kit/capi-common-event.md#oh_commonevent_setdatatosubscriber) to set the result code and data of an ordered common event. 285 286 ```c++ 287 void SetToSubscriber(CommonEvent_Subscriber* subscriber, const int32_t code, const char* data) { 288 // Set the result code of an ordered common event. 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 // Set the result data for an ordered common event. 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 // Obtain the result data and code of an ordered common event. 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