1# HiAppEvent 2 3 4## Overview 5 6Provides APIs for implementing the application event logging function. 7 8This function allows your application to record fault events, statistics events, security events, and user behavior events reported during system running. Based on the event information, you can analyze the operating status of your application. 9 10**System capability**: SystemCapability.HiviewDFX.HiAppEvent 11 12**Since**: 8 13 14 15## Summary 16 17 18### File 19 20| Name| Description| 21| -------- | -------- | 22| [hiappevent.h](hiappevent_8h.md) | Defines the application event logging functions of the HiAppEvent module.<br>**File to include**: <hiappevent/hiappevent.h><br>**Library**: libhiappevent_ndk.z.so| 23| [hiappevent_cfg.h](hiappevent__cfg_8h.md) | Defines the configuration items of the event logging configuration function.<br>**File to include**: <hiappevent/hiappevent_event.h><br>**Library**: libhiappevent_ndk.z.so| 24| [hiappevent_event.h](hiappevent__event_8h.md) | Defines the names of all predefined events.<br>**File to include**: <hiappevent/hiappevent_param.h><br>**Library**: libhiappevent_ndk.z.so| 25| [hiappevent_param.h](hiappevent__param_8h.md) | Defines the names of all predefined event parameters.<br>**File to include**: <hiappevent/hiappevent_cfg.h><br>**Library**: libhiappevent_ndk.z.so| 26 27 28### Macros 29 30| Name| Description| 31| -------- | -------- | 32| [DISABLE](#disable) "disable" | Whether to disable event logging.| 33| [MAX_STORAGE](#max_storage) "max_storage" | Storage quota of the event file directory.| 34| [EVENT_USER_LOGIN](#event_user_login) "hiappevent.user_login" | User login event.| 35| [EVENT_USER_LOGOUT](#event_user_logout) "hiappevent.user_logout" | User logout event.| 36| [EVENT_DISTRIBUTED_SERVICE_START](#event_distributed_service_start) "hiappevent.distributed_service_start" | Distributed service event.| 37| [PARAM_USER_ID](#param_user_id) "user_id" | User ID.| 38| [PARAM_DISTRIBUTED_SERVICE_NAME](#param_distributed_service_name) "ds_name" | Distributed service name.| 39| [PARAM_DISTRIBUTED_SERVICE_INSTANCE_ID](#param_distributed_service_instance_id) "ds_instance_id" | Distributed service instance ID.| 40 41 42### Types 43 44| Name| Description| 45| -------- | -------- | 46| typedef struct ParamListNode \* [ParamList](#paramlist) | Event parameter list node.| 47 48 49### Enums 50 51| Name| Description| 52| -------- | -------- | 53| [EventType](#eventtype) { FAULT = 1, STATISTIC = 2, SECURITY = 3, BEHAVIOR = 4 } | Event type.| 54 55 56### Functions 57 58| Name| Description| 59| -------- | -------- | 60| [ParamList](#paramlist) [OH_HiAppEvent_CreateParamList](#oh_hiappevent_createparamlist) (void) | Creates a pointer to a parameter list object.| 61| void [OH_HiAppEvent_DestroyParamList](#oh_hiappevent_destroyparamlist) ([ParamList](#paramlist) list) | Destroys a pointer to a parameter list object and releases its allocated memory.| 62| [ParamList](#paramlist) [OH_HiAppEvent_AddBoolParam](#oh_hiappevent_addboolparam) ([ParamList](#paramlist) list, const char \*name, bool boolean) | Adds an event parameter of the Boolean type to the parameter list.| 63| [ParamList](#paramlist) [OH_HiAppEvent_AddBoolArrayParam](#oh_hiappevent_addboolarrayparam) ([ParamList](#paramlist) list, const char \*name, const bool \*booleans, int arrSize) | Adds an event parameter of the Boolean array type to the parameter list.| 64| [ParamList](#paramlist) [OH_HiAppEvent_AddInt8Param](#oh_hiappevent_addint8param) ([ParamList](#paramlist) list, const char \*name, int8_t num) | Adds an event parameter of the int8_t type to the parameter list.| 65| [ParamList](#paramlist) [OH_HiAppEvent_AddInt8ArrayParam](#oh_hiappevent_addint8arrayparam) ([ParamList](#paramlist) list, const char \*name, const int8_t \*nums, int arrSize) | Adds an event parameter of the int8_t array type to the parameter list.| 66| [ParamList](#paramlist) [OH_HiAppEvent_AddInt16Param](#oh_hiappevent_addint16param) ([ParamList](#paramlist) list, const char \*name, int16_t num) | Adds an event parameter of the int16_t type to the parameter list.| 67| [ParamList](#paramlist) [OH_HiAppEvent_AddInt16ArrayParam](#oh_hiappevent_addint16arrayparam) ([ParamList](#paramlist) list, const char \*name, const int16_t \*nums, int arrSize) | Adds an event parameter of the int16_t array type to the parameter list.| 68| [ParamList](#paramlist) [OH_HiAppEvent_AddInt32Param](#oh_hiappevent_addint32param) ([ParamList](#paramlist) list, const char \*name, int32_t num) | Adds an event parameter of the int32_t type to the parameter list.| 69| [ParamList](#paramlist) [OH_HiAppEvent_AddInt32ArrayParam](#oh_hiappevent_addint32arrayparam) ([ParamList](#paramlist) list, const char \*name, const int32_t \*nums, int arrSize) | Adds an event parameter of the int32_t array type to the parameter list.| 70| [ParamList](#paramlist) [OH_HiAppEvent_AddInt64Param](#oh_hiappevent_addint64param) ([ParamList](#paramlist) list, const char \*name, int64_t num) | Adds an event parameter of the int64_t type to the parameter list.| 71| [ParamList](#paramlist) [OH_HiAppEvent_AddInt64ArrayParam](#oh_hiappevent_addint64arrayparam) ([ParamList](#paramlist) list, const char \*name, const int64_t \*nums, int arrSize) | Adds an event parameter of the int64_t array type to the parameter list.| 72| [ParamList](#paramlist) [OH_HiAppEvent_AddFloatParam](#oh_hiappevent_addfloatparam) ([ParamList](#paramlist) list, const char \*name, float num) | Adds an event parameter of the float type to the parameter list.| 73| [ParamList](#paramlist) [OH_HiAppEvent_AddFloatArrayParam](#oh_hiappevent_addfloatarrayparam) ([ParamList](#paramlist) list, const char \*name, const float \*nums, int arrSize) | Adds an event parameter of the float array type to the parameter list.| 74| [ParamList](#paramlist) [OH_HiAppEvent_AddDoubleParam](#oh_hiappevent_adddoubleparam) ([ParamList](#paramlist) list, const char \*name, double num) | Adds an event parameter of the Double type to the parameter list.| 75| [ParamList](#paramlist) [OH_HiAppEvent_AddDoubleArrayParam](#oh_hiappevent_adddoublearrayparam) ([ParamList](#paramlist) list, const char \*name, const double \*nums, int arrSize) | Adds an event parameter of the double array type to the parameter list.| 76| [ParamList](#paramlist) [OH_HiAppEvent_AddStringParam](#oh_hiappevent_addstringparam) ([ParamList](#paramlist) list, const char \*name, const char \*str) | Adds a parameter of the string type to the parameter list.| 77| [ParamList](#paramlist) [OH_HiAppEvent_AddStringArrayParam](#oh_hiappevent_addstringarrayparam) ([ParamList](#paramlist) list, const char \*name, const char \*const \*strs, int arrSize) | Adds a parameter of the string array type to the parameter list.| 78| int [OH_HiAppEvent_Write](#oh_hiappevent_write) (const char \*domain, const char \*name, enum [EventType](#eventtype) type, const [ParamList](#paramlist) list) | Logs application events whose parameters are of the list type.| 79| bool [OH_HiAppEvent_Configure](#oh_hiappevent_configure) (const char \*name, const char \*value) | Configures the application event logging function.| 80 81 82## Macro Description 83 84 85### DISABLE 86 87``` 88#define DISABLE "disable" 89``` 90 91**Description** 92 93Whether to disable event logging. 94 95**Since**: 8 96 97 98### EVENT_DISTRIBUTED_SERVICE_START 99 100``` 101#define EVENT_DISTRIBUTED_SERVICE_START "hiappevent.distributed_service_start" 102``` 103 104**Description** 105 106Distributed service event. 107 108**Since**: 8 109 110 111### EVENT_USER_LOGIN 112 113``` 114#define EVENT_USER_LOGIN "hiappevent.user_login" 115``` 116 117**Description** 118 119User login event. 120 121**Since**: 8 122 123 124### EVENT_USER_LOGOUT 125 126``` 127#define EVENT_USER_LOGOUT "hiappevent.user_logout" 128``` 129 130**Description** 131 132User logout event. 133 134**Since**: 8 135 136 137### MAX_STORAGE 138 139``` 140#define MAX_STORAGE "max_storage" 141``` 142 143**Description** 144 145Storage quota of the event file directory. 146 147**Since**: 8 148 149 150### PARAM_DISTRIBUTED_SERVICE_INSTANCE_ID 151 152``` 153#define PARAM_DISTRIBUTED_SERVICE_INSTANCE_ID "ds_instance_id" 154``` 155 156**Description** 157 158Distributed service instance ID. 159 160**Since**: 8 161 162 163### PARAM_DISTRIBUTED_SERVICE_NAME 164 165``` 166#define PARAM_DISTRIBUTED_SERVICE_NAME "ds_name" 167``` 168 169**Description** 170 171Distributed service name. 172 173**Since**: 8 174 175 176### PARAM_USER_ID 177 178``` 179#define PARAM_USER_ID "user_id" 180``` 181 182**Description** 183 184User ID. 185 186**Since**: 8 187 188 189## Type Description 190 191 192### ParamList 193 194``` 195typedef struct ParamListNode* ParamList 196``` 197 198**Description** 199 200Event parameter list node. 201 202**Since**: 8 203 204 205## Enum Description 206 207 208### EventType 209 210``` 211enum EventType 212``` 213 214**Description** 215 216Enumerates the event types. 217 218You are advised to select different event types based on application scenarios. 219 220**Since**: 8 221 222| Value| Description| 223| -------- | -------- | 224| FAULT | Fault event.| 225| STATISTIC | Statistics event.| 226| SECURITY | Security event.| 227| BEHAVIOR | Behavior event.| 228 229 230## Function Description 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**Description** 240 241Adds an event parameter of the Boolean array type to the parameter list. 242 243**Since**: 8 244 245**Parameters** 246 247| Name| Description| 248| -------- | -------- | 249| list | Pointer to the parameter list to which parameters need to be added.| 250| name | Name of the parameter to be added.| 251| booleans | Value of the parameter to be added.| 252| arrSize | Size of the parameter array to be added.| 253 254**Returns** 255 256Pointer to the parameter list that contains the parameters added. 257 258 259### OH_HiAppEvent_AddBoolParam() 260 261``` 262ParamList OH_HiAppEvent_AddBoolParam (ParamList list, const char * name, bool boolean ) 263``` 264 265**Description** 266 267Adds an event parameter of the Boolean type to the parameter list. 268 269**Since**: 8 270 271**Parameters** 272 273| Name| Description| 274| -------- | -------- | 275| list | Pointer to the parameter list to which parameters need to be added.| 276| name | Name of the parameter to be added.| 277| boolean | Value of the parameter to be added.| 278 279**Returns** 280 281Pointer to the parameter list that contains the parameters added. 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**Description** 291 292Adds an event parameter of the double array type to the parameter list. 293 294**Since**: 8 295 296**Parameters** 297 298| Name| Description| 299| -------- | -------- | 300| list | Pointer to the parameter list to which parameters need to be added.| 301| name | Name of the parameter to be added.| 302| nums | Value of the parameter to be added.| 303| arrSize | Size of the parameter array to be added.| 304 305**Returns** 306 307Pointer to the parameter list that contains the parameters added. 308 309 310### OH_HiAppEvent_AddDoubleParam() 311 312``` 313ParamList OH_HiAppEvent_AddDoubleParam (ParamList list, const char * name, double num ) 314``` 315 316**Description** 317 318Adds an event parameter of the Double type to the parameter list. 319 320**Since**: 8 321 322**Parameters** 323 324| Name| Description| 325| -------- | -------- | 326| list | Pointer to the parameter list to which parameters need to be added.| 327| name | Name of the parameter to be added.| 328| num | Value of the parameter to be added.| 329 330**Returns** 331 332Pointer to the parameter list that contains the parameters added. 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**Description** 342 343Adds an event parameter of the float array type to the parameter list. 344 345**Since**: 8 346 347**Parameters** 348 349| Name| Description| 350| -------- | -------- | 351| list | Pointer to the parameter list to which parameters need to be added.| 352| name | Name of the parameter to be added.| 353| nums | Value of the parameter to be added.| 354| arrSize | Size of the parameter array to be added.| 355 356**Returns** 357 358Pointer to the parameter list that contains the parameters added. 359 360 361### OH_HiAppEvent_AddFloatParam() 362 363``` 364ParamList OH_HiAppEvent_AddFloatParam (ParamList list, const char * name, float num ) 365``` 366 367**Description** 368 369Adds an event parameter of the float type to the parameter list. 370 371**Since**: 8 372 373**Parameters** 374 375| Name| Description| 376| -------- | -------- | 377| list | Pointer to the parameter list to which parameters need to be added.| 378| name | Name of the parameter to be added.| 379| num | Value of the parameter to be added.| 380 381**Returns** 382 383Pointer to the parameter list that contains the parameters added. 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**Description** 393 394Adds an event parameter of the int16_t array type to the parameter list. 395 396**Since**: 8 397 398**Parameters** 399 400| Name| Description| 401| -------- | -------- | 402| list | Pointer to the parameter list to which parameters need to be added.| 403| name | Name of the parameter to be added.| 404| nums | Value of the parameter to be added.| 405| arrSize | Size of the parameter array to be added.| 406 407**Returns** 408 409Pointer to the parameter list that contains the parameters added. 410 411 412### OH_HiAppEvent_AddInt16Param() 413 414``` 415ParamList OH_HiAppEvent_AddInt16Param (ParamList list, const char * name, int16_t num ) 416``` 417 418**Description** 419 420Adds an event parameter of the int16_t type to the parameter list. 421 422**Since**: 8 423 424**Parameters** 425 426| Name| Description| 427| -------- | -------- | 428| list | Pointer to the parameter list to which parameters need to be added.| 429| name | Name of the parameter to be added.| 430| num | Value of the parameter to be added.| 431 432**Returns** 433 434Pointer to the parameter list that contains the parameters added. 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**Description** 444 445Adds an event parameter of the int32_t array type to the parameter list. 446 447**Since**: 8 448 449**Parameters** 450 451| Name| Description| 452| -------- | -------- | 453| list | Pointer to the parameter list to which parameters need to be added.| 454| name | Name of the parameter to be added.| 455| nums | Value of the parameter to be added.| 456| arrSize | Size of the parameter array to be added.| 457 458**Returns** 459 460Pointer to the parameter list that contains the parameters added. 461 462 463### OH_HiAppEvent_AddInt32Param() 464 465``` 466ParamList OH_HiAppEvent_AddInt32Param (ParamList list, const char * name, int32_t num ) 467``` 468 469**Description** 470 471Adds an event parameter of the int32_t type to the parameter list. 472 473**Since**: 8 474 475**Parameters** 476 477| Name| Description| 478| -------- | -------- | 479| list | Pointer to the parameter list to which parameters need to be added.| 480| name | Name of the parameter to be added.| 481| num | Value of the parameter to be added.| 482 483**Returns** 484 485Pointer to the parameter list that contains the parameters added. 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**Description** 495 496Adds an event parameter of the int64_t array type to the parameter list. 497 498**Since**: 8 499 500**Parameters** 501 502| Name| Description| 503| -------- | -------- | 504| list | Pointer to the parameter list to which parameters need to be added.| 505| name | Name of the parameter to be added.| 506| nums | Value of the parameter to be added.| 507| arrSize | Size of the parameter array to be added.| 508 509**Returns** 510 511Pointer to the parameter list that contains the parameters added. 512 513 514### OH_HiAppEvent_AddInt64Param() 515 516``` 517ParamList OH_HiAppEvent_AddInt64Param (ParamList list, const char * name, int64_t num ) 518``` 519 520**Description** 521 522Adds an event parameter of the int64_t type to the parameter list. 523 524**Since**: 8 525 526**Parameters** 527 528| Name| Description| 529| -------- | -------- | 530| list | Pointer to the parameter list to which parameters need to be added.| 531| name | Name of the parameter to be added.| 532| num | Value of the parameter to be added.| 533 534**Returns** 535 536Pointer to the parameter list that contains the parameters added. 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**Description** 546 547Adds an event parameter of the int8_t array type to the parameter list. 548 549**Since**: 8 550 551**Parameters** 552 553| Name| Description| 554| -------- | -------- | 555| list | Pointer to the parameter list to which parameters need to be added.| 556| name | Name of the parameter to be added.| 557| nums | Value of the parameter to be added.| 558| arrSize | Size of the parameter array to be added.| 559 560**Returns** 561 562Pointer to the parameter list that contains the parameters added. 563 564 565### OH_HiAppEvent_AddInt8Param() 566 567``` 568ParamList OH_HiAppEvent_AddInt8Param (ParamList list, const char * name, int8_t num ) 569``` 570 571**Description** 572 573Adds an event parameter of the int8_t type to the parameter list. 574 575**Since**: 8 576 577**Parameters** 578 579| Name| Description| 580| -------- | -------- | 581| list | Pointer to the parameter list to which parameters need to be added.| 582| name | Name of the parameter to be added.| 583| num | Value of the parameter to be added.| 584 585**Returns** 586 587Pointer to the parameter list that contains the parameters added. 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**Description** 597 598Adds a parameter of the string array type to the parameter list. 599 600**Since**: 8 601 602**Parameters** 603 604| Name| Description| 605| -------- | -------- | 606| list | Pointer to the parameter list to which parameters need to be added.| 607| name | Name of the parameter to be added.| 608| strs | Value of the parameter to be added.| 609| arrSize | Size of the parameter array to be added.| 610 611**Returns** 612 613Pointer to the parameter list that contains the parameters added. 614 615 616### OH_HiAppEvent_AddStringParam() 617 618``` 619ParamList OH_HiAppEvent_AddStringParam (ParamList list, const char * name, const char * str ) 620``` 621 622**Description** 623 624Adds a parameter of the string type to the parameter list. 625 626**Since**: 8 627 628**Parameters** 629 630| Name| Description| 631| -------- | -------- | 632| list | Pointer to the parameter list to which parameters need to be added.| 633| name | Name of the parameter to be added.| 634| str | Value of the parameter to be added.| 635 636**Returns** 637 638Pointer to the parameter list that contains the parameters added. 639 640 641### OH_HiAppEvent_Configure() 642 643``` 644bool OH_HiAppEvent_Configure (const char * name, const char * value ) 645``` 646 647**Description** 648 649Configures the application event logging function. 650 651This function is used to configure the event logging function and the storage quota of the event file directory. 652 653**Since**: 8 654 655**Parameters** 656 657| Name| Description| 658| -------- | -------- | 659| name | Configuration item name.| 660| value | Configuration item value.| 661 662**Returns** 663 664Configuration result. 665 666 667### OH_HiAppEvent_CreateParamList() 668 669``` 670ParamList OH_HiAppEvent_CreateParamList (void ) 671``` 672 673**Description** 674 675Creates a pointer to a parameter list object. 676 677**Since**: 8 678 679**Returns** 680 681Pointer to the parameter list object. 682 683 684### OH_HiAppEvent_DestroyParamList() 685 686``` 687void OH_HiAppEvent_DestroyParamList (ParamList list) 688``` 689 690**Description** 691 692Destroys a pointer to a parameter list object and releases its allocated memory. 693 694**Since**: 8 695 696**Parameters** 697 698| Name| Description| 699| -------- | -------- | 700| list | Pointer to the parameter list object.| 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**Description** 710 711Logs application events whose parameters are of the list type. 712 713Before application event logging, use this API to verify parameters of the events. If the verification is successful, the API writes the events to the event file. 714 715**Since**: 8 716 717**Parameters** 718 719| Name| Description| 720| -------- | -------- | 721| domain | Event domain. You can customize event domains as required.| 722| name | Event name. You can customize event names as required.| 723| type | Event type, which is defined in [EventType](#eventtype).| 724| list | List of event parameters. Each parameter consists of a parameter name and a parameter value.| 725 726**Returns** 727 728The value **0** indicates that the event parameter verification is successful, and the event will be written to the event file asynchronously. A value greater than **0** indicates that invalid parameters are present in the event, and the event will be written to the event file asynchronously after the invalid parameters are ignored. A value smaller than **0** indicates that the event parameter verification fails, and the event will not be written to the event file. 729