1# HiAppEvent 2 3 4## 概述 5 6HiAppEvent模块提供应用事件打点功能。 7 8为应用程序提供事件打点功能，记录运行过程中上报的故障事件、统计事件、安全事件和用户行为事件。基于事件信息，开发者可以分析应用的运行状态。 9 10**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 11 12**起始版本：** 8 13 14 15## 汇总 16 17 18### 文件 19 20| 名称 | 描述 | 21| -------- | -------- | 22| [hiappevent.h](hiappevent_8h.md) | HiAppEvent模块的应用事件打点函数定义。<br/>**引用文件**：<hiappevent/hiappevent.h><br/>**库**：libhiappevent_ndk.z.so | 23| [hiappevent_cfg.h](hiappevent__cfg_8h.md) | 定义事件打点配置函数的所有配置项名称。<br/>**引用文件**：<hiappevent/hiappevent_event.h><br/>**库**：libhiappevent_ndk.z.so | 24| [hiappevent_event.h](hiappevent__event_8h.md) | 定义所有预定义事件的事件名称。<br/>**引用文件**：<hiappevent/hiappevent_param.h><br/>**库**：libhiappevent_ndk.z.so | 25| [hiappevent_param.h](hiappevent__param_8h.md) | 定义所有预定义事件的参数名称。<br/>**引用文件**：<hiappevent/hiappevent_cfg.h><br/>**库**：libhiappevent_ndk.z.so | 26 27 28### 结构体 29 30| 名称 | 描述 | 31| -------- | -------- | 32| struct [HiAppEvent_AppEventInfo](_hi_app_event___app_event_info.md) | 单个事件信息，包含事件领域，事件名称，事件类型和json格式字符串表示的事件中携带的自定义参数列表。 | 33| struct [HiAppEvent_AppEventGroup](_hi_app_event___app_event_group.md) | 具有相同事件名称的事件组。 | 34 35 36### 宏定义 37 38| 名称 | 描述 | 39| -------- | -------- | 40| [DISABLE](#disable) "disable" | 事件打点开关。默认值为false。true：关闭打点功能，false：不关闭打点功能。 | 41| [MAX_STORAGE](#max_storage) "max_storage" | 事件文件目录存储配额大小。默认值为“10M”。 | 42| [EVENT_USER_LOGIN](#event_user_login) "hiappevent.user_login" | 用户登录事件。 | 43| [EVENT_USER_LOGOUT](#event_user_logout) "hiappevent.user_logout" | 用户登出事件。 | 44| [EVENT_DISTRIBUTED_SERVICE_START](#event_distributed_service_start) "hiappevent.distributed_service_start" | 分布式服务事件。 | 45| [EVENT_APP_CRASH](#event_app_crash) "APP_CRASH" | 应用崩溃事件。 | 46| [EVENT_APP_FREEZE](#event_app_freeze) "APP_FREEZE" | 应用卡顿事件。 | 47| [EVENT_APP_LAUNCH](#event_app_launch) "APP_LAUNCH" | 应用加载事件。 | 48| [EVENT_SCROLL_JANK](#event_scroll_jank) "SCROLL_JANK" | 应用滑动卡顿事件。 | 49| [EVENT_CPU_USAGE_HIGH](#event_cpu_usage_high) "CPU_USAGE_HIGH" | 应用CPU资源占用高事件。 | 50| [EVENT_BATTERY_USAGE](#event_battery_usage) "BATTERY_USAGE" | 应用电源使用率事件。 | 51| [EVENT_RESOURCE_OVERLIMIT](#event_resource_overlimit) "RESOURCE_OVERLIMIT" | 应用资源超限事件。 | 52| [DOMAIN_OS](#domain_os) "OS" | OS作用域。 | 53| [PARAM_USER_ID](#param_user_id) "user_id" | 用户ID。 | 54| [PARAM_DISTRIBUTED_SERVICE_NAME](#param_distributed_service_name) "ds_name" | 分布式服务名称。 | 55| [PARAM_DISTRIBUTED_SERVICE_INSTANCE_ID](#param_distributed_service_instance_id) "ds_instance_id" | 分布式服务实例ID。 | 56 57 58### 类型定义 59 60| 名称 | 描述 | 61| -------- | -------- | 62| typedef struct [HiAppEvent_AppEventInfo](_hi_app_event___app_event_info.md) [HiAppEvent_AppEventInfo](#hiappevent_appeventinfo) | 单个事件信息，包含事件领域，事件名称，事件类型和json格式字符串表示的事件中携带的自定义参数列表。 | 63| typedef struct [HiAppEvent_AppEventGroup](_hi_app_event___app_event_group.md) [HiAppEvent_AppEventGroup](#hiappevent_appeventgroup) | 具有相同事件名称的事件组。 | 64| typedef struct ParamListNode \* [ParamList](#paramlist) | 事件参数列表节点。 | 65| typedef struct [HiAppEvent_Watcher](#hiappevent_watcher) [HiAppEvent_Watcher](#hiappevent_watcher) | 用于接收app事件的监听器。 | 66| typedef void(\* [OH_HiAppEvent_OnReceive](#oh_hiappevent_onreceive)) (const char \*domain, const struct [HiAppEvent_AppEventGroup](_hi_app_event___app_event_group.md) \*appEventGroups, uint32_t groupLen) | 监听器接收到事件后，将触发该回调，将事件内容传递给调用方。 | 67| typedef void(\* [OH_HiAppEvent_OnTrigger](#oh_hiappevent_ontrigger)) (int row, int size) | 监听器收到事件后，若监听器中未设置OH_HiAppEvent_OnReceive回调，将保存该事件。当保存的事件满足通过 OH_HiAppEvent_SetTriggerCondition设定的条件后，将触发该回调。回调结束后，当新保存的事件消息再次满足设定的条件后，将再次进行回调。 | 68| typedef void(\* [OH_HiAppEvent_OnTake](#oh_hiappevent_ontake)) (const char \*const \*events, uint32_t eventLen) | 使用OH_HiAppEvent_TakeWatcherData获取监听器接收到的事件时，监听器接收到的事件将通过该回调函数传递给调用者。 | 69 70 71### 枚举 72 73| 名称 | 描述 | 74| -------- | -------- | 75| [EventType](#eventtype) { **FAULT** = 1, **STATISTIC** = 2, **SECURITY** = 3, **BEHAVIOR** = 4 } | 事件类型。 | 76 77 78### 函数 79 80| 名称 | 描述 | 81| -------- | -------- | 82| [ParamList](#paramlist) [OH_HiAppEvent_CreateParamList](#oh_hiappevent_createparamlist) (void) | 创建一个指向参数列表对象的指针。 | 83| void [OH_HiAppEvent_DestroyParamList](#oh_hiappevent_destroyparamlist) ([ParamList](#paramlist) list) | 销毁一个指向参数列表对象的指针，释放其分配内存。 | 84| [ParamList](#paramlist) [OH_HiAppEvent_AddBoolParam](#oh_hiappevent_addboolparam) ([ParamList](#paramlist) list, const char \*name, bool boolean) | 添加一个布尔参数到参数列表中。 | 85| [ParamList](#paramlist) [OH_HiAppEvent_AddBoolArrayParam](#oh_hiappevent_addboolarrayparam) ([ParamList](#paramlist) list, const char \*name, const bool \*booleans, int arrSize) | 添加一个布尔数组参数到参数列表中。 | 86| [ParamList](#paramlist) [OH_HiAppEvent_AddInt8Param](#oh_hiappevent_addint8param) ([ParamList](#paramlist) list, const char \*name, int8_t num) | 添加一个int8_t参数到参数列表中。 | 87| [ParamList](#paramlist) [OH_HiAppEvent_AddInt8ArrayParam](#oh_hiappevent_addint8arrayparam) ([ParamList](#paramlist) list, const char \*name, const int8_t \*nums, int arrSize) | 添加一个int8_t数组参数到参数列表中。 | 88| [ParamList](#paramlist) [OH_HiAppEvent_AddInt16Param](#oh_hiappevent_addint16param) ([ParamList](#paramlist) list, const char \*name, int16_t num) | 添加一个int16_t参数到参数列表中。 | 89| [ParamList](#paramlist) [OH_HiAppEvent_AddInt16ArrayParam](#oh_hiappevent_addint16arrayparam) ([ParamList](#paramlist) list, const char \*name, const int16_t \*nums, int arrSize) | 添加一个int16_t数组参数到参数列表中。 | 90| [ParamList](#paramlist) [OH_HiAppEvent_AddInt32Param](#oh_hiappevent_addint32param) ([ParamList](#paramlist) list, const char \*name, int32_t num) | 添加一个int32_t参数到参数列表中。 | 91| [ParamList](#paramlist) [OH_HiAppEvent_AddInt32ArrayParam](#oh_hiappevent_addint32arrayparam) ([ParamList](#paramlist) list, const char \*name, const int32_t \*nums, int arrSize) | 添加一个int32_t数组参数到参数列表中。 | 92| [ParamList](#paramlist) [OH_HiAppEvent_AddInt64Param](#oh_hiappevent_addint64param) ([ParamList](#paramlist) list, const char \*name, int64_t num) | 添加一个int64_t参数到参数列表中。 | 93| [ParamList](#paramlist) [OH_HiAppEvent_AddInt64ArrayParam](#oh_hiappevent_addint64arrayparam) ([ParamList](#paramlist) list, const char \*name, const int64_t \*nums, int arrSize) | 添加一个int64_t数组参数到参数列表中。 | 94| [ParamList](#paramlist) [OH_HiAppEvent_AddFloatParam](#oh_hiappevent_addfloatparam) ([ParamList](#paramlist) list, const char \*name, float num) | 添加一个float参数到参数列表中。 | 95| [ParamList](#paramlist) [OH_HiAppEvent_AddFloatArrayParam](#oh_hiappevent_addfloatarrayparam) ([ParamList](#paramlist) list, const char \*name, const float \*nums, int arrSize) | 添加一个float数组参数到参数列表中。 | 96| [ParamList](#paramlist) [OH_HiAppEvent_AddDoubleParam](#oh_hiappevent_adddoubleparam) ([ParamList](#paramlist) list, const char \*name, double num) | 添加一个double参数到参数列表中。 | 97| [ParamList](#paramlist) [OH_HiAppEvent_AddDoubleArrayParam](#oh_hiappevent_adddoublearrayparam) ([ParamList](#paramlist) list, const char \*name, const double \*nums, int arrSize) | 添加一个double数组参数到参数列表中。 | 98| [ParamList](#paramlist) [OH_HiAppEvent_AddStringParam](#oh_hiappevent_addstringparam) ([ParamList](#paramlist) list, const char \*name, const char \*str) | 添加一个字符串参数到参数列表中。 | 99| [ParamList](#paramlist) [OH_HiAppEvent_AddStringArrayParam](#oh_hiappevent_addstringarrayparam) ([ParamList](#paramlist) list, const char \*name, const char \*const \*strs, int arrSize) | 添加一个字符串数组参数到参数列表中。 | 100| int [OH_HiAppEvent_Write](#oh_hiappevent_write) (const char \*domain, const char \*name, enum [EventType](#eventtype) type, const [ParamList](#paramlist) list) | 实现对参数为列表类型的应用事件打点。 | 101| bool [OH_HiAppEvent_Configure](#oh_hiappevent_configure) (const char \*name, const char \*value) | 实现应用事件打点的配置功能。 | 102| [HiAppEvent_Watcher](#hiappevent_watcher) \* [OH_HiAppEvent_CreateWatcher](#oh_hiappevent_createwatcher) (const char \*name) | 创建一个用于监听app事件的监听器。 | 103| void [OH_HiAppEvent_DestroyWatcher](#oh_hiappevent_destroywatcher) ([HiAppEvent_Watcher](#hiappevent_watcher) \*watcher) | 销毁已创建的监听器。 | 104| int [OH_HiAppEvent_SetTriggerCondition](#oh_hiappevent_settriggercondition) ([HiAppEvent_Watcher](#hiappevent_watcher) \*watcher, int row, int size, int timeOut) | 用于设置监听器OH_HiAppEvent_OnTrigger回调的触发条件，分别可以从监视器新接收事件数量，新接收事件大小，onTrigger触发超时时间 设置触发条件，调用方应至少保证从一个方面设置触发条件。 | 105| int [OH_HiAppEvent_SetAppEventFilter](#oh_hiappevent_setappeventfilter) ([HiAppEvent_Watcher](#hiappevent_watcher) \*watcher, const char \*domain, uint8_t eventTypes, const char \*const \*names, int namesLen) | 用于设置监听器需要监听的事件的类型。 | 106| int [OH_HiAppEvent_SetWatcherOnTrigger](#oh_hiappevent_setwatcherontrigger) ([HiAppEvent_Watcher](#hiappevent_watcher) \*watcher, [OH_HiAppEvent_OnTrigger](#oh_hiappevent_ontrigger) onTrigger) | 用于设置监听器onTrigger回调的接口。 | 107| int [OH_HiAppEvent_SetWatcherOnReceive](#oh_hiappevent_setwatcheronreceive) ([HiAppEvent_Watcher](#hiappevent_watcher) \*watcher, [OH_HiAppEvent_OnReceive](#oh_hiappevent_onreceive) onReceive) | 用于设置监听器onReceive回调函数的接口。当监听器监听到相应事件后，onReceive回调函数将被调用。 | 108| int [OH_HiAppEvent_TakeWatcherData](#oh_hiappevent_takewatcherdata) ([HiAppEvent_Watcher](#hiappevent_watcher) \*watcher, uint32_t eventNum, [OH_HiAppEvent_OnTake](#oh_hiappevent_ontake) onTake) | 用于获取监听器收到后保存的事件。 | 109| int [OH_HiAppEvent_AddWatcher](#oh_hiappevent_addwatcher) ([HiAppEvent_Watcher](#hiappevent_watcher) \*watcher) | 添加监听器的接口，监听器开始监听系统消息。 | 110| int [OH_HiAppEvent_RemoveWatcher](#oh_hiappevent_removewatcher) ([HiAppEvent_Watcher](#hiappevent_watcher) \*watcher) | 移除监听器的接口，监听器停止监听系统消息。 | 111| void [OH_HiAppEvent_ClearData](#oh_hiappevent_cleardata) (void) | 清除所有监视器保存的所有事件。 | 112 113 114## 宏定义说明 115 116 117### DISABLE 118 119``` 120#define DISABLE "disable" 121``` 122**描述** 123事件打点开关。默认值为false。true：关闭打点功能，false：不关闭打点功能。 124 125**起始版本：** 8 126 127 128### DOMAIN_OS 129 130``` 131#define DOMAIN_OS "OS" 132``` 133**描述** 134OS作用域。 135 136**起始版本：** 12 137 138 139### EVENT_APP_CRASH 140 141``` 142#define EVENT_APP_CRASH "APP_CRASH" 143``` 144**描述** 145应用崩溃事件。 146 147**起始版本：** 12 148 149 150### EVENT_APP_FREEZE 151 152``` 153#define EVENT_APP_FREEZE "APP_FREEZE" 154``` 155**描述** 156应用卡顿事件。 157 158**起始版本：** 12 159 160 161### EVENT_APP_LAUNCH 162 163``` 164#define EVENT_APP_LAUNCH "APP_LAUNCH" 165``` 166**描述** 167应用加载事件。 168 169**起始版本：** 12 170 171 172### EVENT_BATTERY_USAGE 173 174``` 175#define EVENT_BATTERY_USAGE "BATTERY_USAGE" 176``` 177**描述** 178应用电源使用率事件。 179 180**起始版本：** 12 181 182 183### EVENT_CPU_USAGE_HIGH 184 185``` 186#define EVENT_CPU_USAGE_HIGH "CPU_USAGE_HIGH" 187``` 188**描述** 189应用CPU资源占用高事件。 190 191**起始版本：** 12 192 193 194### EVENT_DISTRIBUTED_SERVICE_START 195 196``` 197#define EVENT_DISTRIBUTED_SERVICE_START "hiappevent.distributed_service_start" 198``` 199**描述** 200分布式服务事件。 201 202**起始版本：** 8 203 204 205### EVENT_RESOURCE_OVERLIMIT 206 207``` 208#define EVENT_RESOURCE_OVERLIMIT "RESOURCE_OVERLIMIT" 209``` 210**描述** 211应用资源超限事件。 212 213**起始版本：** 12 214 215 216### EVENT_SCROLL_JANK 217 218``` 219#define EVENT_SCROLL_JANK "SCROLL_JANK" 220``` 221**描述** 222应用滑动卡顿事件。 223 224**起始版本：** 12 225 226 227### EVENT_USER_LOGIN 228 229``` 230#define EVENT_USER_LOGIN "hiappevent.user_login" 231``` 232**描述** 233用户登录事件。 234 235**起始版本：** 8 236 237 238### EVENT_USER_LOGOUT 239 240``` 241#define EVENT_USER_LOGOUT "hiappevent.user_logout" 242``` 243**描述** 244用户登出事件。 245 246**起始版本：** 8 247 248 249### MAX_STORAGE 250 251``` 252#define MAX_STORAGE "max_storage" 253``` 254**描述** 255事件文件目录存储配额大小。默认值为“10M”。 256 257**起始版本：** 8 258 259 260### PARAM_DISTRIBUTED_SERVICE_INSTANCE_ID 261 262``` 263#define PARAM_DISTRIBUTED_SERVICE_INSTANCE_ID "ds_instance_id" 264``` 265**描述** 266分布式服务实例ID。 267 268**起始版本：** 8 269 270 271### PARAM_DISTRIBUTED_SERVICE_NAME 272 273``` 274#define PARAM_DISTRIBUTED_SERVICE_NAME "ds_name" 275``` 276**描述** 277分布式服务名称。 278 279**起始版本：** 8 280 281 282### PARAM_USER_ID 283 284``` 285#define PARAM_USER_ID "user_id" 286``` 287**描述** 288用户ID。 289 290**起始版本：** 8 291 292 293## 类型定义说明 294 295 296### HiAppEvent_AppEventGroup 297 298``` 299typedef struct HiAppEvent_AppEventGroupHiAppEvent_AppEventGroup 300``` 301**描述** 302具有相同事件名称的事件组。 303 304**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 305 306**起始版本：** 12 307 308 309### HiAppEvent_AppEventInfo 310 311``` 312typedef struct HiAppEvent_AppEventInfoHiAppEvent_AppEventInfo 313``` 314**描述** 315单个事件信息，包含事件领域，事件名称，事件类型和json格式字符串表示的事件中携带的自定义参数列表。 316 317\@SystemCapability.HiviewDFX.HiAppEvent 318 319**起始版本：** 12 320 321 322### HiAppEvent_Watcher 323 324``` 325typedef struct HiAppEvent_WatcherHiAppEvent_Watcher 326``` 327**描述** 328用于接收app事件的监听器。 329 330**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 331 332**起始版本：** 12 333 334 335### OH_HiAppEvent_OnReceive 336 337``` 338typedef void(* OH_HiAppEvent_OnReceive) (const char *domain, const struct HiAppEvent_AppEventGroup *appEventGroups, uint32_t groupLen) 339``` 340**描述** 341监听器接收到事件后，将触发该回调，将事件内容传递给调用方。 342 343注意：回调中的指针所指对象的生命周期仅限于该回调函数内，请勿在该回调函数外直接使用该指针，若需缓存该信息，请对指针指向的内容进行深拷贝。 344 345\@SystemCapability.HiviewDFX.HiAppEvent 346 347**起始版本：** 12 348 349**参数:** 350 351| 名称 | 描述 | 352| -------- | -------- | 353| domain | 接收到的app事件的领域。 | 354| appEventGroups | 按照不同事件名称分组的事件组数组。 | 355| groupLen | 事件组数组的长度。 | 356 357 358### OH_HiAppEvent_OnTake 359 360``` 361typedef void(* OH_HiAppEvent_OnTake) (const char *const *events, uint32_t eventLen) 362``` 363**描述** 364使用OH_HiAppEvent_TakeWatcherData获取监听器接收到的事件时，监听器接收到的事件将通过该回调函数传递给调用者。 365 366注意：回调中的指针所指对象的生命周期仅限于该回调函数内，请勿在该回调函数外直接使用该指针，若需缓存该信息，请对指针指向的内容进行深拷贝。 367 368\@SystemCapability.HiviewDFX.HiAppEvent 369 370**起始版本：** 12 371 372**参数:** 373 374| 名称 | 描述 | 375| -------- | -------- | 376| events | json字符串格式的事件数组。 | 377| eventLen | 事件数组大小。 | 378 379 380### OH_HiAppEvent_OnTrigger 381 382``` 383typedef void(* OH_HiAppEvent_OnTrigger) (int row, int size) 384``` 385**描述** 386监听器收到事件后，若监听器中未设置OH_HiAppEvent_OnReceive回调，将保存该事件。当保存的事件满足通过 OH_HiAppEvent_SetTriggerCondition设定的条件后，将触发该回调。回调结束后，当新保存的事件消息再次满足设定的条件后，将再次进行回调。 387 388\@SystemCapability.HiviewDFX.HiAppEvent 389 390**起始版本：** 12 391 392**参数:** 393 394| 名称 | 描述 | 395| -------- | -------- | 396| row | 监听器新接收到的事件消息的数量。 | 397| size | 监听器新接收的事件消息的大小总和(单个事件大小计算方式为，将消息转换为json字符串后，字符串的长度)。 | 398 399 400### ParamList 401 402``` 403typedef struct ParamListNode* ParamList 404``` 405**描述** 406事件参数列表节点。 407 408**起始版本：** 8 409 410 411## 枚举类型说明 412 413 414### EventType 415 416``` 417enum EventType 418``` 419**描述** 420事件类型。 421 422建议开发者根据不同的使用场景选择不同的事件类型。 423 424**起始版本：** 8 425 426| 枚举值 | 描述 | 427| -------- | -------- | 428| FAULT | 故障事件类型 | 429| STATISTIC | 统计事件类型 | 430| SECURITY | 安全事件类型 | 431| BEHAVIOR | 行为事件类型 | 432 433 434## 函数说明 435 436 437### OH_HiAppEvent_AddBoolArrayParam() 438 439``` 440ParamList OH_HiAppEvent_AddBoolArrayParam (ParamList list, const char * name, const bool * booleans, int arrSize ) 441``` 442**描述** 443添加一个布尔数组参数到参数列表中。 444 445**起始版本：** 8 446 447**参数:** 448 449| 名称 | 描述 | 450| -------- | -------- | 451| list | 需要添加参数的参数列表指针。 | 452| name | 需要添加的参数名称。 | 453| booleans | 需要添加的布尔数组参数值。 | 454| arrSize | 需要添加的参数数组大小。 | 455 456**返回：** 457 458添加参数后的参数列表指针。 459 460 461### OH_HiAppEvent_AddBoolParam() 462 463``` 464ParamList OH_HiAppEvent_AddBoolParam (ParamList list, const char * name, bool boolean ) 465``` 466**描述** 467添加一个布尔参数到参数列表中。 468 469**起始版本：** 8 470 471**参数:** 472 473| 名称 | 描述 | 474| -------- | -------- | 475| list | 需要添加参数的参数列表指针。 | 476| name | 需要添加的参数名称。 | 477| boolean | 需要添加的布尔参数值。 | 478 479**返回：** 480 481添加参数后的参数列表指针。 482 483 484### OH_HiAppEvent_AddDoubleArrayParam() 485 486``` 487ParamList OH_HiAppEvent_AddDoubleArrayParam (ParamList list, const char * name, const double * nums, int arrSize ) 488``` 489**描述** 490添加一个double数组参数到参数列表中。 491 492**起始版本：** 8 493 494**参数:** 495 496| 名称 | 描述 | 497| -------- | -------- | 498| list | 需要添加参数的参数列表指针。 | 499| name | 需要添加的参数名称。 | 500| nums | 需要添加的double数组参数值。 | 501| arrSize | 需要添加的参数数组大小。 | 502 503**返回：** 504 505添加参数后的参数列表指针。 506 507 508### OH_HiAppEvent_AddDoubleParam() 509 510``` 511ParamList OH_HiAppEvent_AddDoubleParam (ParamList list, const char * name, double num ) 512``` 513**描述** 514添加一个double参数到参数列表中。 515 516**起始版本：** 8 517 518**参数:** 519 520| 名称 | 描述 | 521| -------- | -------- | 522| list | 需要添加参数的参数列表指针。 | 523| name | 需要添加的参数名称。 | 524| num | 需要添加的double参数值。 | 525 526**返回：** 527 528添加参数后的参数列表指针。 529 530 531### OH_HiAppEvent_AddFloatArrayParam() 532 533``` 534ParamList OH_HiAppEvent_AddFloatArrayParam (ParamList list, const char * name, const float * nums, int arrSize ) 535``` 536**描述** 537添加一个float数组参数到参数列表中。 538 539**起始版本：** 8 540 541**参数:** 542 543| 名称 | 描述 | 544| -------- | -------- | 545| list | 需要添加参数的参数列表指针。 | 546| name | 需要添加的参数名称。 | 547| nums | 需要添加的float数组参数值。 | 548| arrSize | 需要添加的参数数组大小。 | 549 550**返回：** 551 552添加参数后的参数列表指针。 553 554 555### OH_HiAppEvent_AddFloatParam() 556 557``` 558ParamList OH_HiAppEvent_AddFloatParam (ParamList list, const char * name, float num ) 559``` 560**描述** 561添加一个float参数到参数列表中。 562 563**起始版本：** 8 564 565**参数:** 566 567| 名称 | 描述 | 568| -------- | -------- | 569| list | 需要添加参数的参数列表指针。 | 570| name | 需要添加的参数名称。 | 571| num | 需要添加的float参数值。 | 572 573**返回：** 574 575添加参数后的参数列表指针。 576 577 578### OH_HiAppEvent_AddInt16ArrayParam() 579 580``` 581ParamList OH_HiAppEvent_AddInt16ArrayParam (ParamList list, const char * name, const int16_t * nums, int arrSize ) 582``` 583**描述** 584添加一个int16_t数组参数到参数列表中。 585 586**起始版本：** 8 587 588**参数:** 589 590| 名称 | 描述 | 591| -------- | -------- | 592| list | 需要添加参数的参数列表指针。 | 593| name | 需要添加的参数名称。 | 594| nums | 需要添加的int16_t数组参数值。 | 595| arrSize | 需要添加的参数数组大小。 | 596 597**返回：** 598 599添加参数后的参数列表指针。 600 601 602### OH_HiAppEvent_AddInt16Param() 603 604``` 605ParamList OH_HiAppEvent_AddInt16Param (ParamList list, const char * name, int16_t num ) 606``` 607**描述** 608添加一个int16_t参数到参数列表中。 609 610**起始版本：** 8 611 612**参数:** 613 614| 名称 | 描述 | 615| -------- | -------- | 616| list | 需要添加参数的参数列表指针。 | 617| name | 需要添加的参数名称。 | 618| num | 需要添加的int16_t参数值。 | 619 620**返回：** 621 622添加参数后的参数列表指针。 623 624 625### OH_HiAppEvent_AddInt32ArrayParam() 626 627``` 628ParamList OH_HiAppEvent_AddInt32ArrayParam (ParamList list, const char * name, const int32_t * nums, int arrSize ) 629``` 630**描述** 631添加一个int32_t数组参数到参数列表中。 632 633**起始版本：** 8 634 635**参数:** 636 637| 名称 | 描述 | 638| -------- | -------- | 639| list | 需要添加参数的参数列表指针。 | 640| name | 需要添加的参数名称。 | 641| nums | 需要添加的int32_t数组参数值。 | 642| arrSize | 需要添加的参数数组大小。 | 643 644**返回：** 645 646添加参数后的参数列表指针。 647 648 649### OH_HiAppEvent_AddInt32Param() 650 651``` 652ParamList OH_HiAppEvent_AddInt32Param (ParamList list, const char * name, int32_t num ) 653``` 654**描述** 655添加一个int32_t参数到参数列表中。 656 657**起始版本：** 8 658 659**参数:** 660 661| 名称 | 描述 | 662| -------- | -------- | 663| list | 需要添加参数的参数列表指针。 | 664| name | 需要添加的参数名称。 | 665| num | 需要添加的int32_t参数值。 | 666 667**返回：** 668 669添加参数后的参数列表指针。 670 671 672### OH_HiAppEvent_AddInt64ArrayParam() 673 674``` 675ParamList OH_HiAppEvent_AddInt64ArrayParam (ParamList list, const char * name, const int64_t * nums, int arrSize ) 676``` 677**描述** 678添加一个int64_t数组参数到参数列表中。 679 680**起始版本：** 8 681 682**参数:** 683 684| 名称 | 描述 | 685| -------- | -------- | 686| list | 需要添加参数的参数列表指针。 | 687| name | 需要添加的参数名称。 | 688| nums | 需要添加的int64_t数组参数值。 | 689| arrSize | 需要添加的参数数组大小。 | 690 691**返回：** 692 693添加参数后的参数列表指针。 694 695 696### OH_HiAppEvent_AddInt64Param() 697 698``` 699ParamList OH_HiAppEvent_AddInt64Param (ParamList list, const char * name, int64_t num ) 700``` 701**描述** 702添加一个int64_t参数到参数列表中。 703 704**起始版本：** 8 705 706**参数:** 707 708| 名称 | 描述 | 709| -------- | -------- | 710| list | 需要添加参数的参数列表指针。 | 711| name | 需要添加的参数名称。 | 712| num | 需要添加的int64_t参数值。 | 713 714**返回：** 715 716添加参数后的参数列表指针。 717 718 719### OH_HiAppEvent_AddInt8ArrayParam() 720 721``` 722ParamList OH_HiAppEvent_AddInt8ArrayParam (ParamList list, const char * name, const int8_t * nums, int arrSize ) 723``` 724**描述** 725添加一个int8_t数组参数到参数列表中。 726 727**起始版本：** 8 728 729**参数:** 730 731| 名称 | 描述 | 732| -------- | -------- | 733| list | 需要添加参数的参数列表指针。 | 734| name | 需要添加的参数名称。 | 735| nums | 需要添加的int8_t数组参数值。 | 736| arrSize | 需要添加的参数数组大小。 | 737 738**返回：** 739 740添加参数后的参数列表指针。 741 742 743### OH_HiAppEvent_AddInt8Param() 744 745``` 746ParamList OH_HiAppEvent_AddInt8Param (ParamList list, const char * name, int8_t num ) 747``` 748**描述** 749添加一个int8_t参数到参数列表中。 750 751**起始版本：** 8 752 753**参数:** 754 755| 名称 | 描述 | 756| -------- | -------- | 757| list | 需要添加参数的参数列表指针。 | 758| name | 需要添加的参数名称。 | 759| num | 需要添加的int8_t参数值。 | 760 761**返回：** 762 763添加参数后的参数列表指针。 764 765 766### OH_HiAppEvent_AddStringArrayParam() 767 768``` 769ParamList OH_HiAppEvent_AddStringArrayParam (ParamList list, const char * name, const char *const * strs, int arrSize ) 770``` 771**描述** 772添加一个字符串数组参数到参数列表中。 773 774**起始版本：** 8 775 776**参数:** 777 778| 名称 | 描述 | 779| -------- | -------- | 780| list | 需要添加参数的参数列表指针。 | 781| name | 需要添加的参数名称。 | 782| strs | 需要添加的字符串数组参数值。 | 783| arrSize | 需要添加的参数数组大小。 | 784 785**返回：** 786 787添加参数后的参数列表指针。 788 789 790### OH_HiAppEvent_AddStringParam() 791 792``` 793ParamList OH_HiAppEvent_AddStringParam (ParamList list, const char * name, const char * str ) 794``` 795**描述** 796添加一个字符串参数到参数列表中。 797 798**起始版本：** 8 799 800**参数:** 801 802| 名称 | 描述 | 803| -------- | -------- | 804| list | 需要添加参数的参数列表指针。 | 805| name | 需要添加的参数名称。 | 806| str | 需要添加的字符串参数值。 | 807 808**返回：** 809 810添加参数后的参数列表指针。 811 812 813### OH_HiAppEvent_AddWatcher() 814 815``` 816int OH_HiAppEvent_AddWatcher (HiAppEvent_Watcher * watcher) 817``` 818**描述** 819添加监听器的接口，监听器开始监听系统消息。 820 821\@SystemCapability.HiviewDFX.HiAppEvent 822 823**起始版本：** 12 824 825**参数:** 826 827| 名称 | 描述 | 828| -------- | -------- | 829| watcher | 指向监听器的指针（即OH_HiAppEvent_CreateWatcher接口返回的指针）。 | 830 831**返回：** 832 8330：接口调用成功；-5：watcher入参空指针。 834 835 836### OH_HiAppEvent_ClearData() 837 838``` 839void OH_HiAppEvent_ClearData (void ) 840``` 841**描述** 842清除所有监视器保存的所有事件。 843 844\@SystemCapability.HiviewDFX.HiAppEvent 845 846**起始版本：** 12 847 848 849### OH_HiAppEvent_Configure() 850 851``` 852bool OH_HiAppEvent_Configure (const char * name, const char * value ) 853``` 854**描述** 855实现应用事件打点的配置功能。 856 857应用事件打点配置接口，用于配置事件打点开关、事件文件目录存储配额大小等功能。 858 859**起始版本：** 8 860 861**参数:** 862 863| 名称 | 描述 | 864| -------- | -------- | 865| name | 配置项名称。名称可填[DISABLE](#disable)和[MAX_STORAGE](#max_storage)。 | 866| value | 配置项值。如果配置项名称是[DISABLE](#disable)，值可以填“true”或者“false”；如果配置项名称是[MAX_STORAGE](#max_storage)， 配额值字符串只由数字字符和大小单位字符（单位字符支持[b\|k\|kb\|m\|mb\|g\|gb\|t\|tb]，不区分大小写）构成， 配额值字符串必须以数字开头，后面可以选择不传单位字符（默认使用byte作为单位），或者以单位字符结尾。 | 867 868**返回：** 869 870配置结果。如果配置成功，则返回true；如果配置失败则返回false。 871 872 873### OH_HiAppEvent_CreateParamList() 874 875``` 876ParamList OH_HiAppEvent_CreateParamList (void ) 877``` 878**描述** 879创建一个指向参数列表对象的指针。 880 881**起始版本：** 8 882 883**返回：** 884 885指向参数列表对象的指针。 886 887 888### OH_HiAppEvent_CreateWatcher() 889 890``` 891HiAppEvent_Watcher* OH_HiAppEvent_CreateWatcher (const char * name) 892``` 893**描述** 894创建一个用于监听app事件的监听器。 895 896注意：创建的监听器不再使用后必须通过调用OH_HiAppEvent_DestroyWatcher接口进行销毁。 897 898\@SystemCapability.HiviewDFX.HiAppEvent 899 900**起始版本：** 12 901 902**参数:** 903 904| 名称 | 描述 | 905| -------- | -------- | 906| name | 监听器名称。 | 907 908**返回：** 909 910接口调用成功时返回指向的新建监听器的指针，name参数异常时返回nullptr。 911 912 913### OH_HiAppEvent_DestroyParamList() 914 915``` 916void OH_HiAppEvent_DestroyParamList (ParamList list) 917``` 918**描述** 919销毁一个指向参数列表对象的指针，释放其分配内存。 920 921**起始版本：** 8 922 923**参数:** 924 925| 名称 | 描述 | 926| -------- | -------- | 927| list | 参数列表对象指针。 | 928 929 930### OH_HiAppEvent_DestroyWatcher() 931 932``` 933void OH_HiAppEvent_DestroyWatcher (HiAppEvent_Watcher * watcher) 934``` 935**描述** 936销毁已创建的监听器。 937 938注意：已创建的监听器不再使用后，需要将其销毁，释放内存，防止内存泄漏，销毁后需将对应指针置空。 939 940\@SystemCapability.HiviewDFX.HiAppEvent 941 942**起始版本：** 12 943 944**参数:** 945 946| 名称 | 描述 | 947| -------- | -------- | 948| watcher | 指向监听器的指针（即OH_HiAppEvent_CreateWatcher接口返回的指针）。 | 949 950 951### OH_HiAppEvent_RemoveWatcher() 952 953``` 954int OH_HiAppEvent_RemoveWatcher (HiAppEvent_Watcher * watcher) 955``` 956**描述** 957移除监听器的接口，监听器停止监听系统消息。 958 959注意：该接口仅仅使监听器停止监听系统消息，并未销毁该监听器，该监听器依然常驻内存，直至调用OH_HiAppEvent_DestroyWatcher接口，内存才会释放。 960 961\@SystemCapability.HiviewDFX.HiAppEvent 962 963**起始版本：** 12 964 965**参数:** 966 967| 名称 | 描述 | 968| -------- | -------- | 969| watcher | 指向监听器的指针（即OH_HiAppEvent_CreateWatcher接口返回的指针）。 | 970 971**返回：** 972 9730：接口调用成功；-5：watcher入参空指针；-6：还未调用OH_HiAppEvent_AddWatcher，操作顺序有误。 974 975 976### OH_HiAppEvent_SetAppEventFilter() 977 978``` 979int OH_HiAppEvent_SetAppEventFilter (HiAppEvent_Watcher * watcher, const char * domain, uint8_t eventTypes, const char *const * names, int namesLen ) 980``` 981**描述** 982用于设置监听器需要监听的事件的类型。 983 984该函数可以重复调用，可添加多个过滤规则，而非替换，监听器将收到满足任一过滤规则的事件的通知。 985 986\@SystemCapability.HiviewDFX.HiAppEvent 987 988**起始版本：** 12 989 990**参数:** 991 992| 名称 | 描述 | 993| -------- | -------- | 994| watcher | 指向监听器的指针（即OH_HiAppEvent_CreateWatcher接口返回的指针）。 | 995| domain | 需要监听事件的领域。 | 996| eventTypes | 需要监听事件的事件类型。使用按位与方式进行匹配，可支持监听多种类型的事件， 第一位为1（数值为1）表示支持监听故障类型的事件，第二位为1（数值为2）表示支持监听统计类型的事件， 第三位为1（数值为4）表示支持监听安全类型的事件，第四位为1（数值为8）表示支持监听行为类型的事件， 都为1（数值为15）或者都为0（数值为0）表示支持所有类型事件。 | 997| names | 需要监听的事件名称数组。 | 998| namesLen | 监听的事件名称的数组长度。 | 999 1000**返回：** 1001 10020：接口调用成功；-1：names参数异常；-4：domain参数异常；-5：watcher入参空指针。 1003 1004 1005### OH_HiAppEvent_SetTriggerCondition() 1006 1007``` 1008int OH_HiAppEvent_SetTriggerCondition (HiAppEvent_Watcher * watcher, int row, int size, int timeOut ) 1009``` 1010**描述** 1011用于设置监听器OH_HiAppEvent_OnTrigger回调的触发条件，分别可以从监视器新接收事件数量，新接收事件大小，onTrigger触发超时时间 设置触发条件，调用方应至少保证从一个方面设置触发条件。 1012 1013\@SystemCapability.HiviewDFX.HiAppEvent 1014 1015**起始版本：** 12 1016 1017**参数:** 1018 1019| 名称 | 描述 | 1020| -------- | -------- | 1021| watcher | 指向监听器的指针（即OH_HiAppEvent_CreateWatcher接口返回的指针）。 | 1022| row | 当输入值大于0，且新接收事件的数量大于等于该值时，将调用设置的onTrigger回调函数吗，当输入值小于等于0时，不再以接收数量多少为维度 来触发onTrigger回调。 | 1023| size | 当输入值大于0，且新接收事件的大小(单个事件大小计算方式为，将事件转换为json字符串后，字符串的长度)大于等于该值时，将调用设置的 onTrigger回调函数，当输入值小于等于0时，不再以新接收事件大小为维度触发onTrigger回调。 | 1024| timeOut | 单位秒，当输入值大于0，每经过timeout秒，将检查监视器是否存在新接收到的事件，如果存在将触发onTrigger回调。触发onTrigger 后，经过timeOut秒后将再次检查是否存在新接收到的事件。当输入值小于等于0，不以超时时间为维度触发onTrigger回调。 | 1025 1026**返回：** 1027 10280：接口调用成功；-5：watcher入参空指针。 1029 1030 1031### OH_HiAppEvent_SetWatcherOnReceive() 1032 1033``` 1034int OH_HiAppEvent_SetWatcherOnReceive (HiAppEvent_Watcher * watcher, OH_HiAppEvent_OnReceive onReceive ) 1035``` 1036**描述** 1037用于设置监听器onReceive回调函数的接口。当监听器监听到相应事件后，onReceive回调函数将被调用。 1038 1039\@SystemCapability.HiviewDFX.HiAppEvent 1040 1041**起始版本：** 12 1042 1043**参数:** 1044 1045| 名称 | 描述 | 1046| -------- | -------- | 1047| watcher | 指向监听器的指针（即OH_HiAppEvent_CreateWatcher接口返回的指针）。 | 1048| onReceive | 回调函数的函数指针。 | 1049 1050**返回：** 1051 10520：接口调用成功；-5：watcher入参空指针。 1053 1054 1055### OH_HiAppEvent_SetWatcherOnTrigger() 1056 1057``` 1058int OH_HiAppEvent_SetWatcherOnTrigger (HiAppEvent_Watcher * watcher, OH_HiAppEvent_OnTrigger onTrigger ) 1059``` 1060**描述** 1061用于设置监听器onTrigger回调的接口。 1062 1063\@SystemCapability.HiviewDFX.HiAppEvent 1064 1065**起始版本：** 12 1066 1067**参数:** 1068 1069| 名称 | 描述 | 1070| -------- | -------- | 1071| watcher | 指向监听器的指针（即OH_HiAppEvent_CreateWatcher接口返回的指针）。 | 1072| onTrigger | 需要设置的回调。 | 1073 1074**返回：** 1075 10760：接口调用成功；-5：watcher入参空指针。 1077 1078 1079### OH_HiAppEvent_TakeWatcherData() 1080 1081``` 1082int OH_HiAppEvent_TakeWatcherData (HiAppEvent_Watcher * watcher, uint32_t eventNum, OH_HiAppEvent_OnTake onTake ) 1083``` 1084**描述** 1085用于获取监听器收到后保存的事件。 1086 1087\@SystemCapability.HiviewDFX.HiAppEvent 1088 1089**起始版本：** 12 1090 1091**参数:** 1092 1093| 名称 | 描述 | 1094| -------- | -------- | 1095| watcher | 指向监听器的指针（即OH_HiAppEvent_CreateWatcher接口返回的指针）。 | 1096| eventNum | 当输入值小于等于0时，取全部已保存事件；当输入值大于0时，按照事件发生时间倒序排列，取指定数量的已保存事件。 | 1097| onTake | 回调函数指针，事件通过调用该函数返回事件信息。 | 1098 1099**返回：** 1100 11010：接口调用成功；-5：watcher入参空指针；-6：还未调用OH_HiAppEvent_AddWatcher，操作顺序有误。 1102 1103 1104### OH_HiAppEvent_Write() 1105 1106``` 1107int OH_HiAppEvent_Write (const char * domain, const char * name, enum EventType type, const ParamList list ) 1108``` 1109**描述** 1110实现对参数为列表类型的应用事件打点。 1111 1112在应用事件打点前，该接口会先对该事件的参数进行校验。如果校验成功，则接口会将事件写入事件文件。 1113 1114**起始版本：** 8 1115 1116**参数:** 1117 1118| 名称 | 描述 | 1119| -------- | -------- | 1120| domain | 事件领域。您可以根据需要自定义事件领域。事件领域名称支持数字、字母、下划线字符， 需要以字母开头且不能以下划线结尾，长度非空且不超过32个字符。 | 1121| name | 事件名称。您可以根据需要自定义事件名称。首字符必须为字母字符或$字符，中间字符必须为数字字符、 字母字符或下划线字符，结尾字符必须为数字字符或字母字符，长度非空且不超过48个字符。 | 1122| type | 事件类型，在[EventType](#eventtype)中定义。 | 1123| list | 事件参数列表，每个参数由参数名和参数值组成，其规格定义如下：<br/>1、参数名为字符串类型，首字符必须为字母字符或$字符，中间字符必须为数字字符、字母字符或下划线字符， 结尾字符必须为数字字符或字母字符，长度非空且不超过32个字符。<br/>2、参数值支持字符串、数值、布尔、数组类型，字符串类型参数长度需在8\*1024个字符以内，超出会做丢弃处理； 数组类型参数中的元素类型只能为字符串、数值、布尔中的一种，且元素个数需在100以内，超出会做丢弃处理。<br/>3、参数个数需在32个以内，超出的参数会做丢弃处理。 | 1124 1125**返回：** 1126 1127如果事件参数校验成功，则返回0，将事件写入事件文件；如果事件中存在无效参数，则返回正值，丢弃 无效参数后将事件写入事件文件；如果事件参数校验失败，则返回负值，并且事件将不会写入事件文件。 0 事件参数校验成功。 -1 非法的事件名称。 -4 非法的事件领域名称。 -99 打点功能被关闭。 1 非法的事件参数名称。 4 非法的事件参数字符串长度。 5 非法的事件参数数量。 6 非法的事件参数数组长度。 8 重复的事件参数名称。 1128