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| [DISABLE](#disable) "disable" | 事件打点开关。 | 33| [MAX_STORAGE](#max_storage) "max_storage" | 事件文件目录存储配额大小。 | 34| [EVENT_USER_LOGIN](#event_user_login) "hiappevent.user_login" | 用户登录事件。 | 35| [EVENT_USER_LOGOUT](#event_user_logout) "hiappevent.user_logout" | 用户登出事件。 | 36| [EVENT_DISTRIBUTED_SERVICE_START](#event_distributed_service_start) "hiappevent.distributed_service_start" | 分布式服务事件。 | 37| [PARAM_USER_ID](#param_user_id) "user_id" | 用户ID。 | 38| [PARAM_DISTRIBUTED_SERVICE_NAME](#param_distributed_service_name) "ds_name" | 分布式服务名称。 | 39| [PARAM_DISTRIBUTED_SERVICE_INSTANCE_ID](#param_distributed_service_instance_id) "ds_instance_id" | 分布式服务实例ID。 | 40 41 42### 类型定义 43 44| 名称 | 描述 | 45| -------- | -------- | 46| typedef struct ParamListNode \* [ParamList](#paramlist) | 事件参数列表节点。 | 47 48 49### 枚举 50 51| 名称 | 描述 | 52| -------- | -------- | 53| [EventType](#eventtype) { FAULT = 1, STATISTIC = 2, SECURITY = 3, BEHAVIOR = 4 } | 事件类型。 | 54 55 56### 函数 57 58| 名称 | 描述 | 59| -------- | -------- | 60| [ParamList](#paramlist) [OH_HiAppEvent_CreateParamList](#oh_hiappevent_createparamlist) (void) | 创建一个指向参数列表对象的指针。 | 61| void [OH_HiAppEvent_DestroyParamList](#oh_hiappevent_destroyparamlist) ([ParamList](#paramlist) list) | 销毁一个指向参数列表对象的指针，释放其分配内存。 | 62| [ParamList](#paramlist) [OH_HiAppEvent_AddBoolParam](#oh_hiappevent_addboolparam) ([ParamList](#paramlist) list, const char \*name, bool boolean) | 添加一个布尔参数到参数列表中。 | 63| [ParamList](#paramlist) [OH_HiAppEvent_AddBoolArrayParam](#oh_hiappevent_addboolarrayparam) ([ParamList](#paramlist) list, const char \*name, const bool \*booleans, int arrSize) | 添加一个布尔数组参数到参数列表中。 | 64| [ParamList](#paramlist) [OH_HiAppEvent_AddInt8Param](#oh_hiappevent_addint8param) ([ParamList](#paramlist) list, const char \*name, int8_t num) | 添加一个int8_t参数到参数列表中。 | 65| [ParamList](#paramlist) [OH_HiAppEvent_AddInt8ArrayParam](#oh_hiappevent_addint8arrayparam) ([ParamList](#paramlist) list, const char \*name, const int8_t \*nums, int arrSize) | 添加一个int8_t数组参数到参数列表中。 | 66| [ParamList](#paramlist) [OH_HiAppEvent_AddInt16Param](#oh_hiappevent_addint16param) ([ParamList](#paramlist) list, const char \*name, int16_t num) | 添加一个int16_t参数到参数列表中。 | 67| [ParamList](#paramlist) [OH_HiAppEvent_AddInt16ArrayParam](#oh_hiappevent_addint16arrayparam) ([ParamList](#paramlist) list, const char \*name, const int16_t \*nums, int arrSize) | 添加一个int16_t数组参数到参数列表中。 | 68| [ParamList](#paramlist) [OH_HiAppEvent_AddInt32Param](#oh_hiappevent_addint32param) ([ParamList](#paramlist) list, const char \*name, int32_t num) | 添加一个int32_t参数到参数列表中。 | 69| [ParamList](#paramlist) [OH_HiAppEvent_AddInt32ArrayParam](#oh_hiappevent_addint32arrayparam) ([ParamList](#paramlist) list, const char \*name, const int32_t \*nums, int arrSize) | 添加一个int32_t数组参数到参数列表中。 | 70| [ParamList](#paramlist) [OH_HiAppEvent_AddInt64Param](#oh_hiappevent_addint64param) ([ParamList](#paramlist) list, const char \*name, int64_t num) | 添加一个int64_t参数到参数列表中。 | 71| [ParamList](#paramlist) [OH_HiAppEvent_AddInt64ArrayParam](#oh_hiappevent_addint64arrayparam) ([ParamList](#paramlist) list, const char \*name, const int64_t \*nums, int arrSize) | 添加一个int64_t数组参数到参数列表中。 | 72| [ParamList](#paramlist) [OH_HiAppEvent_AddFloatParam](#oh_hiappevent_addfloatparam) ([ParamList](#paramlist) list, const char \*name, float num) | 添加一个float参数到参数列表中。 | 73| [ParamList](#paramlist) [OH_HiAppEvent_AddFloatArrayParam](#oh_hiappevent_addfloatarrayparam) ([ParamList](#paramlist) list, const char \*name, const float \*nums, int arrSize) | 添加一个float数组参数到参数列表中。 | 74| [ParamList](#paramlist) [OH_HiAppEvent_AddDoubleParam](#oh_hiappevent_adddoubleparam) ([ParamList](#paramlist) list, const char \*name, double num) | 添加一个double参数到参数列表中。 | 75| [ParamList](#paramlist) [OH_HiAppEvent_AddDoubleArrayParam](#oh_hiappevent_adddoublearrayparam) ([ParamList](#paramlist) list, const char \*name, const double \*nums, int arrSize) | 添加一个double数组参数到参数列表中。 | 76| [ParamList](#paramlist) [OH_HiAppEvent_AddStringParam](#oh_hiappevent_addstringparam) ([ParamList](#paramlist) list, const char \*name, const char \*str) | 添加一个字符串参数到参数列表中。 | 77| [ParamList](#paramlist) [OH_HiAppEvent_AddStringArrayParam](#oh_hiappevent_addstringarrayparam) ([ParamList](#paramlist) list, const char \*name, const char \*const \*strs, int arrSize) | 添加一个字符串数组参数到参数列表中。 | 78| int [OH_HiAppEvent_Write](#oh_hiappevent_write) (const char \*domain, const char \*name, enum [EventType](#eventtype) type, const [ParamList](#paramlist) list) | 实现对参数为列表类型的应用事件打点。 | 79| bool [OH_HiAppEvent_Configure](#oh_hiappevent_configure) (const char \*name, const char \*value) | 实现应用事件打点的配置功能。 | 80 81 82## 宏定义说明 83 84 85### DISABLE 86 87``` 88#define DISABLE "disable" 89``` 90 91**描述** 92 93事件打点开关。 94 95**起始版本：** 8 96 97 98### EVENT_DISTRIBUTED_SERVICE_START 99 100``` 101#define EVENT_DISTRIBUTED_SERVICE_START "hiappevent.distributed_service_start" 102``` 103 104**描述** 105 106分布式服务事件。 107 108**起始版本：** 8 109 110 111### EVENT_USER_LOGIN 112 113``` 114#define EVENT_USER_LOGIN "hiappevent.user_login" 115``` 116 117**描述** 118 119用户登录事件。 120 121**起始版本：** 8 122 123 124### EVENT_USER_LOGOUT 125 126``` 127#define EVENT_USER_LOGOUT "hiappevent.user_logout" 128``` 129 130**描述** 131 132用户登出事件。 133 134**起始版本：** 8 135 136 137### MAX_STORAGE 138 139``` 140#define MAX_STORAGE "max_storage" 141``` 142 143**描述** 144 145事件文件目录存储配额大小。 146 147**起始版本：** 8 148 149 150### PARAM_DISTRIBUTED_SERVICE_INSTANCE_ID 151 152``` 153#define PARAM_DISTRIBUTED_SERVICE_INSTANCE_ID "ds_instance_id" 154``` 155 156**描述** 157 158分布式服务实例ID。 159 160**起始版本：** 8 161 162 163### PARAM_DISTRIBUTED_SERVICE_NAME 164 165``` 166#define PARAM_DISTRIBUTED_SERVICE_NAME "ds_name" 167``` 168 169**描述** 170 171分布式服务名称。 172 173**起始版本：** 8 174 175 176### PARAM_USER_ID 177 178``` 179#define PARAM_USER_ID "user_id" 180``` 181 182**描述** 183 184用户ID。 185 186**起始版本：** 8 187 188 189## 类型定义说明 190 191 192### ParamList 193 194``` 195typedef struct ParamListNode* ParamList 196``` 197 198**描述** 199 200事件参数列表节点。 201 202**起始版本：** 8 203 204 205## 枚举类型说明 206 207 208### EventType 209 210``` 211enum EventType 212``` 213 214**描述** 215 216事件类型。 217 218建议开发者根据不同的使用场景选择不同的事件类型。 219 220**起始版本：** 8 221 222| 枚举值 | 描述 | 223| -------- | -------- | 224| FAULT | 故障事件类型 | 225| STATISTIC | 统计事件类型 | 226| SECURITY | 安全事件类型 | 227| BEHAVIOR | 行为事件类型 | 228 229 230## 函数说明 231 232 233### OH_HiAppEvent_AddBoolArrayParam() 234 235``` 236ParamList OH_HiAppEvent_AddBoolArrayParam (ParamList list, const char * name, const bool * booleans, int arrSize ) 237``` 238 239**描述** 240 241添加一个布尔数组参数到参数列表中。 242 243**起始版本：** 8 244 245**参数:** 246 247| 名称 | 描述 | 248| -------- | -------- | 249| list | 需要添加参数的参数列表指针。 | 250| name | 需要添加的参数名称。 | 251| booleans | 需要添加的布尔数组参数值。 | 252| arrSize | 需要添加的参数数组大小。 | 253 254**返回：** 255 256添加参数后的参数列表指针。 257 258 259### OH_HiAppEvent_AddBoolParam() 260 261``` 262ParamList OH_HiAppEvent_AddBoolParam (ParamList list, const char * name, bool boolean ) 263``` 264 265**描述** 266 267添加一个布尔参数到参数列表中。 268 269**起始版本：** 8 270 271**参数:** 272 273| 名称 | 描述 | 274| -------- | -------- | 275| list | 需要添加参数的参数列表指针。 | 276| name | 需要添加的参数名称。 | 277| boolean | 需要添加的布尔参数值。 | 278 279**返回：** 280 281添加参数后的参数列表指针。 282 283 284### OH_HiAppEvent_AddDoubleArrayParam() 285 286``` 287ParamList OH_HiAppEvent_AddDoubleArrayParam (ParamList list, const char * name, const double * nums, int arrSize ) 288``` 289 290**描述** 291 292添加一个double数组参数到参数列表中。 293 294**起始版本：** 8 295 296**参数:** 297 298| 名称 | 描述 | 299| -------- | -------- | 300| list | 需要添加参数的参数列表指针。 | 301| name | 需要添加的参数名称。 | 302| nums | 需要添加的double数组参数值。 | 303| arrSize | 需要添加的参数数组大小。 | 304 305**返回：** 306 307添加参数后的参数列表指针。 308 309 310### OH_HiAppEvent_AddDoubleParam() 311 312``` 313ParamList OH_HiAppEvent_AddDoubleParam (ParamList list, const char * name, double num ) 314``` 315 316**描述** 317 318添加一个double参数到参数列表中。 319 320**起始版本：** 8 321 322**参数:** 323 324| 名称 | 描述 | 325| -------- | -------- | 326| list | 需要添加参数的参数列表指针。 | 327| name | 需要添加的参数名称。 | 328| num | 需要添加的double参数值。 | 329 330**返回：** 331 332添加参数后的参数列表指针。 333 334 335### OH_HiAppEvent_AddFloatArrayParam() 336 337``` 338ParamList OH_HiAppEvent_AddFloatArrayParam (ParamList list, const char * name, const float * nums, int arrSize ) 339``` 340 341**描述** 342 343添加一个float数组参数到参数列表中。 344 345**起始版本：** 8 346 347**参数:** 348 349| 名称 | 描述 | 350| -------- | -------- | 351| list | 需要添加参数的参数列表指针。 | 352| name | 需要添加的参数名称。 | 353| nums | 需要添加的float数组参数值。 | 354| arrSize | 需要添加的参数数组大小。 | 355 356**返回：** 357 358添加参数后的参数列表指针。 359 360 361### OH_HiAppEvent_AddFloatParam() 362 363``` 364ParamList OH_HiAppEvent_AddFloatParam (ParamList list, const char * name, float num ) 365``` 366 367**描述** 368 369添加一个float参数到参数列表中。 370 371**起始版本：** 8 372 373**参数:** 374 375| 名称 | 描述 | 376| -------- | -------- | 377| list | 需要添加参数的参数列表指针。 | 378| name | 需要添加的参数名称。 | 379| num | 需要添加的float参数值。 | 380 381**返回：** 382 383添加参数后的参数列表指针。 384 385 386### OH_HiAppEvent_AddInt16ArrayParam() 387 388``` 389ParamList OH_HiAppEvent_AddInt16ArrayParam (ParamList list, const char * name, const int16_t * nums, int arrSize ) 390``` 391 392**描述** 393 394添加一个int16_t数组参数到参数列表中。 395 396**起始版本：** 8 397 398**参数:** 399 400| 名称 | 描述 | 401| -------- | -------- | 402| list | 需要添加参数的参数列表指针。 | 403| name | 需要添加的参数名称。 | 404| nums | 需要添加的int16_t数组参数值。 | 405| arrSize | 需要添加的参数数组大小。 | 406 407**返回：** 408 409添加参数后的参数列表指针。 410 411 412### OH_HiAppEvent_AddInt16Param() 413 414``` 415ParamList OH_HiAppEvent_AddInt16Param (ParamList list, const char * name, int16_t num ) 416``` 417 418**描述** 419 420添加一个int16_t参数到参数列表中。 421 422**起始版本：** 8 423 424**参数:** 425 426| 名称 | 描述 | 427| -------- | -------- | 428| list | 需要添加参数的参数列表指针。 | 429| name | 需要添加的参数名称。 | 430| num | 需要添加的int16_t参数值。 | 431 432**返回：** 433 434添加参数后的参数列表指针。 435 436 437### OH_HiAppEvent_AddInt32ArrayParam() 438 439``` 440ParamList OH_HiAppEvent_AddInt32ArrayParam (ParamList list, const char * name, const int32_t * nums, int arrSize ) 441``` 442 443**描述** 444 445添加一个int32_t数组参数到参数列表中。 446 447**起始版本：** 8 448 449**参数:** 450 451| 名称 | 描述 | 452| -------- | -------- | 453| list | 需要添加参数的参数列表指针。 | 454| name | 需要添加的参数名称。 | 455| nums | 需要添加的int32_t数组参数值。 | 456| arrSize | 需要添加的参数数组大小。 | 457 458**返回：** 459 460添加参数后的参数列表指针。 461 462 463### OH_HiAppEvent_AddInt32Param() 464 465``` 466ParamList OH_HiAppEvent_AddInt32Param (ParamList list, const char * name, int32_t num ) 467``` 468 469**描述** 470 471添加一个int32_t参数到参数列表中。 472 473**起始版本：** 8 474 475**参数:** 476 477| 名称 | 描述 | 478| -------- | -------- | 479| list | 需要添加参数的参数列表指针。 | 480| name | 需要添加的参数名称。 | 481| num | 需要添加的int32_t参数值。 | 482 483**返回：** 484 485添加参数后的参数列表指针。 486 487 488### OH_HiAppEvent_AddInt64ArrayParam() 489 490``` 491ParamList OH_HiAppEvent_AddInt64ArrayParam (ParamList list, const char * name, const int64_t * nums, int arrSize ) 492``` 493 494**描述** 495 496添加一个int64_t数组参数到参数列表中。 497 498**起始版本：** 8 499 500**参数:** 501 502| 名称 | 描述 | 503| -------- | -------- | 504| list | 需要添加参数的参数列表指针。 | 505| name | 需要添加的参数名称。 | 506| nums | 需要添加的int64_t数组参数值。 | 507| arrSize | 需要添加的参数数组大小。 | 508 509**返回：** 510 511添加参数后的参数列表指针。 512 513 514### OH_HiAppEvent_AddInt64Param() 515 516``` 517ParamList OH_HiAppEvent_AddInt64Param (ParamList list, const char * name, int64_t num ) 518``` 519 520**描述** 521 522添加一个int64_t参数到参数列表中。 523 524**起始版本：** 8 525 526**参数:** 527 528| 名称 | 描述 | 529| -------- | -------- | 530| list | 需要添加参数的参数列表指针。 | 531| name | 需要添加的参数名称。 | 532| num | 需要添加的int64_t参数值。 | 533 534**返回：** 535 536添加参数后的参数列表指针。 537 538 539### OH_HiAppEvent_AddInt8ArrayParam() 540 541``` 542ParamList OH_HiAppEvent_AddInt8ArrayParam (ParamList list, const char * name, const int8_t * nums, int arrSize ) 543``` 544 545**描述** 546 547添加一个int8_t数组参数到参数列表中。 548 549**起始版本：** 8 550 551**参数:** 552 553| 名称 | 描述 | 554| -------- | -------- | 555| list | 需要添加参数的参数列表指针。 | 556| name | 需要添加的参数名称。 | 557| nums | 需要添加的int8_t数组参数值。 | 558| arrSize | 需要添加的参数数组大小。 | 559 560**返回：** 561 562添加参数后的参数列表指针。 563 564 565### OH_HiAppEvent_AddInt8Param() 566 567``` 568ParamList OH_HiAppEvent_AddInt8Param (ParamList list, const char * name, int8_t num ) 569``` 570 571**描述** 572 573添加一个int8_t参数到参数列表中。 574 575**起始版本：** 8 576 577**参数:** 578 579| 名称 | 描述 | 580| -------- | -------- | 581| list | 需要添加参数的参数列表指针。 | 582| name | 需要添加的参数名称。 | 583| num | 需要添加的int8_t参数值。 | 584 585**返回：** 586 587添加参数后的参数列表指针。 588 589 590### OH_HiAppEvent_AddStringArrayParam() 591 592``` 593ParamList OH_HiAppEvent_AddStringArrayParam (ParamList list, const char * name, const char *const * strs, int arrSize ) 594``` 595 596**描述** 597 598添加一个字符串数组参数到参数列表中。 599 600**起始版本：** 8 601 602**参数:** 603 604| 名称 | 描述 | 605| -------- | -------- | 606| list | 需要添加参数的参数列表指针。 | 607| name | 需要添加的参数名称。 | 608| strs | 需要添加的字符串数组参数值。 | 609| arrSize | 需要添加的参数数组大小。 | 610 611**返回：** 612 613添加参数后的参数列表指针。 614 615 616### OH_HiAppEvent_AddStringParam() 617 618``` 619ParamList OH_HiAppEvent_AddStringParam (ParamList list, const char * name, const char * str ) 620``` 621 622**描述** 623 624添加一个字符串参数到参数列表中。 625 626**起始版本：** 8 627 628**参数:** 629 630| 名称 | 描述 | 631| -------- | -------- | 632| list | 需要添加参数的参数列表指针。 | 633| name | 需要添加的参数名称。 | 634| str | 需要添加的字符串参数值。 | 635 636**返回：** 637 638添加参数后的参数列表指针。 639 640 641### OH_HiAppEvent_Configure() 642 643``` 644bool OH_HiAppEvent_Configure (const char * name, const char * value ) 645``` 646 647**描述** 648 649实现应用事件打点的配置功能。 650 651应用事件打点配置接口，用于配置事件打点开关、事件文件目录存储配额大小等功能。 652 653**起始版本：** 8 654 655**参数:** 656 657| 名称 | 描述 | 658| -------- | -------- | 659| name | 配置项名称。 | 660| value | 配置项值。 | 661 662**返回：** 663 664配置结果。 665 666 667### OH_HiAppEvent_CreateParamList() 668 669``` 670ParamList OH_HiAppEvent_CreateParamList (void ) 671``` 672 673**描述** 674 675创建一个指向参数列表对象的指针。 676 677**起始版本：** 8 678 679**返回：** 680 681指向参数列表对象的指针。 682 683 684### OH_HiAppEvent_DestroyParamList() 685 686``` 687void OH_HiAppEvent_DestroyParamList (ParamList list) 688``` 689 690**描述** 691 692销毁一个指向参数列表对象的指针，释放其分配内存。 693 694**起始版本：** 8 695 696**参数:** 697 698| 名称 | 描述 | 699| -------- | -------- | 700| list | 参数列表对象指针。 | 701 702 703### OH_HiAppEvent_Write() 704 705``` 706int OH_HiAppEvent_Write (const char * domain, const char * name, enum EventType type, const ParamList list ) 707``` 708 709**描述** 710 711实现对参数为列表类型的应用事件打点。 712 713在应用事件打点前，该接口会先对该事件的参数进行校验。如果校验成功，则接口会将事件写入事件文件。 714 715**起始版本：** 8 716 717**参数:** 718 719| 名称 | 描述 | 720| -------- | -------- | 721| domain | 事件领域。您可以根据需要自定义事件领域。 | 722| name | 事件名称。您可以根据需要自定义事件名称。 | 723| type | 事件类型，在[EventType](#eventtype)中定义。 | 724| list | 事件参数列表，每个参数由参数名和参数值组成。 | 725 726**返回：** 727 728如果事件参数校验成功，则返回0，将事件写入事件文件；如果事件中存在无效参数，则返回正值，丢弃无效参数后将事件写入事件文件；如果事件参数校验失败，则返回负值，并且事件将不会写入事件文件。 729