1# hiappevent.h 2 3 4## Overview 5 6Defines the application event logging functions of the HiAppEvent module. 7 8Before performing application event logging, you must construct a parameter list object to store the input event parameters and specify the event domain, event name, and event type. 9 10Event domain: domain associated with the application event. 11 12Event name: name of the application event. 13 14Event type: fault, statistics, security, or behavior. 15 16Parameter list: a linked list used to store event parameters. Each parameter consists of a parameter name and a parameter value. 17 18Example: 19 201. Import the header file. 21 ``` 22 #include "hiappevent/hiappevent.h" 23 ``` 24 252. Create a parameter list pointer. 26 ``` 27 ParamList list = OH_HiAppEvent_CreateParamList(); 28 ``` 29 303. Add parameters to the parameter list. 31 ``` 32 bool boolean = true; 33 OH_HiAppEvent_AddBoolParam(list, "bool_key", boolean); 34 int32_t nums[] = {1, 2, 3}; 35 OH_HiAppEvent_AddInt32ArrayParam(list, "int32_arr_key", nums, sizeof(nums) / sizeof(nums[0])); 36 ``` 37 384. Perform event logging. 39 ``` 40 int res = OH_HiAppEvent_Write("test_domain", "test_event", BEHAVIOR, list); 41 ``` 42 435. Destroy the parameter list pointer and release its allocated memory. 44 ``` 45 OH_HiAppEvent_DestroyParamList(list); 46 ``` 47 48**File to include**: <hiappevent/hiappevent.h> 49 50**Library**: libhiappevent_ndk.z.so 51 52**System capability**: SystemCapability.HiviewDFX.HiAppEvent 53 54**Since**: 8 55 56**Related module**: [HiAppEvent](_hi_app_event.md) 57 58 59## Summary 60 61 62### Structs 63 64| Name| Description| 65| -------- | -------- | 66| 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. | 67| struct [HiAppEvent_AppEventGroup](_hi_app_event___app_event_group.md) | Defines an event group with the same event name. | 68 69 70### Types 71 72| Name| Description| 73| -------- | -------- | 74| typedef struct [HiAppEvent_AppEventInfo](_hi_app_event___app_event_info.md) [HiAppEvent_AppEventInfo](_hi_app_event.md#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. | 75| typedef struct [HiAppEvent_AppEventGroup](_hi_app_event___app_event_group.md) [HiAppEvent_AppEventGroup](_hi_app_event.md#hiappevent_appeventgroup) | Defines a struct for the event group with the same event name. | 76| typedef struct ParamListNode \* [ParamList](_hi_app_event.md#paramlist) | Defines a struct for the event parameter list node. | 77| typedef struct [HiAppEvent_Watcher](_hi_app_event.md#hiappevent_watcher) [HiAppEvent_Watcher](_hi_app_event.md#hiappevent_watcher) | Defines a struct for the watcher for application events. | 78| typedef struct [HiAppEvent_Processor](_hi_app_event.md#hiappevent_processor) [HiAppEvent_Processor](_hi_app_event.md#hiappevent_processor) | Defines a struct for the processor for application events. | 79| typedef struct [HiAppEvent_Config](_hi_app_event.md#hiappevent_config) [HiAppEvent_Config](_hi_app_event.md#hiappevent_config) | Defines a struct for the configuration object used to set the conditions for triggering system events. | 80| typedef void(\* [OH_HiAppEvent_OnReceive](_hi_app_event.md#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. | 81| typedef void(\* [OH_HiAppEvent_OnTrigger](_hi_app_event.md#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. | 82| typedef void(\* [OH_HiAppEvent_OnTake](_hi_app_event.md#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. | 83 84 85### Enums 86 87| Name| Description| 88| -------- | -------- | 89| [HiAppEvent_ErrorCode](_hi_app_event.md#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. | 90| [EventType](_hi_app_event.md#eventtype) {<br>FAULT = 1, <br>STATISTIC = 2, <br>SECURITY = 3, <br>BEHAVIOR = 4<br>} | Enumerates the event types. | 91 92 93### Callback 94 95| Name| Description| 96| -------- | -------- | 97| [ParamList](_hi_app_event.md#paramlist) [OH_HiAppEvent_CreateParamList](_hi_app_event.md#oh_hiappevent_createparamlist) (void) | Creates a pointer to a parameter list object. | 98| void [OH_HiAppEvent_DestroyParamList](_hi_app_event.md#oh_hiappevent_destroyparamlist) ([ParamList](_hi_app_event.md#paramlist) list) | Destroys a pointer to a parameter list object and releases its allocated memory. | 99| [ParamList](_hi_app_event.md#paramlist) [OH_HiAppEvent_AddBoolParam](_hi_app_event.md#oh_hiappevent_addboolparam) ([ParamList](_hi_app_event.md#paramlist) list, const char \*name, bool boolean) | Adds an event parameter of the Boolean type to the parameter list. | 100| [ParamList](_hi_app_event.md#paramlist) [OH_HiAppEvent_AddBoolArrayParam](_hi_app_event.md#oh_hiappevent_addboolarrayparam) ([ParamList](_hi_app_event.md#paramlist) list, const char \*name, const bool \*booleans, int arrSize) | Adds an event parameter of the Boolean array type to the parameter list. | 101| [ParamList](_hi_app_event.md#paramlist) [OH_HiAppEvent_AddInt8Param](_hi_app_event.md#oh_hiappevent_addint8param) ([ParamList](_hi_app_event.md#paramlist) list, const char \*name, int8_t num) | Adds an event parameter of the int8_t type to the parameter list. | 102| [ParamList](_hi_app_event.md#paramlist) [OH_HiAppEvent_AddInt8ArrayParam](_hi_app_event.md#oh_hiappevent_addint8arrayparam) ([ParamList](_hi_app_event.md#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. | 103| [ParamList](_hi_app_event.md#paramlist) [OH_HiAppEvent_AddInt16Param](_hi_app_event.md#oh_hiappevent_addint16param) ([ParamList](_hi_app_event.md#paramlist) list, const char \*name, int16_t num) | Adds an event parameter of the int16_t type to the parameter list. | 104| [ParamList](_hi_app_event.md#paramlist) [OH_HiAppEvent_AddInt16ArrayParam](_hi_app_event.md#oh_hiappevent_addint16arrayparam) ([ParamList](_hi_app_event.md#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. | 105| [ParamList](_hi_app_event.md#paramlist) [OH_HiAppEvent_AddInt32Param](_hi_app_event.md#oh_hiappevent_addint32param) ([ParamList](_hi_app_event.md#paramlist) list, const char \*name, int32_t num) | Adds an event parameter of the int32_t type to the parameter list. | 106| [ParamList](_hi_app_event.md#paramlist) [OH_HiAppEvent_AddInt32ArrayParam](_hi_app_event.md#oh_hiappevent_addint32arrayparam) ([ParamList](_hi_app_event.md#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. | 107| [ParamList](_hi_app_event.md#paramlist) [OH_HiAppEvent_AddInt64Param](_hi_app_event.md#oh_hiappevent_addint64param) ([ParamList](_hi_app_event.md#paramlist) list, const char \*name, int64_t num) | Adds an event parameter of the int64_t type to the parameter list. | 108| [ParamList](_hi_app_event.md#paramlist) [OH_HiAppEvent_AddInt64ArrayParam](_hi_app_event.md#oh_hiappevent_addint64arrayparam) ([ParamList](_hi_app_event.md#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. | 109| [ParamList](_hi_app_event.md#paramlist) [OH_HiAppEvent_AddFloatParam](_hi_app_event.md#oh_hiappevent_addfloatparam) ([ParamList](_hi_app_event.md#paramlist) list, const char \*name, float num) | Adds an event parameter of the float type to the parameter list. | 110| [ParamList](_hi_app_event.md#paramlist) [OH_HiAppEvent_AddFloatArrayParam](_hi_app_event.md#oh_hiappevent_addfloatarrayparam) ([ParamList](_hi_app_event.md#paramlist) list, const char \*name, const float \*nums, int arrSize) | Adds an event parameter of the float array type to the parameter list. | 111| [ParamList](_hi_app_event.md#paramlist) [OH_HiAppEvent_AddDoubleParam](_hi_app_event.md#oh_hiappevent_adddoubleparam) ([ParamList](_hi_app_event.md#paramlist) list, const char \*name, double num) | Adds an event parameter of the Double type to the parameter list. | 112| [ParamList](_hi_app_event.md#paramlist) [OH_HiAppEvent_AddDoubleArrayParam](_hi_app_event.md#oh_hiappevent_adddoublearrayparam) ([ParamList](_hi_app_event.md#paramlist) list, const char \*name, const double \*nums, int arrSize) | Adds an event parameter of the double array type to the parameter list. | 113| [ParamList](_hi_app_event.md#paramlist) [OH_HiAppEvent_AddStringParam](_hi_app_event.md#oh_hiappevent_addstringparam) ([ParamList](_hi_app_event.md#paramlist) list, const char \*name, const char \*str) | Adds a parameter of the string type to the parameter list. | 114| [ParamList](_hi_app_event.md#paramlist) [OH_HiAppEvent_AddStringArrayParam](_hi_app_event.md#oh_hiappevent_addstringarrayparam) ([ParamList](_hi_app_event.md#paramlist) list, const char \*name, const char \*const \*strs, int arrSize) | Adds a parameter of the string array type to the parameter list. | 115| int [OH_HiAppEvent_Write](_hi_app_event.md#oh_hiappevent_write) (const char \*domain, const char \*name, enum [EventType](_hi_app_event.md#eventtype) type, const [ParamList](_hi_app_event.md#paramlist) list) | Logs application events whose parameters are of the list type. | 116| bool [OH_HiAppEvent_Configure](_hi_app_event.md#oh_hiappevent_configure) (const char \*name, const char \*value) | Configures the application event logging function. | 117| [HiAppEvent_Watcher](_hi_app_event.md#hiappevent_watcher) \* [OH_HiAppEvent_CreateWatcher](_hi_app_event.md#oh_hiappevent_createwatcher) (const char \*name) | Creates a watcher for application events. | 118| void [OH_HiAppEvent_DestroyWatcher](_hi_app_event.md#oh_hiappevent_destroywatcher) ([HiAppEvent_Watcher](_hi_app_event.md#hiappevent_watcher) \*watcher) | Destroys a created watcher. | 119| int [OH_HiAppEvent_SetTriggerCondition](_hi_app_event.md#oh_hiappevent_settriggercondition) ([HiAppEvent_Watcher](_hi_app_event.md#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. | 120| int [OH_HiAppEvent_SetAppEventFilter](_hi_app_event.md#oh_hiappevent_setappeventfilter) ([HiAppEvent_Watcher](_hi_app_event.md#hiappevent_watcher) \*watcher, const char \*domain, uint8_t eventTypes, const char \*const \*names, int namesLen) | Sets the type of events to listen for. | 121| int [OH_HiAppEvent_SetWatcherOnTrigger](_hi_app_event.md#oh_hiappevent_setwatcherontrigger) ([HiAppEvent_Watcher](_hi_app_event.md#hiappevent_watcher) \*watcher, [OH_HiAppEvent_OnTrigger](_hi_app_event.md#oh_hiappevent_ontrigger) onTrigger) | Sets the **onTrigger** callback. | 122| int [OH_HiAppEvent_SetWatcherOnReceive](_hi_app_event.md#oh_hiappevent_setwatcheronreceive) ([HiAppEvent_Watcher](_hi_app_event.md#hiappevent_watcher) \*watcher, [OH_HiAppEvent_OnReceive](_hi_app_event.md#oh_hiappevent_onreceive) onReceive) | Sets the **onReceive** callback. When the watcher detects the corresponding event, the **onReceive** callback is called. | 123| int [OH_HiAppEvent_TakeWatcherData](_hi_app_event.md#oh_hiappevent_takewatcherdata) ([HiAppEvent_Watcher](_hi_app_event.md#hiappevent_watcher) \*watcher, uint32_t eventNum, [OH_HiAppEvent_OnTake](_hi_app_event.md#oh_hiappevent_ontake) onTake) | Obtains the event saved by the watcher. | 124| int [OH_HiAppEvent_AddWatcher](_hi_app_event.md#oh_hiappevent_addwatcher) ([HiAppEvent_Watcher](_hi_app_event.md#hiappevent_watcher) \*watcher) | Adds a watcher. Once a watcher is added, it starts to listen for system messages. | 125| int [OH_HiAppEvent_RemoveWatcher](_hi_app_event.md#oh_hiappevent_removewatcher) ([HiAppEvent_Watcher](_hi_app_event.md#hiappevent_watcher) \*watcher) | Removes a watcher. Once a watcher is removed, it stops listening for system messages. | 126| void [OH_HiAppEvent_ClearData](_hi_app_event.md#oh_hiappevent_cleardata) (void) | Clears the events saved by all watchers. | 127| [HiAppEvent_Processor](_hi_app_event.md#hiappevent_processor) \* [OH_HiAppEvent_CreateProcessor](_hi_app_event.md#oh_hiappevent_createprocessor) (const char \*name) | Creates a processor for application events. | 128| int [OH_HiAppEvent_SetReportRoute](_hi_app_event.md#oh_hiappevent_setreportroute) ([HiAppEvent_Processor](_hi_app_event.md#hiappevent_processor) \*processor, const char \*appId, const char \*routeInfo) | Sets the report route for a processor. | 129| int [OH_HiAppEvent_SetReportPolicy](_hi_app_event.md#oh_hiappevent_setreportpolicy) ([HiAppEvent_Processor](_hi_app_event.md#hiappevent_processor) \*processor, int periodReport, int batchReport, bool onStartReport, bool onBackgroundReport) | Sets the report policy for a processor. | 130| int [OH_HiAppEvent_SetReportEvent](_hi_app_event.md#oh_hiappevent_setreportevent) ([HiAppEvent_Processor](_hi_app_event.md#hiappevent_processor) \*processor, const char \*domain, const char \*name, bool isRealTime) | Sets the report event for a processor. | 131| int [OH_HiAppEvent_SetCustomConfig](_hi_app_event.md#oh_hiappevent_setcustomconfig) ([HiAppEvent_Processor](_hi_app_event.md#hiappevent_processor) \*processor, const char \*key, const char \*value) | Sets the custom extension parameters of a processor. | 132| int [OH_HiAppEvent_SetConfigId](_hi_app_event.md#oh_hiappevent_setconfigid) ([HiAppEvent_Processor](_hi_app_event.md#hiappevent_processor) \*processor, int configId) | Sets the configuration ID of a processor. | 133| int [OH_HiAppEvent_SetReportUserId](_hi_app_event.md#oh_hiappevent_setreportuserid) ([HiAppEvent_Processor](_hi_app_event.md#hiappevent_processor) \*processor, const char \*const \*userIdNames, int size) | Sets the report user ID of a processor. | 134| int [OH_HiAppEvent_SetReportUserProperty](_hi_app_event.md#oh_hiappevent_setreportuserproperty) ([HiAppEvent_Processor](_hi_app_event.md#hiappevent_processor) \*processor, const char \*const \*userPropertyNames, int size) | Sets the report user property of the processor. | 135| int64_t [OH_HiAppEvent_AddProcessor](_hi_app_event.md#oh_hiappevent_addprocessor) ([HiAppEvent_Processor](_hi_app_event.md#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. | 136| void [OH_HiAppEvent_DestroyProcessor](_hi_app_event.md#oh_hiappevent_destroyprocessor) ([HiAppEvent_Processor](_hi_app_event.md#hiappevent_processor) \*processor) | Destroys a processor. | 137| int [OH_HiAppEvent_RemoveProcessor](_hi_app_event.md#oh_hiappevent_removeprocessor) (int64_t processorId) | Removes a processor. Once a processor is removed, it stops reporting events. | 138| [HiAppEvent_Config](_hi_app_event.md#hiappevent_config) \* [OH_HiAppEvent_CreateConfig](_hi_app_event.md#oh_hiappevent_createconfig) (void) | Creates a pointer to the configuration object that sets the conditions for triggering system events. | 139| void [OH_HiAppEvent_DestroyConfig](_hi_app_event.md#oh_hiappevent_destroyconfig) ([HiAppEvent_Config](_hi_app_event.md#hiappevent_config) \*config) | Destroys a configuration object. | 140| int [OH_HiAppEvent_SetConfigItem](_hi_app_event.md#oh_hiappevent_setconfigitem) ([HiAppEvent_Config](_hi_app_event.md#hiappevent_config) \*config, const char \*itemName, const char \*itemValue) | Sets the items in the configuration object. | 141| int [OH_HiAppEvent_SetEventConfig](_hi_app_event.md#oh_hiappevent_seteventconfig) (const char \*name, [HiAppEvent_Config](_hi_app_event.md#hiappevent_config) \*config) | Sets the conditions for triggering system event subscription. | 142