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