1# HiAppEvent 2 3 4## 概述 5 6HiAppEvent模块提供应用事件打点功能。 7 8为应用程序提供事件打点功能，记录运行过程中上报的故障事件、统计事件、安全事件和用户行为事件。基于事件信息，您可以分析应用的运行状态。 9 10为应用程序提供事件打点功能，记录运行过程中上报的故障事件、统计事件、安全事件和用户行为事件。基于事件信息，开发者可以分析应用的运行状态。 11 12**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 13 14**起始版本：** 8 15 16 17## 汇总 18 19 20### 文件 21 22| 名称 | 描述 | 23| -------- | -------- | 24| [hiappevent.h](hiappevent_8h.md) | HiAppEvent模块的应用事件打点函数定义。<br/>**引用文件**：<hiappevent/hiappevent.h><br/>**库**：libhiappevent_ndk.z.so | 25| [hiappevent_cfg.h](hiappevent__cfg_8h.md) | 定义事件打点配置函数的所有配置项名称。<br/>**引用文件**：<hiappevent/hiappevent_event.h><br/>**库**：libhiappevent_ndk.z.so | 26| [hiappevent_event.h](hiappevent__event_8h.md) | 定义所有预定义事件的事件名称。<br/>**引用文件**：<hiappevent/hiappevent_param.h><br/>**库**：libhiappevent_ndk.z.so | 27| [hiappevent_param.h](hiappevent__param_8h.md) | 定义所有预定义事件的参数名称。<br/>**引用文件**：<hiappevent/hiappevent_cfg.h><br/>**库**：libhiappevent_ndk.z.so | 28 29 30### 结构体 31 32| 名称 | 描述 | 33| -------- | -------- | 34| struct [HiAppEvent_AppEventInfo](_hi_app_event___app_event_info.md) | 单个事件信息，包含事件领域，事件名称，事件类型和json格式字符串表示的事件中携带的自定义参数列表。 | 35| struct [HiAppEvent_AppEventGroup](_hi_app_event___app_event_group.md) | 一组事件信息，包含事件组的名称，按名称分组的单个事件信息数组，事件数组的长度。 | 36 37 38### 宏定义 39 40| 名称 | 描述 | 41| -------- | -------- | 42| [DISABLE](#disable) "disable" | 事件打点开关。默认值为false。true：关闭打点功能，false：不关闭打点功能。 | 43| [MAX_STORAGE](#max_storage) "max_storage" | 事件文件目录存储配额大小。默认值为“10M”。 | 44| [EVENT_USER_LOGIN](#event_user_login) "hiappevent.user_login" | 用户登录事件。 | 45| [EVENT_USER_LOGOUT](#event_user_logout) "hiappevent.user_logout" | 用户登出事件。 | 46| [EVENT_DISTRIBUTED_SERVICE_START](#event_distributed_service_start) "hiappevent.distributed_service_start" | 分布式服务事件。 | 47| [EVENT_APP_CRASH](#event_app_crash) "APP_CRASH" | 应用崩溃事件。 | 48| [EVENT_APP_FREEZE](#event_app_freeze) "APP_FREEZE" | 应用卡顿事件。 | 49| [EVENT_APP_LAUNCH](#event_app_launch) "APP_LAUNCH" | 应用加载事件。 | 50| [EVENT_SCROLL_JANK](#event_scroll_jank) "SCROLL_JANK" | 应用滑动卡顿事件。 | 51| [EVENT_CPU_USAGE_HIGH](#event_cpu_usage_high) "CPU_USAGE_HIGH" | 应用CPU资源占用高事件。 | 52| [EVENT_BATTERY_USAGE](#event_battery_usage) "BATTERY_USAGE" | 应用电源使用率事件。 | 53| [EVENT_RESOURCE_OVERLIMIT](#event_resource_overlimit) "RESOURCE_OVERLIMIT" | 应用资源超限事件。 | 54| [EVENT_ADDRESS_SANITIZER](#event_address_sanitizer) "ADDRESS_SANITIZER" | 应用踩内存事件。 | 55| [EVENT_MAIN_THREAD_JANK](#event_main_thread_jank) "MAIN_THREAD_JANK" | 应用主线程超时事件。 | 56| [EVENT_APP_HICOLLIE](#event_app_hicollie) "APP_HICOLLIE" | 应用任务执行超时事件。 | 57| [DOMAIN_OS](#domain_os) "OS" | OS作用域。 | 58| [PARAM_USER_ID](#param_user_id) "user_id" | 用户ID。 | 59| [PARAM_DISTRIBUTED_SERVICE_NAME](#param_distributed_service_name) "ds_name" | 分布式服务名称。 | 60| [PARAM_DISTRIBUTED_SERVICE_INSTANCE_ID](#param_distributed_service_instance_id) "ds_instance_id" | 分布式服务实例ID。 | 61 62 63### 类型定义 64 65| 名称 | 描述 | 66| -------- | -------- | 67| typedef struct [HiAppEvent_AppEventInfo](_hi_app_event___app_event_info.md) [HiAppEvent_AppEventInfo](#hiappevent_appeventinfo) | 单个事件信息，包含事件领域，事件名称，事件类型和json格式字符串表示的事件中携带的自定义参数列表。 | 68| typedef struct [HiAppEvent_AppEventGroup](_hi_app_event___app_event_group.md) [HiAppEvent_AppEventGroup](#hiappevent_appeventgroup) | 一组事件信息，包含事件组的名称，按名称分组的单个事件信息数组，事件数组的长度。 | 69| typedef struct ParamListNode \* [ParamList](#paramlist) | 事件参数列表节点。 | 70| typedef struct [HiAppEvent_Watcher](#hiappevent_watcher) [HiAppEvent_Watcher](#hiappevent_watcher) | 用于接收app事件的监听器。 | 71| typedef struct [HiAppEvent_Processor](#hiappevent_processor) [HiAppEvent_Processor](#hiappevent_processor) | 用于处理app事件上报的处理者。 | 72| typedef struct [HiAppEvent_Config](#hiappevent_config) [HiAppEvent_Config](#hiappevent_config) | 用于设置系统事件触发条件的配置对象。 | 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) | 监听器接收到事件后，将触发该回调，将事件内容传递给调用方。 | 74| typedef void(\* [OH_HiAppEvent_OnTrigger](#oh_hiappevent_ontrigger)) (int row, int size) | 监听器收到事件后，若监听器中未设置OH_HiAppEvent_OnReceive回调，将保存该事件。当保存的事件满足通过 OH_HiAppEvent_SetTriggerCondition设定的条件后，将触发该回调。回调结束后，当新保存的事件消息再次满足设定的条件后，将再次进行回调。 | 75| typedef void(\* [OH_HiAppEvent_OnTake](#oh_hiappevent_ontake)) (const char \*const \*events, uint32_t eventLen) | 使用OH_HiAppEvent_TakeWatcherData获取监听器接收到的事件时，监听器接收到的事件将通过该回调函数传递给调用者。 | 76 77 78### 枚举 79 80| 名称 | 描述 | 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/>} | 错误码定义。 | 83| [EventType](#eventtype) {<br/>FAULT = 1, <br/>STATISTIC = 2, <br/>SECURITY = 3, <br/>BEHAVIOR = 4 <br/>} | 事件类型。 | 84 85 86### 函数 87 88| 名称 | 描述 | 89| -------- | -------- | 90| [ParamList](#paramlist) [OH_HiAppEvent_CreateParamList](#oh_hiappevent_createparamlist) (void) | 创建一个指向参数列表对象的指针。 | 91| void [OH_HiAppEvent_DestroyParamList](#oh_hiappevent_destroyparamlist) ([ParamList](#paramlist) list) | 销毁一个指向参数列表对象的指针，释放其分配内存。 | 92| [ParamList](#paramlist) [OH_HiAppEvent_AddBoolParam](#oh_hiappevent_addboolparam) ([ParamList](#paramlist) list, const char \*name, bool boolean) | 添加一个布尔参数到参数列表中。 | 93| [ParamList](#paramlist) [OH_HiAppEvent_AddBoolArrayParam](#oh_hiappevent_addboolarrayparam) ([ParamList](#paramlist) list, const char \*name, const bool \*booleans, int arrSize) | 添加一个布尔数组参数到参数列表中。 | 94| [ParamList](#paramlist) [OH_HiAppEvent_AddInt8Param](#oh_hiappevent_addint8param) ([ParamList](#paramlist) list, const char \*name, int8_t num) | 添加一个int8_t参数到参数列表中。 | 95| [ParamList](#paramlist) [OH_HiAppEvent_AddInt8ArrayParam](#oh_hiappevent_addint8arrayparam) ([ParamList](#paramlist) list, const char \*name, const int8_t \*nums, int arrSize) | 添加一个int8_t数组参数到参数列表中。 | 96| [ParamList](#paramlist) [OH_HiAppEvent_AddInt16Param](#oh_hiappevent_addint16param) ([ParamList](#paramlist) list, const char \*name, int16_t num) | 添加一个int16_t参数到参数列表中。 | 97| [ParamList](#paramlist) [OH_HiAppEvent_AddInt16ArrayParam](#oh_hiappevent_addint16arrayparam) ([ParamList](#paramlist) list, const char \*name, const int16_t \*nums, int arrSize) | 添加一个int16_t数组参数到参数列表中。 | 98| [ParamList](#paramlist) [OH_HiAppEvent_AddInt32Param](#oh_hiappevent_addint32param) ([ParamList](#paramlist) list, const char \*name, int32_t num) | 添加一个int32_t参数到参数列表中。 | 99| [ParamList](#paramlist) [OH_HiAppEvent_AddInt32ArrayParam](#oh_hiappevent_addint32arrayparam) ([ParamList](#paramlist) list, const char \*name, const int32_t \*nums, int arrSize) | 添加一个int32_t数组参数到参数列表中。 | 100| [ParamList](#paramlist) [OH_HiAppEvent_AddInt64Param](#oh_hiappevent_addint64param) ([ParamList](#paramlist) list, const char \*name, int64_t num) | 添加一个int64_t参数到参数列表中。 | 101| [ParamList](#paramlist) [OH_HiAppEvent_AddInt64ArrayParam](#oh_hiappevent_addint64arrayparam) ([ParamList](#paramlist) list, const char \*name, const int64_t \*nums, int arrSize) | 添加一个int64_t数组参数到参数列表中。 | 102| [ParamList](#paramlist) [OH_HiAppEvent_AddFloatParam](#oh_hiappevent_addfloatparam) ([ParamList](#paramlist) list, const char \*name, float num) | 添加一个float参数到参数列表中。 | 103| [ParamList](#paramlist) [OH_HiAppEvent_AddFloatArrayParam](#oh_hiappevent_addfloatarrayparam) ([ParamList](#paramlist) list, const char \*name, const float \*nums, int arrSize) | 添加一个float数组参数到参数列表中。 | 104| [ParamList](#paramlist) [OH_HiAppEvent_AddDoubleParam](#oh_hiappevent_adddoubleparam) ([ParamList](#paramlist) list, const char \*name, double num) | 添加一个double参数到参数列表中。 | 105| [ParamList](#paramlist) [OH_HiAppEvent_AddDoubleArrayParam](#oh_hiappevent_adddoublearrayparam) ([ParamList](#paramlist) list, const char \*name, const double \*nums, int arrSize) | 添加一个double数组参数到参数列表中。 | 106| [ParamList](#paramlist) [OH_HiAppEvent_AddStringParam](#oh_hiappevent_addstringparam) ([ParamList](#paramlist) list, const char \*name, const char \*str) | 添加一个字符串参数到参数列表中。 | 107| [ParamList](#paramlist) [OH_HiAppEvent_AddStringArrayParam](#oh_hiappevent_addstringarrayparam) ([ParamList](#paramlist) list, const char \*name, const char \*const \*strs, int arrSize) | 添加一个字符串数组参数到参数列表中。 | 108| int [OH_HiAppEvent_Write](#oh_hiappevent_write) (const char \*domain, const char \*name, enum [EventType](#eventtype) type, const [ParamList](#paramlist) list) | 实现对参数为列表类型的应用事件打点。 | 109| bool [OH_HiAppEvent_Configure](#oh_hiappevent_configure) (const char \*name, const char \*value) | 实现应用事件打点的配置功能。 | 110| [HiAppEvent_Watcher](#hiappevent_watcher) \* [OH_HiAppEvent_CreateWatcher](#oh_hiappevent_createwatcher) (const char \*name) | 创建一个用于监听app事件的监听器。 | 111| void [OH_HiAppEvent_DestroyWatcher](#oh_hiappevent_destroywatcher) ([HiAppEvent_Watcher](#hiappevent_watcher) \*watcher) | 销毁已创建的监听器。 | 112| int [OH_HiAppEvent_SetTriggerCondition](#oh_hiappevent_settriggercondition) ([HiAppEvent_Watcher](#hiappevent_watcher) \*watcher, int row, int size, int timeOut) | 用于设置监听器OH_HiAppEvent_OnTrigger回调的触发条件。<br/>分别可以从监视器新接收事件数量、新接收事件大小、onTrigger触发超时时间，设置触发条件。调用方应至少保证从一个方面设置触发条件。 | 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) | 用于设置监听器需要监听的事件的类型。 | 114| int [OH_HiAppEvent_SetWatcherOnTrigger](#oh_hiappevent_setwatcherontrigger) ([HiAppEvent_Watcher](#hiappevent_watcher) \*watcher, [OH_HiAppEvent_OnTrigger](#oh_hiappevent_ontrigger) onTrigger) | 用于设置监听器onTrigger回调的接口。<br/>如果未设置OnReceive回调或已将其设置为nullptr，则将保存观察者接收到的应用事件。当保存的应用事件满足onTrigger回调的触发条件时，将调用onTrigger回调。 | 115| int [OH_HiAppEvent_SetWatcherOnReceive](#oh_hiappevent_setwatcheronreceive) ([HiAppEvent_Watcher](#hiappevent_watcher) \*watcher, [OH_HiAppEvent_OnReceive](#oh_hiappevent_onreceive) onReceive) | 用于设置监听器onReceive回调函数的接口。当监听器监听到相应事件后，onReceive回调函数将被调用。 | 116| int [OH_HiAppEvent_TakeWatcherData](#oh_hiappevent_takewatcherdata) ([HiAppEvent_Watcher](#hiappevent_watcher) \*watcher, uint32_t eventNum, [OH_HiAppEvent_OnTake](#oh_hiappevent_ontake) onTake) | 用于获取监听器收到后保存的事件。 | 117| int [OH_HiAppEvent_AddWatcher](#oh_hiappevent_addwatcher) ([HiAppEvent_Watcher](#hiappevent_watcher) \*watcher) | 添加监听器的接口，监听器开始监听系统消息。 | 118| int [OH_HiAppEvent_RemoveWatcher](#oh_hiappevent_removewatcher) ([HiAppEvent_Watcher](#hiappevent_watcher) \*watcher) | 移除监听器的接口，监听器停止监听系统消息。 | 119| void [OH_HiAppEvent_ClearData](#oh_hiappevent_cleardata) () | 清除所有监视器保存的所有事件。 | 120| [HiAppEvent_Processor](#hiappevent_processor) \* [OH_HiAppEvent_CreateProcessor](#oh_hiappevent_createprocessor) (const char \*name) | 创建一个用于处理app事件上报的处理者。 | 121| int [OH_HiAppEvent_SetReportRoute](#oh_hiappevent_setreportroute) ([HiAppEvent_Processor](#hiappevent_processor) \*processor, const char \*appId, const char \*routeInfo) | 设置处理者事件上报路由的接口。 | 122| int [OH_HiAppEvent_SetReportPolicy](#oh_hiappevent_setreportpolicy) ([HiAppEvent_Processor](#hiappevent_processor) \*processor, int periodReport, int batchReport, bool onStartReport, bool onBackgroundReport) | 设置处理者事件上报策略的接口。 | 123| int [OH_HiAppEvent_SetReportEvent](#oh_hiappevent_setreportevent) ([HiAppEvent_Processor](#hiappevent_processor) \*processor, const char \*domain, const char \*name, bool isRealTime) | 设置处理者上报事件的接口。 | 124| int [OH_HiAppEvent_SetCustomConfig](#oh_hiappevent_setcustomconfig) ([HiAppEvent_Processor](#hiappevent_processor) \*processor, const char \*key, const char \*value) | 设置处理者自定义扩展参数的接口。 | 125| int [OH_HiAppEvent_SetConfigId](#oh_hiappevent_setconfigid) ([HiAppEvent_Processor](#hiappevent_processor) \*processor, int configId) | 设置处理者配置id的接口。 | 126| int [OH_HiAppEvent_SetReportUserId](#oh_hiappevent_setreportuserid) ([HiAppEvent_Processor](#hiappevent_processor) \*processor, const char \*const \*userIdNames, int size) | 设置处理者用户ID的接口。 | 127| int [OH_HiAppEvent_SetReportUserProperty](#oh_hiappevent_setreportuserproperty) ([HiAppEvent_Processor](#hiappevent_processor) \*processor, const char \*const \*userPropertyNames, int size) | 设置处理者用户属性的接口。 | 128| int64_t [OH_HiAppEvent_AddProcessor](#oh_hiappevent_addprocessor) ([HiAppEvent_Processor](#hiappevent_processor) \*processor) | 添加数据处理者的接口。开发者可添加数据处理者，用于提供事件上云功能。数据处理者的实现可预置在设备中，开发者可根据数据处理者的约束设置属性。 | 129| void [OH_HiAppEvent_DestroyProcessor](#oh_hiappevent_destroyprocessor) ([HiAppEvent_Processor](#hiappevent_processor) \*processor) | 销毁已创建的数据处理者。 | 130| int [OH_HiAppEvent_RemoveProcessor](#oh_hiappevent_removeprocessor) (int64_t processorId) | 移除数据处理者的接口，处理者停止上报事件。 | 131| [HiAppEvent_Config](#hiappevent_config) \* [OH_HiAppEvent_CreateConfig](#oh_hiappevent_createconfig) (void) | 创建一个指向设置系统事件触发条件的配置对象的指针。 | 132| void [OH_HiAppEvent_DestroyConfig](#oh_hiappevent_destroyconfig) ([HiAppEvent_Config](#hiappevent_config) \*config) | 销毁已创建的配置对象。 | 133| int [OH_HiAppEvent_SetConfigItem](#oh_hiappevent_setconfigitem) ([HiAppEvent_Config](#hiappevent_config) \*config, const char \*itemName, const char \*itemValue) | 设置配置对象中的配置项。 | 134| int [OH_HiAppEvent_SetEventConfig](#oh_hiappevent_seteventconfig) (const char \*name, [HiAppEvent_Config](#hiappevent_config) \*config) | 设定系统事件订阅触发条件。 | 135 136 137## 宏定义说明 138 139 140### DISABLE 141 142``` 143#define DISABLE "disable" 144``` 145**描述** 146事件打点开关。默认值为false。true：关闭打点功能，false：不关闭打点功能。 147 148**起始版本：** 8 149 150 151### DOMAIN_OS 152 153``` 154#define DOMAIN_OS "OS" 155``` 156**描述** 157OS作用域。 158 159**起始版本：** 12 160 161 162### EVENT_ADDRESS_SANITIZER 163 164``` 165#define EVENT_ADDRESS_SANITIZER "ADDRESS_SANITIZER" 166``` 167**描述** 168应用踩内存事件。 169 170**起始版本：** 12 171 172 173### EVENT_APP_CRASH 174 175``` 176#define EVENT_APP_CRASH "APP_CRASH" 177``` 178**描述** 179应用崩溃事件。 180 181**起始版本：** 12 182 183 184### EVENT_APP_FREEZE 185 186``` 187#define EVENT_APP_FREEZE "APP_FREEZE" 188``` 189**描述** 190应用卡顿事件。 191 192**起始版本：** 12 193 194 195### EVENT_APP_HICOLLIE 196 197``` 198#define EVENT_APP_HICOLLIE "APP_HICOLLIE" 199``` 200**描述** 201应用任务执行超时事件。 202 203**起始版本：** 18 204 205 206### EVENT_APP_LAUNCH 207 208``` 209#define EVENT_APP_LAUNCH "APP_LAUNCH" 210``` 211**描述** 212应用加载事件。 213 214**起始版本：** 12 215 216 217### EVENT_BATTERY_USAGE 218 219``` 220#define EVENT_BATTERY_USAGE "BATTERY_USAGE" 221``` 222**描述** 223应用电源使用率事件。 224 225**起始版本：** 12 226 227 228### EVENT_CPU_USAGE_HIGH 229 230``` 231#define EVENT_CPU_USAGE_HIGH "CPU_USAGE_HIGH" 232``` 233**描述** 234应用CPU资源占用高事件。 235 236**起始版本：** 12 237 238 239### EVENT_DISTRIBUTED_SERVICE_START 240 241``` 242#define EVENT_DISTRIBUTED_SERVICE_START "hiappevent.distributed_service_start" 243``` 244**描述** 245分布式服务事件。 246 247**起始版本：** 8 248 249 250### EVENT_MAIN_THREAD_JANK 251 252``` 253#define EVENT_MAIN_THREAD_JANK "MAIN_THREAD_JANK" 254``` 255**描述** 256应用主线程超时事件。 257 258**起始版本：** 12 259 260 261### EVENT_RESOURCE_OVERLIMIT 262 263``` 264#define EVENT_RESOURCE_OVERLIMIT "RESOURCE_OVERLIMIT" 265``` 266**描述** 267应用资源超限事件。 268 269**起始版本：** 12 270 271 272### EVENT_SCROLL_JANK 273 274``` 275#define EVENT_SCROLL_JANK "SCROLL_JANK" 276``` 277**描述** 278应用滑动卡顿事件。 279 280**起始版本：** 12 281 282 283### EVENT_USER_LOGIN 284 285``` 286#define EVENT_USER_LOGIN "hiappevent.user_login" 287``` 288**描述** 289用户登录事件。 290 291**起始版本：** 8 292 293 294### EVENT_USER_LOGOUT 295 296``` 297#define EVENT_USER_LOGOUT "hiappevent.user_logout" 298``` 299**描述** 300用户登出事件。 301 302**起始版本：** 8 303 304 305### MAX_STORAGE 306 307``` 308#define MAX_STORAGE "max_storage" 309``` 310**描述** 311事件文件目录存储配额大小。默认值为“10M”。 312 313**起始版本：** 8 314 315 316### PARAM_DISTRIBUTED_SERVICE_INSTANCE_ID 317 318``` 319#define PARAM_DISTRIBUTED_SERVICE_INSTANCE_ID "ds_instance_id" 320``` 321**描述** 322分布式服务实例ID。 323 324**起始版本：** 8 325 326 327### PARAM_DISTRIBUTED_SERVICE_NAME 328 329``` 330#define PARAM_DISTRIBUTED_SERVICE_NAME "ds_name" 331``` 332**描述** 333分布式服务名称。 334 335**起始版本：** 8 336 337 338### PARAM_USER_ID 339 340``` 341#define PARAM_USER_ID "user_id" 342``` 343**描述** 344用户ID。 345 346**起始版本：** 8 347 348 349## 类型定义说明 350 351 352### HiAppEvent_AppEventGroup 353 354``` 355typedef struct HiAppEvent_AppEventGroupHiAppEvent_AppEventGroup 356``` 357**描述** 358一组事件信息，包含事件组的名称，按名称分组的单个事件信息数组，事件数组的长度。 359 360**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 361 362**起始版本：** 12 363 364 365### HiAppEvent_AppEventInfo 366 367``` 368typedef struct HiAppEvent_AppEventInfoHiAppEvent_AppEventInfo 369``` 370**描述** 371单个事件信息，包含事件领域，事件名称，事件类型和json格式字符串表示的事件中携带的自定义参数列表。 372 373**起始版本：** 12 374 375 376### HiAppEvent_Config 377 378``` 379typedef struct HiAppEvent_ConfigHiAppEvent_Config 380``` 381**描述** 382用于设置系统事件触发条件的配置对象。 383 384**起始版本：** 15 385 386 387### HiAppEvent_Processor 388 389``` 390typedef struct HiAppEvent_ProcessorHiAppEvent_Processor 391``` 392**描述** 393用于处理app事件上报的处理者。 394 395**起始版本：** 18 396 397 398### HiAppEvent_Watcher 399 400``` 401typedef struct HiAppEvent_WatcherHiAppEvent_Watcher 402``` 403**描述** 404用于接收app事件的监听器。 405 406**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 407 408**起始版本：** 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**描述** 417监听器接收到事件后，将触发该回调，将事件内容传递给调用方。 418 419注意：回调中的指针所指对象的生命周期仅限于该回调函数内，请勿在该回调函数外直接使用该指针，若需缓存该信息，请对指针指向的内容进行深拷贝。 420 421**起始版本：** 12 422 423**参数：** 424 425| 名称 | 描述 | 426| -------- | -------- | 427| domain | 接收到的app事件的领域。 | 428| appEventGroups | 按照不同事件名称分组的事件组数组。 | 429| groupLen | 事件组数组的长度。 | 430 431 432### OH_HiAppEvent_OnTake 433 434``` 435typedef void(* OH_HiAppEvent_OnTake) (const char *const *events, uint32_t eventLen) 436``` 437**描述** 438使用OH_HiAppEvent_TakeWatcherData获取监听器接收到的事件时，监听器接收到的事件将通过该回调函数传递给调用者。 439 440注意：回调中的指针所指对象的生命周期仅限于该回调函数内，请勿在该回调函数外直接使用该指针。若需缓存该信息，请对指针指向的内容进行深拷贝。 441 442**起始版本：** 12 443 444**参数：** 445 446| 名称 | 描述 | 447| -------- | -------- | 448| events | json字符串格式的事件数组。 | 449| eventLen | 事件数组大小。 | 450 451 452### OH_HiAppEvent_OnTrigger 453 454``` 455typedef void(* OH_HiAppEvent_OnTrigger) (int row, int size) 456``` 457**描述** 458监听器收到事件后，若监听器中未设置OH_HiAppEvent_OnReceive回调，将保存该事件。 459 460当保存的事件满足通过OH_HiAppEvent_SetTriggerCondition设定的条件后，将触发该回调。回调结束后，当新保存的事件消息再次满足设定的条件后，将再次进行回调。 461 462**起始版本：** 12 463 464**参数：** 465 466| 名称 | 描述 | 467| -------- | -------- | 468| row | 监听器新接收到的事件消息的数量。 | 469| size | 监听器新接收的事件消息的大小总和(单个事件大小计算方式为：将消息转换为json字符串后，字符串的长度)。 | 470 471 472### ParamList 473 474``` 475typedef struct ParamListNode* ParamList 476``` 477**描述** 478事件参数列表节点。 479 480**起始版本：** 8 481 482 483## 枚举类型说明 484 485 486### EventType 487 488``` 489enum EventType 490``` 491**描述** 492事件类型。 493 494建议开发者根据不同的使用场景选择不同的事件类型。 495 496**起始版本：** 8 497 498| 枚举值 | 描述 | 499| -------- | -------- | 500| FAULT | 故障事件类型。 | 501| STATISTIC | 统计事件类型。 | 502| SECURITY | 安全事件类型。 | 503| BEHAVIOR | 行为事件类型。 | 504 505 506### HiAppEvent_ErrorCode 507 508``` 509enum HiAppEvent_ErrorCode 510``` 511**描述** 512错误码定义。 513 514**起始版本：** 15 515 516| 枚举值 | 描述 | 517| -------- | -------- | 518| HIAPPEVENT_SUCCESS | 操作成功。 | 519| HIAPPEVENT_INVALID_PARAM_VALUE_LENGTH | 参数值长度无效。**起始版本：** 18 | 520| HIAPPEVENT_PROCESSOR_IS_NULL | 事件处理者为空。**起始版本：** 18 | 521| HIAPPEVENT_PROCESSOR_NOT_FOUND | 事件处理者不存在。**起始版本：** 18 | 522| HIAPPEVENT_INVALID_PARAM_VALUE | 参数值无效。 | 523| HIAPPEVENT_EVENT_CONFIG_IS_NULL | 事件配置为空。 | 524| HIAPPEVENT_OPERATE_FAILED | 操作失败。**起始版本：** 18 | 525| HIAPPEVENT_INVALID_UID | 无效的用户标识。**起始版本：** 18 | 526 527 528## 函数说明 529 530 531### OH_HiAppEvent_AddBoolArrayParam() 532 533``` 534ParamList OH_HiAppEvent_AddBoolArrayParam (ParamList list, const char * name, const bool * booleans, int arrSize ) 535``` 536**描述** 537添加一个布尔数组参数到参数列表中。 538 539**起始版本：** 8 540 541**参数：** 542 543| 名称 | 描述 | 544| -------- | -------- | 545| list | 需要添加参数的参数列表指针。 | 546| name | 需要添加的参数名称。 | 547| booleans | 需要添加的布尔数组参数值。 | 548| arrSize | 需要添加的参数数组大小。 | 549 550**返回：** 551 552添加参数后的参数列表指针。 553 554 555### OH_HiAppEvent_AddBoolParam() 556 557``` 558ParamList OH_HiAppEvent_AddBoolParam (ParamList list, const char * name, bool boolean ) 559``` 560**描述** 561添加一个布尔参数到参数列表中。 562 563**起始版本：** 8 564 565**参数：** 566 567| 名称 | 描述 | 568| -------- | -------- | 569| list | 需要添加参数的参数列表指针。 | 570| name | 需要添加的参数名称。 | 571| boolean | 需要添加的布尔参数值。 | 572 573**返回：** 574 575添加参数后的参数列表指针。 576 577 578### OH_HiAppEvent_AddDoubleArrayParam() 579 580``` 581ParamList OH_HiAppEvent_AddDoubleArrayParam (ParamList list, const char * name, const double * nums, int arrSize ) 582``` 583**描述** 584添加一个double数组参数到参数列表中。 585 586**起始版本：** 8 587 588**参数：** 589 590| 名称 | 描述 | 591| -------- | -------- | 592| list | 需要添加参数的参数列表指针。 | 593| name | 需要添加的参数名称。 | 594| nums | 需要添加的double数组参数值。 | 595| arrSize | 需要添加的参数数组大小。 | 596 597**返回：** 598 599添加参数后的参数列表指针。 600 601 602### OH_HiAppEvent_AddDoubleParam() 603 604``` 605ParamList OH_HiAppEvent_AddDoubleParam (ParamList list, const char * name, double num ) 606``` 607**描述** 608添加一个double参数到参数列表中。 609 610**起始版本：** 8 611 612**参数：** 613 614| 名称 | 描述 | 615| -------- | -------- | 616| list | 需要添加参数的参数列表指针。 | 617| name | 需要添加的参数名称。 | 618| num | 需要添加的double参数值。 | 619 620**返回：** 621 622添加参数后的参数列表指针。 623 624 625### OH_HiAppEvent_AddFloatArrayParam() 626 627``` 628ParamList OH_HiAppEvent_AddFloatArrayParam (ParamList list, const char * name, const float * nums, int arrSize ) 629``` 630**描述** 631添加一个float数组参数到参数列表中。 632 633**起始版本：** 8 634 635**参数：** 636 637| 名称 | 描述 | 638| -------- | -------- | 639| list | 需要添加参数的参数列表指针。 | 640| name | 需要添加的参数名称。 | 641| nums | 需要添加的float数组参数值。 | 642| arrSize | 需要添加的参数数组大小。 | 643 644**返回：** 645 646添加参数后的参数列表指针。 647 648 649### OH_HiAppEvent_AddFloatParam() 650 651``` 652ParamList OH_HiAppEvent_AddFloatParam (ParamList list, const char * name, float num ) 653``` 654**描述** 655添加一个float参数到参数列表中。 656 657**起始版本：** 8 658 659**参数：** 660 661| 名称 | 描述 | 662| -------- | -------- | 663| list | 需要添加参数的参数列表指针。 | 664| name | 需要添加的参数名称。 | 665| num | 需要添加的float参数值。 | 666 667**返回：** 668 669添加参数后的参数列表指针。 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**描述** 678添加一个int16_t数组参数到参数列表中。 679 680**起始版本：** 8 681 682**参数：** 683 684| 名称 | 描述 | 685| -------- | -------- | 686| list | 需要添加参数的参数列表指针。 | 687| name | 需要添加的参数名称。 | 688| nums | 需要添加的int16_t数组参数值。 | 689| arrSize | 需要添加的参数数组大小。 | 690 691**返回：** 692 693添加参数后的参数列表指针。 694 695 696### OH_HiAppEvent_AddInt16Param() 697 698``` 699ParamList OH_HiAppEvent_AddInt16Param (ParamList list, const char * name, int16_t num ) 700``` 701**描述** 702添加一个int16_t参数到参数列表中。 703 704**起始版本：** 8 705 706**参数：** 707 708| 名称 | 描述 | 709| -------- | -------- | 710| list | 需要添加参数的参数列表指针。 | 711| name | 需要添加的参数名称。 | 712| num | 需要添加的int16_t参数值。 | 713 714**返回：** 715 716添加参数后的参数列表指针。 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**描述** 725添加一个int32_t数组参数到参数列表中。 726 727**起始版本：** 8 728 729**参数：** 730 731| 名称 | 描述 | 732| -------- | -------- | 733| list | 需要添加参数的参数列表指针。 | 734| name | 需要添加的参数名称。 | 735| nums | 需要添加的int32_t数组参数值。 | 736| arrSize | 需要添加的参数数组大小。 | 737 738**返回：** 739 740添加参数后的参数列表指针。 741 742 743### OH_HiAppEvent_AddInt32Param() 744 745``` 746ParamList OH_HiAppEvent_AddInt32Param (ParamList list, const char * name, int32_t num ) 747``` 748**描述** 749添加一个int32_t参数到参数列表中。 750 751**起始版本：** 8 752 753**参数：** 754 755| 名称 | 描述 | 756| -------- | -------- | 757| list | 需要添加参数的参数列表指针。 | 758| name | 需要添加的参数名称。 | 759| num | 需要添加的int32_t参数值。 | 760 761**返回：** 762 763添加参数后的参数列表指针。 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**描述** 772添加一个int64_t数组参数到参数列表中。 773 774**起始版本：** 8 775 776**参数：** 777 778| 名称 | 描述 | 779| -------- | -------- | 780| list | 需要添加参数的参数列表指针。 | 781| name | 需要添加的参数名称。 | 782| nums | 需要添加的int64_t数组参数值。 | 783| arrSize | 需要添加的参数数组大小。 | 784 785**返回：** 786 787添加参数后的参数列表指针。 788 789 790### OH_HiAppEvent_AddInt64Param() 791 792``` 793ParamList OH_HiAppEvent_AddInt64Param (ParamList list, const char * name, int64_t num ) 794``` 795**描述** 796添加一个int64_t参数到参数列表中。 797 798**起始版本：** 8 799 800**参数：** 801 802| 名称 | 描述 | 803| -------- | -------- | 804| list | 需要添加参数的参数列表指针。 | 805| name | 需要添加的参数名称。 | 806| num | 需要添加的int64_t参数值。 | 807 808**返回：** 809 810添加参数后的参数列表指针。 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**描述** 819添加一个int8_t数组参数到参数列表中。 820 821**起始版本：** 8 822 823**参数：** 824 825| 名称 | 描述 | 826| -------- | -------- | 827| list | 需要添加参数的参数列表指针。 | 828| name | 需要添加的参数名称。 | 829| nums | 需要添加的int8_t数组参数值。 | 830| arrSize | 需要添加的参数数组大小。 | 831 832**返回：** 833 834添加参数后的参数列表指针。 835 836 837### OH_HiAppEvent_AddInt8Param() 838 839``` 840ParamList OH_HiAppEvent_AddInt8Param (ParamList list, const char * name, int8_t num ) 841``` 842**描述** 843添加一个int8_t参数到参数列表中。 844 845**起始版本：** 8 846 847**参数：** 848 849| 名称 | 描述 | 850| -------- | -------- | 851| list | 需要添加参数的参数列表指针。 | 852| name | 需要添加的参数名称。 | 853| num | 需要添加的int8_t参数值。 | 854 855**返回：** 856 857添加参数后的参数列表指针。 858 859 860### OH_HiAppEvent_AddProcessor() 861 862``` 863int64_t OH_HiAppEvent_AddProcessor (HiAppEvent_Processor * processor) 864``` 865**描述** 866添加数据处理者的接口。开发者可添加数据处理者，用于提供事件上云功能。数据处理者的实现可预置在设备中，开发者可根据数据处理者的约束设置属性。 867 868注意：Processor的配置信息需要由数据处理者提供，目前设备内暂未预置可供交互的数据处理者，因此当前事件上云功能不可用。 869 870**起始版本：** 18 871 872**参数：** 873 874| 名称 | 描述 | 875| -------- | -------- | 876| processor | 指向处理者的指针（即OH_HiAppEvent_CreateProcessor接口返回的指针）。 | 877 878**返回：** 879 880调用成功时返回处理者唯一ID，大于0； 881 882HIAPPEVENT_PROCESSOR_IS_NULL：processor入参为空； 883 884HIAPPEVENT_INVALID_PARAM_VALUE：参数值无效； 885 886HIAPPEVENT_OPERATE_FAILED：数据处理者名称未找到或注册失败； 887 888HIAPPEVENT_INVALID_UID：用户标识无效。 889 890具体可参考[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**描述** 899添加一个字符串数组参数到参数列表中。 900 901**起始版本：** 8 902 903**参数：** 904 905| 名称 | 描述 | 906| -------- | -------- | 907| list | 需要添加参数的参数列表指针。 | 908| name | 需要添加的参数名称。 | 909| strs | 需要添加的字符串数组参数值。 | 910| arrSize | 需要添加的参数数组大小。 | 911 912**返回：** 913 914添加参数后的参数列表指针。 915 916 917### OH_HiAppEvent_AddStringParam() 918 919``` 920ParamList OH_HiAppEvent_AddStringParam (ParamList list, const char * name, const char * str ) 921``` 922**描述** 923添加一个字符串参数到参数列表中。 924 925**起始版本：** 8 926 927**参数：** 928 929| 名称 | 描述 | 930| -------- | -------- | 931| list | 需要添加参数的参数列表指针。 | 932| name | 需要添加的参数名称。 | 933| str | 需要添加的字符串参数值。 | 934 935**返回：** 936 937添加参数后的参数列表指针。 938 939 940### OH_HiAppEvent_AddWatcher() 941 942``` 943int OH_HiAppEvent_AddWatcher (HiAppEvent_Watcher * watcher) 944``` 945**描述** 946添加监听器的接口，监听器开始监听系统消息。 947 948**起始版本：** 12 949 950**参数：** 951 952| 名称 | 描述 | 953| -------- | -------- | 954| watcher | 指向监听器的指针（即OH_HiAppEvent_CreateWatcher接口返回的指针）。 | 955 956**返回：** 957 9580：接口调用成功；-5：watcher入参空指针。 959 960 961### OH_HiAppEvent_ClearData() 962 963``` 964void OH_HiAppEvent_ClearData () 965``` 966**描述** 967清除所有监视器保存的所有事件。 968 969**起始版本：** 12 970 971 972### OH_HiAppEvent_Configure() 973 974``` 975bool OH_HiAppEvent_Configure (const char * name, const char * value ) 976``` 977**描述** 978实现应用事件打点的配置功能。 979 980应用事件打点配置接口，用于配置事件打点开关、事件文件目录存储配额大小等功能。 981 982**起始版本：** 8 983 984**参数：** 985 986| 名称 | 描述 | 987| -------- | -------- | 988| name | 配置项名称。名称可填[DISABLE](#disable)和[MAX_STORAGE](#max_storage)。 | 989| value | 配置项值。如果配置项名称是[DISABLE](#disable)，值可以填“true”或者“false”；<br/>如果配置项名称是[MAX_STORAGE](#max_storage)，配额值字符串只由数字字符和大小单位字符（单位字符支持[b\|k\|kb\|m\|mb\|g\|gb\|t\|tb]，不区分大小写）构成。<br/>配额值字符串必须以数字开头，后面可以选择不传单位字符（默认使用byte作为单位），或者以单位字符结尾。 | 990 991**返回：** 992 993配置结果。如果配置成功，则返回true；如果配置失败则返回false。 994 995 996### OH_HiAppEvent_CreateConfig() 997 998``` 999HiAppEvent_Config* OH_HiAppEvent_CreateConfig (void ) 1000``` 1001**描述** 1002创建一个指向设置系统事件触发条件的配置对象的指针。 1003 1004**起始版本：** 15 1005 1006**返回：** 1007 1008指向设置系统事件触发条件的配置对象的指针。 1009 1010 1011### OH_HiAppEvent_CreateParamList() 1012 1013``` 1014ParamList OH_HiAppEvent_CreateParamList (void ) 1015``` 1016**描述** 1017创建一个指向参数列表对象的指针。 1018 1019**起始版本：** 8 1020 1021**返回：** 1022 1023指向参数列表对象的指针。 1024 1025 1026### OH_HiAppEvent_CreateProcessor() 1027 1028``` 1029HiAppEvent_Processor* OH_HiAppEvent_CreateProcessor (const char * name) 1030``` 1031**描述** 1032创建一个用于处理app事件上报的处理者。 1033 1034注意：创建的处理者不再使用后必须通过调用OH_HiAppEvent_DestroyProcessor接口进行销毁。 1035 1036**起始版本：** 18 1037 1038**参数：** 1039 1040| 名称 | 描述 | 1041| -------- | -------- | 1042| name | 处理者名称。只能包含大小写字母、数字、下划线和$，不能以数字开头，长度非空且不超过256个字符。 | 1043 1044**返回：** 1045 1046接口调用成功时返回指向的新建处理者的指针，name参数异常时返回nullptr。 1047 1048 1049### OH_HiAppEvent_CreateWatcher() 1050 1051``` 1052HiAppEvent_Watcher* OH_HiAppEvent_CreateWatcher (const char * name) 1053``` 1054**描述** 1055创建一个用于监听app事件的监听器。 1056 1057注意：创建的监听器不再使用后必须通过调用OH_HiAppEvent_DestroyWatcher接口进行销毁。 1058 1059**起始版本：** 12 1060 1061**参数：** 1062 1063| 名称 | 描述 | 1064| -------- | -------- | 1065| name | 监听器名称。 | 1066 1067**返回：** 1068 1069接口调用成功时返回指向的新建监听器的指针，name参数异常时返回nullptr。 1070 1071 1072### OH_HiAppEvent_DestroyConfig() 1073 1074``` 1075void OH_HiAppEvent_DestroyConfig (HiAppEvent_Config * config) 1076``` 1077**描述** 1078销毁已创建的配置对象。 1079 1080注意：已创建的配置对象不再使用后，需要将其销毁，释放内存，防止内存泄漏，销毁后需要将对应指针置空。 1081 1082**起始版本：** 15 1083 1084**参数：** 1085 1086| 名称 | 描述 | 1087| -------- | -------- | 1088| config | 指向配置对象的指针（即OH_HiAppEvent_CreateConfig接口返回的指针）。 | 1089 1090 1091### OH_HiAppEvent_DestroyParamList() 1092 1093``` 1094void OH_HiAppEvent_DestroyParamList (ParamList list) 1095``` 1096**描述** 1097销毁一个指向参数列表对象的指针，释放其分配内存。 1098 1099**起始版本：** 8 1100 1101**参数：** 1102 1103| 名称 | 描述 | 1104| -------- | -------- | 1105| list | 参数列表对象指针。 | 1106 1107 1108### OH_HiAppEvent_DestroyProcessor() 1109 1110``` 1111void OH_HiAppEvent_DestroyProcessor (HiAppEvent_Processor * processor) 1112``` 1113**描述** 1114销毁已创建的数据处理者。 1115 1116注意：已创建的处理者不再使用后，需要将其销毁，释放内存，防止内存泄漏，销毁后需将对应指针置空。 1117 1118**起始版本：** 18 1119 1120**参数：** 1121 1122| 名称 | 描述 | 1123| -------- | -------- | 1124| processor | 指向处理者的指针（即OH_HiAppEvent_CreateProcessor接口返回的指针）。 | 1125 1126 1127### OH_HiAppEvent_DestroyWatcher() 1128 1129``` 1130void OH_HiAppEvent_DestroyWatcher (HiAppEvent_Watcher * watcher) 1131``` 1132**描述** 1133销毁已创建的监听器。 1134 1135注意：已创建的监听器不再使用后，需要将其销毁，释放内存，防止内存泄漏，销毁后需将对应指针置空。 1136 1137**起始版本：** 12 1138 1139**参数：** 1140 1141| 名称 | 描述 | 1142| -------- | -------- | 1143| watcher | 指向监听器的指针（即OH_HiAppEvent_CreateWatcher接口返回的指针）。 | 1144 1145 1146### OH_HiAppEvent_RemoveProcessor() 1147 1148``` 1149int OH_HiAppEvent_RemoveProcessor (int64_t processorId) 1150``` 1151**描述** 1152移除数据处理者的接口，处理者停止上报事件。 1153 1154注意：该接口仅仅使处理者停止上报事件，并未销毁该处理者，该处理者依然常驻内存，直至调用OH_HiAppEvent_DestroyProcessor接口，内存才会释放。 1155 1156**起始版本：** 18 1157 1158**参数：** 1159 1160| 名称 | 描述 | 1161| -------- | -------- | 1162| processorId | 处理者唯一ID。 | 1163 1164**返回：** 1165 1166HIAPPEVENT_SUCCESS：接口调用成功； 1167 1168HIAPPEVENT_PROCESSOR_NOT_FOUND：事件处理者不存在； 1169 1170HIAPPEVENT_OPERATE_FAILED：操作失败； 1171 1172HIAPPEVENT_INVALID_UID：用户标识无效。 1173 1174具体可参考[HiAppEvent_ErrorCode](#hiappevent_errorcode)。 1175 1176 1177### OH_HiAppEvent_RemoveWatcher() 1178 1179``` 1180int OH_HiAppEvent_RemoveWatcher (HiAppEvent_Watcher * watcher) 1181``` 1182**描述** 1183移除监听器的接口，监听器停止监听系统消息。 1184 1185注意：该接口仅仅使监听器停止监听系统消息，并未销毁该监听器，该监听器依然常驻内存，直至调用OH_HiAppEvent_DestroyWatcher接口，内存才会释放。 1186 1187**起始版本：** 12 1188 1189**参数：** 1190 1191| 名称 | 描述 | 1192| -------- | -------- | 1193| watcher | 指向监听器的指针（即OH_HiAppEvent_CreateWatcher接口返回的指针）。 | 1194 1195**返回：** 1196 11970：接口调用成功；-5：watcher入参空指针；-6：还未调用OH_HiAppEvent_AddWatcher，操作顺序有误。 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**描述** 1206用于设置监听器需要监听的事件的类型。 1207 1208该函数可以重复调用，可添加多个过滤规则，而非替换，监听器将收到满足任一过滤规则的事件的通知。 1209 1210**起始版本：** 12 1211 1212**参数：** 1213 1214| 名称 | 描述 | 1215| -------- | -------- | 1216| watcher | 指向监听器的指针（即OH_HiAppEvent_CreateWatcher接口返回的指针）。 | 1217| domain | 需要监听事件的领域。 | 1218| eventTypes | 需要监听事件的事件类型。使用按位与方式进行匹配，可支持监听多种类型的事件。 第一位为1（数值为1）表示支持监听故障类型的事件；<br/>第二位为1（数值为2）表示支持监听统计类型的事件；<br/>第三位为1（数值为4）表示支持监听安全类型的事件；<br/>第四位为1（数值为8）表示支持监听行为类型的事件。<br/>都为1（数值为15）或者都为0（数值为0）表示支持所有类型事件。 | 1219| names | 需要监听的事件名称数组。 | 1220| namesLen | 监听的事件名称的数组长度。 | 1221 1222**返回：** 1223 12240：接口调用成功；-1：names参数异常；-4：domain参数异常；-5：watcher入参空指针。 1225 1226 1227### OH_HiAppEvent_SetConfigId() 1228 1229``` 1230int OH_HiAppEvent_SetConfigId (HiAppEvent_Processor * processor, int configId ) 1231``` 1232**描述** 1233设置处理者配置id的接口。 1234 1235**起始版本：** 18 1236 1237**参数：** 1238 1239| 名称 | 描述 | 1240| -------- | -------- | 1241| processor | 指向处理者的指针（即OH_HiAppEvent_CreateProcessor接口返回的指针）。 | 1242| configId | 数据处理者配置id，自然数。 | 1243 1244**返回：** 1245 1246HIAPPEVENT_SUCCESS：接口调用成功； 1247 1248HIAPPEVENT_PROCESSOR_IS_NULL：processor入参为空； 1249 1250HIAPPEVENT_INVALID_PARAM_VALUE：参数值无效； 1251 1252HIAPPEVENT_INVALID_UID：用户标识无效。 1253 1254具体可参考[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**描述** 1263设置配置对象中的配置项。 1264 1265**起始版本：** 15 1266 1267**参数：** 1268 1269| 名称 | 描述 | 1270| -------- | -------- | 1271| config | 指向配置对象的指针（即OH_HiAppEvent_CreateConfig接口返回的指针）。 | 1272| itemName | 待设定配置项的名称。 | 1273| itemValue | 待设定配置项的值。 | 1274 1275**返回：** 1276 1277HIAPPEVENT_SUCCESS：接口调用成功； 1278 1279HIAPPEVENT_EVENT_CONFIG_IS_NULL：传入的指向配置对象的指针为空； 1280 1281HIAPPEVENT_INVALID_PARAM_VALUE：设定的配置项无效。 1282 1283具体可参考[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**描述** 1292设置处理者自定义扩展参数的接口。 1293 1294**起始版本：** 18 1295 1296**参数：** 1297 1298| 名称 | 描述 | 1299| -------- | -------- | 1300| processor | 指向处理者的指针（即OH_HiAppEvent_CreateProcessor接口返回的指针）。 | 1301| key | 参数名，长度不超过32个字符。 | 1302| value | 参数值，长度不超过1024个字符。 | 1303 1304**返回：** 1305 1306HIAPPEVENT_SUCCESS：接口调用成功； 1307 1308HIAPPEVENT_PROCESSOR_IS_NULL：processor入参为空； 1309 1310HIAPPEVENT_INVALID_PARAM_VALUE：参数值无效； 1311 1312HIAPPEVENT_INVALID_UID：用户标识无效； 1313 1314HIAPPEVENT_INVALID_PARAM_VALUE_LENGTH：参数值长度无效。 1315 1316具体可参考[HiAppEvent_ErrorCode](#hiappevent_errorcode)。 1317 1318 1319### OH_HiAppEvent_SetEventConfig() 1320 1321``` 1322int OH_HiAppEvent_SetEventConfig (const char * name, HiAppEvent_Config * config ) 1323``` 1324**描述** 1325设定系统事件订阅触发条件。 1326 1327**起始版本：** 15 1328 1329**参数：** 1330 1331| 名称 | 描述 | 1332| -------- | -------- | 1333| name | 系统事件的名称。 | 1334| config | 指向配置对象的指针（即OH_HiAppEvent_CreateConfig接口返回的指针）。 | 1335 1336**返回：** 1337 1338HIAPPEVENT_SUCCESS：接口调用成功； 1339 1340HIAPPEVENT_INVALID_PARAM_VALUE：设置的参数无效。 1341 1342具体可参考[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**描述** 1351设置处理者上报事件的接口。 1352 1353**起始版本：** 18 1354 1355**参数：** 1356 1357| 名称 | 描述 | 1358| -------- | -------- | 1359| processor | 指向处理者的指针（即OH_HiAppEvent_CreateProcessor接口返回的指针）。 | 1360| domain | 上报事件的领域。 | 1361| name | 上报事件的名称。 | 1362| isRealTime | 是否实时上报。 | 1363 1364**返回：** 1365 1366HIAPPEVENT_SUCCESS：接口调用成功； 1367 1368HIAPPEVENT_PROCESSOR_IS_NULL：processor入参为空； 1369 1370HIAPPEVENT_INVALID_PARAM_VALUE：参数值无效； 1371 1372HIAPPEVENT_INVALID_UID：用户标识无效。 1373 1374具体可参考[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**描述** 1383设置处理者事件上报策略的接口。 1384 1385**起始版本：** 18 1386 1387**参数：** 1388 1389| 名称 | 描述 | 1390| -------- | -------- | 1391| processor | 指向处理者的指针（即OH_HiAppEvent_CreateProcessor接口返回的指针）。 | 1392| periodReport | 事件定时上报周期，单位为秒。 | 1393| batchReport | 事件上报阈值，当事件条数达到阈值时上报事件。 | 1394| onStartReport | 数据处理者在启动时是否上报事件，默认值为false。 | 1395| onBackgroundReport | 应用程序进入后台时，是否上报事件，默认值为false。 | 1396 1397**返回：** 1398 1399HIAPPEVENT_SUCCESS：接口调用成功； 1400 1401HIAPPEVENT_PROCESSOR_IS_NULL：processor入参为空； 1402 1403HIAPPEVENT_INVALID_PARAM_VALUE：参数值无效； 1404 1405HIAPPEVENT_INVALID_UID：用户标识无效。 1406 1407具体可参考[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**描述** 1416设置处理者事件上报路由的接口。 1417 1418**起始版本：** 18 1419 1420**参数：** 1421 1422| 名称 | 描述 | 1423| -------- | -------- | 1424| processor | 指向处理者的指针（即OH_HiAppEvent_CreateProcessor接口返回的指针）。 | 1425| appId | 处理者的应用ID。 | 1426| routeInfo | 服务器位置信息，默认为空字符串。传入字符串长度不能超8KB，超过时会被置为默认值。 | 1427 1428**返回：** 1429 1430HIAPPEVENT_SUCCESS：接口调用成功； 1431 1432HIAPPEVENT_PROCESSOR_IS_NULL：processor入参为空； 1433 1434HIAPPEVENT_INVALID_PARAM_VALUE：参数值无效； 1435 1436HIAPPEVENT_INVALID_UID：用户标识无效； 1437 1438HIAPPEVENT_INVALID_PARAM_VALUE_LENGTH：参数值长度无效。 1439 1440具体可参考[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**描述** 1449设置处理者用户ID的接口。 1450 1451**起始版本：** 18 1452 1453**参数：** 1454 1455| 名称 | 描述 | 1456| -------- | -------- | 1457| processor | 指向处理者的指针（即OH_HiAppEvent_CreateProcessor接口返回的指针）。 | 1458| userIdNames | 处理者可以上报的用户ID的name数组。 | 1459| size | 用户ID的name数组长度。 | 1460 1461**返回：** 1462 1463HIAPPEVENT_SUCCESS：接口调用成功； 1464 1465HIAPPEVENT_PROCESSOR_IS_NULL：processor入参为空； 1466 1467HIAPPEVENT_INVALID_PARAM_VALUE：参数值无效； 1468 1469HIAPPEVENT_INVALID_UID：用户标识无效； 1470 1471HIAPPEVENT_INVALID_PARAM_VALUE_LENGTH：参数值长度无效。 1472 1473具体可参考[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**描述** 1482设置处理者用户属性的接口。 1483 1484**起始版本：** 18 1485 1486**参数：** 1487 1488| 名称 | 描述 | 1489| -------- | -------- | 1490| processor | 指向处理者的指针（即OH_HiAppEvent_CreateProcessor接口返回的指针）。 | 1491| userPropertyNames | 处理者可以上报的用户属性数组。 | 1492| size | 用户属性数组的长度。 | 1493 1494**返回：** 1495 1496HIAPPEVENT_SUCCESS：接口调用成功； 1497 1498HIAPPEVENT_PROCESSOR_IS_NULL：processor入参为空； 1499 1500HIAPPEVENT_INVALID_PARAM_VALUE：参数值无效； 1501 1502HIAPPEVENT_INVALID_UID：用户标识无效； 1503 1504HIAPPEVENT_INVALID_PARAM_VALUE_LENGTH：参数值长度无效。 1505 1506具体可参考[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**描述** 1515用于设置监听器OH_HiAppEvent_OnTrigger回调的触发条件。 1516 1517分别可以从监视器新接收事件数量、新接收事件大小、onTrigger触发超时时间，设置触发条件。调用方应至少保证从一个方面设置触发条件。 1518 1519**起始版本：** 12 1520 1521**参数：** 1522 1523| 名称 | 描述 | 1524| -------- | -------- | 1525| watcher | 指向监听器的指针（即OH_HiAppEvent_CreateWatcher接口返回的指针）。 | 1526| row | 当输入值大于0，且新接收事件的数量大于等于该值时，将调用设置的onTrigger回调函数；<br/>当输入值小于等于0时，不再以接收数量多少为维度来触发onTrigger回调。 | 1527| size | 当输入值大于0，且新接收事件的大小(单个事件大小计算方式为，将事件转换为json字符串后，字符串的长度)大于等于该值时，将调用设置的onTrigger回调函数；<br/>当输入值小于等于0时，不再以新接收事件大小为维度触发onTrigger回调。 | 1528| timeOut | 单位秒，当输入值大于0，每经过timeout秒，将检查监视器是否存在新接收到的事件，如果存在将触发onTrigger回调。<br/>触发onTrigger后，经过timeOut秒后将再次检查是否存在新接收到的事件。<br/>当输入值小于等于0，不以超时时间为维度触发onTrigger回调。 | 1529 1530**返回：** 1531 15320：接口调用成功；-5：watcher入参空指针。 1533 1534 1535### OH_HiAppEvent_SetWatcherOnReceive() 1536 1537``` 1538int OH_HiAppEvent_SetWatcherOnReceive (HiAppEvent_Watcher * watcher, OH_HiAppEvent_OnReceive onReceive ) 1539``` 1540**描述** 1541用于设置监听器onReceive回调函数的接口。当监听器监听到相应事件后，onReceive回调函数将被调用。 1542 1543**起始版本：** 12 1544 1545**参数：** 1546 1547| 名称 | 描述 | 1548| -------- | -------- | 1549| watcher | 指向监听器的指针（即OH_HiAppEvent_CreateWatcher接口返回的指针）。 | 1550| onReceive | 回调函数的函数指针。 | 1551 1552**返回：** 1553 15540：接口调用成功；-5：watcher入参空指针。 1555 1556 1557### OH_HiAppEvent_SetWatcherOnTrigger() 1558 1559``` 1560int OH_HiAppEvent_SetWatcherOnTrigger (HiAppEvent_Watcher * watcher, OH_HiAppEvent_OnTrigger onTrigger ) 1561``` 1562**描述** 1563用于设置监听器onTrigger回调的接口。 1564 1565如果未设置OnReceive回调或已将其设置为nullptr，则将保存观察者接收到的应用事件。当保存的应用事件满足onTrigger回调的触发条件时，将调用onTrigger回调。 1566 1567**起始版本：** 12 1568 1569**参数：** 1570 1571| 名称 | 描述 | 1572| -------- | -------- | 1573| watcher | 指向监听器的指针（即OH_HiAppEvent_CreateWatcher接口返回的指针）。 | 1574| onTrigger | 需要设置的回调。 | 1575 1576**返回：** 1577 15780：接口调用成功；-5：watcher入参空指针。 1579 1580 1581### OH_HiAppEvent_TakeWatcherData() 1582 1583``` 1584int OH_HiAppEvent_TakeWatcherData (HiAppEvent_Watcher * watcher, uint32_t eventNum, OH_HiAppEvent_OnTake onTake ) 1585``` 1586**描述** 1587用于获取监听器收到后保存的事件。 1588 1589**起始版本：** 12 1590 1591**参数：** 1592 1593| 名称 | 描述 | 1594| -------- | -------- | 1595| watcher | 指向监听器的指针（即OH_HiAppEvent_CreateWatcher接口返回的指针）。 | 1596| eventNum | 当输入值小于等于0时，取全部已保存事件；当输入值大于0时，按照事件发生时间倒序排列，取指定数量的已保存事件。 | 1597| onTake | 回调函数指针，事件通过调用该函数返回事件信息。 | 1598 1599**返回：** 1600 16010：接口调用成功；-5：watcher入参空指针；-6：还未调用OH_HiAppEvent_AddWatcher，操作顺序有误。 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**描述** 1610实现对参数为列表类型的应用事件打点。 1611 1612在应用事件打点前，该接口会先对该事件的参数进行校验。如果校验成功，则接口会将事件写入事件文件。 1613 1614**起始版本：** 8 1615 1616**参数：** 1617 1618| 名称 | 描述 | 1619| -------- | -------- | 1620| domain | 事件领域。开发者可以根据需要自定义事件领域。<br/>事件领域名称支持数字、字母、下划线字符，需要以字母开头且不能以下划线结尾，长度非空且不超过32个字符。 | 1621| name | 事件名称。开发者可以根据需要自定义事件名称。<br/>首字符必须为字母字符或$字符，中间字符必须为数字字符、字母字符或下划线字符，结尾字符必须为数字字符或字母字符，长度非空且不超过48个字符。 | 1622| type | 事件类型，在[EventType](#eventtype)中定义。 | 1623| list | 事件参数列表，每个参数由参数名和参数值组成，其规格定义如下：<br/>1、参数名为字符串类型。<br/>首字符必须为字母字符或$字符，中间字符必须为数字字符、字母字符或下划线字符，结尾字符必须为数字字符或字母字符，长度非空且不超过32个字符。<br/>2、参数值支持字符串、数值、布尔、数组类型。字符串类型参数长度需在8\*1024个字符以内，超出会做丢弃处理；<br/>数组类型参数中的元素类型只能为字符串、数值、布尔中的一种，且元素个数需在100以内，超出会做丢弃处理。<br/>3、参数个数需在32个以内，超出的参数会做丢弃处理。 | 1624 1625**返回：** 1626 1627如果事件参数校验成功，则返回0，将事件写入事件文件； 1628 1629如果事件中存在无效参数，则返回正值，丢弃无效参数后将事件写入事件文件； 1630 1631如果事件参数校验失败，则返回负值，并且事件将不会写入事件文件。 16320 事件参数校验成功。-1 非法的事件名称。-4 非法的事件领域名称。-99 打点功能被关闭。1 非法的事件参数名称。4 非法的事件参数字符串长度。5 非法的事件参数数量。6 非法的事件参数数组长度。8 重复的事件参数名称。 1633