1 /* 2 * Copyright (c) 2021 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 HIVIEWDFX_HIAPPEVENT_H 17 #define HIVIEWDFX_HIAPPEVENT_H 18 /** 19 * @addtogroup HiAppEvent 20 * @{ 21 * 22 * @brief Provides application event logging functions. 23 * 24 * Provides the event logging function for applications to log the fault, statistical, security, and user behavior 25 * events reported during running. Based on event information, you will be able to analyze the running status of 26 * applications. 27 * 28 * @syscap SystemCapability.HiviewDFX.HiAppEvent 29 * 30 * @since 8 31 * @version 1.0 32 */ 33 34 /** 35 * @file hiappevent.h 36 * 37 * @brief Defines the application event logging functions of the HiAppEvent module. 38 * 39 * Before performing application event logging, you must construct a ParamList object to store the input 40 * event parameters and specify the event domain, event name, and event type. 41 * 42 * <p>Event domain: a string used to identify the domain of event logging. 43 * <p>Event name: a string used to identify the event name of event logging. 44 * <p>Event type: FAULT, STATISTIC, SECURITY, BEHAVIOR. 45 * <p>ParamList: a linked list used to store event parameters, each of which is comprised of the parameter name and 46 * parameter value. 47 * 48 * Sample code: 49 * 00 Including the header file: 50 * <pre> 51 * #include "hiappevent/hiappevent.h" 52 * </pre> 53 * 01 create a ParamList pointer. 54 * <pre> 55 * ParamList list = OH_HiAppEvent_CreateParamList(); 56 * </pre> 57 * 02 add params to the ParamList. 58 * <pre> 59 * bool boolean = true; 60 * OH_HiAppEvent_AddBoolParam(list, "bool_key", boolean); 61 * int32_t nums[] = {1, 2, 3}; 62 * OH_HiAppEvent_AddInt32ArrayParam(list, "int32_arr_key", nums, sizeof(nums) / sizeof(nums[0])); 63 * </pre> 64 * 03 performing event logging. 65 * <pre> 66 * int res = OH_HiAppEvent_Write("test_domain", "test_event", BEHAVIOR, list); 67 * </pre> 68 * 04 destroy the ParamList pointer. 69 * <pre> 70 * OH_HiAppEvent_DestroyParamList(list); 71 * </pre> 72 * 73 * @since 8 74 * @version 1.0 75 */ 76 77 #include <stdbool.h> 78 #include <stdint.h> 79 80 #include "hiappevent_cfg.h" 81 #include "hiappevent_event.h" 82 #include "hiappevent_param.h" 83 84 #ifdef __cplusplus 85 extern "C" { 86 #endif 87 88 /** 89 * @brief Event types. 90 * 91 * You are advised to select event types based on their respective usage scenarios. 92 * 93 * @since 8 94 * @version 1.0 95 */ 96 enum EventType { 97 /* Fault event type */ 98 FAULT = 1, 99 100 /* Statistic event type */ 101 STATISTIC = 2, 102 103 /* Security event type */ 104 SECURITY = 3, 105 106 /* Behavior event type */ 107 BEHAVIOR = 4 108 }; 109 110 /** 111 * @brief The HiAppEvent_AppEventInfo structure is used to represent event information in an application, including 112 * the event's domain, name, type, and parameters. 113 * 114 * @SystemCapability.HiviewDFX.HiAppEvent 115 * @since 12 116 * @version 1.0 117 */ 118 typedef struct HiAppEvent_AppEventInfo { 119 /* The domain of the event. */ 120 const char* domain; 121 /* The name of the event. */ 122 const char* name; 123 /* The type of the event. */ 124 enum EventType type; 125 /* The json string of the parameter. */ 126 const char* params; 127 } HiAppEvent_AppEventInfo; 128 129 /** 130 * @brief The HiAppEvent_AppEventGroup structure represents a group of events in an application. It contains the name 131 * of the event group, an array of HiAppEvent_AppEventInfo structures representing individual events grouped by the 132 * name, and the length of the event array. 133 * 134 * @syscap SystemCapability.HiviewDFX.HiAppEvent 135 * @since 12 136 * @version 1.0 137 */ 138 typedef struct HiAppEvent_AppEventGroup { 139 /* The name of the event. */ 140 const char* name; 141 /* The event array which is group by the name. */ 142 const struct HiAppEvent_AppEventInfo* appEventInfos; 143 /* The length of appEventInfos array. */ 144 uint32_t infoLen; 145 } HiAppEvent_AppEventGroup; 146 147 /** 148 * @brief Event param list node. 149 * 150 * @since 8 151 * @version 1.0 152 */ 153 typedef struct ParamListNode* ParamList; 154 155 /** 156 * @brief The HiAppEvent_Watcher structure is designed for event monitoring, allowing it to be invoked when the event 157 * occurs. 158 * 159 * @syscap SystemCapability.HiviewDFX.HiAppEvent 160 * @since 12 161 * @version 1.0 162 */ 163 typedef struct HiAppEvent_Watcher HiAppEvent_Watcher; 164 165 /** 166 * @brief The OH_HiAppEvent_OnReceive function acts as the callback function for the HiAppEvent_Watcher. It is called 167 * when an event occurs. 168 * 169 * @SystemCapability.HiviewDFX.HiAppEvent 170 * @param domain The domain of the event. 171 * @param appEventGroups The event group by the domain. 172 * @param groupLen The length of appEventGroups array. 173 * @since 12 174 * @version 1.0 175 */ 176 typedef void (*OH_HiAppEvent_OnReceive)( 177 const char* domain, const struct HiAppEvent_AppEventGroup* appEventGroups, uint32_t groupLen); 178 179 /** 180 * @brief Called when watcher receive the event meet the condition. 181 * 182 * @SystemCapability.HiviewDFX.HiAppEvent 183 * @param row The row of events received by watcher. 184 * @param size The size of events received by watcher. 185 * @since 12 186 * @version 1.0 187 */ 188 typedef void (*OH_HiAppEvent_OnTrigger)(int row, int size); 189 190 /** 191 * @brief Called when watcher take the events. 192 * 193 * @SystemCapability.HiviewDFX.HiAppEvent 194 * @param events The event json string array. 195 * @param eventLen The length of events array. 196 * @since 12 197 * @version 1.0 198 */ 199 typedef void (*OH_HiAppEvent_OnTake)(const char* const *events, uint32_t eventLen); 200 201 /** 202 * @brief Create a pointer to the ParamList. 203 * 204 * @return Pointer to the ParamList. 205 * @since 8 206 * @version 1.0 207 */ 208 ParamList OH_HiAppEvent_CreateParamList(void); 209 210 /** 211 * @brief Destroy a pointer to the ParamList. 212 * 213 * @param list Event param list. 214 * @since 8 215 * @version 1.0 216 */ 217 void OH_HiAppEvent_DestroyParamList(ParamList list); 218 219 /** 220 * @brief Add bool param to the ParamList. 221 * 222 * @param list The ParamList of params to be added. 223 * @param name The name of the param to be added. 224 * @param boolean The bool value of the param to be added. 225 * @return ParamList after the param is added. 226 * @since 8 227 * @version 1.0 228 */ 229 ParamList OH_HiAppEvent_AddBoolParam(ParamList list, const char* name, bool boolean); 230 231 /** 232 * @brief Add bool array param to the ParamList. 233 * 234 * @param list The ParamList of params to be added. 235 * @param name The name of the param to be added. 236 * @param booleans The bool array value of the param to be added. 237 * @param arrSize The array size of the param to be added. 238 * @return ParamList after the param is added. 239 * @since 8 240 * @version 1.0 241 */ 242 ParamList OH_HiAppEvent_AddBoolArrayParam(ParamList list, const char* name, const bool* booleans, int arrSize); 243 244 /** 245 * @brief Add int8_t param to the ParamList. 246 * 247 * @param list The ParamList of params to be added. 248 * @param name The name of the param to be added. 249 * @param num The int8_t value of the param to be added. 250 * @return ParamList after the param is added. 251 * @since 8 252 * @version 1.0 253 */ 254 ParamList OH_HiAppEvent_AddInt8Param(ParamList list, const char* name, int8_t num); 255 256 /** 257 * @brief Add int8_t array param to the ParamList. 258 * 259 * @param list The ParamList of params to be added. 260 * @param name The name of the param to be added. 261 * @param nums The int8_t array value of the param to be added. 262 * @param arrSize The array size of the param to be added. 263 * @return ParamList after the param is added. 264 * @since 8 265 * @version 1.0 266 */ 267 ParamList OH_HiAppEvent_AddInt8ArrayParam(ParamList list, const char* name, const int8_t* nums, int arrSize); 268 269 /** 270 * @brief Add int16_t param to the ParamList. 271 * 272 * @param list The ParamList of params to be added. 273 * @param name The name of the param to be added. 274 * @param num The int16_t value of the param to be added. 275 * @return ParamList after the param is added. 276 * @since 8 277 * @version 1.0 278 */ 279 ParamList OH_HiAppEvent_AddInt16Param(ParamList list, const char* name, int16_t num); 280 281 /** 282 * @brief Add int16_t array param to the ParamList. 283 * 284 * @param list The ParamList of params to be added. 285 * @param name The name of the param to be added. 286 * @param nums The int16_t array value of the param to be added. 287 * @param arrSize The array size of the param to be added. 288 * @return ParamList after the param is added. 289 * @since 8 290 * @version 1.0 291 */ 292 ParamList OH_HiAppEvent_AddInt16ArrayParam(ParamList list, const char* name, const int16_t* nums, int arrSize); 293 294 /** 295 * @brief Add int32_t param to the ParamList. 296 * 297 * @param list The ParamList of params to be added. 298 * @param name The name of the param to be added. 299 * @param num The int32_t value of the param to be added. 300 * @return ParamList after the param is added. 301 * @since 8 302 * @version 1.0 303 */ 304 ParamList OH_HiAppEvent_AddInt32Param(ParamList list, const char* name, int32_t num); 305 306 /** 307 * @brief Add int32_t array param to the ParamList. 308 * 309 * @param list The ParamList of params to be added. 310 * @param name The name of the param to be added. 311 * @param nums The int32_t array value of the param to be added. 312 * @param arrSize The array size of the param to be added. 313 * @return ParamList after the param is added. 314 * @since 8 315 * @version 1.0 316 */ 317 ParamList OH_HiAppEvent_AddInt32ArrayParam(ParamList list, const char* name, const int32_t* nums, int arrSize); 318 319 /** 320 * @brief Add int64_t param to the ParamList. 321 * 322 * @param list The ParamList of params to be added. 323 * @param name The name of the param to be added. 324 * @param num The int64_t value of the param to be added. 325 * @return ParamList after the param is added. 326 * @since 8 327 * @version 1.0 328 */ 329 ParamList OH_HiAppEvent_AddInt64Param(ParamList list, const char* name, int64_t num); 330 331 /** 332 * @brief Add int64_t array param to the ParamList. 333 * 334 * @param list The ParamList of params to be added. 335 * @param name The name of the param to be added. 336 * @param nums The int64_t array value of the param to be added. 337 * @param arrSize The array size of the param to be added. 338 * @return ParamList after the param is added. 339 * @since 8 340 * @version 1.0 341 */ 342 ParamList OH_HiAppEvent_AddInt64ArrayParam(ParamList list, const char* name, const int64_t* nums, int arrSize); 343 344 /** 345 * @brief Add float param to the ParamList. 346 * 347 * @param list The ParamList of params to be added. 348 * @param name The name of the param to be added. 349 * @param num The float value of the param to be added. 350 * @return ParamList after the param is added. 351 * @since 8 352 * @version 1.0 353 */ 354 ParamList OH_HiAppEvent_AddFloatParam(ParamList list, const char* name, float num); 355 356 /** 357 * @brief Add float array param to the ParamList. 358 * 359 * @param list The ParamList of params to be added. 360 * @param name The name of the param to be added. 361 * @param nums The float array value of the param to be added. 362 * @param arrSize The array size of the param to be added. 363 * @return ParamList after the param is added. 364 * @since 8 365 * @version 1.0 366 */ 367 ParamList OH_HiAppEvent_AddFloatArrayParam(ParamList list, const char* name, const float* nums, int arrSize); 368 369 /** 370 * @brief Add double param to the ParamList. 371 * 372 * @param list The ParamList of params to be added. 373 * @param name The name of the param to be added. 374 * @param num The double value of the param to be added. 375 * @return ParamList after the param is added. 376 * @since 8 377 * @version 1.0 378 */ 379 ParamList OH_HiAppEvent_AddDoubleParam(ParamList list, const char* name, double num); 380 381 /** 382 * @brief Add double array param to the ParamList. 383 * 384 * @param list The ParamList of params to be added. 385 * @param name The name of the param to be added. 386 * @param nums The double array value of the param to be added. 387 * @param arrSize The array size of the param to be added. 388 * @return ParamList after the param is added. 389 * @since 8 390 * @version 1.0 391 */ 392 ParamList OH_HiAppEvent_AddDoubleArrayParam(ParamList list, const char* name, const double* nums, int arrSize); 393 394 /** 395 * @brief Add string param to the ParamList. 396 * 397 * @param list The ParamList of params to be added. 398 * @param name The name of the param to be added. 399 * @param str The string value of the param to be added. 400 * @return ParamList after the param is added. 401 * @since 8 402 * @version 1.0 403 */ 404 ParamList OH_HiAppEvent_AddStringParam(ParamList list, const char* name, const char* str); 405 406 /** 407 * @brief Add string array param to the ParamList. 408 * 409 * @param list The ParamList of params to be added. 410 * @param name The name of the param to be added. 411 * @param strs The string array value of the param to be added. 412 * @param arrSize The array size of the param to be added. 413 * @return ParamList after the param is added. 414 * @since 8 415 * @version 1.0 416 */ 417 ParamList OH_HiAppEvent_AddStringArrayParam(ParamList list, const char* name, const char * const *strs, int arrSize); 418 419 /** 420 * @brief Implements logging of application events whose parameters are of the list type. 421 * 422 * Before logging an application event, this API will first verify parameters of this event. 423 * If the verification is successful, the API will write the event to the event file. 424 * 425 * @param domain Indicates the event domain. You can customize the event domain as needed. 426 * @param name Indicates the event name. You can customize the event name as needed. 427 * @param type Indicates the event type, which is defined in {@link EventType}. 428 * @param list Indicates a linked list of event parameters, each of which is comprised of the parameter name and 429 * parameter value. 430 * @return Returns {@code 0} if the event parameter verification is successful, and the event will be written to 431 * the event file; returns a positive integer if invalid parameters are present in the event, and 432 * the event will be written to the event file after the invalid parameters are ignored; returns a 433 * negative integer if the event parameter verification fails, and the event will not be written to the event file. 434 * @since 8 435 * @version 1.0 436 */ 437 int OH_HiAppEvent_Write(const char* domain, const char* name, enum EventType type, const ParamList list); 438 439 /** 440 * @brief Implements the configuration function of application events logging. 441 * 442 * Application event logging configuration interface, which is used to configure event logging switch, 443 * event file directory storage quota size and other functions. 444 * 445 * @param name Configuration item name. 446 * @param value Configuration item value. 447 * @return Configuration result. 448 * @since 8 449 * @version 1.0 450 */ 451 bool OH_HiAppEvent_Configure(const char* name, const char* value); 452 453 /** 454 * @brief Create a HiAppEvent_Watcher handler pointer to set the property. 455 * 456 * @SystemCapability.HiviewDFX.HiAppEvent 457 * @param name The name of the watcher. 458 * @return Returns a pointer to the HiAppEvent_Watcher instance. 459 * @since 12 460 * @version 1.0 461 */ 462 HiAppEvent_Watcher* OH_HiAppEvent_CreateWatcher(const char* name); 463 464 /** 465 * @brief Destroy the specified HiAppEvent_Watcher handle resource. 466 * 467 * @SystemCapability.HiviewDFX.HiAppEvent 468 * @param watcher The pointer to the HiAppEvent_Watcher instance. 469 * @since 12 470 * @version 1.0 471 */ 472 void OH_HiAppEvent_DestroyWatcher(HiAppEvent_Watcher* watcher); 473 474 /** 475 * @brief The interface to set trigger conditions for the watcher. Three trigger conditions can be set through this 476 * interface and any of the condition which is set over than 0 met, the onTrigger callback set through 477 * OH_HiAppEvent_SetWatcherOnTrigger will be invoked. 478 * 479 * @SystemCapability.HiviewDFX.HiAppEvent 480 * @param watcher The pointer to the HiAppEvent_Watcher instance. 481 * @param row The row of write events that trigger the onTrigger callback. 482 * @param size The size of write events that trigger the onTrigger callback. 483 * @param timeOut The interval for trigger the onTrigger callback. 484 * @return Returns {@code 0} if set TriggerCondition is successful, and returns a 485 * negative integer if set fail. 486 * @since 12 487 * @version 1.0 488 */ 489 int OH_HiAppEvent_SetTriggerCondition(HiAppEvent_Watcher* watcher, int row, int size, int timeOut); 490 491 /** 492 * @brief The interface to set the AppEventFilter which defines the kind of app events will be received by the watcher. 493 * 494 * @SystemCapability.HiviewDFX.HiAppEvent 495 * @param watcher The pointer to the HiAppEvent_Watcher instance. 496 * @param domain The name of the event domain to be monitored by the watcher. 497 * @param eventTypes The types of the events to be monitored by the watcher.0x08 means BEHAVIOR,0x04 means 498 * SECURITY, 0x02 means STATISTIC,0x01 means FAULT, 0xff and 0x00 means all. 499 * @param names The names of the events to be monitored by the watcher. 500 * @param namesLen The length of names array. 501 * @return Returns {@code 0} if set AppEventFilter is successful, and returns a 502 * negative integer if set fail. 503 * @since 12 504 * @version 1.0 505 */ 506 int OH_HiAppEvent_SetAppEventFilter(HiAppEvent_Watcher* watcher, const char* domain, uint8_t eventTypes, 507 const char* const *names, int namesLen); 508 509 /** 510 * @brief The interface to set onTrigger callback for watcher. If the OnReceive callback is not be set or has been set 511 * to nullptr, the app events received by the watcher will be saved. When the new saved appEvents met the conditions set 512 * by OH_HiAppEvent_SetTriggerCondition, the onTrigger callback will be invoked. 513 * 514 * @SystemCapability.HiviewDFX.HiAppEvent 515 * @param watcher The pointer to the HiAppEvent_Watcher instance. 516 * @param onTrigger The callback of the watcher. 517 * @return Returns {@code 0} if set OnTrigger is successful, and returns a 518 * negative integer if set fail. 519 * @since 12 520 * @version 1.0 521 */ 522 int OH_HiAppEvent_SetWatcherOnTrigger(HiAppEvent_Watcher* watcher, OH_HiAppEvent_OnTrigger onTrigger); 523 524 /** 525 * @brief The interface to set onReceive callback for watcher. When the watcher received an app event, the onReceive 526 * callback set will be invoked. 527 * 528 * @SystemCapability.HiviewDFX.HiAppEvent 529 * @param watcher The pointer to the HiAppEvent_Watcher instance. 530 * @param onReceive The callback of the watcher. 531 * @return Returns {@code 0} if set OnReceive is successful, and returns a 532 * negative integer if set fail. 533 * @since 12 534 * @version 1.0 535 */ 536 int OH_HiAppEvent_SetWatcherOnReceive(HiAppEvent_Watcher* watcher, OH_HiAppEvent_OnReceive onReceive); 537 538 /** 539 * @brief The interface to take saved events data for the watcher. 540 * 541 * @SystemCapability.HiviewDFX.HiAppEvent 542 * @param watcher The pointer to the HiAppEvent_Watcher instance. 543 * @param eventNum The num of events to take. 544 * @param onTake The callback of the watcher. 545 * @return Returns {@code 0} if remove watcher is successful, and returns a 546 * negative integer if remove fail. 547 * @since 12 548 * @version 1.0 549 */ 550 int OH_HiAppEvent_TakeWatcherData(HiAppEvent_Watcher* watcher, uint32_t eventNum, OH_HiAppEvent_OnTake onTake); 551 552 /** 553 * @brief The interface to add the watcher. The watcher will start receiving app events after it is added. 554 * 555 * @SystemCapability.HiviewDFX.HiAppEvent 556 * @param watcher The pointer to the HiAppEvent_Watcher instance which receive the event. 557 * @return Returns {@code 0} if add watcher is successful, and returns a 558 * negative integer if add fail. 559 * @since 12 560 * @version 1.0 561 */ 562 int OH_HiAppEvent_AddWatcher(HiAppEvent_Watcher* watcher); 563 564 /** 565 * @brief The interface to remove the watcher. The watcher will stop receiving app events after it is removed. 566 * 567 * @SystemCapability.HiviewDFX.HiAppEvent 568 * @param watcher The pointer to the HiAppEvent_Watcher instance. 569 * @return Returns {@code 0} if remove watcher is successful, and returns a 570 * negative integer if remove fail. 571 * @since 12 572 * @version 1.0 573 */ 574 int OH_HiAppEvent_RemoveWatcher(HiAppEvent_Watcher* watcher); 575 576 /** 577 * @brief Clear all local saved event data of the application. 578 * 579 * @SystemCapability.HiviewDFX.HiAppEvent 580 * @since 12 581 * @version 1.0 582 */ 583 void OH_HiAppEvent_ClearData(); 584 585 /** 586 * @brief The HiAppEvent_Processor structure is designed to process events, allowing it to be invoked when the event 587 * occurs. 588 * 589 * @syscap SystemCapability.HiviewDFX.HiAppEvent 590 * @since 12 591 * @version 1.0 592 */ 593 typedef struct HiAppEvent_Processor HiAppEvent_Processor; 594 #ifdef __cplusplus 595 } 596 #endif 597 /** @} */ 598 #endif // HIVIEWDFX_HIAPPEVENT_H