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