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