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 the 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) | Defines an event group 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) | 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. | 63| typedef struct [HiAppEvent_AppEventGroup](_hi_app_event___app_event_group.md) [HiAppEvent_AppEventGroup](#hiappevent_appeventgroup) | Defines a struct for the event group with the same event name. | 64| typedef struct ParamListNode \* [ParamList](#paramlist) | Defines a struct for the event parameter list node. | 65| typedef struct [HiAppEvent_Watcher](#hiappevent_watcher) [HiAppEvent_Watcher](#hiappevent_watcher) | Defines a struct for the watcher for application events. | 66| typedef struct [HiAppEvent_Processor](#hiappevent_processor) [HiAppEvent_Processor](#hiappevent_processor) | Defines a struct for the processor for application events. | 67| 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. | 68| 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. | 69| 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. After the callback is complete, if a newly saved event meets the specified condition, the callback is invoked again. | 70| 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. | 71 72 73### Enums 74 75| Name| Description| 76| -------- | -------- | 77| [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. | 78| [EventType](#eventtype) {<br>FAULT = 1, <br>STATISTIC = 2, <br>SECURITY = 3, <br>BEHAVIOR = 4 <br>} | Enumerates the event types. | 79 80 81### Functions 82 83| Name| Description| 84| -------- | -------- | 85| [ParamList](#paramlist) [OH_HiAppEvent_CreateParamList](#oh_hiappevent_createparamlist) (void) | Creates a pointer to a parameter list object. | 86| void [OH_HiAppEvent_DestroyParamList](#oh_hiappevent_destroyparamlist) ([ParamList](#paramlist) list) | Destroys a pointer to a parameter list object and releases its allocated memory. | 87| [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. | 88| [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. | 89| [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. | 90| [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. | 91| [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. | 92| [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. | 93| [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. | 94| [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. | 95| [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. | 96| [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. | 97| [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. | 98| [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. | 99| [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. | 100| [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. | 101| [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. | 102| [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. | 103| 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. | 104| bool [OH_HiAppEvent_Configure](#oh_hiappevent_configure) (const char \*name, const char \*value) | Configures the application event logging function. | 105| [HiAppEvent_Watcher](#hiappevent_watcher) \* [OH_HiAppEvent_CreateWatcher](#oh_hiappevent_createwatcher) (const char \*name) | Creates a watcher for application events. | 106| void [OH_HiAppEvent_DestroyWatcher](#oh_hiappevent_destroywatcher) ([HiAppEvent_Watcher](#hiappevent_watcher) \*watcher) | Destroys a created watcher. | 107| int [OH_HiAppEvent_SetTriggerCondition](#oh_hiappevent_settriggercondition) ([HiAppEvent_Watcher](#hiappevent_watcher) \*watcher, int row, int size, int timeOut) | Sets the trigger conditions of 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. | 108| 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. | 109| int [OH_HiAppEvent_SetWatcherOnTrigger](#oh_hiappevent_setwatcherontrigger) ([HiAppEvent_Watcher](#hiappevent_watcher) \*watcher, [OH_HiAppEvent_OnTrigger](#oh_hiappevent_ontrigger) onTrigger) | Sets the **onTrigger** callback. | 110| 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. | 111| 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. | 112| 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. | 113| 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. | 114| void [OH_HiAppEvent_ClearData](#oh_hiappevent_cleardata) (void) | Clears the events saved by all watchers. | 115| [HiAppEvent_Processor](#hiappevent_processor) \* [OH_HiAppEvent_CreateProcessor](#oh_hiappevent_createprocessor) (const char \*name) | Creates a processor for application events. | 116| 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. | 117| 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. | 118| 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. | 119| 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. | 120| int [OH_HiAppEvent_SetConfigId](#oh_hiappevent_setconfigid) ([HiAppEvent_Processor](#hiappevent_processor) \*processor, int configId) | Sets the configuration ID of the processor. | 121| 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. | 122| 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. | 123| 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. | 124| void [OH_HiAppEvent_DestroyProcessor](#oh_hiappevent_destroyprocessor) ([HiAppEvent_Processor](#hiappevent_processor) \*processor) | Destroys a processor. | 125| int [OH_HiAppEvent_RemoveProcessor](#oh_hiappevent_removeprocessor) (int64_t processorId) | Removes a processor. Once a processor is removed, it stops reporting events. | 126| [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. | 127| void [OH_HiAppEvent_DestroyConfig](#oh_hiappevent_destroyconfig) ([HiAppEvent_Config](#hiappevent_config) \*config) | Destroys a configuration object. | 128| 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. | 129| int [OH_HiAppEvent_SetEventConfig](#oh_hiappevent_seteventconfig) (const char \*name, [HiAppEvent_Config](#hiappevent_config) \*config) | Sets the conditions for triggering system event subscription. | 130 131 132## Macro Description 133 134 135### DISABLE 136 137``` 138#define DISABLE "disable" 139``` 140**Description** 141Whether 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. 142 143**Since**: 8 144 145 146### DOMAIN_OS 147 148``` 149#define DOMAIN_OS "OS" 150``` 151**Description** 152OS scope. 153 154**Since**: 12 155 156 157### EVENT_APP_CRASH 158 159``` 160#define EVENT_APP_CRASH "APP_CRASH" 161``` 162**Description** 163Application crash event. 164 165**Since**: 12 166 167 168### EVENT_APP_FREEZE 169 170``` 171#define EVENT_APP_FREEZE "APP_FREEZE" 172``` 173**Description** 174Application freeze event. 175 176**Since**: 12 177 178 179### EVENT_APP_LAUNCH 180 181``` 182#define EVENT_APP_LAUNCH "APP_LAUNCH" 183``` 184**Description** 185Application loading event. 186 187**Since**: 12 188 189 190### EVENT_BATTERY_USAGE 191 192``` 193#define EVENT_BATTERY_USAGE "BATTERY_USAGE" 194``` 195**Description** 196Application power usage event. 197 198**Since**: 12 199 200 201### EVENT_CPU_USAGE_HIGH 202 203``` 204#define EVENT_CPU_USAGE_HIGH "CPU_USAGE_HIGH" 205``` 206**Description** 207Event indicating high CPU usage of an application. 208 209**Since**: 12 210 211 212### EVENT_DISTRIBUTED_SERVICE_START 213 214``` 215#define EVENT_DISTRIBUTED_SERVICE_START "hiappevent.distributed_service_start" 216``` 217**Description** 218Distributed service event. 219 220**Since**: 8 221 222 223### EVENT_RESOURCE_OVERLIMIT 224 225``` 226#define EVENT_RESOURCE_OVERLIMIT "RESOURCE_OVERLIMIT" 227``` 228**Description** 229Application resource threshold-crossing event. 230 231**Since**: 12 232 233 234### EVENT_SCROLL_JANK 235 236``` 237#define EVENT_SCROLL_JANK "SCROLL_JANK" 238``` 239**Description** 240Event indicating application freeze during swiping. 241 242**Since**: 12 243 244 245### EVENT_USER_LOGIN 246 247``` 248#define EVENT_USER_LOGIN "hiappevent.user_login" 249``` 250**Description** 251User login event. 252 253**Since**: 8 254 255 256### EVENT_USER_LOGOUT 257 258``` 259#define EVENT_USER_LOGOUT "hiappevent.user_logout" 260``` 261**Description** 262User logout event. 263 264**Since**: 8 265 266 267### MAX_STORAGE 268 269``` 270#define MAX_STORAGE "max_storage" 271``` 272**Description** 273Storage quota of the event file directory. The default value is **10M**. 274 275**Since**: 8 276 277 278### PARAM_DISTRIBUTED_SERVICE_INSTANCE_ID 279 280``` 281#define PARAM_DISTRIBUTED_SERVICE_INSTANCE_ID "ds_instance_id" 282``` 283**Description** 284Distributed service instance ID. 285 286**Since**: 8 287 288 289### PARAM_DISTRIBUTED_SERVICE_NAME 290 291``` 292#define PARAM_DISTRIBUTED_SERVICE_NAME "ds_name" 293``` 294**Description** 295Distributed service name. 296 297**Since**: 8 298 299 300### PARAM_USER_ID 301 302``` 303#define PARAM_USER_ID "user_id" 304``` 305**Description** 306User ID. 307 308**Since**: 8 309 310 311## Type Description 312 313 314### HiAppEvent_AppEventGroup 315 316``` 317typedef struct HiAppEvent_AppEventGroupHiAppEvent_AppEventGroup 318``` 319**Description** 320Defines a struct for the event group with the same event name. 321 322**System capability**: SystemCapability.HiviewDFX.HiAppEvent 323 324**Since**: 12 325 326 327### HiAppEvent_AppEventInfo 328 329``` 330typedef struct HiAppEvent_AppEventInfoHiAppEvent_AppEventInfo 331``` 332**Description** 333Defines 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. 334 335**System capability**: SystemCapability.HiviewDFX.HiAppEvent 336 337**Since**: 12 338 339 340### HiAppEvent_Config 341 342``` 343typedef struct HiAppEvent_ConfigHiAppEvent_Config 344``` 345**Description** 346Defines a struct for the configuration object used to set the conditions for triggering system events. 347 348**System capability**: SystemCapability.HiviewDFX.HiAppEvent 349 350**Since**: 15 351 352 353### HiAppEvent_Processor 354 355``` 356typedef struct HiAppEvent_ProcessorHiAppEvent_Processor 357``` 358**Description** 359Defines a struct for the processor for application events. 360 361**Since**: 18 362 363 364### HiAppEvent_Watcher 365 366``` 367typedef struct HiAppEvent_WatcherHiAppEvent_Watcher 368``` 369**Description** 370Defines a struct for the watcher for application events. 371 372**System capability**: SystemCapability.HiviewDFX.HiAppEvent 373 374**Since**: 12 375 376 377### OH_HiAppEvent_OnReceive 378 379``` 380typedef void(* OH_HiAppEvent_OnReceive) (const char *domain, const struct HiAppEvent_AppEventGroup *appEventGroups, uint32_t groupLen) 381``` 382**Description** 383Defines a callback invoked to pass event content to the caller. 384 385Note: 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. 386 387**System capability**: SystemCapability.HiviewDFX.HiAppEvent 388 389**Since**: 12 390 391**Parameters** 392 393| Name| Description| 394| -------- | -------- | 395| domain | Domain of the received application event. | 396| appEventGroups | Event group array. | 397| groupLen | Length of the event group array. | 398 399 400### OH_HiAppEvent_OnTake 401 402``` 403typedef void(* OH_HiAppEvent_OnTake) (const char *const *events, uint32_t eventLen) 404``` 405**Description** 406Defines a callback invoked to pass the events received by the watcher to the caller when OH_HiAppEvent_TakeWatcherData is used to obtain the events. 407 408Note: 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. 409 410**System capability**: SystemCapability.HiviewDFX.HiAppEvent 411 412**Since**: 12 413 414**Parameters** 415 416| Name| Description| 417| -------- | -------- | 418| events | Event array in JSON string format. | 419| eventLen | Size of the event array. | 420 421 422### OH_HiAppEvent_OnTrigger 423 424``` 425typedef void(* OH_HiAppEvent_OnTrigger) (int row, int size) 426``` 427**Description** 428Defines 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. After the callback is complete, if a newly saved event meets the specified condition, the callback is invoked again. 429 430**System capability**: SystemCapability.HiviewDFX.HiAppEvent 431 432**Since**: 12 433 434**Parameters** 435 436| Name| Description| 437| -------- | -------- | 438| row | Number of events newly received by the watcher. | 439| 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. | 440 441 442### ParamList 443 444``` 445typedef struct ParamListNode* ParamList 446``` 447**Description** 448Defines a struct for the event parameter list node. 449 450**Since**: 8 451 452 453## Enum Description 454 455 456### EventType 457 458``` 459enum EventType 460``` 461**Description** 462Enumerates the event types. 463 464You are advised to select different event types based on application scenarios. 465 466**Since**: 8 467 468| Value| Description| 469| -------- | -------- | 470| FAULT | Fault event. | 471| STATISTIC | Statistics event. | 472| SECURITY | Security event. | 473| BEHAVIOR | Behavior event. | 474 475 476### HiAppEvent_ErrorCode 477 478``` 479enum HiAppEvent_ErrorCode 480``` 481**Description** 482Enumerates the error codes used in the HiAppEvent module. 483 484**Since**: 15 485 486| Value| Description| 487| -------- | -------- | 488| HIAPPEVENT_SUCCESS | The operation is successful. | 489| HIAPPEVENT_INVALID_PARAM_VALUE_LENGTH | The parameter value length is invalid. | 490| HIAPPEVENT_PROCESSOR_IS_NULL | The processor is null. | 491| HIAPPEVENT_PROCESSOR_NOT_FOUND | The processor is not found. | 492| HIAPPEVENT_INVALID_PARAM_VALUE | The parameter value is invalid. | 493| HIAPPEVENT_EVENT_CONFIG_IS_NULL | The event configuration is null. | 494| HIAPPEVENT_OPERATE_FAILED | The operation failed. | 495| HIAPPEVENT_INVALID_UID | The user ID is invalid. | 496 497 498## Function Description 499 500 501### OH_HiAppEvent_AddBoolArrayParam() 502 503``` 504ParamList OH_HiAppEvent_AddBoolArrayParam (ParamList list, const char * name, const bool * booleans, int arrSize ) 505``` 506**Description** 507Adds an event parameter of the Boolean array type to the parameter list. 508 509**Since**: 8 510 511**Parameters** 512 513| Name| Description| 514| -------- | -------- | 515| list | Pointer to the parameter list to which parameters need to be added. | 516| name | Name of the parameter to be added. | 517| booleans | Value of the parameter to be added. | 518| arrSize | Size of the parameter array to be added. | 519 520**Returns** 521 522Pointer to the parameter list that contains the parameters added. 523 524 525### OH_HiAppEvent_AddBoolParam() 526 527``` 528ParamList OH_HiAppEvent_AddBoolParam (ParamList list, const char * name, bool boolean ) 529``` 530**Description** 531Adds an event parameter of the Boolean type to the parameter list. 532 533**Since**: 8 534 535**Parameters** 536 537| Name| Description| 538| -------- | -------- | 539| list | Pointer to the parameter list to which parameters need to be added. | 540| name | Name of the parameter to be added. | 541| boolean | Value of the parameter to be added. | 542 543**Returns** 544 545Pointer to the parameter list that contains the parameters added. 546 547 548### OH_HiAppEvent_AddDoubleArrayParam() 549 550``` 551ParamList OH_HiAppEvent_AddDoubleArrayParam (ParamList list, const char * name, const double * nums, int arrSize ) 552``` 553**Description** 554Adds an event parameter of the double array type to the parameter list. 555 556**Since**: 8 557 558**Parameters** 559 560| Name| Description| 561| -------- | -------- | 562| list | Pointer to the parameter list to which parameters need to be added. | 563| name | Name of the parameter to be added. | 564| nums | Value of the parameter to be added. | 565| arrSize | Size of the parameter array to be added. | 566 567**Returns** 568 569Pointer to the parameter list that contains the parameters added. 570 571 572### OH_HiAppEvent_AddDoubleParam() 573 574``` 575ParamList OH_HiAppEvent_AddDoubleParam (ParamList list, const char * name, double num ) 576``` 577**Description** 578Adds an event parameter of the Double type to the parameter list. 579 580**Since**: 8 581 582**Parameters** 583 584| Name| Description| 585| -------- | -------- | 586| list | Pointer to the parameter list to which parameters need to be added. | 587| name | Name of the parameter to be added. | 588| num | Value of the parameter to be added. | 589 590**Returns** 591 592Pointer to the parameter list that contains the parameters added. 593 594 595### OH_HiAppEvent_AddFloatArrayParam() 596 597``` 598ParamList OH_HiAppEvent_AddFloatArrayParam (ParamList list, const char * name, const float * nums, int arrSize ) 599``` 600**Description** 601Adds an event parameter of the float array type to the parameter list. 602 603**Since**: 8 604 605**Parameters** 606 607| Name| Description| 608| -------- | -------- | 609| list | Pointer to the parameter list to which parameters need to be added. | 610| name | Name of the parameter to be added. | 611| nums | Value of the parameter to be added. | 612| arrSize | Size of the parameter array to be added. | 613 614**Returns** 615 616Pointer to the parameter list that contains the parameters added. 617 618 619### OH_HiAppEvent_AddFloatParam() 620 621``` 622ParamList OH_HiAppEvent_AddFloatParam (ParamList list, const char * name, float num ) 623``` 624**Description** 625Adds an event parameter of the float type to the parameter list. 626 627**Since**: 8 628 629**Parameters** 630 631| Name| Description| 632| -------- | -------- | 633| list | Pointer to the parameter list to which parameters need to be added. | 634| name | Name of the parameter to be added. | 635| num | Value of the parameter to be added. | 636 637**Returns** 638 639Pointer to the parameter list that contains the parameters added. 640 641 642### OH_HiAppEvent_AddInt16ArrayParam() 643 644``` 645ParamList OH_HiAppEvent_AddInt16ArrayParam (ParamList list, const char * name, const int16_t * nums, int arrSize ) 646``` 647**Description** 648Adds an event parameter of the int16_t array type to the parameter list. 649 650**Since**: 8 651 652**Parameters** 653 654| Name| Description| 655| -------- | -------- | 656| list | Pointer to the parameter list to which parameters need to be added. | 657| name | Name of the parameter to be added. | 658| nums | Value of the parameter to be added. | 659| arrSize | Size of the parameter array to be added. | 660 661**Returns** 662 663Pointer to the parameter list that contains the parameters added. 664 665 666### OH_HiAppEvent_AddInt16Param() 667 668``` 669ParamList OH_HiAppEvent_AddInt16Param (ParamList list, const char * name, int16_t num ) 670``` 671**Description** 672Adds an event parameter of the int16_t type to the parameter list. 673 674**Since**: 8 675 676**Parameters** 677 678| Name| Description| 679| -------- | -------- | 680| list | Pointer to the parameter list to which parameters need to be added. | 681| name | Name of the parameter to be added. | 682| num | Value of the parameter to be added. | 683 684**Returns** 685 686Pointer to the parameter list that contains the parameters added. 687 688 689### OH_HiAppEvent_AddInt32ArrayParam() 690 691``` 692ParamList OH_HiAppEvent_AddInt32ArrayParam (ParamList list, const char * name, const int32_t * nums, int arrSize ) 693``` 694**Description** 695Adds an event parameter of the int32_t array type to the parameter list. 696 697**Since**: 8 698 699**Parameters** 700 701| Name| Description| 702| -------- | -------- | 703| list | Pointer to the parameter list to which parameters need to be added. | 704| name | Name of the parameter to be added. | 705| nums | Value of the parameter to be added. | 706| arrSize | Size of the parameter array to be added. | 707 708**Returns** 709 710Pointer to the parameter list that contains the parameters added. 711 712 713### OH_HiAppEvent_AddInt32Param() 714 715``` 716ParamList OH_HiAppEvent_AddInt32Param (ParamList list, const char * name, int32_t num ) 717``` 718**Description** 719Adds an event parameter of the int32_t type to the parameter list. 720 721**Since**: 8 722 723**Parameters** 724 725| Name| Description| 726| -------- | -------- | 727| list | Pointer to the parameter list to which parameters need to be added. | 728| name | Name of the parameter to be added. | 729| num | Value of the parameter to be added. | 730 731**Returns** 732 733Pointer to the parameter list that contains the parameters added. 734 735 736### OH_HiAppEvent_AddInt64ArrayParam() 737 738``` 739ParamList OH_HiAppEvent_AddInt64ArrayParam (ParamList list, const char * name, const int64_t * nums, int arrSize ) 740``` 741**Description** 742Adds an event parameter of the int64_t array type to the parameter list. 743 744**Since**: 8 745 746**Parameters** 747 748| Name| Description| 749| -------- | -------- | 750| list | Pointer to the parameter list to which parameters need to be added. | 751| name | Name of the parameter to be added. | 752| nums | Value of the parameter to be added. | 753| arrSize | Size of the parameter array to be added. | 754 755**Returns** 756 757Pointer to the parameter list that contains the parameters added. 758 759 760### OH_HiAppEvent_AddInt64Param() 761 762``` 763ParamList OH_HiAppEvent_AddInt64Param (ParamList list, const char * name, int64_t num ) 764``` 765**Description** 766Adds an event parameter of the int64_t type to the parameter list. 767 768**Since**: 8 769 770**Parameters** 771 772| Name| Description| 773| -------- | -------- | 774| list | Pointer to the parameter list to which parameters need to be added. | 775| name | Name of the parameter to be added. | 776| num | Value of the parameter to be added. | 777 778**Returns** 779 780Pointer to the parameter list that contains the parameters added. 781 782 783### OH_HiAppEvent_AddInt8ArrayParam() 784 785``` 786ParamList OH_HiAppEvent_AddInt8ArrayParam (ParamList list, const char * name, const int8_t * nums, int arrSize ) 787``` 788**Description** 789Adds an event parameter of the int8_t array type to the parameter list. 790 791**Since**: 8 792 793**Parameters** 794 795| Name| Description| 796| -------- | -------- | 797| list | Pointer to the parameter list to which parameters need to be added. | 798| name | Name of the parameter to be added. | 799| nums | Value of the parameter to be added. | 800| arrSize | Size of the parameter array to be added. | 801 802**Returns** 803 804Pointer to the parameter list that contains the parameters added. 805 806 807### OH_HiAppEvent_AddInt8Param() 808 809``` 810ParamList OH_HiAppEvent_AddInt8Param (ParamList list, const char * name, int8_t num ) 811``` 812**Description** 813Adds an event parameter of the int8_t type to the parameter list. 814 815**Since**: 8 816 817**Parameters** 818 819| Name| Description| 820| -------- | -------- | 821| list | Pointer to the parameter list to which parameters need to be added. | 822| name | Name of the parameter to be added. | 823| num | Value of the parameter to be added. | 824 825**Returns** 826 827Pointer to the parameter list that contains the parameters added. 828 829 830### OH_HiAppEvent_AddProcessor() 831 832``` 833int64_t OH_HiAppEvent_AddProcessor (HiAppEvent_Processor * processor) 834``` 835**Description** 836Adds 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. 837 838Note 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. 839 840**Since**: 18 841 842**Parameters** 843 844| Name| Description| 845| -------- | -------- | 846| processor | Pointer to the processor, that is, the pointer returned by **OH_HiAppEvent_CreateProcessor**. | 847 848**Returns** 849 850Unique ID of the processor if the API is called successfully. The value is greater than 0; **-7** if the input parameter of the processor is empty; **-9** if the parameter value is invalid; **-200** if the user ID is invalid. 851 852 853### OH_HiAppEvent_AddStringArrayParam() 854 855``` 856ParamList OH_HiAppEvent_AddStringArrayParam (ParamList list, const char * name, const char *const * strs, int arrSize ) 857``` 858**Description** 859Adds a parameter of the string array type to the parameter list. 860 861**Since**: 8 862 863**Parameters** 864 865| Name| Description| 866| -------- | -------- | 867| list | Pointer to the parameter list to which parameters need to be added. | 868| name | Name of the parameter to be added. | 869| strs | Value of the parameter to be added. | 870| arrSize | Size of the parameter array to be added. | 871 872**Returns** 873 874Pointer to the parameter list that contains the parameters added. 875 876 877### OH_HiAppEvent_AddStringParam() 878 879``` 880ParamList OH_HiAppEvent_AddStringParam (ParamList list, const char * name, const char * str ) 881``` 882**Description** 883Adds a parameter of the string type to the parameter list. 884 885**Since**: 8 886 887**Parameters** 888 889| Name| Description| 890| -------- | -------- | 891| list | Pointer to the parameter list to which parameters need to be added. | 892| name | Name of the parameter to be added. | 893| str | Value of the parameter to be added. | 894 895**Returns** 896 897Pointer to the parameter list that contains the parameters added. 898 899 900### OH_HiAppEvent_AddWatcher() 901 902``` 903int OH_HiAppEvent_AddWatcher (HiAppEvent_Watcher * watcher) 904``` 905**Description** 906Adds a watcher. Once a watcher is added, it starts to listen for system messages. 907 908**System capability**: SystemCapability.HiviewDFX.HiAppEvent 909 910**Since**: 12 911 912**Parameters** 913 914| Name| Description| 915| -------- | -------- | 916| watcher | Pointer to the watcher (that is, the pointer returned by OH_HiAppEvent_CreateWatcher). | 917 918**Returns** 919 920**0** if the API is called successfully; **-5** if the pointer of an input parameter is null. 921 922 923### OH_HiAppEvent_ClearData() 924 925``` 926void OH_HiAppEvent_ClearData (void ) 927``` 928**Description** 929Clears the events saved by all watchers. 930 931**System capability**: SystemCapability.HiviewDFX.HiAppEvent 932 933**Since**: 12 934 935 936### OH_HiAppEvent_Configure() 937 938``` 939bool OH_HiAppEvent_Configure (const char * name, const char * value ) 940``` 941**Description** 942Configures the application event logging function. 943 944This function is used to configure the event logging function and the storage quota of the event file directory. 945 946**Since**: 8 947 948**Parameters** 949 950| Name| Description| 951| -------- | -------- | 952| name | Configuration item name. The value can be set to [DISABLE](#disable) or [MAX_STORAGE](#max_storage). | 953| 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. | 954 955**Returns** 956 957Configuration result. The value **true** indicates that the configuration is successful, and the value **false** indicates the opposite. 958 959 960### OH_HiAppEvent_CreateConfig() 961 962``` 963HiAppEvent_Config* OH_HiAppEvent_CreateConfig (void ) 964``` 965**Description** 966Creates a pointer to the configuration object that sets the conditions for triggering system events. 967 968**System capability**: SystemCapability.HiviewDFX.HiAppEvent 969 970**Since**: 15 971 972**Returns** 973 974Pointer to the configuration object that sets the conditions for triggering system events. 975 976 977### OH_HiAppEvent_CreateParamList() 978 979``` 980ParamList OH_HiAppEvent_CreateParamList (void ) 981``` 982**Description** 983Creates a pointer to a parameter list object. 984 985**Since**: 8 986 987**Returns** 988 989Pointer to the parameter list object. 990 991 992### OH_HiAppEvent_CreateProcessor() 993 994``` 995HiAppEvent_Processor* OH_HiAppEvent_CreateProcessor (const char * name) 996``` 997**Description** 998Creates a processor for application events. 999 1000Note: If a processor is no longer used, call **OH_HiAppEvent_DestroyProcessor** to destroy it. 1001 1002**Since**: 18 1003 1004**Parameters** 1005 1006| Name| Description| 1007| -------- | -------- | 1008| name | Processor name, which can contain only letters, digits, underscores (_), and dollar signs ($). It cannot start with a digit and cannot exceed 256 characters. | 1009 1010**Returns** 1011 1012Pointer to the new processor if the API is called successfully; **nullptr** if the **name** parameter is invalid. 1013 1014 1015### OH_HiAppEvent_CreateWatcher() 1016 1017``` 1018HiAppEvent_Watcher* OH_HiAppEvent_CreateWatcher (const char * name) 1019``` 1020**Description** 1021Creates a watcher for application events. 1022 1023Note: If a created watcher is no longer used, you are required to destroy it by calling OH_HiAppEvent_DestroyWatcher. 1024 1025**System capability**: SystemCapability.HiviewDFX.HiAppEvent 1026 1027**Since**: 12 1028 1029**Parameters** 1030 1031| Name| Description| 1032| -------- | -------- | 1033| name | Watcher name. | 1034 1035**Returns** 1036 1037Pointer to the new watcher if the API is called successfully; **nullptr** if the **name** parameter is invalid. 1038 1039 1040### OH_HiAppEvent_DestroyConfig() 1041 1042``` 1043void OH_HiAppEvent_DestroyConfig (HiAppEvent_Config * config) 1044``` 1045**Description** 1046Destroys a configuration object. 1047 1048Note: 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. 1049 1050**System capability**: SystemCapability.HiviewDFX.HiAppEvent 1051 1052**Since**: 15 1053 1054**Parameters** 1055 1056| Name| Description| 1057| -------- | -------- | 1058| config | Pointer to the configuration object, that is, the pointer returned by the **OH_HiAppEvent_CreateConfig** API. | 1059 1060 1061### OH_HiAppEvent_DestroyParamList() 1062 1063``` 1064void OH_HiAppEvent_DestroyParamList (ParamList list) 1065``` 1066**Description** 1067Destroys a pointer to a parameter list object and releases its allocated memory. 1068 1069**Since**: 8 1070 1071**Parameters** 1072 1073| Name| Description| 1074| -------- | -------- | 1075| list | Pointer to the parameter list object. | 1076 1077 1078### OH_HiAppEvent_DestroyProcessor() 1079 1080``` 1081void OH_HiAppEvent_DestroyProcessor (HiAppEvent_Processor * processor) 1082``` 1083**Description** 1084Destroys a processor. 1085 1086Note: 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. 1087 1088**Since**: 18 1089 1090**Parameters** 1091 1092| Name| Description| 1093| -------- | -------- | 1094| processor | Pointer to the processor, that is, the pointer returned by **OH_HiAppEvent_CreateProcessor**. | 1095 1096 1097### OH_HiAppEvent_DestroyWatcher() 1098 1099``` 1100void OH_HiAppEvent_DestroyWatcher (HiAppEvent_Watcher * watcher) 1101``` 1102**Description** 1103Destroys a created watcher. 1104 1105Note: 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. 1106 1107**System capability**: SystemCapability.HiviewDFX.HiAppEvent 1108 1109**Since**: 12 1110 1111**Parameters** 1112 1113| Name| Description| 1114| -------- | -------- | 1115| watcher | Pointer to the watcher (that is, the pointer returned by OH_HiAppEvent_CreateWatcher). | 1116 1117 1118### OH_HiAppEvent_RemoveProcessor() 1119 1120``` 1121int OH_HiAppEvent_RemoveProcessor (int64_t processorId) 1122``` 1123**Description** 1124Removes a processor. Once a processor is removed, it stops reporting events. 1125 1126Note: 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. 1127 1128**Since**: 18 1129 1130**Parameters** 1131 1132| Name| Description| 1133| -------- | -------- | 1134| processorId | Unique ID of a processor. | 1135 1136**Returns** 1137 1138**0** if the API is called successfully; **-8** if the processor is not found; **-100** if the operation fails; **-200** if the user ID is invalid. 1139 1140 1141### OH_HiAppEvent_RemoveWatcher() 1142 1143``` 1144int OH_HiAppEvent_RemoveWatcher (HiAppEvent_Watcher * watcher) 1145``` 1146**Description** 1147Removes a watcher. Once a watcher is removed, it stops listening for system messages. 1148 1149Note: 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. 1150 1151**System capability**: SystemCapability.HiviewDFX.HiAppEvent 1152 1153**Since**: 12 1154 1155**Parameters** 1156 1157| Name| Description| 1158| -------- | -------- | 1159| watcher | Pointer to the watcher (that is, the pointer returned by OH_HiAppEvent_CreateWatcher). | 1160 1161**Returns** 1162 1163**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. 1164 1165 1166### OH_HiAppEvent_SetAppEventFilter() 1167 1168``` 1169int OH_HiAppEvent_SetAppEventFilter (HiAppEvent_Watcher * watcher, const char * domain, uint8_t eventTypes, const char *const * names, int namesLen ) 1170``` 1171**Description** 1172Sets the type of events to listen for. 1173 1174This 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. 1175 1176**System capability**: SystemCapability.HiviewDFX.HiAppEvent 1177 1178**Since**: 12 1179 1180**Parameters** 1181 1182| Name| Description| 1183| -------- | -------- | 1184| watcher | Pointer to the watcher (that is, the pointer returned by OH_HiAppEvent_CreateWatcher). | 1185| domain | Domain of events to be listened for. | 1186| 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. 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, if the fourth digit is 1 (the value is **8**), behavior events can be listened for.<br>If the fourth digit is 1 (the value is **15**) or 0 (the value is **0**), events of all types can be listened for.| 1187| names | Array of the event names. | 1188| namesLen | Length of the event name array. | 1189 1190**Returns** 1191 1192**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. 1193 1194 1195### OH_HiAppEvent_SetConfigId() 1196 1197``` 1198int OH_HiAppEvent_SetConfigId (HiAppEvent_Processor * processor, int configId ) 1199``` 1200**Description** 1201Sets the configuration ID of the processor. 1202 1203**Since**: 18 1204 1205**Parameters** 1206 1207| Name| Description| 1208| -------- | -------- | 1209| processor | Pointer to the processor, that is, the pointer returned by **OH_HiAppEvent_CreateProcessor**. | 1210| configId | Configuration ID of the processor, which is a natural number. | 1211 1212**Returns** 1213 1214**0** if the API is called successfully; **-7** if the input parameters of the processor are empty; **-9** if the parameter values are invalid; **-200** if the user ID is invalid. 1215 1216 1217### OH_HiAppEvent_SetConfigItem() 1218 1219``` 1220int OH_HiAppEvent_SetConfigItem (HiAppEvent_Config * config, const char * itemName, const char * itemValue ) 1221``` 1222**Description** 1223Sets the items in the configuration object. 1224 1225**System capability**: SystemCapability.HiviewDFX.HiAppEvent 1226 1227**Since**: 15 1228 1229**Parameters** 1230 1231| Name| Description| 1232| -------- | -------- | 1233| config | Pointer to the configuration object, that is, the pointer returned by the **OH_HiAppEvent_CreateConfig** API. | 1234| itemName | Name of the configuration item. | 1235| itemValue | Value of the configuration item. | 1236 1237**Returns** 1238 1239**0** if the API is called successfully; **-9** if the configuration item is invalid; **-10** if the pointer to the configuration object is null. 1240 1241 1242### OH_HiAppEvent_SetCustomConfig() 1243 1244``` 1245int OH_HiAppEvent_SetCustomConfig (HiAppEvent_Processor * processor, const char * key, const char * value ) 1246``` 1247**Description** 1248Sets the custom extension parameters of the processor. 1249 1250**Since**: 18 1251 1252**Parameters** 1253 1254| Name| Description| 1255| -------- | -------- | 1256| processor | Pointer to the processor, that is, the pointer returned by **OH_HiAppEvent_CreateProcessor**. | 1257| key | Parameter name, which contains a maximum of 32 characters. | 1258| value | Parameter value, which contains a maximum of 1024 characters. | 1259 1260**Returns** 1261 1262**0** if the API is called successfully; **7** if the input parameter of the processor is empty; **9** if the parameter value is invalid; **200** if the user ID is invalid; **4** if the parameter value length is invalid. 1263 1264 1265### OH_HiAppEvent_SetEventConfig() 1266 1267``` 1268int OH_HiAppEvent_SetEventConfig (const char * name, HiAppEvent_Config * config ) 1269``` 1270**Description** 1271Sets the conditions for triggering system event subscription. 1272 1273**System capability**: SystemCapability.HiviewDFX.HiAppEvent 1274 1275**Since**: 15 1276 1277**Parameters** 1278 1279| Name| Description| 1280| -------- | -------- | 1281| name | Name of the system event. | 1282| config | Pointer to the configuration object, that is, the pointer returned by the **OH_HiAppEvent_CreateConfig** API. | 1283 1284**Returns** 1285 1286**0** if the API is called successfully; **-9** if the parameter is invalid. 1287 1288 1289### OH_HiAppEvent_SetReportEvent() 1290 1291``` 1292int OH_HiAppEvent_SetReportEvent (HiAppEvent_Processor * processor, const char * domain, const char * name, bool isRealTime ) 1293``` 1294**Description** 1295Sets the report event for the processor. 1296 1297**Since**: 18 1298 1299**Parameters** 1300 1301| Name| Description| 1302| -------- | -------- | 1303| processor | Pointer to the processor, that is, the pointer returned by **OH_HiAppEvent_CreateProcessor**. | 1304| domain | Domain of the report event. | 1305| name | Name of the report event. | 1306| isRealTime | Whether to report events in real time. | 1307 1308**Returns** 1309 1310**0** if the API is called successfully; **-7** if the input parameters of the processor are empty; **-9** if the parameter values are invalid; **-200** if the user ID is invalid. 1311 1312 1313### OH_HiAppEvent_SetReportPolicy() 1314 1315``` 1316int OH_HiAppEvent_SetReportPolicy (HiAppEvent_Processor * processor, int periodReport, int batchReport, bool onStartReport, bool onBackgroundReport ) 1317``` 1318**Description** 1319Sets the report policy for the processor. 1320 1321**Since**: 18 1322 1323**Parameters** 1324 1325| Name| Description| 1326| -------- | -------- | 1327| processor | Pointer to the processor, that is, the pointer returned by **OH_HiAppEvent_CreateProcessor**. | 1328| periodReport | Period for reporting events, in seconds. | 1329| batchReport | Threshold for reporting events. When the number of events reaches the threshold, an event is reported. | 1330| onStartReport | Whether to report an event when the processor is started. The default value is **false**. | 1331| onBackgroundReport | Whether to report an event when an application enters the background. The default value is **false**. | 1332 1333**Returns** 1334 1335**0** if the API is called successfully; **-7** if the input parameters of the processor are empty; **-9** if the parameter values are invalid; **-200** if the user ID is invalid. 1336 1337 1338### OH_HiAppEvent_SetReportRoute() 1339 1340``` 1341int OH_HiAppEvent_SetReportRoute (HiAppEvent_Processor * processor, const char * appId, const char * routeInfo ) 1342``` 1343**Description** 1344Sets the report route for the processor. 1345 1346**Since**: 18 1347 1348**Parameters** 1349 1350| Name| Description| 1351| -------- | -------- | 1352| processor | Pointer to the processor, that is, the pointer returned by **OH_HiAppEvent_CreateProcessor**. | 1353| appId | Application ID of the processor. | 1354| routeInfo | Server location information. The default value is an empty string. The string length cannot exceed 8 KB. Otherwise, the default value is used. | 1355 1356**Returns** 1357 1358**0** if the API is called successfully; **7** if the input parameter of the processor is empty; **9** if the parameter value is invalid; **200** if the user ID is invalid; **4** if the parameter value length is invalid. 1359 1360 1361### OH_HiAppEvent_SetReportUserId() 1362 1363``` 1364int OH_HiAppEvent_SetReportUserId (HiAppEvent_Processor * processor, const char *const * userIdNames, int size ) 1365``` 1366**Description** 1367Sets the report user ID of the processor. 1368 1369**Since**: 18 1370 1371**Parameters** 1372 1373| Name| Description| 1374| -------- | -------- | 1375| processor | Pointer to the processor, that is, the pointer returned by **OH_HiAppEvent_CreateProcessor**. | 1376| userIdNames | Name array of user IDs that can be reported by the processor. | 1377| size | Length of the name array of user IDs. | 1378 1379**Returns** 1380 1381**0** if the API is called successfully; **7** if the input parameter of the processor is empty; **9** if the parameter value is invalid; **200** if the user ID is invalid; **4** if the parameter value length is invalid. 1382 1383 1384### OH_HiAppEvent_SetReportUserProperty() 1385 1386``` 1387int OH_HiAppEvent_SetReportUserProperty (HiAppEvent_Processor * processor, const char *const * userPropertyNames, int size ) 1388``` 1389**Description** 1390Sets the report user property of the processor. 1391 1392**Since**: 18 1393 1394**Parameters** 1395 1396| Name| Description| 1397| -------- | -------- | 1398| processor | Pointer to the processor, that is, the pointer returned by **OH_HiAppEvent_CreateProcessor**. | 1399| userPropertyNames | Name array of user properties that can be reported by the processor. | 1400| size | Length of the name array of user properties. | 1401 1402**Returns** 1403 1404**0** if the API is called successfully; **7** if the input parameter of the processor is empty; **9** if the parameter value is invalid; **200** if the user ID is invalid; **4** if the parameter value length is invalid. 1405 1406 1407### OH_HiAppEvent_SetTriggerCondition() 1408 1409``` 1410int OH_HiAppEvent_SetTriggerCondition (HiAppEvent_Watcher * watcher, int row, int size, int timeOut ) 1411``` 1412**Description** 1413Sets the trigger conditions of 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. 1414 1415**System capability**: SystemCapability.HiviewDFX.HiAppEvent 1416 1417**Since**: 12 1418 1419**Parameters** 1420 1421| Name| Description| 1422| -------- | -------- | 1423| watcher | Pointer to the watcher (that is, the pointer returned by OH_HiAppEvent_CreateWatcher). | 1424| 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. | 1425| 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. | 1426| 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. | 1427 1428**Returns** 1429 1430**0** if the API is called successfully; **-5** if the pointer of an input parameter is null. 1431 1432 1433### OH_HiAppEvent_SetWatcherOnReceive() 1434 1435``` 1436int OH_HiAppEvent_SetWatcherOnReceive (HiAppEvent_Watcher * watcher, OH_HiAppEvent_OnReceive onReceive ) 1437``` 1438**Description** 1439Sets the **onReceive** callback. When the listener detects the corresponding event, the onReceive callback is called. 1440 1441**System capability**: SystemCapability.HiviewDFX.HiAppEvent 1442 1443**Since**: 12 1444 1445**Parameters** 1446 1447| Name| Description| 1448| -------- | -------- | 1449| watcher | Pointer to the watcher (that is, the pointer returned by OH_HiAppEvent_CreateWatcher). | 1450| onReceive | Pointer to the callback function. | 1451 1452**Returns** 1453 1454**0** if the API is called successfully; **-5** if the pointer of an input parameter is null. 1455 1456 1457### OH_HiAppEvent_SetWatcherOnTrigger() 1458 1459``` 1460int OH_HiAppEvent_SetWatcherOnTrigger (HiAppEvent_Watcher * watcher, OH_HiAppEvent_OnTrigger onTrigger ) 1461``` 1462**Description** 1463Sets the **onTrigger** callback. 1464 1465**System capability**: SystemCapability.HiviewDFX.HiAppEvent 1466 1467**Since**: 12 1468 1469**Parameters** 1470 1471| Name| Description| 1472| -------- | -------- | 1473| watcher | Pointer to the watcher (that is, the pointer returned by OH_HiAppEvent_CreateWatcher). | 1474| onTrigger | Callback to be set. | 1475 1476**Returns** 1477 1478**0** if the API is called successfully; **-5** if the pointer of an input parameter is null. 1479 1480 1481### OH_HiAppEvent_TakeWatcherData() 1482 1483``` 1484int OH_HiAppEvent_TakeWatcherData (HiAppEvent_Watcher * watcher, uint32_t eventNum, OH_HiAppEvent_OnTake onTake ) 1485``` 1486**Description** 1487Obtains the event saved by the watcher. 1488 1489**System capability**: SystemCapability.HiviewDFX.HiAppEvent 1490 1491**Since**: 12 1492 1493**Parameters** 1494 1495| Name| Description| 1496| -------- | -------- | 1497| watcher | Pointer to the watcher (that is, the pointer returned by OH_HiAppEvent_CreateWatcher). | 1498| 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. | 1499| onTake | Pointer to the callback. The event information is returned through this callback. | 1500 1501**Returns** 1502 1503**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. 1504 1505 1506### OH_HiAppEvent_Write() 1507 1508``` 1509int OH_HiAppEvent_Write (const char * domain, const char * name, enum EventType type, const ParamList list ) 1510``` 1511**Description** 1512Logs application events whose parameters are of the list type. 1513 1514Before 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. 1515 1516**Since**: 8 1517 1518**Parameters** 1519 1520| Name| Description| 1521| -------- | -------- | 1522| domain | Event domain. You can customize event domains as required. 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 (\_). | 1523| name | Event name. You can customize event names as required. 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. | 1524| type | Event type, which is defined in [EventType](#eventtype). | 1525| 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 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 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. | 1526 1527**Returns** 1528 1529The 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. 15300 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. 1531