1# HiAppEvent 2 3 4## Overview 5 6Provides APIs for implementing the application event logging function. 7 8This function allows your application to record fault events, statistics events, security events, and user behavior events reported during system running. Based on the event information, you can analyze the operating status of your application. 9 10**System capability**: SystemCapability.HiviewDFX.HiAppEvent 11 12**Since**: 8 13 14 15## Summary 16 17 18### File 19 20| Name| Description| 21| -------- | -------- | 22| [hiappevent.h](hiappevent_8h.md) | Defines the application event logging functions of the HiAppEvent module.<br>**File to include**: <hiappevent/hiappevent.h><br>**Library**: libhiappevent_ndk.z.so| 23| [hiappevent_cfg.h](hiappevent__cfg_8h.md) | Defines the configuration items of the event logging configuration function.<br>**File to include**: <hiappevent/hiappevent_event.h><br>**Library**: libhiappevent_ndk.z.so| 24| [hiappevent_event.h](hiappevent__event_8h.md) | Defines the names of all predefined events.<br>**File to include**: <hiappevent/hiappevent_param.h><br>**Library**: libhiappevent_ndk.z.so| 25| [hiappevent_param.h](hiappevent__param_8h.md) | Defines the names of all predefined event parameters.<br>**File to include**: <hiappevent/hiappevent_cfg.h><br>**Library**: libhiappevent_ndk.z.so| 26 27 28### Structs 29 30| Name| Description| 31| -------- | -------- | 32| struct [HiAppEvent_AppEventInfo](_hi_app_event___app_event_info.md) | Defines information about a single event, including the event domain, event name, event type, and custom parameter list in JSON string format. | 33| struct [HiAppEvent_AppEventGroup](_hi_app_event___app_event_group.md) | Event array with the same event name. | 34 35 36### Macros 37 38| Name| Description| 39| -------- | -------- | 40| [DISABLE](#disable) "disable" | Whether to disable event logging. The default value is **false**. The value **true** means to disable the event logging function, and the value **false** means the opposite. | 41| [MAX_STORAGE](#max_storage) "max_storage" | Storage quota of the event file directory. The default value is **10M**. | 42| [EVENT_USER_LOGIN](#event_user_login) "hiappevent.user_login" | User login event. | 43| [EVENT_USER_LOGOUT](#event_user_logout) "hiappevent.user_logout" | User logout event. | 44| [EVENT_DISTRIBUTED_SERVICE_START](#event_distributed_service_start) "hiappevent.distributed_service_start" | Distributed service event. | 45| [EVENT_APP_CRASH](#event_app_crash) "APP_CRASH" | Application crash event. | 46| [EVENT_APP_FREEZE](#event_app_freeze) "APP_FREEZE" | Application freeze event. | 47| [EVENT_APP_LAUNCH](#event_app_launch) "APP_LAUNCH" | Application loading event. | 48| [EVENT_SCROLL_JANK](#event_scroll_jank) "SCROLL_JANK" | Event indicating application freeze during swiping. | 49| [EVENT_CPU_USAGE_HIGH](#event_cpu_usage_high) "CPU_USAGE_HIGH" | Event indicating high CPU usage of an application. | 50| [EVENT_BATTERY_USAGE](#event_battery_usage) "BATTERY_USAGE" | Application power usage event. | 51| [EVENT_RESOURCE_OVERLIMIT](#event_resource_overlimit) "RESOURCE_OVERLIMIT" | Application resource threshold-crossing event. | 52| [DOMAIN_OS](#domain_os) "OS" | OS scope. | 53| [PARAM_USER_ID](#param_user_id) "user_id" | User ID. | 54| [PARAM_DISTRIBUTED_SERVICE_NAME](#param_distributed_service_name) "ds_name" | Distributed service name. | 55| [PARAM_DISTRIBUTED_SERVICE_INSTANCE_ID](#param_distributed_service_instance_id) "ds_instance_id" | Distributed service instance ID. | 56 57 58### Types 59 60| Name| Description| 61| -------- | -------- | 62| typedef struct [HiAppEvent_AppEventInfo](_hi_app_event___app_event_info.md) [HiAppEvent_AppEventInfo](#hiappevent_appeventinfo) | Information about a single event, including the event domain, event name, event type, and custom parameter list in JSON string format. | 63| typedef struct [HiAppEvent_AppEventGroup](_hi_app_event___app_event_group.md) [HiAppEvent_AppEventGroup](#hiappevent_appeventgroup) | Event array with the same event name. | 64| typedef struct ParamListNode \* [ParamList](#paramlist) | Event parameter list node. | 65| typedef struct [HiAppEvent_Watcher](#hiappevent_watcher) [HiAppEvent_Watcher](#hiappevent_watcher) | Watcher for application events. | 66| typedef void(\* [OH_HiAppEvent_OnReceive](#oh_hiappevent_onreceive)) (const char \*domain, const struct [HiAppEvent_AppEventGroup](_hi_app_event___app_event_group.md) \*appEventGroups, uint32_t groupLen) | Callback invoked to pass event content to the caller. | 67| typedef void(\* [OH_HiAppEvent_OnTrigger](#oh_hiappevent_ontrigger)) (int row, int size) | Callback invoked if the event received by the watcher meets the conditions specified by **OH_HiAppEvent_SetTriggerCondition**. Specifically, if the **OH_HiAppEvent_OnReceive** callback is not set in the watcher, the event received by the watcher will be saved. If the saved event meets the conditions specified by OH_HiAppEvent_SetTriggerCondition, the callback is invoked. After the callback is complete, if a newly saved event meets the specified condition, the callback is invoked again. | 68| typedef void(\* [OH_HiAppEvent_OnTake](#oh_hiappevent_ontake)) (const char \*const \*events, uint32_t eventLen) | Callback invoked to pass the events received by the watcher to the caller when OH_HiAppEvent_TakeWatcherData is used to obtain the events. | 69 70 71### Enums 72 73| Name| Description| 74| -------- | -------- | 75| [EventType](#eventtype) { **FAULT** = 1, **STATISTIC** = 2, **SECURITY** = 3, **BEHAVIOR** = 4 } | Event type. | 76 77 78### Functions 79 80| Name| Description| 81| -------- | -------- | 82| [ParamList](#paramlist) [OH_HiAppEvent_CreateParamList](#oh_hiappevent_createparamlist) (void) | Creates a pointer to a parameter list object. | 83| void [OH_HiAppEvent_DestroyParamList](#oh_hiappevent_destroyparamlist) ([ParamList](#paramlist) list) | Destroys a pointer to a parameter list object and releases its allocated memory. | 84| [ParamList](#paramlist) [OH_HiAppEvent_AddBoolParam](#oh_hiappevent_addboolparam) ([ParamList](#paramlist) list, const char \*name, bool boolean) | Adds an event parameter of the Boolean type to the parameter list. | 85| [ParamList](#paramlist) [OH_HiAppEvent_AddBoolArrayParam](#oh_hiappevent_addboolarrayparam) ([ParamList](#paramlist) list, const char \*name, const bool \*booleans, int arrSize) | Adds an event parameter of the Boolean array type to the parameter list. | 86| [ParamList](#paramlist) [OH_HiAppEvent_AddInt8Param](#oh_hiappevent_addint8param) ([ParamList](#paramlist) list, const char \*name, int8_t num) | Adds an event parameter of the int8_t type to the parameter list. | 87| [ParamList](#paramlist) [OH_HiAppEvent_AddInt8ArrayParam](#oh_hiappevent_addint8arrayparam) ([ParamList](#paramlist) list, const char \*name, const int8_t \*nums, int arrSize) | Adds an event parameter of the int8_t array type to the parameter list. | 88| [ParamList](#paramlist) [OH_HiAppEvent_AddInt16Param](#oh_hiappevent_addint16param) ([ParamList](#paramlist) list, const char \*name, int16_t num) | Adds an event parameter of the int16_t type to the parameter list. | 89| [ParamList](#paramlist) [OH_HiAppEvent_AddInt16ArrayParam](#oh_hiappevent_addint16arrayparam) ([ParamList](#paramlist) list, const char \*name, const int16_t \*nums, int arrSize) | Adds an event parameter of the int16_t array type to the parameter list. | 90| [ParamList](#paramlist) [OH_HiAppEvent_AddInt32Param](#oh_hiappevent_addint32param) ([ParamList](#paramlist) list, const char \*name, int32_t num) | Adds an event parameter of the int32_t type to the parameter list. | 91| [ParamList](#paramlist) [OH_HiAppEvent_AddInt32ArrayParam](#oh_hiappevent_addint32arrayparam) ([ParamList](#paramlist) list, const char \*name, const int32_t \*nums, int arrSize) | Adds an event parameter of the int32_t array type to the parameter list. | 92| [ParamList](#paramlist) [OH_HiAppEvent_AddInt64Param](#oh_hiappevent_addint64param) ([ParamList](#paramlist) list, const char \*name, int64_t num) | Adds an event parameter of the int64_t type to the parameter list. | 93| [ParamList](#paramlist) [OH_HiAppEvent_AddInt64ArrayParam](#oh_hiappevent_addint64arrayparam) ([ParamList](#paramlist) list, const char \*name, const int64_t \*nums, int arrSize) | Adds an event parameter of the int64_t array type to the parameter list. | 94| [ParamList](#paramlist) [OH_HiAppEvent_AddFloatParam](#oh_hiappevent_addfloatparam) ([ParamList](#paramlist) list, const char \*name, float num) | Adds an event parameter of the float type to the parameter list. | 95| [ParamList](#paramlist) [OH_HiAppEvent_AddFloatArrayParam](#oh_hiappevent_addfloatarrayparam) ([ParamList](#paramlist) list, const char \*name, const float \*nums, int arrSize) | Adds an event parameter of the float array type to the parameter list. | 96| [ParamList](#paramlist) [OH_HiAppEvent_AddDoubleParam](#oh_hiappevent_adddoubleparam) ([ParamList](#paramlist) list, const char \*name, double num) | Adds an event parameter of the Double type to the parameter list. | 97| [ParamList](#paramlist) [OH_HiAppEvent_AddDoubleArrayParam](#oh_hiappevent_adddoublearrayparam) ([ParamList](#paramlist) list, const char \*name, const double \*nums, int arrSize) | Adds an event parameter of the double array type to the parameter list. | 98| [ParamList](#paramlist) [OH_HiAppEvent_AddStringParam](#oh_hiappevent_addstringparam) ([ParamList](#paramlist) list, const char \*name, const char \*str) | Adds a parameter of the string type to the parameter list. | 99| [ParamList](#paramlist) [OH_HiAppEvent_AddStringArrayParam](#oh_hiappevent_addstringarrayparam) ([ParamList](#paramlist) list, const char \*name, const char \*const \*strs, int arrSize) | Adds a parameter of the string array type to the parameter list. | 100| int [OH_HiAppEvent_Write](#oh_hiappevent_write) (const char \*domain, const char \*name, enum [EventType](#eventtype) type, const [ParamList](#paramlist) list) | Logs application events whose parameters are of the list type. | 101| bool [OH_HiAppEvent_Configure](#oh_hiappevent_configure) (const char \*name, const char \*value) | Configures the application event logging function. | 102| [HiAppEvent_Watcher](#hiappevent_watcher) \* [OH_HiAppEvent_CreateWatcher](#oh_hiappevent_createwatcher) (const char \*name) | Creates a watcher for application events. | 103| void [OH_HiAppEvent_DestroyWatcher](#oh_hiappevent_destroywatcher) ([HiAppEvent_Watcher](#hiappevent_watcher) \*watcher) | Destroys a created watcher. | 104| int [OH_HiAppEvent_SetTriggerCondition](#oh_hiappevent_settriggercondition) ([HiAppEvent_Watcher](#hiappevent_watcher) \*watcher, int row, int size, int timeOut) | Sets the conditions for triggering the **OH_HiAppEvent_OnTrigger** callback, including the number and size of newly received events and the timeout interval for triggering **onTrigger**. Ensure that at least one of the trigger conditions is set on the caller side. | 105| int [OH_HiAppEvent_SetAppEventFilter](#oh_hiappevent_setappeventfilter) ([HiAppEvent_Watcher](#hiappevent_watcher) \*watcher, const char \*domain, uint8_t eventTypes, const char \*const \*names, int namesLen) | Sets the type of events to listen for. | 106| int [OH_HiAppEvent_SetWatcherOnTrigger](#oh_hiappevent_setwatcherontrigger) ([HiAppEvent_Watcher](#hiappevent_watcher) \*watcher, [OH_HiAppEvent_OnTrigger](#oh_hiappevent_ontrigger) onTrigger) | Sets the **onTrigger** callback. | 107| int [OH_HiAppEvent_SetWatcherOnReceive](#oh_hiappevent_setwatcheronreceive) ([HiAppEvent_Watcher](#hiappevent_watcher) \*watcher, [OH_HiAppEvent_OnReceive](#oh_hiappevent_onreceive) onReceive) | Sets the **onReceive** callback. When the listener detects the corresponding event, the onReceive callback is called. | 108| int [OH_HiAppEvent_TakeWatcherData](#oh_hiappevent_takewatcherdata) ([HiAppEvent_Watcher](#hiappevent_watcher) \*watcher, uint32_t eventNum, [OH_HiAppEvent_OnTake](#oh_hiappevent_ontake) onTake) | Obtains the event saved by the watcher. | 109| int [OH_HiAppEvent_AddWatcher](#oh_hiappevent_addwatcher) ([HiAppEvent_Watcher](#hiappevent_watcher) \*watcher) | Adds a watcher. Once a watcher is added, it starts to listen for system messages. | 110| int [OH_HiAppEvent_RemoveWatcher](#oh_hiappevent_removewatcher) ([HiAppEvent_Watcher](#hiappevent_watcher) \*watcher) | Removes a watcher. Once a watcher is removed, it stops listening for system messages. | 111| void [OH_HiAppEvent_ClearData](#oh_hiappevent_cleardata) (void) | Clears the events saved by all watchers. | 112 113 114## Macro Description 115 116 117### DISABLE 118 119``` 120#define DISABLE "disable" 121``` 122**Description** 123Whether to disable event logging. The default value is **false**. The value **true** means to disable the event logging function, and the value **false** means the opposite. 124 125**Since**: 8 126 127 128### DOMAIN_OS 129 130``` 131#define DOMAIN_OS "OS" 132``` 133**Description** 134OS scope. 135 136**Since**: 12 137 138 139### EVENT_APP_CRASH 140 141``` 142#define EVENT_APP_CRASH "APP_CRASH" 143``` 144**Description** 145Defines an application crash event. 146 147**Since**: 12 148 149 150### EVENT_APP_FREEZE 151 152``` 153#define EVENT_APP_FREEZE "APP_FREEZE" 154``` 155**Description** 156Defines an application freeze event. 157 158**Since**: 12 159 160 161### EVENT_APP_LAUNCH 162 163``` 164#define EVENT_APP_LAUNCH "APP_LAUNCH" 165``` 166**Description** 167Defines an application loading event. 168 169**Since**: 12 170 171 172### EVENT_BATTERY_USAGE 173 174``` 175#define EVENT_BATTERY_USAGE "BATTERY_USAGE" 176``` 177**Description** 178Defines an application power usage event. 179 180**Since**: 12 181 182 183### EVENT_CPU_USAGE_HIGH 184 185``` 186#define EVENT_CPU_USAGE_HIGH "CPU_USAGE_HIGH" 187``` 188**Description** 189Defines an event indicating high CPU usage of an application. 190 191**Since**: 12 192 193 194### EVENT_DISTRIBUTED_SERVICE_START 195 196``` 197#define EVENT_DISTRIBUTED_SERVICE_START "hiappevent.distributed_service_start" 198``` 199**Description** 200Distributed service event. 201 202**Since**: 8 203 204 205### EVENT_RESOURCE_OVERLIMIT 206 207``` 208#define EVENT_RESOURCE_OVERLIMIT "RESOURCE_OVERLIMIT" 209``` 210**Description** 211Defines an application resource threshold-crossing event. 212 213**Since**: 12 214 215 216### EVENT_SCROLL_JANK 217 218``` 219#define EVENT_SCROLL_JANK "SCROLL_JANK" 220``` 221**Description** 222Defines an event indicating application freeze during swiping. 223 224**Since**: 12 225 226 227### EVENT_USER_LOGIN 228 229``` 230#define EVENT_USER_LOGIN "hiappevent.user_login" 231``` 232**Description** 233User login event. 234 235**Since**: 8 236 237 238### EVENT_USER_LOGOUT 239 240``` 241#define EVENT_USER_LOGOUT "hiappevent.user_logout" 242``` 243**Description** 244User logout event. 245 246**Since**: 8 247 248 249### MAX_STORAGE 250 251``` 252#define MAX_STORAGE "max_storage" 253``` 254**Description** 255Storage quota of the event file directory. The default value is **10M**. 256 257**Since**: 8 258 259 260### PARAM_DISTRIBUTED_SERVICE_INSTANCE_ID 261 262``` 263#define PARAM_DISTRIBUTED_SERVICE_INSTANCE_ID "ds_instance_id" 264``` 265**Description** 266Distributed service instance ID. 267 268**Since**: 8 269 270 271### PARAM_DISTRIBUTED_SERVICE_NAME 272 273``` 274#define PARAM_DISTRIBUTED_SERVICE_NAME "ds_name" 275``` 276**Description** 277Distributed service name. 278 279**Since**: 8 280 281 282### PARAM_USER_ID 283 284``` 285#define PARAM_USER_ID "user_id" 286``` 287**Description** 288User ID. 289 290**Since**: 8 291 292 293## Type Description 294 295 296### HiAppEvent_AppEventGroup 297 298``` 299typedef struct HiAppEvent_AppEventGroupHiAppEvent_AppEventGroup 300``` 301**Description** 302Defines an event array with the same event name. 303 304**System capability**: SystemCapability.HiviewDFX.HiAppEvent 305 306**Since**: 12 307 308 309### HiAppEvent_AppEventInfo 310 311``` 312typedef struct HiAppEvent_AppEventInfoHiAppEvent_AppEventInfo 313``` 314**Description** 315Defines information about a single event, including the event domain, event name, event type, and custom parameter list in JSON string format. 316 317\@SystemCapability.HiviewDFX.HiAppEvent 318 319**Since**: 12 320 321 322### HiAppEvent_Watcher 323 324``` 325typedef struct HiAppEvent_WatcherHiAppEvent_Watcher 326``` 327**Description** 328Defines the watcher for application events. 329 330**System capability**: SystemCapability.HiviewDFX.HiAppEvent 331 332**Since**: 12 333 334 335### OH_HiAppEvent_OnReceive 336 337``` 338typedef void(* OH_HiAppEvent_OnReceive) (const char *domain, const struct HiAppEvent_AppEventGroup *appEventGroups, uint32_t groupLen) 339``` 340**Description** 341Defines the callback invoked to pass event content to the caller. 342 343Note: The lifecycle of the object pointed by the pointer in the callback is limited to the callback function. Do not use the pointer outside of the callback function. If the information needs to be cached, perform a deep copy of the content pointed by the pointer. 344 345\@SystemCapability.HiviewDFX.HiAppEvent 346 347**Since**: 12 348 349**Parameters** 350 351| Name| Description| 352| -------- | -------- | 353| domain | Domain of the received application event. | 354| appEventGroups | Event group array. | 355| groupLen | Length of the event group array. | 356 357 358### OH_HiAppEvent_OnTake 359 360``` 361typedef void(* OH_HiAppEvent_OnTake) (const char *const *events, uint32_t eventLen) 362``` 363**Description** 364Defines the callback invoked to pass the events received by the watcher to the caller when OH_HiAppEvent_TakeWatcherData is used to obtain the events. 365 366Note: The lifecycle of the object pointed by the pointer in the callback is limited to the callback function. Do not use the pointer outside of the callback function. If the information needs to be cached, perform a deep copy of the content pointed by the pointer. 367 368\@SystemCapability.HiviewDFX.HiAppEvent 369 370**Since**: 12 371 372**Parameters** 373 374| Name| Description| 375| -------- | -------- | 376| events | Event array in JSON string format. | 377| eventLen | Size of the event array. | 378 379 380### OH_HiAppEvent_OnTrigger 381 382``` 383typedef void(* OH_HiAppEvent_OnTrigger) (int row, int size) 384``` 385**Description** 386Defines the callback invoked if the event received by the watcher meets the conditions specified by **OH_HiAppEvent_SetTriggerCondition**. Specifically, if the **OH_HiAppEvent_OnReceive** callback is not set in the watcher, the event received by the watcher will be saved. If the saved event meets the conditions specified by OH_HiAppEvent_SetTriggerCondition, the callback is invoked. After the callback is complete, if a newly saved event meets the specified condition, the callback is invoked again. 387 388\@SystemCapability.HiviewDFX.HiAppEvent 389 390**Since**: 12 391 392**Parameters** 393 394| Name| Description| 395| -------- | -------- | 396| row | Number of events newly received by the watcher. | 397| size | Total size of events newly received by the watcher. The size of a single event is the length of the JSON string converted from the event. | 398 399 400### ParamList 401 402``` 403typedef struct ParamListNode* ParamList 404``` 405**Description** 406Event parameter list node. 407 408**Since**: 8 409 410 411## Enum Description 412 413 414### EventType 415 416``` 417enum EventType 418``` 419**Description** 420Enumerates the event types. 421 422You are advised to select different event types based on application scenarios. 423 424**Since**: 8 425 426| Value| Description| 427| -------- | -------- | 428| FAULT | Fault event.| 429| STATISTIC | Statistics event.| 430| SECURITY | Security event.| 431| BEHAVIOR | Behavior event.| 432 433 434## Function Description 435 436 437### OH_HiAppEvent_AddBoolArrayParam() 438 439``` 440ParamList OH_HiAppEvent_AddBoolArrayParam (ParamList list, const char * name, const bool * booleans, int arrSize ) 441``` 442**Description** 443Adds an event parameter of the Boolean array type to the parameter list. 444 445**Since**: 8 446 447**Parameters** 448 449| Name| Description| 450| -------- | -------- | 451| list | Pointer to the parameter list to which parameters need to be added. | 452| name | Name of the parameter to be added. | 453| booleans | Value of the parameter to be added. | 454| arrSize | Size of the parameter array to be added. | 455 456**Returns** 457 458Pointer to the parameter list that contains the parameters added. 459 460 461### OH_HiAppEvent_AddBoolParam() 462 463``` 464ParamList OH_HiAppEvent_AddBoolParam (ParamList list, const char * name, bool boolean ) 465``` 466**Description** 467Adds an event parameter of the Boolean type to the parameter list. 468 469**Since**: 8 470 471**Parameters** 472 473| Name| Description| 474| -------- | -------- | 475| list | Pointer to the parameter list to which parameters need to be added. | 476| name | Name of the parameter to be added. | 477| boolean | Value of the parameter to be added. | 478 479**Returns** 480 481Pointer to the parameter list that contains the parameters added. 482 483 484### OH_HiAppEvent_AddDoubleArrayParam() 485 486``` 487ParamList OH_HiAppEvent_AddDoubleArrayParam (ParamList list, const char * name, const double * nums, int arrSize ) 488``` 489**Description** 490Adds an event parameter of the double array type to the parameter list. 491 492**Since**: 8 493 494**Parameters** 495 496| Name| Description| 497| -------- | -------- | 498| list | Pointer to the parameter list to which parameters need to be added. | 499| name | Name of the parameter to be added. | 500| nums | Value of the parameter to be added. | 501| arrSize | Size of the parameter array to be added. | 502 503**Returns** 504 505Pointer to the parameter list that contains the parameters added. 506 507 508### OH_HiAppEvent_AddDoubleParam() 509 510``` 511ParamList OH_HiAppEvent_AddDoubleParam (ParamList list, const char * name, double num ) 512``` 513**Description** 514Adds an event parameter of the Double type to the parameter list. 515 516**Since**: 8 517 518**Parameters** 519 520| Name| Description| 521| -------- | -------- | 522| list | Pointer to the parameter list to which parameters need to be added. | 523| name | Name of the parameter to be added. | 524| num | Value of the parameter to be added. | 525 526**Returns** 527 528Pointer to the parameter list that contains the parameters added. 529 530 531### OH_HiAppEvent_AddFloatArrayParam() 532 533``` 534ParamList OH_HiAppEvent_AddFloatArrayParam (ParamList list, const char * name, const float * nums, int arrSize ) 535``` 536**Description** 537Adds an event parameter of the float array type to the parameter list. 538 539**Since**: 8 540 541**Parameters** 542 543| Name| Description| 544| -------- | -------- | 545| list | Pointer to the parameter list to which parameters need to be added. | 546| name | Name of the parameter to be added. | 547| nums | Value of the parameter to be added. | 548| arrSize | Size of the parameter array to be added. | 549 550**Returns** 551 552Pointer to the parameter list that contains the parameters added. 553 554 555### OH_HiAppEvent_AddFloatParam() 556 557``` 558ParamList OH_HiAppEvent_AddFloatParam (ParamList list, const char * name, float num ) 559``` 560**Description** 561Adds an event parameter of the float type to the parameter list. 562 563**Since**: 8 564 565**Parameters** 566 567| Name| Description| 568| -------- | -------- | 569| list | Pointer to the parameter list to which parameters need to be added. | 570| name | Name of the parameter to be added. | 571| num | Value of the parameter to be added. | 572 573**Returns** 574 575Pointer to the parameter list that contains the parameters added. 576 577 578### OH_HiAppEvent_AddInt16ArrayParam() 579 580``` 581ParamList OH_HiAppEvent_AddInt16ArrayParam (ParamList list, const char * name, const int16_t * nums, int arrSize ) 582``` 583**Description** 584Adds an event parameter of the int16_t array type to the parameter list. 585 586**Since**: 8 587 588**Parameters** 589 590| Name| Description| 591| -------- | -------- | 592| list | Pointer to the parameter list to which parameters need to be added. | 593| name | Name of the parameter to be added. | 594| nums | Value of the parameter to be added. | 595| arrSize | Size of the parameter array to be added. | 596 597**Returns** 598 599Pointer to the parameter list that contains the parameters added. 600 601 602### OH_HiAppEvent_AddInt16Param() 603 604``` 605ParamList OH_HiAppEvent_AddInt16Param (ParamList list, const char * name, int16_t num ) 606``` 607**Description** 608Adds an event parameter of the int16_t type to the parameter list. 609 610**Since**: 8 611 612**Parameters** 613 614| Name| Description| 615| -------- | -------- | 616| list | Pointer to the parameter list to which parameters need to be added. | 617| name | Name of the parameter to be added. | 618| num | Value of the parameter to be added. | 619 620**Returns** 621 622Pointer to the parameter list that contains the parameters added. 623 624 625### OH_HiAppEvent_AddInt32ArrayParam() 626 627``` 628ParamList OH_HiAppEvent_AddInt32ArrayParam (ParamList list, const char * name, const int32_t * nums, int arrSize ) 629``` 630**Description** 631Adds an event parameter of the int32_t array type to the parameter list. 632 633**Since**: 8 634 635**Parameters** 636 637| Name| Description| 638| -------- | -------- | 639| list | Pointer to the parameter list to which parameters need to be added. | 640| name | Name of the parameter to be added. | 641| nums | Value of the parameter to be added. | 642| arrSize | Size of the parameter array to be added. | 643 644**Returns** 645 646Pointer to the parameter list that contains the parameters added. 647 648 649### OH_HiAppEvent_AddInt32Param() 650 651``` 652ParamList OH_HiAppEvent_AddInt32Param (ParamList list, const char * name, int32_t num ) 653``` 654**Description** 655Adds an event parameter of the int32_t type to the parameter list. 656 657**Since**: 8 658 659**Parameters** 660 661| Name| Description| 662| -------- | -------- | 663| list | Pointer to the parameter list to which parameters need to be added. | 664| name | Name of the parameter to be added. | 665| num | Value of the parameter to be added. | 666 667**Returns** 668 669Pointer to the parameter list that contains the parameters added. 670 671 672### OH_HiAppEvent_AddInt64ArrayParam() 673 674``` 675ParamList OH_HiAppEvent_AddInt64ArrayParam (ParamList list, const char * name, const int64_t * nums, int arrSize ) 676``` 677**Description** 678Adds an event parameter of the int64_t array type to the parameter list. 679 680**Since**: 8 681 682**Parameters** 683 684| Name| Description| 685| -------- | -------- | 686| list | Pointer to the parameter list to which parameters need to be added. | 687| name | Name of the parameter to be added. | 688| nums | Value of the parameter to be added. | 689| arrSize | Size of the parameter array to be added. | 690 691**Returns** 692 693Pointer to the parameter list that contains the parameters added. 694 695 696### OH_HiAppEvent_AddInt64Param() 697 698``` 699ParamList OH_HiAppEvent_AddInt64Param (ParamList list, const char * name, int64_t num ) 700``` 701**Description** 702Adds an event parameter of the int64_t type to the parameter list. 703 704**Since**: 8 705 706**Parameters** 707 708| Name| Description| 709| -------- | -------- | 710| list | Pointer to the parameter list to which parameters need to be added. | 711| name | Name of the parameter to be added. | 712| num | Value of the parameter to be added. | 713 714**Returns** 715 716Pointer to the parameter list that contains the parameters added. 717 718 719### OH_HiAppEvent_AddInt8ArrayParam() 720 721``` 722ParamList OH_HiAppEvent_AddInt8ArrayParam (ParamList list, const char * name, const int8_t * nums, int arrSize ) 723``` 724**Description** 725Adds an event parameter of the int8_t array type to the parameter list. 726 727**Since**: 8 728 729**Parameters** 730 731| Name| Description| 732| -------- | -------- | 733| list | Pointer to the parameter list to which parameters need to be added. | 734| name | Name of the parameter to be added. | 735| nums | Value of the parameter to be added. | 736| arrSize | Size of the parameter array to be added. | 737 738**Returns** 739 740Pointer to the parameter list that contains the parameters added. 741 742 743### OH_HiAppEvent_AddInt8Param() 744 745``` 746ParamList OH_HiAppEvent_AddInt8Param (ParamList list, const char * name, int8_t num ) 747``` 748**Description** 749Adds an event parameter of the int8_t type to the parameter list. 750 751**Since**: 8 752 753**Parameters** 754 755| Name| Description| 756| -------- | -------- | 757| list | Pointer to the parameter list to which parameters need to be added. | 758| name | Name of the parameter to be added. | 759| num | Value of the parameter to be added. | 760 761**Returns** 762 763Pointer to the parameter list that contains the parameters added. 764 765 766### OH_HiAppEvent_AddStringArrayParam() 767 768``` 769ParamList OH_HiAppEvent_AddStringArrayParam (ParamList list, const char * name, const char *const * strs, int arrSize ) 770``` 771**Description** 772Adds a parameter of the string array type to the parameter list. 773 774**Since**: 8 775 776**Parameters** 777 778| Name| Description| 779| -------- | -------- | 780| list | Pointer to the parameter list to which parameters need to be added. | 781| name | Name of the parameter to be added. | 782| strs | Value of the parameter to be added. | 783| arrSize | Size of the parameter array to be added. | 784 785**Returns** 786 787Pointer to the parameter list that contains the parameters added. 788 789 790### OH_HiAppEvent_AddStringParam() 791 792``` 793ParamList OH_HiAppEvent_AddStringParam (ParamList list, const char * name, const char * str ) 794``` 795**Description** 796Adds a parameter of the string type to the parameter list. 797 798**Since**: 8 799 800**Parameters** 801 802| Name| Description| 803| -------- | -------- | 804| list | Pointer to the parameter list to which parameters need to be added. | 805| name | Name of the parameter to be added. | 806| str | Value of the parameter to be added. | 807 808**Returns** 809 810Pointer to the parameter list that contains the parameters added. 811 812 813### OH_HiAppEvent_AddWatcher() 814 815``` 816int OH_HiAppEvent_AddWatcher (HiAppEvent_Watcher * watcher) 817``` 818**Description** 819Adds a watcher. Once a watcher is added, it starts to listen for system messages. 820 821\@SystemCapability.HiviewDFX.HiAppEvent 822 823**Since**: 12 824 825**Parameters** 826 827| Name| Description| 828| -------- | -------- | 829| watcher | Pointer to the watcher (that is, the pointer returned by OH_HiAppEvent_CreateWatcher). | 830 831**Returns** 832 833**0** if the API is called successfully; **-5** if the pointer of an input parameter is null. 834 835 836### OH_HiAppEvent_ClearData() 837 838``` 839void OH_HiAppEvent_ClearData (void ) 840``` 841**Description** 842Clears the events saved by all watchers. 843 844\@SystemCapability.HiviewDFX.HiAppEvent 845 846**Since**: 12 847 848 849### OH_HiAppEvent_Configure() 850 851``` 852bool OH_HiAppEvent_Configure (const char * name, const char * value ) 853``` 854**Description** 855Configures the application event logging function. 856 857This function is used to configure the event logging function and the storage quota of the event file directory. 858 859**Since**: 8 860 861**Parameters** 862 863| Name| Description| 864| -------- | -------- | 865| name | Configuration item name. The value can be set to [DISABLE](#disable) or [MAX_STORAGE](#max_storage). | 866| value | Configuration item value. If the configuration item name is [DISABLE](#disable), the value can be **true** or **false**. If the configuration item name is [MAX_STORAGE](#max_storage), the quota value can contain only digits and a unit, which can be one of [b\|k\|kb\|m\|mb\|g\|gb\|t\|tb] and is case insensitive. The quota value string must start with a digit and can end with or without a unit. If no unit is specified, byte is used by default. | 867 868**Returns** 869 870Configuration result. The value **true** indicates that the configuration is successful, and the value **false** indicates the opposite. 871 872 873### OH_HiAppEvent_CreateParamList() 874 875``` 876ParamList OH_HiAppEvent_CreateParamList (void ) 877``` 878**Description** 879Creates a pointer to a parameter list object. 880 881**Since**: 8 882 883**Returns** 884 885Pointer to the parameter list object. 886 887 888### OH_HiAppEvent_CreateWatcher() 889 890``` 891HiAppEvent_Watcher* OH_HiAppEvent_CreateWatcher (const char * name) 892``` 893**Description** 894Creates a watcher for application events. 895 896Note: If a created watcher is no longer used, you are required to destroy it by calling OH_HiAppEvent_DestroyWatcher. 897 898\@SystemCapability.HiviewDFX.HiAppEvent 899 900**Since**: 12 901 902**Parameters** 903 904| Name| Description| 905| -------- | -------- | 906| name | Watcher name. | 907 908**Returns** 909 910Pointer to the new watcher if the API is called successfully; **nullptr** if the **name** parameter is invalid. 911 912 913### OH_HiAppEvent_DestroyParamList() 914 915``` 916void OH_HiAppEvent_DestroyParamList (ParamList list) 917``` 918**Description** 919Destroys a pointer to a parameter list object and releases its allocated memory. 920 921**Since**: 8 922 923**Parameters** 924 925| Name| Description| 926| -------- | -------- | 927| list | Pointer to the parameter list object. | 928 929 930### OH_HiAppEvent_DestroyWatcher() 931 932``` 933void OH_HiAppEvent_DestroyWatcher (HiAppEvent_Watcher * watcher) 934``` 935**Description** 936Destroys a created watcher. 937 938Note: If a created watcher is no longer used, destroy it to release memory to prevent memory leakage. After the watcher is destroyed, set its pointer to null. 939 940\@SystemCapability.HiviewDFX.HiAppEvent 941 942**Since**: 12 943 944**Parameters** 945 946| Name| Description| 947| -------- | -------- | 948| watcher | Pointer to the watcher (that is, the pointer returned by OH_HiAppEvent_CreateWatcher). | 949 950 951### OH_HiAppEvent_RemoveWatcher() 952 953``` 954int OH_HiAppEvent_RemoveWatcher (HiAppEvent_Watcher * watcher) 955``` 956**Description** 957Removes a watcher. Once a watcher is removed, it stops listening for system messages. 958 959Note: This API only enables the watcher to stop listening for system messages. It does not destroy the watcher. The watcher still resides in the memory until the OH_HiAppEvent_DestroyWatcher API is called. 960 961\@SystemCapability.HiviewDFX.HiAppEvent 962 963**Since**: 12 964 965**Parameters** 966 967| Name| Description| 968| -------- | -------- | 969| watcher | Pointer to the watcher (that is, the pointer returned by OH_HiAppEvent_CreateWatcher). | 970 971**Returns** 972 973**0** if the API is called successfully; **-5** if the pointer of an input parameter is null; **-6** if **OH_HiAppEvent_AddWatcher** has not been called to add a watcher. 974 975 976### OH_HiAppEvent_SetAppEventFilter() 977 978``` 979int OH_HiAppEvent_SetAppEventFilter (HiAppEvent_Watcher * watcher, const char * domain, uint8_t eventTypes, const char *const * names, int namesLen ) 980``` 981**Description** 982Sets the type of events to listen for. 983 984This function can be called repeatedly. You can add multiple filtering conditions instead of replacing them. The watcher will receive notifications of events that meet any of the filtering conditions. 985 986\@SystemCapability.HiviewDFX.HiAppEvent 987 988**Since**: 12 989 990**Parameters** 991 992| Name| Description| 993| -------- | -------- | 994| watcher | Pointer to the watcher (that is, the pointer returned by OH_HiAppEvent_CreateWatcher). | 995| domain | Domain of events to be listened for. | 996| eventTypes | Types of events to be listened for. The bitwise AND matching mode is used. Multiple types of events can be intercepted. If the first bit is 1 (the value is 1), fault events can be intercepted. If the second bit is 1 (the value is 2), statistics events can be intercepted. If the third bit is 1 (the value is 4), security events can be intercepted, if the fourth digit is 1 (the value is 8), events of the listening behavior type are supported. If the fourth digit is 1 (the value is 15) or 0 (the value is 0), events of all types are supported. | 997| names | Array of the event names. | 998| namesLen | Length of the event name array. | 999 1000**Returns** 1001 1002**0** if the API is called successfully; **-1** if the **names** parameter is invalid; **-4** if the **domain** parameter is invalid; **-5** if the pointer of an input parameter is null. 1003 1004 1005### OH_HiAppEvent_SetTriggerCondition() 1006 1007``` 1008int OH_HiAppEvent_SetTriggerCondition (HiAppEvent_Watcher * watcher, int row, int size, int timeOut ) 1009``` 1010**Description** 1011Sets the conditions for triggering the **OH_HiAppEvent_OnTrigger** callback, including the number and size of newly received events and the timeout interval for triggering **onTrigger**. Ensure that at least one of the trigger conditions is set on the caller side. 1012 1013\@SystemCapability.HiviewDFX.HiAppEvent 1014 1015**Since**: 12 1016 1017**Parameters** 1018 1019| Name| Description| 1020| -------- | -------- | 1021| watcher | Pointer to the watcher (that is, the pointer returned by OH_HiAppEvent_CreateWatcher). | 1022| row | Row count. If the input value is greater than 0 and the number of newly received events is greater than or equal to the value of this parameter, the configured onTrigger callback is called. If the input value is less than or equal to 0, the number of received events is not used as the condition to trigger the onTrigger callback. | 1023| size | Size value. If the input value is greater than 0 and the size of the newly received event is greater than or equal to the value of this parameter, the configured onTrigger callback is called. The size of a single event is the length of the JSON string converted from the event. If the input value is less than or equal to 0, the size of received events is not used as the condition to trigger the onTrigger callback. | 1024| timeOut | Timeout value, in seconds. If the input value is greater than 0, the system checks the watcher for newly received events based on the timeout interval. If there are any newly received events, the configured onTrigger callback is triggered. After the callback is complete, the system checks the watcher for newly received events when the timeout value expires. If the input value is less than or equal to 0, the timeout interval is not used as the condition to trigger the onTrigger callback. | 1025 1026**Returns** 1027 1028**0** if the API is called successfully; **-5** if the pointer of an input parameter is null. 1029 1030 1031### OH_HiAppEvent_SetWatcherOnReceive() 1032 1033``` 1034int OH_HiAppEvent_SetWatcherOnReceive (HiAppEvent_Watcher * watcher, OH_HiAppEvent_OnReceive onReceive ) 1035``` 1036**Description** 1037Sets the **onReceive** callback. When the listener detects the corresponding event, the onReceive callback is called. 1038 1039\@SystemCapability.HiviewDFX.HiAppEvent 1040 1041**Since**: 12 1042 1043**Parameters** 1044 1045| Name| Description| 1046| -------- | -------- | 1047| watcher | Pointer to the watcher (that is, the pointer returned by OH_HiAppEvent_CreateWatcher). | 1048| onReceive | Pointer to the callback function. | 1049 1050**Returns** 1051 1052**0** if the API is called successfully; **-5** if the pointer of an input parameter is null. 1053 1054 1055### OH_HiAppEvent_SetWatcherOnTrigger() 1056 1057``` 1058int OH_HiAppEvent_SetWatcherOnTrigger (HiAppEvent_Watcher * watcher, OH_HiAppEvent_OnTrigger onTrigger ) 1059``` 1060**Description** 1061Sets the **onTrigger** callback. 1062 1063\@SystemCapability.HiviewDFX.HiAppEvent 1064 1065**Since**: 12 1066 1067**Parameters** 1068 1069| Name| Description| 1070| -------- | -------- | 1071| watcher | Pointer to the watcher (that is, the pointer returned by OH_HiAppEvent_CreateWatcher). | 1072| onTrigger | Callback to be set. | 1073 1074**Returns** 1075 1076**0** if the API is called successfully; **-5** if the pointer of an input parameter is null. 1077 1078 1079### OH_HiAppEvent_TakeWatcherData() 1080 1081``` 1082int OH_HiAppEvent_TakeWatcherData (HiAppEvent_Watcher * watcher, uint32_t eventNum, OH_HiAppEvent_OnTake onTake ) 1083``` 1084**Description** 1085Obtains the event saved by the watcher. 1086 1087\@SystemCapability.HiviewDFX.HiAppEvent 1088 1089**Since**: 12 1090 1091**Parameters** 1092 1093| Name| Description| 1094| -------- | -------- | 1095| watcher | Pointer to the watcher (that is, the pointer returned by OH_HiAppEvent_CreateWatcher). | 1096| eventNum | If the input value is less than or equal to **0**, all saved events are obtained. If the input value is greater than **0**, events are sorted by time in descending order and a specified number of saved events are obtained. | 1097| onTake | Pointer to the callback. The event information is returned through this callback. | 1098 1099**Returns** 1100 1101**0** if the API is called successfully; **-5** if the pointer of an input parameter is null; **-6** if **OH_HiAppEvent_AddWatcher** has not been called to add a watcher. 1102 1103 1104### OH_HiAppEvent_Write() 1105 1106``` 1107int OH_HiAppEvent_Write (const char * domain, const char * name, enum EventType type, const ParamList list ) 1108``` 1109**Description** 1110Logs application events whose parameters are of the list type. 1111 1112Before application event logging, use this API to verify parameters of the events. If the verification is successful, the API writes the events to the event file. 1113 1114**Since**: 8 1115 1116**Parameters** 1117 1118| Name| Description| 1119| -------- | -------- | 1120| domain | Event domain. You can customize event domains as required. The value is a string of up to 32 characters, including digits (0 to 9), letters (a to z), and underscores (\_). It must start with a letter and cannot end with an underscore (_). | 1121| name | Event name. You can customize event names as required. The value is string that contains a maximum of 48 characters, including digits (0 to 9), letters (a to z), underscore (_), and dollar sign ($). It must start with a letter or dollar sign ($) and end with a digit or letter. | 1122| type | Event type, which is defined in [EventType](#eventtype). | 1123| list | List of event parameters, each of which consists of a parameter name and a parameter value. The specifications are as follows:<br>1. A parameter name is a string that contains a maximum of 16 characters, including digits (0 to 9), letters (a to z), underscore (_), and dollar sign ($). It must start with a letter or dollar sign ($) and end with a digit or letter.<br>2. The parameter value can be string, number, Boolean, or array. The length of a parameter of the string type must be less than 8 × 1024 characters. If this limit is exceeded, the parameter will be discarded. The element type of an array parameter can only be string, number, or Boolean, and the number of elements must be less than 100. If this limit is exceeded, excess elements will be discarded.<br>3. The maximum number of parameters is 32. If this limit is exceeded, excess parameters will be discarded.| 1124 1125**Returns** 1126 1127The value **0** indicates that the event parameter is valid, and the event will be written to the event file asynchronously. A value greater than **0** indicates that invalid parameters are present in the event, and the event will be written to the event file asynchronously after the invalid parameters are ignored. A value smaller than **0** indicates that the event parameter verification fails, and the event will not be written to the event file. 0 The event parameter is valid. -1 The event name is invalid. -4 The event domain name is invalid. -99 The application event logging is disabled. 1 The event parameter name is invalid. 4 The length of the event parameter string is invalid. 5 The number of event parameters is invalid. 6 The length of the event parameter array is invalid. 8 The event parameter name is duplicate. 1128