1# Subscribing to Common Events in 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## When to Use 11 12A subscriber created using [OH_CommonEvent_CreateSubscriber](../../reference/apis-basic-services-kit/capi-oh-commonevent-h.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. 13 14## Available APIs 15 16For details about the APIs, see [oh_commonevent.h](../../reference/apis-basic-services-kit/capi-oh-commonevent-h.md). 17 18| API | Description | 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)|Creates the subscriber information.| 21|[void OH_CommonEvent_DestroySubscribeInfo(CommonEvent_SubscribeInfo* info)](../../reference/apis-basic-services-kit/capi-oh-commonevent-h.md#oh_commonevent_destroysubscribeinfo)|Destroys the subscriber information.| 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)| Creates a subscriber.| 23|[void OH_CommonEvent_DestroySubscriber(CommonEvent_Subscriber* subscriber)](../../reference/apis-basic-services-kit/capi-oh-commonevent-h.md#oh_commonevent_destroysubscriber)|Destroys a subscriber.| 24|[CommonEvent_ErrCode OH_CommonEvent_Subscribe(const CommonEvent_Subscriber* subscriber)](../../reference/apis-basic-services-kit/capi-oh-commonevent-h.md#oh_commonevent_subscribe)|Subscribes to an event.| 25|[bool OH_CommonEvent_AbortCommonEvent(CommonEvent_Subscriber* subscriber)](../../reference/apis-basic-services-kit/capi-oh-commonevent-h.md#oh_commonevent_abortcommonevent)|Whether to abort an ordered common event.| 26|[bool OH_CommonEvent_ClearAbortCommonEvent(CommonEvent_Subscriber* subscriber)](../../reference/apis-basic-services-kit/capi-oh-commonevent-h.md#oh_commonevent_clearabortcommonevent)|Whether to clear the aborted state of an ordered common event.| 27|[bool OH_CommonEvent_FinishCommonEvent(CommonEvent_Subscriber* subscriber)](../../reference/apis-basic-services-kit/capi-oh-commonevent-h.md#oh_commonevent_finishcommonevent)|Whether to finish processing an ordered common event.| 28 29## How to Develop 30 311. Include header files. 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. Add dynamic link libraries to the CMake script. 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. Create the subscriber information using [OH_CommonEvent_CreateSubscribeInfo](../../reference/apis-basic-services-kit/capi-oh-commonevent-h.md#oh_commonevent_createsubscribeinfo). 53 54 ```c++ 55CommonEvent_SubscribeInfo* CreateSubscribeInfo(const char* events[], int32_t eventsNum, const char* permission, const char* bundleName) { 56 int32_t ret = -1; 57 // Create the subscriber information. 58 CommonEvent_SubscribeInfo* info = OH_CommonEvent_CreateSubscribeInfo(events, eventsNum); 59 60 // Set the publisher permission. 61 ret = OH_CommonEvent_SetPublisherPermission(info, permission); 62 OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "OH_CommonEvent_SetPublisherPermission ret <%{public}d>.", ret); 63 64 // Set the publisher bundle name. 65 ret = OH_CommonEvent_SetPublisherBundleName(info, bundleName); 66 OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "OH_CommonEvent_SetPublisherBundleName ret <%{public}d>.", ret); 67 return info; 68 } 69 70 // Destroy the subscriber information. 71 void DestroySubscribeInfo(CommonEvent_SubscribeInfo* info) { 72 OH_CommonEvent_DestroySubscribeInfo(info); 73 info = nullptr; 74 } 75 ``` 76 774. Create a subscriber. 78 79 When creating a subscriber, pass in [CommonEvent_ReceiveCallback](../../reference/apis-basic-services-kit/capi-oh-commonevent-h.md#commonevent_receivecallback). When the event is published, the subscriber receives [CommonEvent_RcvData](../../reference/apis-basic-services-kit/capi-oh-commonevent-h.md#structs). 80 81 ```c++ 82 // Common event callback. 83 void OnReceive(const CommonEvent_RcvData *data) { 84 // Obtain the name of a common event. 85 const char *event = OH_CommonEvent_GetEventFromRcvData(data); 86 87 // Obtain the result code of a common event. 88 int code = OH_CommonEvent_GetCodeFromRcvData(data); 89 90 // Obtain the custom result data of a common event. 91 const char *retData = OH_CommonEvent_GetDataStrFromRcvData(data); 92 93 // Obtain the bundle name of a common event. 94 const char *bundle = OH_CommonEvent_GetBundleNameFromRcvData(data); 95 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); 96 } 97 ``` 98 99 Use [CommonEvent_Parameters](../../reference/apis-basic-services-kit/capi-oh-commonevent-h.md#variables) to pass in a key to obtain the additional information. 100 101 ```c++ 102 void GetParameters(const CommonEvent_RcvData *data) { 103 // Obtain the additional information of a common event. 104 bool exists = false; 105 const CommonEvent_Parameters *parameters = OH_CommonEvent_GetParametersFromRcvData(data); 106 107 // Check whether the additional information of a common event contains a KV pair. 108 exists = OH_CommonEvent_HasKeyInParameters(parameters, "intKey"); 109 // Obtain the int data from the additional information of a common event. 110 int intValue = OH_CommonEvent_GetIntFromParameters(parameters, "intKey", 10); 111 OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "exists = %{public}d, intValue = %{public}d", exists, intValue); 112 113 exists = OH_CommonEvent_HasKeyInParameters(parameters, "boolKey"); 114 // Obtain the Boolean data from the additional information of a common event. 115 bool boolValue = OH_CommonEvent_GetBoolFromParameters(parameters, "boolKey", false); 116 OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "exists = %{public}d, boolValue = %{public}d", exists, boolValue); 117 118 exists = OH_CommonEvent_HasKeyInParameters(parameters, "longKey"); 119 // Obtain the long data from the additional information of a common event. 120 long longValue = OH_CommonEvent_GetLongFromParameters(parameters, "longKey", 1111111111); 121 OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "exists = %{public}d, longValue = %{public}ld", exists, longValue); 122 123 exists = OH_CommonEvent_HasKeyInParameters(parameters, "doubleKey"); 124 // Obtain the double data from the additional information of a common event. 125 double doubleValue = OH_CommonEvent_GetDoubleFromParameters(parameters, "doubleKey", 11.11); 126 OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "exists = %{public}d, doubleValue = %{public}f", exists, doubleValue); 127 128 exists = OH_CommonEvent_HasKeyInParameters(parameters, "charKey"); 129 // Obtain the char data from the additional information of a common event. 130 char charValue = OH_CommonEvent_GetCharFromParameters(parameters, "charKey", 'A'); 131 OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "exists = %{public}d, charValue = %{public}c", exists, charValue); 132 133 int** arr = new int*; 134 exists = OH_CommonEvent_HasKeyInParameters(parameters, "intArrayKey"); 135 // Obtain the int array from the additional information of a common event. 136 int32_t intArraySize = OH_CommonEvent_GetIntArrayFromParameters(parameters, "intArrayKey", arr); 137 if (intArraySize <= 0 || *arr == nullptr) { 138 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); 139 } else { 140 OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "exists = %{public}d, intArraySize = %{public}d", exists, intArraySize); 141 for (int i = 0; i < intArraySize; i++) { 142 OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "<%{public}d>", *((*arr) + i)); 143 } 144 } 145 146 long** longArray = new long*; 147 exists = OH_CommonEvent_HasKeyInParameters(parameters, "longArrayKey"); 148 // Obtain the long array from the additional information of a common event. 149 int32_t longArraySize = OH_CommonEvent_GetLongArrayFromParameters(parameters, "longArrayKey", longArray); 150 if (longArraySize <= 0 || *longArray == nullptr) { 151 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); 152 } else { 153 OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "exists = %{public}d, longArraySize = %{public}d", exists, longArraySize); 154 for (int i = 0; i < longArraySize; i++) { 155 OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "<%{public}ld>", *((*longArray) + i)); 156 } 157 } 158 159 double** doubleArray = new double*; 160 exists = OH_CommonEvent_HasKeyInParameters(parameters, "doubleArrayKey"); 161 // Obtain the double array from the additional information of a common event. 162 int32_t doubleArraySize = OH_CommonEvent_GetDoubleArrayFromParameters(parameters, "doubleArrayKey", doubleArray); 163 if (doubleArraySize <= 0 || *doubleArray == nullptr) { 164 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); 165 } else { 166 OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "exists = %{public}d, doubleArraySize = %{public}d", exists, doubleArraySize); 167 for (int i = 0; i < doubleArraySize; i++) { 168 OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "<%{public}f>", *((*doubleArray) + i)); 169 } 170 } 171 172 char** charArray = new char*; 173 exists = OH_CommonEvent_HasKeyInParameters(parameters, "charArrayKey"); 174 // Obtain the char array from the additional information of a common event. 175 int32_t charArraySize = OH_CommonEvent_GetCharArrayFromParameters(parameters, "charArrayKey", charArray); 176 if (charArraySize <= 0 || *charArray == nullptr) { 177 OH_LOG_Print(LOG_APP, LOG_ERROR, 1, "CES_TEST", "exists = %{public}d, Failed to get charArray or invalid size: %{public}d", exists, charArraySize); 178 } else { 179 OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "charArray as string: %{public}s", *charArray); 180 } 181 182 bool** boolArray = new bool*; 183 exists = OH_CommonEvent_HasKeyInParameters(parameters, "boolArrayKey"); 184 // Obtain the Boolean array from the additional information of a common event. 185 int32_t boolArraySize = OH_CommonEvent_GetBoolArrayFromParameters(parameters, "boolArrayKey", boolArray); 186 if (boolArraySize <= 0 || *boolArray == nullptr) { 187 OH_LOG_Print(LOG_APP, LOG_ERROR, 1, "CES_TEST", "exists = %{public}d, Failed to get boolArray or invalid size: %{public}d", exists, boolArraySize); 188 } else { 189 OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "exists = %{public}d, boolArraySize = %{public}d", exists, boolArraySize); 190 for (int i = 0; i < boolArraySize; i++) { 191 OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "<%{public}d>", *((*boolArray) + i)); 192 } 193 } 194 } 195 ``` 196 197 Create a subscriber through [OH_CommonEvent_CreateSubscriber](../../reference/apis-basic-services-kit/capi-oh-commonevent-h.md#oh_commonevent_createsubscriber), and pass in [CommonEvent_SubscribeInfo](../../reference/apis-basic-services-kit/capi-oh-commonevent-h.md#structs) and the **OnReceive** function defined in step 4. 198 199 ```c++ 200 // Create a subscriber. 201 CommonEvent_Subscriber* CreateSubscriber(CommonEvent_SubscribeInfo* info) { 202 return OH_CommonEvent_CreateSubscriber(info, OnReceive); 203 } 204 205 // Destroy a subscriber. 206 void DestroySubscriber(CommonEvent_Subscriber* Subscriber) { 207 OH_CommonEvent_DestroySubscriber(Subscriber); 208 Subscriber = nullptr; 209 } 210 ``` 211 2125. Subscribe to an event using [OH_CommonEvent_Subscribe](../../reference/apis-basic-services-kit/capi-oh-commonevent-h.md#oh_commonevent_subscribe). 213 214 ```c++ 215void Subscribe(CommonEvent_Subscriber* subscriber) { 216 // Subscribe to an event by passing a subscriber. 217 int32_t ret = OH_CommonEvent_Subscribe(subscriber); 218 OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "OH_CommonEvent_Subscribe ret <%{public}d>.", ret); 219 } 220 ``` 221 2226. (Optional) Further process the subscribed event if this event is an ordered common event. 223 224 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. 225 226 > **NOTE** 227 > 228 > After receiving a common event, the subscriber can further process the ordered common event through the following API. 229 230 - Abort an ordered common event. 231 232 Use [OH_CommonEvent_AbortCommonEvent](../../reference/apis-basic-services-kit/capi-oh-commonevent-h.md#oh_commonevent_abortcommonevent) and [OH_CommonEvent_FinishCommonEvent](../../reference/apis-basic-services-kit/capi-oh-commonevent-h.md#oh_commonevent_finishcommonevent) together to abort an ordered common event so that this event is not published to the next subscriber. 233 234 ```c++ 235 void AbortCommonEvent(CommonEvent_Subscriber* subscriber) { 236 // Check whether the event is an ordered common event. 237 if(!OH_CommonEvent_IsOrderedCommonEvent(subscriber)) { 238 OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "Not ordered common event."); 239 return; 240 } 241 // Abort an ordered common event. 242 if(OH_CommonEvent_AbortCommonEvent(subscriber)) { 243 if(OH_CommonEvent_FinishCommonEvent(subscriber)) { 244 // Obtain the result of the abort state of an ordered common event. 245 OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "Abort common event success, Get abort <%{public}d>.", OH_CommonEvent_GetAbortCommonEvent(subscriber)); 246 } 247 } else { 248 OH_LOG_Print(LOG_APP, LOG_ERROR, 1, "CES_TEST", "Abort common event failed."); 249 } 250 } 251 ``` 252 253 - Clear the aborted state of an ordered common event. 254 255 Use [OH_CommonEvent_ClearAbortCommonEvent](../../reference/apis-basic-services-kit/capi-oh-commonevent-h.md#oh_commonevent_clearabortcommonevent) and [OH_CommonEvent_FinishCommonEvent](../../reference/apis-basic-services-kit/capi-oh-commonevent-h.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. 256 257 ```c++ 258 void ClearAbortCommonEvent(CommonEvent_Subscriber* subscriber) { 259 // Check whether the event is an ordered common event. 260 if(!OH_CommonEvent_IsOrderedCommonEvent(subscriber)) { 261 OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "Not ordered common event."); 262 return; 263 } 264 // Abort an ordered common event. 265 if(!OH_CommonEvent_AbortCommonEvent(subscriber)) { 266 OH_LOG_Print(LOG_APP, LOG_ERROR, 1, "CES_TEST", "Abort common event failed."); 267 return; 268 } 269 // Clear the aborted state of an ordered event. 270 if(OH_CommonEvent_ClearAbortCommonEvent(subscriber)) { 271 if(OH_CommonEvent_FinishCommonEvent(subscriber)) { 272 // Obtain the result of the abort state of an ordered common event. 273 OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "Clear abort common event success, Get abort <%{public}d>.", OH_CommonEvent_GetAbortCommonEvent(subscriber)); 274 } 275 } else { 276 OH_LOG_Print(LOG_APP, LOG_ERROR, 1, "CES_TEST", "Clear abort common event failed."); 277 } 278 } 279 ``` 280 281 - Modify the content of an ordered common event using [OH_CommonEvent_SetCodeToSubscriber](../../reference/apis-basic-services-kit/capi-oh-commonevent-h.md#oh_commonevent_setcodetosubscriber) and [OH_CommonEvent_SetDataToSubscriber](../../reference/apis-basic-services-kit/capi-oh-commonevent-h.md#oh_commonevent_setdatatosubscriber). 282 283 ```c++ 284void SetToSubscriber(CommonEvent_Subscriber* subscriber, const int32_t code, const char* data) { 285 // Set the result code for an ordered common event. 286 if(!OH_CommonEvent_SetCodeToSubscriber(subscriber, code)) { 287 OH_LOG_Print(LOG_APP, LOG_ERROR, 1, "CES_TEST", "OH_CommonEvent_SetCodeToSubscriber failed."); 288 return; 289 } 290 // Set the result data for an ordered common event. 291 size_t dataLength = strlen(data); 292 if(!OH_CommonEvent_SetDataToSubscriber(subscriber, data, dataLength)) { 293 OH_LOG_Print(LOG_APP, LOG_ERROR, 1, "CES_TEST", "OH_CommonEvent_SetDataToSubscriber failed."); 294 return; 295 } 296 } 297 298 void GetFromSubscriber(CommonEvent_Subscriber* subscriber) { 299 // Obtain the result data and code of an ordered common event. 300 const char* data = OH_CommonEvent_GetDataFromSubscriber(subscriber); 301 int32_t code = OH_CommonEvent_GetCodeFromSubscriber(subscriber); 302 OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "Subscriber data <%{public}s>, code <%{public}d>.", data, code); 303 } 304 ``` 305 306