1# Publishing 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 12You can use the [OH_CommonEvent_Publish](../../reference/apis-basic-services-kit/capi-oh-commonevent-h.md#oh_commonevent_publish) and [OH_CommonEvent_PublishWithInfo](../../reference/apis-basic-services-kit/capi-oh-commonevent-h.md#oh_commonevent_publishwithinfo) methods to publish a common event, which can carry data for subscribers to parse and process. 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|[struct CommonEvent_PublishInfo](../../reference/apis-basic-services-kit/capi-oh-commonevent-h.md#structs)|Defines the property object used for publishing a common event.| 21|[CommonEvent_ErrCode OH_CommonEvent_Publish(const char* event)](../../reference/apis-basic-services-kit/capi-oh-commonevent-h.md#oh_commonevent_publish)|Publish a common event.| 22|[CommonEvent_ErrCode OH_CommonEvent_PublishWithInfo(const char* event, const CommonEvent_PublishInfo* info)](../../reference/apis-basic-services-kit/capi-oh-commonevent-h.md#oh_commonevent_publishwithinfo)| Publishes a common event with specified properties.| 23|[CommonEvent_PublishInfo* OH_CommonEvent_CreatePublishInfo(bool ordered)](../../reference/apis-basic-services-kit/capi-oh-commonevent-h.md#oh_commonevent_createpublishinfo)|Creates an attribute object of a common event.| 24|[void OH_CommonEvent_DestroyPublishInfo(CommonEvent_PublishInfo* info)](../../reference/apis-basic-services-kit/capi-oh-commonevent-h.md#oh_commonevent_destroypublishinfo)|Destroys an attribute object of a common event.| 25|[CommonEvent_Parameters* OH_CommonEvent_CreateParameters()](../../reference/apis-basic-services-kit/capi-oh-commonevent-h.md#oh_commonevent_createparameters)|Creates an additional information object of a common event.| 26|[void OH_CommonEvent_DestroyParameters(CommonEvent_Parameters* param)](../../reference/apis-basic-services-kit/capi-oh-commonevent-h.md#oh_commonevent_destroyparameters)|Destroys an additional information object of a common event.| 27 28## How to Develop 29 301. Reference header files. 31 32 ```c++ 33 #include <cstdint> 34 #include <cstdio> 35 #include <cwchar> 36 #include <string.h> 37 #include "hilog/log.h" 38 #include "BasicServicesKit/oh_commonevent.h" 39 ``` 40 412. Add dynamic link libraries to the CMake script. 42 43 ```txt 44 target_link_libraries(entry PUBLIC 45 libace_napi.z.so 46 libhilog_ndk.z.so 47 libohcommonevent.so 48 ) 49 ``` 50 513. (Optional) Create an attribute object of a common event. 52 53 When publishing a common event that carries data, you need to create a property object of the common event using [OH_CommonEvent_CreatePublishInfo](../../reference/apis-basic-services-kit/capi-oh-commonevent-h.md#oh_commonevent_createpublishinfo) and set the properties using the following APIs: 54 55 ```c++ 56 // Create and add additional information of common event attributes. 57 CommonEvent_Parameters* CreateParameters() 58 { 59 int32_t ret = -1; 60 // Create the additional information of a common event. 61 CommonEvent_Parameters* param = OH_CommonEvent_CreateParameters(); 62 63 // Set the additional information and key of the int type. 64 ret = OH_CommonEvent_SetIntToParameters(param, "intKey", 10); 65 OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "OH_CommonEvent_SetIntToParameters ret <%{public}d>.", ret); 66 67 // Set the additional information and key of the int array type. 68 int intArray[] = {123, 234, 567}; 69 size_t arraySize = 3; 70 ret = OH_CommonEvent_SetIntArrayToParameters(param, "intArrayKey", intArray, arraySize); 71 OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "OH_CommonEvent_SetIntArrayToParameters ret <%{public}d>.", ret); 72 73 // Set the additional information and key of the long type. 74 ret = OH_CommonEvent_SetLongToParameters(param, "longKey", 2147483646); 75 OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "OH_CommonEvent_SetLongToParameters ret <%{public}d>.", ret); 76 77 // Set the additional information and key of the long array type. 78 long longArray[] = {2147483646, 555, 2147483645}; 79 ret = OH_CommonEvent_SetLongArrayToParameters(param, "longArrayKey", longArray, arraySize); 80 OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "OH_CommonEvent_SetLongArrayToParameters ret <%{public}d>.", ret); 81 82 // Set the additional information and key of the double type. 83 ret = OH_CommonEvent_SetDoubleToParameters(param, "doubleKey", 11.22); 84 OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "OH_CommonEvent_SetDoubleToParameters ret <%{public}d>.", ret); 85 86 // Set the additional information and key of the double array type. 87 double doubleArray[] = {11.22, 33.44, 55.66}; 88 ret = OH_CommonEvent_SetDoubleArrayToParameters(param, "doubleArrayKey", doubleArray, arraySize); 89 OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "OH_CommonEvent_SetDoubleArrayToParameters ret <%{public}d>.", ret); 90 91 // Set the additional information and key of the Boolean type. 92 ret = OH_CommonEvent_SetBoolToParameters(param, "boolKey", true); 93 OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "OH_CommonEvent_SetBoolToParameters ret <%{public}d>.", ret); 94 95 // Set the additional information and key of the Boolean array type. 96 bool boolArray[] = {true, false, true}; 97 ret = OH_CommonEvent_SetBoolArrayToParameters(param, "boolArrayKey", boolArray, arraySize); 98 OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "OH_CommonEvent_SetBoolArrayToParameters ret <%{public}d>.", ret); 99 100 // Set the additional information and key of the char type. 101 ret = OH_CommonEvent_SetCharToParameters(param, "charKey", 'A'); 102 OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "OH_CommonEvent_SetCharToParameters ret <%{public}d>.", ret); 103 104 // Set the additional information and key of the char array type. 105 const char* value= "Char Array"; 106 size_t valueLength = strlen(value); 107 ret = OH_CommonEvent_SetCharArrayToParameters(param, "charArrayKey", value, valueLength); 108 OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "OH_CommonEvent_SetCharArrayToParameters ret <%{public}d>.", ret); 109 return param; 110 } 111 112 // Set common event attributes. 113 void SetPublishInfo(const char* bundleName, const char* permissions[], int32_t num, const int32_t code, const char* data) 114 { 115 int32_t ret = -1; 116 // Create publishInfo. Setting the value to true indicates an ordered common event; false indicates an unordered common event. 117 CommonEvent_PublishInfo* info = OH_CommonEvent_CreatePublishInfo(true); 118 119 // Set the bundle name of a common event. 120 ret = OH_CommonEvent_SetPublishInfoBundleName(info, bundleName); 121 OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "OH_CommonEvent_SetPublishInfoBundleName ret <%{public}d>.", ret); 122 123 // Set the common event permission. The parameters consist of the permission array and the number of permissions. 124 ret = OH_CommonEvent_SetPublishInfoPermissions(info, permissions, num); 125 OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "OH_CommonEvent_SetPublishInfoPermissions ret <%{public}d>.", ret); 126 127 // Set the result code of a common event. 128 ret = OH_CommonEvent_SetPublishInfoCode(info, code); 129 OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "OH_CommonEvent_SetPublishInfoCode ret <%{public}d>.", ret); 130 131 // Set the result data of a common event. 132 size_t dataLength = strlen(data); 133 ret = OH_CommonEvent_SetPublishInfoData(info, data, dataLength); 134 OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "OH_CommonEvent_SetPublishInfoData ret <%{public}d>.", ret); 135 136 // Set the additional information of a common event. 137 CommonEvent_Parameters* param = CreateParameters(); 138 ret = OH_CommonEvent_SetPublishInfoParameters(info, param); 139 OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "OH_CommonEvent_SetPublishInfoParameters ret <%{public}d>.", ret); 140 } 141 ``` 142 1434. Publish a common event. 144 145 - Use [OH_CommonEvent_Publish](../../reference/apis-basic-services-kit/capi-oh-commonevent-h.md#oh_commonevent_publish) to publish common events that do not carry information. 146 147 > **NOTE** 148 > 149 > Common events that do not carry information can be published only as unordered common events. 150 151 ```c++ 152 void Publish(const char* event) 153 { 154 int32_t ret = OH_CommonEvent_Publish(event); 155 OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "OH_CommonEvent_Publish ret <%{public}d>.", ret); 156 } 157 ``` 158 159 - Use [OH_CommonEvent_PublishWithInfo](../../reference/apis-basic-services-kit/capi-oh-commonevent-h.md#oh_commonevent_publishwithinfo) to publish common events that carry information. 160 161 ```c++ 162 void PublishWithInfo(const char* event, CommonEvent_PublishInfo* info) 163 { 164 // Create a common event with the attribute object. 165 int32_t ret = OH_CommonEvent_PublishWithInfo(event, info); 166 OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "OH_CommonEvent_PublishWithInfo ret <%{public}d>.", ret); 167 } 168 ``` 169 1705. Destroy a common event object. 171 172 If the created common event object is no longer used to publish a common event, destroy the **CommonEvent_Parameters** object by using [OH_CommonEvent_DestroyParameters](../../reference/apis-basic-services-kit/capi-oh-commonevent-h.md#oh_commonevent_destroyparameters), and then destroy the common event object by using [OH_CommonEvent_DestroyPublishInfo](../../reference/apis-basic-services-kit/capi-oh-commonevent-h.md#oh_commonevent_destroypublishinfo). 173 174 ```c++ 175 void DestroyPublishInfo(CommonEvent_Parameters* param, CommonEvent_PublishInfo* info) 176 { 177 // First, destroy Parameters. 178 OH_CommonEvent_DestroyParameters(param); 179 param = nullptr; 180 // Second, destroy PublishInfo. 181 OH_CommonEvent_DestroyPublishInfo(info); 182 info = nullptr; 183 } 184 ``` 185