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