1 /* 2 * Copyright (c) 2024 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16 #ifndef OH_COMMON_EVENT_C_H 17 #define OH_COMMON_EVENT_C_H 18 19 #include <stdint.h> 20 21 #ifdef __cplusplus 22 extern "C" { 23 #endif 24 25 typedef enum CommonEvent_ErrCode { 26 /** @error Execution successful. */ 27 COMMONEVENT_ERR_OK = 0, 28 /** @error Permission verification failed. */ 29 COMMONEVENT_ERR_PERMISSION_ERROR = 201, 30 /** @error Invalid input parameter. */ 31 COMMONEVENT_ERR_INVALID_PARAMETER = 401, 32 /** @error IPC request failed to send. */ 33 COMMONEVENT_ERR_FAIL_SEND_REQUEST = 1500007, 34 /** @error Common event service not init. */ 35 COMMONEVENT_ERR_INIT_UNDONE = 1500008, 36 /** @error the subscriber number exceed system specification */ 37 COMMONEVENT_ERR_SUBSCRIBER_NUM_EXCEEDED = 1500010, 38 /** @error A memory allocation error occurs. */ 39 COMMONEVENT_ERR_ALLOC_MEMORY_FAILED = 1500011, 40 } CommonEvent_ErrCode; 41 42 /** 43 * @brief the information of the subscriber 44 * 45 */ 46 typedef struct CommonEvent_SubscribeInfo CommonEvent_SubscribeInfo; 47 48 /** 49 * @brief the subscriber of common event 50 * 51 */ 52 typedef void CommonEvent_Subscriber; 53 54 /** 55 * @brief the data of the commonEvent callback 56 * 57 */ 58 typedef struct CommonEvent_RcvData CommonEvent_RcvData; 59 60 /** 61 * @brief The description of the parameters in a common event callback data. 62 * 63 */ 64 typedef void CommonEvent_Parameters; 65 66 /** 67 * @brief Common event callback. 68 * 69 * @param data common event callback data. 70 */ 71 typedef void (*CommonEvent_ReceiveCallback)(const CommonEvent_RcvData *data); 72 73 74 /** 75 * @brief Create subscribe information. 76 * 77 * @param events Indicates the subscribed events. 78 * @param eventsNum Indicates the subscribed events of number. 79 * @return Returns the CommonEvent_SubscribeInfo, if create failed, returns null. 80 */ 81 CommonEvent_SubscribeInfo* OH_CommonEvent_CreateSubscribeInfo(const char* events[], int32_t eventsNum); 82 83 /** 84 * @brief Set the subscribe information of permission. 85 * 86 * @param info Indicates the subscribed events. 87 * @param permission Indicates the subscribed events of number. 88 * @return Returns the error code. 89 * Returns {@link COMMONEVENT_ERR_OK} if the operation is successful. 90 * Returns {@link COMMONEVENT_ERR_INVALID_PARAMETER} if a parameter error occurs. 91 */ 92 CommonEvent_ErrCode OH_CommonEvent_SetPublisherPermission(CommonEvent_SubscribeInfo* info, const char* permission); 93 94 /** 95 * @brief Set the subscribe information of bundleName. 96 * 97 * @param info Indicates the subscribed events. 98 * @param bundleName Indicates the subscribed events of number. 99 * @return Returns the error code. 100 * Returns {@link COMMONEVENT_ERR_OK} if the operation is successful. 101 * Returns {@link COMMONEVENT_ERR_INVALID_PARAMETER} if a parameter error occurs. 102 */ 103 CommonEvent_ErrCode OH_CommonEvent_SetPublisherBundleName(CommonEvent_SubscribeInfo* info, const char* bundleName); 104 105 /** 106 * @brief Destroy the subscribe information. 107 * 108 * @param info Indicates the subscribe info. 109 */ 110 void OH_CommonEvent_DestroySubscribeInfo(CommonEvent_SubscribeInfo* info); 111 112 /** 113 * @brief Create a subscriber. 114 * 115 * @param info Indicates the created subscribe Info. 116 * @param callback Indicates the received common event callback. 117 * @return Returns the CommonEvent_Subscriber, if create failed, returns null. 118 */ 119 CommonEvent_Subscriber* OH_CommonEvent_CreateSubscriber(const CommonEvent_SubscribeInfo* info, 120 CommonEvent_ReceiveCallback callback); 121 122 /** 123 * @brief Destory the subscriber. 124 * 125 * @param subscriber Indicates the created subscriber. 126 */ 127 void OH_CommonEvent_DestroySubscriber(CommonEvent_Subscriber* subscriber); 128 129 /** 130 * @brief Subscribe event by a subscriber. 131 * 132 * @param subscriber Indicates the subscriber. 133 * @return Returns the error code. 134 * Returns {@link COMMONEVENT_ERR_OK} if the operation is successful. 135 * Returns {@link COMMONEVENT_ERR_INVALID_PARAMETER } if the input parameter is invalid. 136 * Returns {@link COMMONEVENT_ERR_FAIL_SEND_REQUEST } if IPC request failed to send. 137 * Returns {@link COMMONEVENT_ERR_INIT_UNDONE } if ces not init done. 138 * Returns {@link COMMONEVENT_ERR_SUBSCRIBER_NUM_EXCEEDED } if the subscriber number is exceeded. 139 * Returns {@link COMMONEVENT_ERR_ALLOC_MEMORY_FAILED } if a memory allocation error occurs. 140 * @since 12 141 */ 142 CommonEvent_ErrCode OH_CommonEvent_Subscribe(const CommonEvent_Subscriber* subscriber); 143 144 /** 145 * @brief Unsubscribe event by a subscriber. 146 * 147 * @param subscriber Indicates the subscriber. 148 * @return Returns the error code. 149 * Returns {@link COMMONEVENT_ERR_OK} if the operation is successful. 150 * Returns {@link COMMONEVENT_ERR_INVALID_PARAMETER } if the input parameter is invalid. 151 * Returns {@link COMMONEVENT_ERR_FAIL_SEND_REQUEST } if IPC request failed to send. 152 * Returns {@link COMMONEVENT_ERR_INIT_UNDONE } if ces not init done. 153 * @since 12 154 */ 155 CommonEvent_ErrCode OH_CommonEvent_UnSubscribe(const CommonEvent_Subscriber* subscriber); 156 157 /** 158 * @brief Get event name from callback data. 159 * 160 * @param rcvData Indicates the event of callback data. 161 * @return Returns the event name. 162 */ 163 const char* OH_CommonEvent_GetEventFromRcvData(const CommonEvent_RcvData* rcvData); 164 165 /** 166 * @brief Get event result code from callback data. 167 * 168 * @param rcvData Indicates the event of callback data. 169 * @return Returns the event of result code, default is 0. 170 */ 171 int32_t OH_CommonEvent_GetCodeFromRcvData(const CommonEvent_RcvData* rcvData); 172 173 /** 174 * @brief Get event result data from callback data. 175 * 176 * @param rcvData Indicates the event of callback data. 177 * @return Returns the event of result data, default is null. 178 */ 179 const char* OH_CommonEvent_GetDataStrFromRcvData(const CommonEvent_RcvData* rcvData); 180 181 /** 182 * @brief Get event bundlename from callback data. 183 * 184 * @param rcvData Indicates the event of callback data. 185 * @return Returns the event of bundlename, default is null. 186 */ 187 const char* OH_CommonEvent_GetBundleNameFromRcvData(const CommonEvent_RcvData* rcvData); 188 189 /** 190 * @brief Get event parameters data from callback data. 191 * 192 * @param rcvData Indicates the event of callback data. 193 * @return Returns the event of parameters data, default is null. 194 */ 195 const CommonEvent_Parameters* OH_CommonEvent_GetParametersFromRcvData(const CommonEvent_RcvData* rcvData); 196 197 /** 198 * @brief Check whether the parameters contains a key. 199 * 200 * @param rcvData Indicates the event of callback data. 201 * @param key Indicates the key of parameter. 202 * @return Returns the result of check, true means it contains. 203 */ 204 bool OH_CommonEvent_HasKeyInParameters(const CommonEvent_Parameters* para, const char* key); 205 206 /** 207 * @brief Get int data from parameters data by key. 208 * 209 * @param rcvData Indicates the event of parameters data. 210 * @param key Indicates the key of parameters data. 211 * @param defaultValue Indicates default return value. 212 * @return Returns the int data of the key in the parameters. 213 */ 214 int OH_CommonEvent_GetIntFromParameters(const CommonEvent_Parameters* para, const char* key, const int defaultValue); 215 216 /** 217 * @brief Get int array data from parameters data by key. 218 * 219 * @param rcvData Indicates the event of parameters data. 220 * @param key Indicates the key of parameters data. 221 * @param array Indicates the int array. 222 * @return Returns the length of the array. 223 */ 224 int32_t OH_CommonEvent_GetIntArrayFromParameters(const CommonEvent_Parameters* para, const char* key, int** array); 225 226 /** 227 * @brief Get long data from parameters data by key. 228 * 229 * @param rcvData Indicates the event of parameters data. 230 * @param key Indicates the key of parameters data. 231 * @param defaultValue Indicates default return value. 232 * @return Returns the long data of the key in the parameters. 233 */ 234 long OH_CommonEvent_GetLongFromParameters(const CommonEvent_Parameters* para, const char* key, 235 const long defaultValue); 236 237 /** 238 * @brief Get long array data from parameters data by key. 239 * 240 * @param rcvData Indicates the event of parameters data. 241 * @param key Indicates the key of parameters data. 242 * @param array Indicates the long array. 243 * @return Returns the length of the array. 244 */ 245 int32_t OH_CommonEvent_GetLongArrayFromParameters(const CommonEvent_Parameters* para, const char* key, long** array); 246 247 /** 248 * @brief Get bool data from parameters data by key. 249 * 250 * @param rcvData Indicates the event of parameters data. 251 * @param key Indicates the key of parameters data. 252 * @param defaultValue Indicates default return value. 253 * @return Returns the bool data of the key in the parameters. 254 */ 255 bool OH_CommonEvent_GetBoolFromParameters(const CommonEvent_Parameters* para, const char* key, 256 const bool defaultValue); 257 258 /** 259 * @brief Get bool array data from parameters data by key. 260 * 261 * @param rcvData Indicates the event of parameters data. 262 * @param key Indicates the key of parameters data. 263 * @param array Indicates the bool array. 264 * @return Returns the length of the array. 265 */ 266 int32_t OH_CommonEvent_GetBoolArrayFromParameters(const CommonEvent_Parameters* para, const char* key, bool** array); 267 268 /** 269 * @brief Get char data from parameters data by key. 270 * 271 * @param rcvData Indicates the event of parameters data. 272 * @param key Indicates the key of parameters data. 273 * @param defaultValue Indicates default return value. 274 * @return Returns the char data of the key in the parameters. 275 */ 276 char OH_CommonEvent_GetCharFromParameters(const CommonEvent_Parameters* para, const char* key, 277 const char defaultValue); 278 279 /** 280 * @brief Get char array data from parameters data by key. 281 * 282 * @param rcvData Indicates the event of parameters data. 283 * @param key Indicates the key of parameters data. 284 * @param array Indicates the char array. 285 * @return Returns the length of the array. 286 */ 287 int32_t OH_CommonEvent_GetCharArrayFromParameters(const CommonEvent_Parameters* para, const char* key, char** array); 288 289 /** 290 * @brief Get double data from parameters data by key. 291 * 292 * @param rcvData Indicates the event of parameters data. 293 * @param key Indicates the key of parameters data. 294 * @param defaultValue Indicates default return value. 295 * @return Returns the double data of the key in the parameters. 296 */ 297 double OH_CommonEvent_GetDoubleFromParameters(const CommonEvent_Parameters* para, const char* key, 298 const double defaultValue); 299 300 /** 301 * @brief Get double array data from parameters data by key. 302 * 303 * @param rcvData Indicates the event of parameters data. 304 * @param key Indicates the key of parameters data. 305 * @param array Indicates the double array. 306 * @return Returns the length of the array, default is 0. 307 */ 308 int32_t OH_CommonEvent_GetDoubleArrayFromParameters(const CommonEvent_Parameters* para, const char* key, 309 double** array); 310 311 #ifdef __cplusplus 312 } 313 #endif 314 #endif // OH_COMMONEVENT_SUPPORT_CODE_H