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 11 12**System capability**: SystemCapability.HiviewDFX.HiAppEvent 13 14**Since**: 8 15 16 17## Summary 18 19 20### Files 21 22| Name| Description| 23| -------- | -------- | 24| [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| 25| [hiappevent_cfg.h](hiappevent__cfg_8h.md) | Defines the configuration items of the event logging configuration function.<br>**File to include**: <hiappevent/hiappevent_cfg.h><br>**Library**: libhiappevent_ndk.z.so| 26| [hiappevent_event.h](hiappevent__event_8h.md) | Defines the names of all predefined events.<br>**File to include**: <hiappevent/hiappevent_event.h><br>**Library**: libhiappevent_ndk.z.so| 27| [hiappevent_param.h](hiappevent__param_8h.md) | Defines the names of all predefined event parameters.<br>**File to include**: <hiappevent/hiappevent_param.h><br>**Library**: libhiappevent_ndk.z.so| 28 29 30### Structs 31 32| Name| Description| 33| -------- | -------- | 34| struct [HiAppEvent_AppEventInfo](_hi_app_event___app_event_info.md) | Defines the information about a single event, including the event domain, event name, event type, and custom parameter list in JSON string format. | 35| struct [HiAppEvent_AppEventGroup](_hi_app_event___app_event_group.md) | Defines the information about an event group, including its name, the array of event information grouped by name, and the length of the event array. | 36 37 38### Macros 39 40| Name| Description| 41| -------- | -------- | 42| [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. | 43| [MAX_STORAGE](#max_storage) "max_storage" | Storage quota of the event file directory. The default value is **10M**. | 44| [EVENT_USER_LOGIN](#event_user_login) "hiappevent.user_login" | User login event. | 45| [EVENT_USER_LOGOUT](#event_user_logout) "hiappevent.user_logout" | User logout event. | 46| [EVENT_DISTRIBUTED_SERVICE_START](#event_distributed_service_start) "hiappevent.distributed_service_start" | Distributed service event. | 47| [EVENT_APP_CRASH](#event_app_crash) "APP_CRASH" | Application crash event. | 48| [EVENT_APP_FREEZE](#event_app_freeze) "APP_FREEZE" | Application freeze event. | 49| [EVENT_APP_LAUNCH](#event_app_launch) "APP_LAUNCH" | Application loading event. | 50| [EVENT_SCROLL_JANK](#event_scroll_jank) "SCROLL_JANK" | Event indicating application freeze during swiping. | 51| [EVENT_CPU_USAGE_HIGH](#event_cpu_usage_high) "CPU_USAGE_HIGH" | Event indicating high CPU usage of an application. | 52| [EVENT_BATTERY_USAGE](#event_battery_usage) "BATTERY_USAGE" | Application power usage event. | 53| [EVENT_RESOURCE_OVERLIMIT](#event_resource_overlimit) "RESOURCE_OVERLIMIT" | Application resource threshold-crossing event. | 54| [EVENT_ADDRESS_SANITIZER](#event_address_sanitizer) "ADDRESS_SANITIZER" | Address sanitizer event. | 55| [EVENT_MAIN_THREAD_JANK](#event_main_thread_jank) "MAIN_THREAD_JANK" | Main thread jank event. | 56| [EVENT_APP_HICOLLIE](#event_app_hicollie) "APP_HICOLLIE" | Task execution timeout event. | 57| [DOMAIN_OS](#domain_os) "OS" | OS scope. | 58| [PARAM_USER_ID](#param_user_id) "user_id" | User ID. | 59| [PARAM_DISTRIBUTED_SERVICE_NAME](#param_distributed_service_name) "ds_name" | Distributed service name. | 60| [PARAM_DISTRIBUTED_SERVICE_INSTANCE_ID](#param_distributed_service_instance_id) "ds_instance_id" | Distributed service instance ID. | 61 62 63### Types 64 65| Name| Description| 66| -------- | -------- | 67| typedef struct [HiAppEvent_AppEventInfo](_hi_app_event___app_event_info.md) [HiAppEvent_AppEventInfo](#hiappevent_appeventinfo) | Defines a struct for the information about a single event, including the event domain, event name, event type, and custom parameter list in JSON string format. | 68| typedef struct [HiAppEvent_AppEventGroup](_hi_app_event___app_event_group.md) [HiAppEvent_AppEventGroup](#hiappevent_appeventgroup) | Defines a struct for the information about an event group, including its name, the array of event information grouped by name, and the length of the event array. | 69| typedef struct ParamListNode \* [ParamList](#paramlist) | Defines a struct for the event parameter list node. | 70| typedef struct [HiAppEvent_Watcher](#hiappevent_watcher) [HiAppEvent_Watcher](#hiappevent_watcher) | Defines a struct for the watcher for application events. | 71| typedef struct [HiAppEvent_Processor](#hiappevent_processor) [HiAppEvent_Processor](#hiappevent_processor) | Defines a struct for the processor for application events. | 72| typedef struct [HiAppEvent_Config](#hiappevent_config) [HiAppEvent_Config](#hiappevent_config) | Defines a struct for the configuration object used to set the conditions for triggering system events. | 73| 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) | Defines a callback invoked to pass event content to the caller. | 74| typedef void(\* [OH_HiAppEvent_OnTrigger](#oh_hiappevent_ontrigger)) (int row, int size) | Defines a callback invoked if the event received by the watcher meets the conditions specified by **OH_HiAppEvent_SetTriggerCondition**. When the **OH_HiAppEvent_OnReceive** callback is not set in the watcher, the event received by the watcher will be saved.<br> After the callback is complete, if a newly saved event meets the specified condition, the callback is invoked again.| 75| typedef void(\* [OH_HiAppEvent_OnTake](#oh_hiappevent_ontake)) (const char \*const \*events, uint32_t eventLen) | Defines a callback invoked to pass the events received by the watcher to the caller when **OH_HiAppEvent_TakeWatcherData** is used to obtain the events. | 76 77 78### Enums 79 80| Name| Description| 81| -------- | -------- | 82| [HiAppEvent_ErrorCode](#hiappevent_errorcode) {<br>HIAPPEVENT_SUCCESS = 0, <br>HIAPPEVENT_INVALID_PARAM_VALUE_LENGTH = 4, <br>HIAPPEVENT_PROCESSOR_IS_NULL = -7, <br>HIAPPEVENT_PROCESSOR_NOT_FOUND = -8,<br>HIAPPEVENT_INVALID_PARAM_VALUE = -9, <br>HIAPPEVENT_EVENT_CONFIG_IS_NULL = -10, <br>HIAPPEVENT_OPERATE_FAILED = -100, <br>HIAPPEVENT_INVALID_UID = -200<br>} | Enumerates the error codes used in the HiAppEvent module. | 83| [EventType](#eventtype) {<br>FAULT = 1, <br>STATISTIC = 2, <br>SECURITY = 3, <br>BEHAVIOR = 4 <br>} | Enumerates the event types. | 84 85 86### Functions 87 88| Name| Description| 89| -------- | -------- | 90| [ParamList](#paramlist) [OH_HiAppEvent_CreateParamList](#oh_hiappevent_createparamlist) (void) | Creates a pointer to a parameter list object. | 91| void [OH_HiAppEvent_DestroyParamList](#oh_hiappevent_destroyparamlist) ([ParamList](#paramlist) list) | Destroys a pointer to a parameter list object and releases its allocated memory. | 92| [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. | 93| [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. | 94| [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. | 95| [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. | 96| [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. | 97| [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. | 98| [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. | 99| [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. | 100| [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. | 101| [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. | 102| [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. | 103| [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. | 104| [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. | 105| [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. | 106| [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. | 107| [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. | 108| 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. | 109| bool [OH_HiAppEvent_Configure](#oh_hiappevent_configure) (const char \*name, const char \*value) | Configures the application event logging function. | 110| [HiAppEvent_Watcher](#hiappevent_watcher) \* [OH_HiAppEvent_CreateWatcher](#oh_hiappevent_createwatcher) (const char \*name) | Creates a watcher for application events. | 111| void [OH_HiAppEvent_DestroyWatcher](#oh_hiappevent_destroywatcher) ([HiAppEvent_Watcher](#hiappevent_watcher) \*watcher) | Destroys a created watcher. | 112| int [OH_HiAppEvent_SetTriggerCondition](#oh_hiappevent_settriggercondition) ([HiAppEvent_Watcher](#hiappevent_watcher) \*watcher, int row, int size, int timeOut) | Sets the trigger condition of the **OH_HiAppEvent_OnTrigger** callback.<br>You can set the trigger condition by the number and size of new events received by the watcher, and **onTrigger** timeout interval. Ensure that at least one of the trigger conditions is set on the caller side.| 113| 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. | 114| int [OH_HiAppEvent_SetWatcherOnTrigger](#oh_hiappevent_setwatcherontrigger) ([HiAppEvent_Watcher](#hiappevent_watcher) \*watcher, [OH_HiAppEvent_OnTrigger](#oh_hiappevent_ontrigger) onTrigger) | Sets the **onTrigger** callback.<br>If **OnReceive** is not set or is set to **nullptr**, the application events received by the watcher will be saved. If the saved application events meet the trigger conditions of the **onTrigger** callback, the **onTrigger** callback will be called.| 115| 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. | 116| 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. | 117| 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. | 118| 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. | 119| void [OH_HiAppEvent_ClearData](#oh_hiappevent_cleardata) () | Clears the events saved by all watchers. | 120| [HiAppEvent_Processor](#hiappevent_processor) \* [OH_HiAppEvent_CreateProcessor](#oh_hiappevent_createprocessor) (const char \*name) | Creates a processor for application events. | 121| int [OH_HiAppEvent_SetReportRoute](#oh_hiappevent_setreportroute) ([HiAppEvent_Processor](#hiappevent_processor) \*processor, const char \*appId, const char \*routeInfo) | Sets the report route for the processor. | 122| int [OH_HiAppEvent_SetReportPolicy](#oh_hiappevent_setreportpolicy) ([HiAppEvent_Processor](#hiappevent_processor) \*processor, int periodReport, int batchReport, bool onStartReport, bool onBackgroundReport) | Sets the report policy for the processor. | 123| int [OH_HiAppEvent_SetReportEvent](#oh_hiappevent_setreportevent) ([HiAppEvent_Processor](#hiappevent_processor) \*processor, const char \*domain, const char \*name, bool isRealTime) | Sets the report event for the processor. | 124| int [OH_HiAppEvent_SetCustomConfig](#oh_hiappevent_setcustomconfig) ([HiAppEvent_Processor](#hiappevent_processor) \*processor, const char \*key, const char \*value) | Sets the custom extension parameters of the processor. | 125| int [OH_HiAppEvent_SetConfigId](#oh_hiappevent_setconfigid) ([HiAppEvent_Processor](#hiappevent_processor) \*processor, int configId) | Sets the configuration ID of the processor. | 126| int [OH_HiAppEvent_SetReportUserId](#oh_hiappevent_setreportuserid) ([HiAppEvent_Processor](#hiappevent_processor) \*processor, const char \*const \*userIdNames, int size) | Sets the report user ID of the processor. | 127| int [OH_HiAppEvent_SetReportUserProperty](#oh_hiappevent_setreportuserproperty) ([HiAppEvent_Processor](#hiappevent_processor) \*processor, const char \*const \*userPropertyNames, int size) | Sets the report user property of the processor. | 128| int64_t [OH_HiAppEvent_AddProcessor](#oh_hiappevent_addprocessor) ([HiAppEvent_Processor](#hiappevent_processor) \*processor) | Adds a processor. You can add a processor to migrate event data to the cloud. You can preset the implementation of the processor on the device and set its properties based on its constraints. | 129| void [OH_HiAppEvent_DestroyProcessor](#oh_hiappevent_destroyprocessor) ([HiAppEvent_Processor](#hiappevent_processor) \*processor) | Destroys a processor. | 130| int [OH_HiAppEvent_RemoveProcessor](#oh_hiappevent_removeprocessor) (int64_t processorId) | Removes a processor. Once a processor is removed, it stops reporting events. | 131| [HiAppEvent_Config](#hiappevent_config) \* [OH_HiAppEvent_CreateConfig](#oh_hiappevent_createconfig) (void) | Creates a pointer to the configuration object that sets the conditions for triggering system events. | 132| void [OH_HiAppEvent_DestroyConfig](#oh_hiappevent_destroyconfig) ([HiAppEvent_Config](#hiappevent_config) \*config) | Destroys a configuration object. | 133| int [OH_HiAppEvent_SetConfigItem](#oh_hiappevent_setconfigitem) ([HiAppEvent_Config](#hiappevent_config) \*config, const char \*itemName, const char \*itemValue) | Sets the items in the configuration object. | 134| int [OH_HiAppEvent_SetEventConfig](#oh_hiappevent_seteventconfig) (const char \*name, [HiAppEvent_Config](#hiappevent_config) \*config) | Sets the conditions for triggering system event subscription. | 135 136 137## Macro Description 138 139 140### DISABLE 141 142``` 143#define DISABLE "disable" 144``` 145**Description** 146Whether 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. 147 148**Since**: 8 149 150 151### DOMAIN_OS 152 153``` 154#define DOMAIN_OS "OS" 155``` 156**Description** 157OS scope. 158 159**Since**: 12 160 161 162### EVENT_ADDRESS_SANITIZER 163 164``` 165#define EVENT_ADDRESS_SANITIZER "ADDRESS_SANITIZER" 166``` 167**Description** 168Address sanitizer event. 169 170**Since**: 12 171 172 173### EVENT_APP_CRASH 174 175``` 176#define EVENT_APP_CRASH "APP_CRASH" 177``` 178**Description** 179Application crash event. 180 181**Since**: 12 182 183 184### EVENT_APP_FREEZE 185 186``` 187#define EVENT_APP_FREEZE "APP_FREEZE" 188``` 189**Description** 190Application freeze event. 191 192**Since**: 12 193 194 195### EVENT_APP_HICOLLIE 196 197``` 198#define EVENT_APP_HICOLLIE "APP_HICOLLIE" 199``` 200**Description** 201Task execution timeout event. 202 203**Since**: 18 204 205 206### EVENT_APP_LAUNCH 207 208``` 209#define EVENT_APP_LAUNCH "APP_LAUNCH" 210``` 211**Description** 212Application loading event. 213 214**Since**: 12 215 216 217### EVENT_BATTERY_USAGE 218 219``` 220#define EVENT_BATTERY_USAGE "BATTERY_USAGE" 221``` 222**Description** 223Application power usage event. 224 225**Since**: 12 226 227 228### EVENT_CPU_USAGE_HIGH 229 230``` 231#define EVENT_CPU_USAGE_HIGH "CPU_USAGE_HIGH" 232``` 233**Description** 234Event indicating high CPU usage of an application. 235 236**Since**: 12 237 238 239### EVENT_DISTRIBUTED_SERVICE_START 240 241``` 242#define EVENT_DISTRIBUTED_SERVICE_START "hiappevent.distributed_service_start" 243``` 244**Description** 245Distributed service event. 246 247**Since**: 8 248 249 250### EVENT_MAIN_THREAD_JANK 251 252``` 253#define EVENT_MAIN_THREAD_JANK "MAIN_THREAD_JANK" 254``` 255**Description** 256Main thread jank event. 257 258**Since**: 12 259 260 261### EVENT_RESOURCE_OVERLIMIT 262 263``` 264#define EVENT_RESOURCE_OVERLIMIT "RESOURCE_OVERLIMIT" 265``` 266**Description** 267Application resource threshold-crossing event. 268 269**Since**: 12 270 271 272### EVENT_SCROLL_JANK 273 274``` 275#define EVENT_SCROLL_JANK "SCROLL_JANK" 276``` 277**Description** 278Event indicating application freeze during swiping. 279 280**Since**: 12 281 282 283### EVENT_USER_LOGIN 284 285``` 286#define EVENT_USER_LOGIN "hiappevent.user_login" 287``` 288**Description** 289User login event. 290 291**Since**: 8 292 293 294### EVENT_USER_LOGOUT 295 296``` 297#define EVENT_USER_LOGOUT "hiappevent.user_logout" 298``` 299**Description** 300User logout event. 301 302**Since**: 8 303 304 305### MAX_STORAGE 306 307``` 308#define MAX_STORAGE "max_storage" 309``` 310**Description** 311Storage quota of the event file directory. The default value is **10M**. 312 313**Since**: 8 314 315 316### PARAM_DISTRIBUTED_SERVICE_INSTANCE_ID 317 318``` 319#define PARAM_DISTRIBUTED_SERVICE_INSTANCE_ID "ds_instance_id" 320``` 321**Description** 322Distributed service instance ID. 323 324**Since**: 8 325 326 327### PARAM_DISTRIBUTED_SERVICE_NAME 328 329``` 330#define PARAM_DISTRIBUTED_SERVICE_NAME "ds_name" 331``` 332**Description** 333Distributed service name. 334 335**Since**: 8 336 337 338### PARAM_USER_ID 339 340``` 341#define PARAM_USER_ID "user_id" 342``` 343**Description** 344User ID. 345 346**Since**: 8 347 348 349## Type Description 350 351 352### HiAppEvent_AppEventGroup 353 354``` 355typedef struct HiAppEvent_AppEventGroupHiAppEvent_AppEventGroup 356``` 357**Description** 358Defines the information of an event group, including its name, the array of event information grouped by name, and the length of the event array. 359 360**System capability**: SystemCapability.HiviewDFX.HiAppEvent 361 362**Since**: 12 363 364 365### HiAppEvent_AppEventInfo 366 367``` 368typedef struct HiAppEvent_AppEventInfoHiAppEvent_AppEventInfo 369``` 370**Description** 371Defines a struct for the information about a single event, including the event domain, event name, event type, and custom parameter list in JSON string format. 372 373**Since**: 12 374 375 376### HiAppEvent_Config 377 378``` 379typedef struct HiAppEvent_ConfigHiAppEvent_Config 380``` 381**Description** 382Defines a struct for the configuration object used to set the conditions for triggering system events. 383 384**Since**: 15 385 386 387### HiAppEvent_Processor 388 389``` 390typedef struct HiAppEvent_ProcessorHiAppEvent_Processor 391``` 392**Description** 393Defines a struct for the processor for application events. 394 395**Since**: 18 396 397 398### HiAppEvent_Watcher 399 400``` 401typedef struct HiAppEvent_WatcherHiAppEvent_Watcher 402``` 403**Description** 404Defines a struct for the watcher for application events. 405 406**System capability**: SystemCapability.HiviewDFX.HiAppEvent 407 408**Since**: 12 409 410 411### OH_HiAppEvent_OnReceive 412 413``` 414typedef void(* OH_HiAppEvent_OnReceive) (const char *domain, const struct HiAppEvent_AppEventGroup *appEventGroups, uint32_t groupLen) 415``` 416**Description** 417Defines a callback invoked to pass event content to the caller. 418 419Note: 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. 420 421**Since**: 12 422 423**Parameters** 424 425| Name| Description| 426| -------- | -------- | 427| domain | Domain of the received application event. | 428| appEventGroups | Event group array. | 429| groupLen | Length of the event group array. | 430 431 432### OH_HiAppEvent_OnTake 433 434``` 435typedef void(* OH_HiAppEvent_OnTake) (const char *const *events, uint32_t eventLen) 436``` 437**Description** 438Defines a callback invoked to pass the events received by the watcher to the caller when OH_HiAppEvent_TakeWatcherData is used to obtain the events. 439 440Note: 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. 441 442**Since**: 12 443 444**Parameters** 445 446| Name| Description| 447| -------- | -------- | 448| events | Event array in JSON string format. | 449| eventLen | Size of the event array. | 450 451 452### OH_HiAppEvent_OnTrigger 453 454``` 455typedef void(* OH_HiAppEvent_OnTrigger) (int row, int size) 456``` 457**Description** 458Defines a callback invoked if the event received by the watcher meets the conditions specified by **OH_HiAppEvent_SetTriggerCondition**. When the **OH_HiAppEvent_OnReceive** callback is not set in the watcher, the event received by the watcher will be saved. 459 460 After the callback is complete, if a newly saved event meets the specified condition, the callback is invoked again. 461 462**Since**: 12 463 464**Parameters** 465 466| Name| Description| 467| -------- | -------- | 468| row | Number of events newly received by the watcher. | 469| 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. | 470 471 472### ParamList 473 474``` 475typedef struct ParamListNode* ParamList 476``` 477**Description** 478Defines a struct for the event parameter list node. 479 480**Since**: 8 481 482 483## Enum Description 484 485 486### EventType 487 488``` 489enum EventType 490``` 491**Description** 492Enumerates the event types. 493 494You are advised to select an event type based on the application scenario. 495 496**Since**: 8 497 498| Value| Description| 499| -------- | -------- | 500| FAULT | Fault event. | 501| STATISTIC | Statistics event. | 502| SECURITY | Security event. | 503| BEHAVIOR | Behavior event. | 504 505 506### HiAppEvent_ErrorCode 507 508``` 509enum HiAppEvent_ErrorCode 510``` 511**Description** 512Enumerates the error codes used in the HiAppEvent module. 513 514**Since**: 15 515 516| Value| Description| 517| -------- | -------- | 518| HIAPPEVENT_SUCCESS | The operation is successful. | 519| HIAPPEVENT_INVALID_PARAM_VALUE_LENGTH | The parameter value length is invalid.<br>**Since**: 18| 520| HIAPPEVENT_PROCESSOR_IS_NULL | The processor is null.<br>**Since**: 18| 521| HIAPPEVENT_PROCESSOR_NOT_FOUND | The processor is not found. <br/**Since**: 18| 522| HIAPPEVENT_INVALID_PARAM_VALUE | The parameter value is invalid. | 523| HIAPPEVENT_EVENT_CONFIG_IS_NULL | The event configuration is null. | 524| HIAPPEVENT_OPERATE_FAILED | The operation failed.<br>**Since**: 18| 525| HIAPPEVENT_INVALID_UID | The user ID is invalid.<br>**Since**: 18| 526 527 528## Function Description 529 530 531### OH_HiAppEvent_AddBoolArrayParam() 532 533``` 534ParamList OH_HiAppEvent_AddBoolArrayParam (ParamList list, const char * name, const bool * booleans, int arrSize ) 535``` 536**Description** 537Adds an event parameter of the Boolean 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| booleans | 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_AddBoolParam() 556 557``` 558ParamList OH_HiAppEvent_AddBoolParam (ParamList list, const char * name, bool boolean ) 559``` 560**Description** 561Adds an event parameter of the Boolean 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| boolean | 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_AddDoubleArrayParam() 579 580``` 581ParamList OH_HiAppEvent_AddDoubleArrayParam (ParamList list, const char * name, const double * nums, int arrSize ) 582``` 583**Description** 584Adds an event parameter of the double 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_AddDoubleParam() 603 604``` 605ParamList OH_HiAppEvent_AddDoubleParam (ParamList list, const char * name, double num ) 606``` 607**Description** 608Adds an event parameter of the Double 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_AddFloatArrayParam() 626 627``` 628ParamList OH_HiAppEvent_AddFloatArrayParam (ParamList list, const char * name, const float * nums, int arrSize ) 629``` 630**Description** 631Adds an event parameter of the float 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_AddFloatParam() 650 651``` 652ParamList OH_HiAppEvent_AddFloatParam (ParamList list, const char * name, float num ) 653``` 654**Description** 655Adds an event parameter of the float 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_AddInt16ArrayParam() 673 674``` 675ParamList OH_HiAppEvent_AddInt16ArrayParam (ParamList list, const char * name, const int16_t * nums, int arrSize ) 676``` 677**Description** 678Adds an event parameter of the int16_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_AddInt16Param() 697 698``` 699ParamList OH_HiAppEvent_AddInt16Param (ParamList list, const char * name, int16_t num ) 700``` 701**Description** 702Adds an event parameter of the int16_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_AddInt32ArrayParam() 720 721``` 722ParamList OH_HiAppEvent_AddInt32ArrayParam (ParamList list, const char * name, const int32_t * nums, int arrSize ) 723``` 724**Description** 725Adds an event parameter of the int32_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_AddInt32Param() 744 745``` 746ParamList OH_HiAppEvent_AddInt32Param (ParamList list, const char * name, int32_t num ) 747``` 748**Description** 749Adds an event parameter of the int32_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_AddInt64ArrayParam() 767 768``` 769ParamList OH_HiAppEvent_AddInt64ArrayParam (ParamList list, const char * name, const int64_t * nums, int arrSize ) 770``` 771**Description** 772Adds an event parameter of the int64_t 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| nums | 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_AddInt64Param() 791 792``` 793ParamList OH_HiAppEvent_AddInt64Param (ParamList list, const char * name, int64_t num ) 794``` 795**Description** 796Adds an event parameter of the int64_t 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| num | 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_AddInt8ArrayParam() 814 815``` 816ParamList OH_HiAppEvent_AddInt8ArrayParam (ParamList list, const char * name, const int8_t * nums, int arrSize ) 817``` 818**Description** 819Adds an event parameter of the int8_t array type to the parameter list. 820 821**Since**: 8 822 823**Parameters** 824 825| Name| Description| 826| -------- | -------- | 827| list | Pointer to the parameter list to which parameters need to be added. | 828| name | Name of the parameter to be added. | 829| nums | Value of the parameter to be added. | 830| arrSize | Size of the parameter array to be added. | 831 832**Returns** 833 834Pointer to the parameter list that contains the parameters added. 835 836 837### OH_HiAppEvent_AddInt8Param() 838 839``` 840ParamList OH_HiAppEvent_AddInt8Param (ParamList list, const char * name, int8_t num ) 841``` 842**Description** 843Adds an event parameter of the int8_t type to the parameter list. 844 845**Since**: 8 846 847**Parameters** 848 849| Name| Description| 850| -------- | -------- | 851| list | Pointer to the parameter list to which parameters need to be added. | 852| name | Name of the parameter to be added. | 853| num | Value of the parameter to be added. | 854 855**Returns** 856 857Pointer to the parameter list that contains the parameters added. 858 859 860### OH_HiAppEvent_AddProcessor() 861 862``` 863int64_t OH_HiAppEvent_AddProcessor (HiAppEvent_Processor * processor) 864``` 865**Description** 866Adds a processor. You can add a processor to migrate event data to the cloud. You can preset the implementation of the processor on the device and set its properties based on its constraints. 867 868Note that the configuration information of **Processor** must be provided by the data processor. Yet, as no data processor is preset in the device for interaction for the moment, migrating events to the cloud is unavailable. 869 870**Since**: 18 871 872**Parameters** 873 874| Name| Description| 875| -------- | -------- | 876| processor | Pointer to the processor, that is, the pointer returned by **OH_HiAppEvent_CreateProcessor**. | 877 878**Returns** 879 880Unique ID of the processor is returned when the API is successfully called. The value is greater than 0. 881 882**HIAPPEVENT_PROCESSOR_IS_NULL**: The input parameter of the processor is empty. 883 884**HIAPPEVENT_INVALID_PARAM_VALUE**: The parameter value is invalid. 885 886**HIAPPEVENT_OPERATE_FAILED** is returned when the data processor name is not found or fails to be registered. 887 888**HIAPPEVENT_INVALID_UID**: The user ID is invalid. 889 890For details, see [HiAppEvent_ErrorCode](#hiappevent_errorcode). 891 892 893### OH_HiAppEvent_AddStringArrayParam() 894 895``` 896ParamList OH_HiAppEvent_AddStringArrayParam (ParamList list, const char * name, const char *const * strs, int arrSize ) 897``` 898**Description** 899Adds a parameter of the string array type to the parameter list. 900 901**Since**: 8 902 903**Parameters** 904 905| Name| Description| 906| -------- | -------- | 907| list | Pointer to the parameter list to which parameters need to be added. | 908| name | Name of the parameter to be added. | 909| strs | Value of the parameter to be added. | 910| arrSize | Size of the parameter array to be added. | 911 912**Returns** 913 914Pointer to the parameter list that contains the parameters added. 915 916 917### OH_HiAppEvent_AddStringParam() 918 919``` 920ParamList OH_HiAppEvent_AddStringParam (ParamList list, const char * name, const char * str ) 921``` 922**Description** 923Adds a parameter of the string type to the parameter list. 924 925**Since**: 8 926 927**Parameters** 928 929| Name| Description| 930| -------- | -------- | 931| list | Pointer to the parameter list to which parameters need to be added. | 932| name | Name of the parameter to be added. | 933| str | Value of the parameter to be added. | 934 935**Returns** 936 937Pointer to the parameter list that contains the parameters added. 938 939 940### OH_HiAppEvent_AddWatcher() 941 942``` 943int OH_HiAppEvent_AddWatcher (HiAppEvent_Watcher * watcher) 944``` 945**Description** 946Adds a watcher. Once a watcher is added, it starts to listen for system messages. 947 948**Since**: 12 949 950**Parameters** 951 952| Name| Description| 953| -------- | -------- | 954| watcher | Pointer to the watcher (that is, the pointer returned by OH_HiAppEvent_CreateWatcher). | 955 956**Returns** 957 958**0** if the API is called successfully; **-5** if the pointer to an input parameter is null. 959 960 961### OH_HiAppEvent_ClearData() 962 963``` 964void OH_HiAppEvent_ClearData () 965``` 966**Description** 967Clears the events saved by all watchers. 968 969**Since**: 12 970 971 972### OH_HiAppEvent_Configure() 973 974``` 975bool OH_HiAppEvent_Configure (const char * name, const char * value ) 976``` 977**Description** 978Configures the application event logging function. 979 980This function is used to configure the event logging function and the storage quota of the event file directory. 981 982**Since**: 8 983 984**Parameters** 985 986| Name| Description| 987| -------- | -------- | 988| name | Configuration item name. The value can be set to [DISABLE](#disable) or [MAX_STORAGE](#max_storage). | 989| value | Configuration item value. If the configuration item name is [DISABLE](#disable), the value can be **true** or **false**.<br>If the configuration item name is [MAX_STORAGE](#max_storage), the quota value can contain only digits and the unit character. The unit character can be **b**\|**k**\|**kb**\|**m**\|**mb**\|**g**\|**gb**\|**t**\|**tb**, which is case insensitive.<br>The quota value must start with a digit. You can determine whether to pass the unit. If the unit is left empty, **b** (that is, byte) is used by default.| 990 991**Returns** 992 993Configuration result. The value **true** indicates that the configuration is successful, and the value **false** indicates the opposite. 994 995 996### OH_HiAppEvent_CreateConfig() 997 998``` 999HiAppEvent_Config* OH_HiAppEvent_CreateConfig (void ) 1000``` 1001**Description** 1002Creates a pointer to the configuration object that sets the conditions for triggering system events. 1003 1004**Since**: 15 1005 1006**Returns** 1007 1008Pointer to the configuration object that sets the conditions for triggering system events. 1009 1010 1011### OH_HiAppEvent_CreateParamList() 1012 1013``` 1014ParamList OH_HiAppEvent_CreateParamList (void ) 1015``` 1016**Description** 1017Creates a pointer to a parameter list object. 1018 1019**Since**: 8 1020 1021**Returns** 1022 1023Pointer to the parameter list object. 1024 1025 1026### OH_HiAppEvent_CreateProcessor() 1027 1028``` 1029HiAppEvent_Processor* OH_HiAppEvent_CreateProcessor (const char * name) 1030``` 1031**Description** 1032Creates a processor for application events. 1033 1034Note: If a processor is no longer used, call **OH_HiAppEvent_DestroyProcessor** to destroy it. 1035 1036**Since**: 18 1037 1038**Parameters** 1039 1040| Name| Description| 1041| -------- | -------- | 1042| name | Processor name, which can contain only letters, digits, underscores (_), and dollar signs ($). It cannot start with a digit and cannot exceed 256 characters. | 1043 1044**Returns** 1045 1046Pointer to the new processor if the API is called successfully; **nullptr** if the **name** parameter is invalid. 1047 1048 1049### OH_HiAppEvent_CreateWatcher() 1050 1051``` 1052HiAppEvent_Watcher* OH_HiAppEvent_CreateWatcher (const char * name) 1053``` 1054**Description** 1055Creates a watcher for application events. 1056 1057Note: If a created watcher is no longer used, you are required to destroy it by calling OH_HiAppEvent_DestroyWatcher. 1058 1059**Since**: 12 1060 1061**Parameters** 1062 1063| Name| Description| 1064| -------- | -------- | 1065| name | Watcher name. | 1066 1067**Returns** 1068 1069Pointer to the new watcher if the API is called successfully; **nullptr** if the **name** parameter is invalid. 1070 1071 1072### OH_HiAppEvent_DestroyConfig() 1073 1074``` 1075void OH_HiAppEvent_DestroyConfig (HiAppEvent_Config * config) 1076``` 1077**Description** 1078Destroys a configuration object. 1079 1080Note: If a configuration object is no longer used, destroy it to release memory to prevent memory leaks. After the object is destroyed, set its pointer to null. 1081 1082**Since**: 15 1083 1084**Parameters** 1085 1086| Name| Description| 1087| -------- | -------- | 1088| config | Pointer to the configuration object, that is, the pointer returned by the **OH_HiAppEvent_CreateConfig** API. | 1089 1090 1091### OH_HiAppEvent_DestroyParamList() 1092 1093``` 1094void OH_HiAppEvent_DestroyParamList (ParamList list) 1095``` 1096**Description** 1097Destroys a pointer to a parameter list object and releases its allocated memory. 1098 1099**Since**: 8 1100 1101**Parameters** 1102 1103| Name| Description| 1104| -------- | -------- | 1105| list | Pointer to the parameter list object. | 1106 1107 1108### OH_HiAppEvent_DestroyProcessor() 1109 1110``` 1111void OH_HiAppEvent_DestroyProcessor (HiAppEvent_Processor * processor) 1112``` 1113**Description** 1114Destroys a processor. 1115 1116Note: If a processor is no longer used, destroy it to release memory to prevent memory leaks. After the processor is destroyed, set its pointer to null. 1117 1118**Since**: 18 1119 1120**Parameters** 1121 1122| Name| Description| 1123| -------- | -------- | 1124| processor | Pointer to the processor, that is, the pointer returned by **OH_HiAppEvent_CreateProcessor**. | 1125 1126 1127### OH_HiAppEvent_DestroyWatcher() 1128 1129``` 1130void OH_HiAppEvent_DestroyWatcher (HiAppEvent_Watcher * watcher) 1131``` 1132**Description** 1133Destroys a created watcher. 1134 1135Note: If a created watcher is no longer used, destroy it to release memory to prevent memory leaks. After the watcher is destroyed, set its pointer to null. 1136 1137**Since**: 12 1138 1139**Parameters** 1140 1141| Name| Description| 1142| -------- | -------- | 1143| watcher | Pointer to the watcher (that is, the pointer returned by OH_HiAppEvent_CreateWatcher). | 1144 1145 1146### OH_HiAppEvent_RemoveProcessor() 1147 1148``` 1149int OH_HiAppEvent_RemoveProcessor (int64_t processorId) 1150``` 1151**Description** 1152Removes a processor. Once a processor is removed, it stops reporting events. 1153 1154Note: This API only stops the processor reporting events but does not destroy the processor. You can call **OH_HiAppEvent_DestroyProcessor** to destroy the processor and release the memory. 1155 1156**Since**: 18 1157 1158**Parameters** 1159 1160| Name| Description| 1161| -------- | -------- | 1162| processorId | Unique ID of a processor. | 1163 1164**Returns** 1165 1166**HIAPPEVENT_SUCCESS**: The API is successfully called. 1167 1168**HIAPPEVENT_PROCESSOR_NOT_FOUND**: The processor is not found. 1169 1170**HIAPPEVENT_OPERATE_FAILED**: The operation fails. 1171 1172**HIAPPEVENT_INVALID_UID**: The user ID is invalid. 1173 1174For details, see [HiAppEvent_ErrorCode](#hiappevent_errorcode). 1175 1176 1177### OH_HiAppEvent_RemoveWatcher() 1178 1179``` 1180int OH_HiAppEvent_RemoveWatcher (HiAppEvent_Watcher * watcher) 1181``` 1182**Description** 1183Removes a watcher. Once a watcher is removed, it stops listening for system messages. 1184 1185Note: 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. 1186 1187**Since**: 12 1188 1189**Parameters** 1190 1191| Name| Description| 1192| -------- | -------- | 1193| watcher | Pointer to the watcher (that is, the pointer returned by OH_HiAppEvent_CreateWatcher). | 1194 1195**Returns** 1196 1197**0** if the API is called successfully; **-5** if the pointer to an input parameter is null; **-6** if **OH_HiAppEvent_AddWatcher** has not been called to add a watcher. 1198 1199 1200### OH_HiAppEvent_SetAppEventFilter() 1201 1202``` 1203int OH_HiAppEvent_SetAppEventFilter (HiAppEvent_Watcher * watcher, const char * domain, uint8_t eventTypes, const char *const * names, int namesLen ) 1204``` 1205**Description** 1206Sets the type of events to listen for. 1207 1208This 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. 1209 1210**Since**: 12 1211 1212**Parameters** 1213 1214| Name| Description| 1215| -------- | -------- | 1216| watcher | Pointer to the watcher (that is, the pointer returned by OH_HiAppEvent_CreateWatcher). | 1217| domain | Domain of events to be listened for. | 1218| eventTypes | Types of events to be listened for. The bitwise AND matching mode is used. Multiple types of events can be listened for. If the first bit is **1** (the value is **1**), fault events can be listened for.<br>If the second bit is **1** (the value is **2**), statistics events can be listened for.<br>If the third bit is **1** (the value is **4**), security events can be listened for.<br>If the fourth digit is **1** (the value is **8**), events of the listening behavior type can be listened for.<br>If four digits are **1** (the value is **15**) or 0 (the value is **0**), events of all types can be listened for.| 1219| names | Array of the event names. | 1220| namesLen | Length of the event name array. | 1221 1222**Returns** 1223 1224**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 to an input parameter is null. 1225 1226 1227### OH_HiAppEvent_SetConfigId() 1228 1229``` 1230int OH_HiAppEvent_SetConfigId (HiAppEvent_Processor * processor, int configId ) 1231``` 1232**Description** 1233Sets the configuration ID of the processor. 1234 1235**Since**: 18 1236 1237**Parameters** 1238 1239| Name| Description| 1240| -------- | -------- | 1241| processor | Pointer to the processor, that is, the pointer returned by **OH_HiAppEvent_CreateProcessor**. | 1242| configId | Configuration ID of the processor, which is a natural number. | 1243 1244**Returns** 1245 1246**HIAPPEVENT_SUCCESS**: The API is successfully called. 1247 1248**HIAPPEVENT_PROCESSOR_IS_NULL**: The input parameter of the processor is empty. 1249 1250**HIAPPEVENT_INVALID_PARAM_VALUE**: The parameter value is invalid. 1251 1252**HIAPPEVENT_INVALID_UID**: The user ID is invalid. 1253 1254For details, see [HiAppEvent_ErrorCode](#hiappevent_errorcode). 1255 1256 1257### OH_HiAppEvent_SetConfigItem() 1258 1259``` 1260int OH_HiAppEvent_SetConfigItem (HiAppEvent_Config * config, const char * itemName, const char * itemValue ) 1261``` 1262**Description** 1263Sets the items in the configuration object. 1264 1265**Since**: 15 1266 1267**Parameters** 1268 1269| Name| Description| 1270| -------- | -------- | 1271| config | Pointer to the configuration object, that is, the pointer returned by the **OH_HiAppEvent_CreateConfig** API. | 1272| itemName | Name of the configuration item. | 1273| itemValue | Value of the configuration item. | 1274 1275**Returns** 1276 1277**HIAPPEVENT_SUCCESS**: The API is successfully called. 1278 1279**HIAPPEVENT_EVENT_CONFIG_IS_NULL**: The pointer to the configuration object is null. 1280 1281**HIAPPEVENT_INVALID_PARAM_VALUE**: The configuration item is invalid. 1282 1283For details, see [HiAppEvent_ErrorCode](#hiappevent_errorcode). 1284 1285 1286### OH_HiAppEvent_SetCustomConfig() 1287 1288``` 1289int OH_HiAppEvent_SetCustomConfig (HiAppEvent_Processor * processor, const char * key, const char * value ) 1290``` 1291**Description** 1292Sets the custom extension parameters of the processor. 1293 1294**Since**: 18 1295 1296**Parameters** 1297 1298| Name| Description| 1299| -------- | -------- | 1300| processor | Pointer to the processor, that is, the pointer returned by **OH_HiAppEvent_CreateProcessor**. | 1301| key | Parameter name, which contains a maximum of 32 characters. | 1302| value | Parameter value, which contains a maximum of 1024 characters. | 1303 1304**Returns** 1305 1306**HIAPPEVENT_SUCCESS**: The API is successfully called. 1307 1308**HIAPPEVENT_PROCESSOR_IS_NULL**: The input parameter of the processor is empty. 1309 1310**HIAPPEVENT_INVALID_PARAM_VALUE**: The parameter value is invalid. 1311 1312**HIAPPEVENT_INVALID_UID**: The user ID is invalid. 1313 1314**HIAPPEVENT_INVALID_PARAM_VALUE_LENGTH**: The parameter value length is invalid. 1315 1316For details, see [HiAppEvent_ErrorCode](#hiappevent_errorcode). 1317 1318 1319### OH_HiAppEvent_SetEventConfig() 1320 1321``` 1322int OH_HiAppEvent_SetEventConfig (const char * name, HiAppEvent_Config * config ) 1323``` 1324**Description** 1325Sets the conditions for triggering system event subscription. 1326 1327**Since**: 15 1328 1329**Parameters** 1330 1331| Name| Description| 1332| -------- | -------- | 1333| name | Name of the system event. | 1334| config | Pointer to the configuration object, that is, the pointer returned by the **OH_HiAppEvent_CreateConfig** API. | 1335 1336**Returns** 1337 1338**HIAPPEVENT_SUCCESS**: The API is successfully called. 1339 1340**HIAPPEVENT_INVALID_PARAM_VALUE**: The parameter is invalid. 1341 1342For details, see [HiAppEvent_ErrorCode](#hiappevent_errorcode). 1343 1344 1345### OH_HiAppEvent_SetReportEvent() 1346 1347``` 1348int OH_HiAppEvent_SetReportEvent (HiAppEvent_Processor * processor, const char * domain, const char * name, bool isRealTime ) 1349``` 1350**Description** 1351Sets the report event for the processor. 1352 1353**Since**: 18 1354 1355**Parameters** 1356 1357| Name| Description| 1358| -------- | -------- | 1359| processor | Pointer to the processor, that is, the pointer returned by **OH_HiAppEvent_CreateProcessor**. | 1360| domain | Domain of the report event. | 1361| name | Name of the report event. | 1362| isRealTime | Whether to report events in real time. | 1363 1364**Returns** 1365 1366**HIAPPEVENT_SUCCESS**: The API is successfully called. 1367 1368**HIAPPEVENT_PROCESSOR_IS_NULL**: The input parameter of the processor is empty. 1369 1370**HIAPPEVENT_INVALID_PARAM_VALUE**: The parameter value is invalid. 1371 1372**HIAPPEVENT_INVALID_UID**: The user ID is invalid. 1373 1374For details, see [HiAppEvent_ErrorCode](#hiappevent_errorcode). 1375 1376 1377### OH_HiAppEvent_SetReportPolicy() 1378 1379``` 1380int OH_HiAppEvent_SetReportPolicy (HiAppEvent_Processor * processor, int periodReport, int batchReport, bool onStartReport, bool onBackgroundReport ) 1381``` 1382**Description** 1383Sets the report policy for the processor. 1384 1385**Since**: 18 1386 1387**Parameters** 1388 1389| Name| Description| 1390| -------- | -------- | 1391| processor | Pointer to the processor, that is, the pointer returned by **OH_HiAppEvent_CreateProcessor**. | 1392| periodReport | Period for reporting events, in seconds. | 1393| batchReport | Threshold for reporting events. When the number of events reaches the threshold, an event is reported. | 1394| onStartReport | Whether to report an event when the processor is started. The default value is **false**. | 1395| onBackgroundReport | Whether to report an event when an application enters the background. The default value is **false**. | 1396 1397**Returns** 1398 1399**HIAPPEVENT_SUCCESS**: The API is successfully called. 1400 1401**HIAPPEVENT_PROCESSOR_IS_NULL**: The input parameter of the processor is empty. 1402 1403**HIAPPEVENT_INVALID_PARAM_VALUE**: The parameter value is invalid. 1404 1405**HIAPPEVENT_INVALID_UID**: The user ID is invalid. 1406 1407For details, see [HiAppEvent_ErrorCode](#hiappevent_errorcode). 1408 1409 1410### OH_HiAppEvent_SetReportRoute() 1411 1412``` 1413int OH_HiAppEvent_SetReportRoute (HiAppEvent_Processor * processor, const char * appId, const char * routeInfo ) 1414``` 1415**Description** 1416Sets the report route for the processor. 1417 1418**Since**: 18 1419 1420**Parameters** 1421 1422| Name| Description| 1423| -------- | -------- | 1424| processor | Pointer to the processor, that is, the pointer returned by **OH_HiAppEvent_CreateProcessor**. | 1425| appId | Application ID of the processor. | 1426| routeInfo | Server location information. The default value is an empty string. The string length cannot exceed 8 KB. Otherwise, the default value is used. | 1427 1428**Returns** 1429 1430**HIAPPEVENT_SUCCESS**: The API is successfully called. 1431 1432**HIAPPEVENT_PROCESSOR_IS_NULL**: The input parameter of the processor is empty. 1433 1434**HIAPPEVENT_INVALID_PARAM_VALUE**: The parameter value is invalid. 1435 1436**HIAPPEVENT_INVALID_UID**: The user ID is invalid. 1437 1438**HIAPPEVENT_INVALID_PARAM_VALUE_LENGTH**: The parameter value length is invalid. 1439 1440For details, see [HiAppEvent_ErrorCode](#hiappevent_errorcode). 1441 1442 1443### OH_HiAppEvent_SetReportUserId() 1444 1445``` 1446int OH_HiAppEvent_SetReportUserId (HiAppEvent_Processor * processor, const char *const * userIdNames, int size ) 1447``` 1448**Description** 1449Sets the report user ID of the processor. 1450 1451**Since**: 18 1452 1453**Parameters** 1454 1455| Name| Description| 1456| -------- | -------- | 1457| processor | Pointer to the processor, that is, the pointer returned by **OH_HiAppEvent_CreateProcessor**. | 1458| userIdNames | Name array of user IDs that can be reported by the processor. | 1459| size | Length of the name array of user IDs. | 1460 1461**Returns** 1462 1463**HIAPPEVENT_SUCCESS**: The API is successfully called. 1464 1465**HIAPPEVENT_PROCESSOR_IS_NULL**: The input parameter of the processor is empty. 1466 1467**HIAPPEVENT_INVALID_PARAM_VALUE**: The parameter value is invalid. 1468 1469**HIAPPEVENT_INVALID_UID**: The user ID is invalid. 1470 1471**HIAPPEVENT_INVALID_PARAM_VALUE_LENGTH**: The parameter value length is invalid. 1472 1473For details, see [HiAppEvent_ErrorCode](#hiappevent_errorcode). 1474 1475 1476### OH_HiAppEvent_SetReportUserProperty() 1477 1478``` 1479int OH_HiAppEvent_SetReportUserProperty (HiAppEvent_Processor * processor, const char *const * userPropertyNames, int size ) 1480``` 1481**Description** 1482Sets the report user property of the processor. 1483 1484**Since**: 18 1485 1486**Parameters** 1487 1488| Name| Description| 1489| -------- | -------- | 1490| processor | Pointer to the processor, that is, the pointer returned by **OH_HiAppEvent_CreateProcessor**. | 1491| userPropertyNames | Name array of user properties that can be reported by the processor. | 1492| size | Length of the name array of user properties. | 1493 1494**Returns** 1495 1496**HIAPPEVENT_SUCCESS**: The API is successfully called. 1497 1498**HIAPPEVENT_PROCESSOR_IS_NULL**: The input parameter of the processor is empty. 1499 1500**HIAPPEVENT_INVALID_PARAM_VALUE**: The parameter value is invalid. 1501 1502**HIAPPEVENT_INVALID_UID**: The user ID is invalid. 1503 1504**HIAPPEVENT_INVALID_PARAM_VALUE_LENGTH**: The parameter value length is invalid. 1505 1506For details, see [HiAppEvent_ErrorCode](#hiappevent_errorcode). 1507 1508 1509### OH_HiAppEvent_SetTriggerCondition() 1510 1511``` 1512int OH_HiAppEvent_SetTriggerCondition (HiAppEvent_Watcher * watcher, int row, int size, int timeOut ) 1513``` 1514**Description** 1515Sets the trigger condition of the **OH_HiAppEvent_OnTrigger** callback. 1516 1517You can set the trigger condition by the number and size of new events received by the watcher, and **onTrigger** timeout interval. Ensure that at least one of the trigger conditions is set on the caller side. 1518 1519**Since**: 12 1520 1521**Parameters** 1522 1523| Name| Description| 1524| -------- | -------- | 1525| watcher | Pointer to the watcher (that is, the pointer returned by OH_HiAppEvent_CreateWatcher). | 1526| 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.<br>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.| 1527| 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. <br>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.| 1528| 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.<br>After the callback is complete, the system checks the watcher for newly received events when the timeout value expires.<br>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.| 1529 1530**Returns** 1531 1532**0** if the API is called successfully; **-5** if the pointer to an input parameter is null. 1533 1534 1535### OH_HiAppEvent_SetWatcherOnReceive() 1536 1537``` 1538int OH_HiAppEvent_SetWatcherOnReceive (HiAppEvent_Watcher * watcher, OH_HiAppEvent_OnReceive onReceive ) 1539``` 1540**Description** 1541Sets the **onReceive** callback. When the listener detects the corresponding event, the onReceive callback is called. 1542 1543**Since**: 12 1544 1545**Parameters** 1546 1547| Name| Description| 1548| -------- | -------- | 1549| watcher | Pointer to the watcher (that is, the pointer returned by OH_HiAppEvent_CreateWatcher). | 1550| onReceive | Pointer to the callback function. | 1551 1552**Returns** 1553 1554**0** if the API is called successfully; **-5** if the pointer to an input parameter is null. 1555 1556 1557### OH_HiAppEvent_SetWatcherOnTrigger() 1558 1559``` 1560int OH_HiAppEvent_SetWatcherOnTrigger (HiAppEvent_Watcher * watcher, OH_HiAppEvent_OnTrigger onTrigger ) 1561``` 1562**Description** 1563Sets the **onTrigger** callback. 1564 1565If **OnReceive** is not set or is set to **nullptr**, the application events received by the watcher will be saved. If the saved application events meet the trigger conditions of the **onTrigger** callback, the **onTrigger** callback will be called. 1566 1567**Since**: 12 1568 1569**Parameters** 1570 1571| Name| Description| 1572| -------- | -------- | 1573| watcher | Pointer to the watcher (that is, the pointer returned by OH_HiAppEvent_CreateWatcher). | 1574| onTrigger | Callback to be set. | 1575 1576**Returns** 1577 1578**0** if the API is called successfully; **-5** if the pointer to an input parameter is null. 1579 1580 1581### OH_HiAppEvent_TakeWatcherData() 1582 1583``` 1584int OH_HiAppEvent_TakeWatcherData (HiAppEvent_Watcher * watcher, uint32_t eventNum, OH_HiAppEvent_OnTake onTake ) 1585``` 1586**Description** 1587Obtains the event saved by the watcher. 1588 1589**Since**: 12 1590 1591**Parameters** 1592 1593| Name| Description| 1594| -------- | -------- | 1595| watcher | Pointer to the watcher (that is, the pointer returned by OH_HiAppEvent_CreateWatcher). | 1596| 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. | 1597| onTake | Pointer to the callback. The event information is returned through this callback. | 1598 1599**Returns** 1600 1601**0** if the API is called successfully; **-5** if the pointer to an input parameter is null; **-6** if **OH_HiAppEvent_AddWatcher** has not been called to add a watcher. 1602 1603 1604### OH_HiAppEvent_Write() 1605 1606``` 1607int OH_HiAppEvent_Write (const char * domain, const char * name, enum EventType type, const ParamList list ) 1608``` 1609**Description** 1610Logs application events whose parameters are of the list type. 1611 1612Before 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. 1613 1614**Since**: 8 1615 1616**Parameters** 1617 1618| Name| Description| 1619| -------- | -------- | 1620| domain | Event domain. You can customize event domains as required.<br>The value is a string that contains a maximum of 32 characters, including digits (0 to 9), letters (a to z), and underscore (\_). It must start with a letter and cannot end with an underscore (\_).| 1621| name | Event name. You can customize event names as required.<br>The value is a 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. | 1622| type | Event type, which is defined in [EventType](#eventtype). | 1623| list | List of event parameters, each of which consists of a parameter name and a parameter value. The specifications are as follows:<br>1.<br>The value is a string that contains a maximum of 32 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 a string, number, Boolean, or array. The length of a string must be less than 8 × 1024 characters. If this limit is exceeded, excess characters will be discarded.<br>The element type of an array parameter can only be a 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.| 1624 1625**Returns** 1626 1627If the event parameters are successfully verified, **0** is returned and the event is written into the event file. 1628 1629If an event contains invalid parameters, a positive value is returned. The event is written into the event file after the invalid parameters are discarded. 1630 1631If the event parameter fails to be verified, a negative value is returned and the event is not written to the event file. 1632**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. 1633