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 /** 17 * @addtogroup OH_CommonEvent 18 * @{ 19 * 20 * @brief Provides the APIs of common event service. 21 * 22 * @since 12 23 */ 24 /** 25 * @file oh_commonevent.h 26 * 27 * @brief Declares the APIs to subscribe and unsubscribe common event, and so on. 28 * 29 * @library libohcommonevent.so 30 * @kit BasicServicesKit 31 * @syscap SystemCapability.Notification.CommonEvent 32 * @since 12 33 * @version 1.0 34 */ 35 36 #ifndef OH_COMMONEVENT_H 37 #define OH_COMMONEVENT_H 38 39 #include <stdint.h> 40 41 #ifdef __cplusplus 42 extern "C" { 43 #endif 44 45 /** 46 * @brief Defines error codes. 47 * 48 * @since 12 49 * @version 1.0 50 */ 51 typedef enum CommonEvent_ErrCode { 52 /** @error Execution successful. */ 53 COMMONEVENT_ERR_OK = 0, 54 55 /** @error permission verification failed. */ 56 COMMONEVENT_ERR_PERMISSION_ERROR = 201, 57 58 /** @error invalid input parameter. */ 59 COMMONEVENT_ERR_INVALID_PARAMETER = 401, 60 61 /** @error IPC request failed to send. */ 62 COMMONEVENT_ERR_SENDING_REQUEST_FAILED = 1500007, 63 64 /** @error Common event service not init. */ 65 COMMONEVENT_ERR_INIT_UNDONE = 1500008, 66 67 /** @error The subscriber number exceed system specification */ 68 COMMONEVENT_ERR_SUBSCRIBER_NUM_EXCEEDED = 1500010, 69 70 /** @error A memory allocation error occurs. */ 71 COMMONEVENT_ERR_ALLOC_MEMORY_FAILED = 1500011, 72 } CommonEvent_ErrCode; 73 74 /** 75 * @brief the information of the subscriber 76 * 77 * @since 12 78 */ 79 typedef struct CommonEvent_SubscribeInfo CommonEvent_SubscribeInfo; 80 81 /** 82 * @brief the subscriber of common event 83 * 84 * @since 12 85 */ 86 typedef void CommonEvent_Subscriber; 87 88 /** 89 * @brief the data of the commonEvent callback 90 * 91 * @since 12 92 */ 93 typedef struct CommonEvent_RcvData CommonEvent_RcvData; 94 95 /** 96 * @brief The description of the parameters in a common event callback data. 97 * 98 * @since 12 99 */ 100 typedef void CommonEvent_Parameters; 101 102 /** 103 * @brief Common event callback. 104 * 105 * @param data common event callback data. 106 * @since 12 107 */ 108 typedef void (*CommonEvent_ReceiveCallback)(const CommonEvent_RcvData *data); 109 110 /** 111 * @brief Create subscribe information. 112 * 113 * @param events Indicates the subscribed events. 114 * @param eventsNum Indicates the subscribed events of number. 115 * @return Returns the CommonEvent_SubscribeInfo, if allocate memory failed, returns null. 116 * @since 12 117 */ 118 CommonEvent_SubscribeInfo* OH_CommonEvent_CreateSubscribeInfo(const char* events[], int32_t eventsNum); 119 120 /** 121 * @brief Set the subscribe information of permission. 122 * 123 * @param info Indicates the subscribed events. 124 * @param permission Indicates the subscribed events of permission. 125 * @return Returns the error code. 126 * Returns {@link COMMONEVENT_ERR_OK} if the operation is successful. 127 * Returns {@link COMMONEVENT_ERR_INVALID_PARAMETER} if a parameter error occurs. 128 * @since 12 129 */ 130 CommonEvent_ErrCode OH_CommonEvent_SetPublisherPermission(CommonEvent_SubscribeInfo* info, const char* permission); 131 132 /** 133 * @brief Set the subscribe information of bundleName. 134 * 135 * @param info Indicates the subscribed events. 136 * @param bundleName Indicates the subscribed events of bundleName. 137 * @return Returns the error code. 138 * Returns {@link COMMONEVENT_ERR_OK} if the operation is successful. 139 * Returns {@link COMMONEVENT_ERR_INVALID_PARAMETER} if a parameter error occurs. 140 * @since 12 141 */ 142 CommonEvent_ErrCode OH_CommonEvent_SetPublisherBundleName(CommonEvent_SubscribeInfo* info, const char* bundleName); 143 144 /** 145 * @brief Destroy the subscribe information. 146 * 147 * @param info Indicates the subscribe info. 148 * @since 12 149 */ 150 void OH_CommonEvent_DestroySubscribeInfo(CommonEvent_SubscribeInfo* info); 151 152 /** 153 * @brief Create a subscriber. 154 * 155 * @param info Indicates the created subscribe Info. 156 * @param callback Indicates the received common event callback. 157 * @return Returns the CommonEvent_Subscriber, if allocate memory failed, returns null. 158 * @since 12 159 */ 160 CommonEvent_Subscriber* OH_CommonEvent_CreateSubscriber(const CommonEvent_SubscribeInfo* info, 161 CommonEvent_ReceiveCallback callback); 162 163 /** 164 * @brief Destory the subscriber. 165 * 166 * @param subscriber Indicates the created subscriber. 167 * @since 12 168 */ 169 void OH_CommonEvent_DestroySubscriber(CommonEvent_Subscriber* subscriber); 170 171 /** 172 * @brief Subscribe event by a subscriber. 173 * 174 * @param subscriber Indicates the subscriber. 175 * @return Returns the error code. 176 * Returns {@link COMMONEVENT_ERR_OK} if the operation is successful. 177 * Returns {@link COMMONEVENT_ERR_INVALID_PARAMETER } if the input parameter is invalid. 178 * Returns {@link COMMONEVENT_ERR_SENDING_REQUEST_FAILED } if IPC request failed to send. 179 * Returns {@link COMMONEVENT_ERR_INIT_UNDONE } if ces not init done. 180 * Returns {@link COMMONEVENT_ERR_SUBSCRIBER_NUM_EXCEEDED } if the subscriber number is exceeded. 181 * Returns {@link COMMONEVENT_ERR_ALLOC_MEMORY_FAILED } if a memory allocation error occurs. 182 * @since 12 183 */ 184 CommonEvent_ErrCode OH_CommonEvent_Subscribe(const CommonEvent_Subscriber* subscriber); 185 186 /** 187 * @brief Unsubscribe event by a subscriber. 188 * 189 * @param subscriber Indicates the subscriber. 190 * @return Returns the error code. 191 * Returns {@link COMMONEVENT_ERR_OK} if the operation is successful. 192 * Returns {@link COMMONEVENT_ERR_INVALID_PARAMETER } if the input parameter is invalid. 193 * Returns {@link COMMONEVENT_ERR_SENDING_REQUEST_FAILED } if IPC request failed to send. 194 * Returns {@link COMMONEVENT_ERR_INIT_UNDONE } if ces not init done. 195 * @since 12 196 */ 197 CommonEvent_ErrCode OH_CommonEvent_UnSubscribe(const CommonEvent_Subscriber* subscriber); 198 199 /** 200 * @brief Get event name from callback data. 201 * 202 * @param rcvData Indicates the event of callback data. 203 * @return Returns the event name. 204 * @since 12 205 */ 206 const char* OH_CommonEvent_GetEventFromRcvData(const CommonEvent_RcvData* rcvData); 207 208 /** 209 * @brief Get event result code from callback data. 210 * 211 * @param rcvData Indicates the event of callback data. 212 * @return Returns the event of result code, default is 0. 213 * @since 12 214 */ 215 int32_t OH_CommonEvent_GetCodeFromRcvData(const CommonEvent_RcvData* rcvData); 216 217 /** 218 * @brief Get event result data from callback data. 219 * 220 * @param rcvData Indicates the event of callback data. 221 * @return Returns the event of result data, default is null. 222 * @since 12 223 */ 224 const char* OH_CommonEvent_GetDataStrFromRcvData(const CommonEvent_RcvData* rcvData); 225 226 /** 227 * @brief Get event bundlename from callback data. 228 * 229 * @param rcvData Indicates the event of callback data. 230 * @return Returns the event of bundlename, default is null. 231 * @since 12 232 */ 233 const char* OH_CommonEvent_GetBundleNameFromRcvData(const CommonEvent_RcvData* rcvData); 234 235 /** 236 * @brief Get event parameters data from callback data. 237 * 238 * @param rcvData Indicates the event of callback data. 239 * @return Returns the event of parameters data, default is null. 240 * @since 12 241 */ 242 const CommonEvent_Parameters* OH_CommonEvent_GetParametersFromRcvData(const CommonEvent_RcvData* rcvData); 243 244 /** 245 * @brief Check whether the parameters contains a key. 246 * 247 * @param para Indicates the event of callback data. 248 * @param key Indicates the key of parameter. 249 * @return Returns the result of check, true means it contains. 250 * @since 12 251 */ 252 bool OH_CommonEvent_HasKeyInParameters(const CommonEvent_Parameters* para, const char* key); 253 254 /** 255 * @brief Get int data from parameters data by key. 256 * 257 * @param para Indicates the event of parameters data. 258 * @param key Indicates the key of parameters data. 259 * @param defaultValue Indicates default return value. 260 * @return Returns the int data of the key in the parameters. 261 * @since 12 262 */ 263 int OH_CommonEvent_GetIntFromParameters(const CommonEvent_Parameters* para, const char* key, const int defaultValue); 264 265 /** 266 * @brief Get int array data from parameters data by key. 267 * 268 * @param para Indicates the event of parameters data. 269 * @param key Indicates the key of parameters data. 270 * @param array Indicates the int array. 271 * @return Returns the length of the array. 272 * @since 12 273 */ 274 int32_t OH_CommonEvent_GetIntArrayFromParameters(const CommonEvent_Parameters* para, const char* key, int** array); 275 276 /** 277 * @brief Get long data from parameters data by key. 278 * 279 * @param para Indicates the event of parameters data. 280 * @param key Indicates the key of parameters data. 281 * @param defaultValue Indicates default return value. 282 * @return Returns the long data of the key in the parameters. 283 * @since 12 284 */ 285 long OH_CommonEvent_GetLongFromParameters(const CommonEvent_Parameters* para, const char* key, const long defaultValue); 286 287 /** 288 * @brief Get long array data from parameters data by key. 289 * 290 * @param para Indicates the event of parameters data. 291 * @param key Indicates the key of parameters data. 292 * @param array Indicates the long array. 293 * @return Returns the length of the array. 294 * @since 12 295 */ 296 int32_t OH_CommonEvent_GetLongArrayFromParameters(const CommonEvent_Parameters* para, const char* key, long** array); 297 298 /** 299 * @brief Get bool data from parameters data by key. 300 * 301 * @param para Indicates the event of parameters data. 302 * @param key Indicates the key of parameters data. 303 * @param defaultValue Indicates default return value. 304 * @return Returns the bool data of the key in the parameters. 305 * @since 12 306 */ 307 bool OH_CommonEvent_GetBoolFromParameters(const CommonEvent_Parameters* para, const char* key, const bool defaultValue); 308 309 /** 310 * @brief Get bool array data from parameters data by key. 311 * 312 * @param para Indicates the event of parameters data. 313 * @param key Indicates the key of parameters data. 314 * @param array Indicates the bool array. 315 * @return Returns the length of the array. 316 * @since 12 317 */ 318 int32_t OH_CommonEvent_GetBoolArrayFromParameters(const CommonEvent_Parameters* para, const char* key, bool** array); 319 320 /** 321 * @brief Get char data from parameters data by key. 322 * 323 * @param para Indicates the event of parameters data. 324 * @param key Indicates the key of parameters data. 325 * @param defaultValue Indicates default return value. 326 * @return Returns the char data of the key in the parameters. 327 * @since 12 328 */ 329 char OH_CommonEvent_GetCharFromParameters(const CommonEvent_Parameters* para, const char* key, const char defaultValue); 330 331 /** 332 * @brief Get char array data from parameters data by key. 333 * 334 * @param para Indicates the event of parameters data. 335 * @param key Indicates the key of parameters data. 336 * @param array Indicates the char array. 337 * @return Returns the length of the array. 338 * @since 12 339 */ 340 int32_t OH_CommonEvent_GetCharArrayFromParameters(const CommonEvent_Parameters* para, const char* key, char** array); 341 342 /** 343 * @brief Get double data from parameters data by key. 344 * 345 * @param para Indicates the event of parameters data. 346 * @param key Indicates the key of parameters data. 347 * @param defaultValue Indicates default return value. 348 * @return Returns the double data of the key in the parameters. 349 * @since 12 350 */ 351 double OH_CommonEvent_GetDoubleFromParameters(const CommonEvent_Parameters* para, const char* key, 352 const double defaultValue); 353 354 /** 355 * @brief Get double array data from parameters data by key. 356 * 357 * @param para Indicates the event of parameters data. 358 * @param key Indicates the key of parameters data. 359 * @param array Indicates the double array. 360 * @return Returns the length of the array, default is 0. 361 * @since 12 362 */ 363 int32_t OH_CommonEvent_GetDoubleArrayFromParameters(const CommonEvent_Parameters* para, const char* key, 364 double** array); 365 366 #ifdef __cplusplus 367 } 368 #endif 369 #endif // OH_COMMONEVENT_H 370 /** @} */ 371