1# hiappevent.h 2 3<!--Kit: Performance Analysis Kit--> 4<!--Subsystem: HiviewDFX--> 5<!--Owner: @liujiaxing2024--> 6<!--Designer: @junjie_shi--> 7<!--Tester: @gcw_KuLfPSbe--> 8<!--Adviser: @foryourself--> 9 10## Overview 11 12Defines the application event logging functions of the HiAppEvent module. Before performing application event logging, you must construct a parameter list object to store the input event parameters and specify the event domain, event name, and event type. <p>Event domain: domain associated with the application event. <p>Event name: name of the application event. <p>Event type: fault, statistics, security, or behavior. <p>Parameter list: a linked list used to store event parameters. Each parameter consists of a parameter name and a parameter value. 13 14**File to include**: <hiappevent/hiappevent.h> 15 16**Library**: libhiappevent_ndk.z.so 17 18**System capability**: SystemCapability.HiviewDFX.HiAppEvent 19 20**Since**: 8 21 22**Related Module**: [HiAppEvent](capi-hiappevent.md) 23 24## Summary 25 26### Structs 27 28| Name| typedef Keyword| Description| 29| -- | -- | -- | 30| [HiAppEvent_AppEventInfo](capi-hiappevent-hiappevent-appeventinfo.md) | HiAppEvent_AppEventInfo | Defines the information about a single event, including the event domain, event name, event type, and custom parameter list in JSON string format.| 31| [HiAppEvent_AppEventGroup](capi-hiappevent-hiappevent-appeventgroup.md) | HiAppEvent_AppEventGroup | Defines the information about an event group, including its name, the array of event information grouped by name, and the length of the event array.| 32| [ParamListNode*](capi-hiappevent-paramlistnode8h.md) | ParamList | Defines a struct for the event parameter list node.| 33| [HiAppEvent_Watcher](capi-hiappevent-hiappevent-watcher.md) | HiAppEvent_Watcher | Defines a struct for the watcher for application events.| 34| [HiAppEvent_Processor](capi-hiappevent-hiappevent-processor.md) | HiAppEvent_Processor | Defines a struct for the processor for application events.| 35| [HiAppEvent_Config](capi-hiappevent-hiappevent-config.md) | HiAppEvent_Config | Defines a struct for the configuration object used to set the conditions for triggering system events.| 36 37### Enums 38 39| Name| typedef Keyword| Description| 40| -- | -- | -- | 41| [HiAppEvent_ErrorCode](#hiappevent_errorcode) | HiAppEvent_ErrorCode | Enumerates the error codes used in the HiAppEvent module.| 42| [EventType](#eventtype) | - | Enumerates the event types. You are advised to select different event types based on application scenarios.| 43 44### Functions 45 46| Name| typedef Keyword| Description| 47| -- | -- | -- | 48| [typedef void (\*OH_HiAppEvent_OnReceive)(const char* domain, const struct HiAppEvent_AppEventGroup* appEventGroups, uint32_t groupLen)](#oh_hiappevent_onreceive) | OH_HiAppEvent_OnReceive | Invoked to pass event content to the caller. **Note**: The lifecycle of the object pointed by the pointer in the callback is limited to the callback function. Do not use the pointer outside of the callback function. If the information needs to be cached, perform a deep copy of the content pointed by the pointer.| 49| [typedef void (\*OH_HiAppEvent_OnTrigger)(int row, int size)](#oh_hiappevent_ontrigger) | OH_HiAppEvent_OnTrigger | Invoked if the event received by the watcher meets the conditions specified by **OH_HiAppEvent_SetTriggerCondition**. When the **OH_HiAppEvent_OnReceive** callback is not set in the watcher, the event received by the watcher will be saved.<br> After the callback is complete, if a newly saved event meets the specified condition, the callback is invoked again.| 50| [typedef void (\*OH_HiAppEvent_OnTake)(const char* const *events, uint32_t eventLen)](#oh_hiappevent_ontake) | OH_HiAppEvent_OnTake | Invoked to pass the events received by the watcher to the caller when **OH_HiAppEvent_TakeWatcherData** is used to obtain the events. Note: The lifecycle of the object pointed by the pointer in the callback is limited to the callback function. Do not use the pointer outside of the callback function. If the information needs to be cached, perform a deep copy of the content pointed by the pointer.| 51| [ParamList OH_HiAppEvent_CreateParamList(void)](#oh_hiappevent_createparamlist) | - | Creates a pointer to a parameter list object.| 52| [void OH_HiAppEvent_DestroyParamList(ParamList list)](#oh_hiappevent_destroyparamlist) | - | Destroys a pointer to a parameter list object and releases its allocated memory.| 53| [ParamList OH_HiAppEvent_AddBoolParam(ParamList list, const char* name, bool boolean)](#oh_hiappevent_addboolparam) | - | Adds an event parameter of the Boolean type to the parameter list.| 54| [ParamList OH_HiAppEvent_AddBoolArrayParam(ParamList list, const char* name, const bool* booleans, int arrSize)](#oh_hiappevent_addboolarrayparam) | - | Adds an event parameter of the Boolean array type to the parameter list.| 55| [ParamList OH_HiAppEvent_AddInt8Param(ParamList list, const char* name, int8_t num)](#oh_hiappevent_addint8param) | - | Adds an event parameter of the int8_t type to the parameter list.| 56| [ParamList OH_HiAppEvent_AddInt8ArrayParam(ParamList list, const char* name, const int8_t* nums, int arrSize)](#oh_hiappevent_addint8arrayparam) | - | Adds an event parameter of the int8_t array type to the parameter list.| 57| [ParamList OH_HiAppEvent_AddInt16Param(ParamList list, const char* name, int16_t num)](#oh_hiappevent_addint16param) | - | Adds an event parameter of the int16_t type to the parameter list.| 58| [ParamList OH_HiAppEvent_AddInt16ArrayParam(ParamList list, const char* name, const int16_t* nums, int arrSize)](#oh_hiappevent_addint16arrayparam) | - | Adds an event parameter of the int16_t array type to the parameter list.| 59| [ParamList OH_HiAppEvent_AddInt32Param(ParamList list, const char* name, int32_t num)](#oh_hiappevent_addint32param) | - | Adds an event parameter of the int32_t type to the parameter list.| 60| [ParamList OH_HiAppEvent_AddInt32ArrayParam(ParamList list, const char* name, const int32_t* nums, int arrSize)](#oh_hiappevent_addint32arrayparam) | - | Adds an event parameter of the int32_t array type to the parameter list.| 61| [ParamList OH_HiAppEvent_AddInt64Param(ParamList list, const char* name, int64_t num)](#oh_hiappevent_addint64param) | - | Adds an event parameter of the int64_t type to the parameter list.| 62| [ParamList OH_HiAppEvent_AddInt64ArrayParam(ParamList list, const char* name, const int64_t* nums, int arrSize)](#oh_hiappevent_addint64arrayparam) | - | Adds an event parameter of the int64_t array type to the parameter list.| 63| [ParamList OH_HiAppEvent_AddFloatParam(ParamList list, const char* name, float num)](#oh_hiappevent_addfloatparam) | - | Adds an event parameter of the float type to the parameter list.| 64| [ParamList OH_HiAppEvent_AddFloatArrayParam(ParamList list, const char* name, const float* nums, int arrSize)](#oh_hiappevent_addfloatarrayparam) | - | Adds an event parameter of the float array type to the parameter list.| 65| [ParamList OH_HiAppEvent_AddDoubleParam(ParamList list, const char* name, double num)](#oh_hiappevent_adddoubleparam) | - | Adds an event parameter of the Double type to the parameter list.| 66| [ParamList OH_HiAppEvent_AddDoubleArrayParam(ParamList list, const char* name, const double* nums, int arrSize)](#oh_hiappevent_adddoublearrayparam) | - | Adds an event parameter of the double array type to the parameter list.| 67| [ParamList OH_HiAppEvent_AddStringParam(ParamList list, const char* name, const char* str)](#oh_hiappevent_addstringparam) | - | Adds a parameter of the string type to the parameter list.| 68| [ParamList OH_HiAppEvent_AddStringArrayParam(ParamList list, const char* name, const char * const *strs, int arrSize)](#oh_hiappevent_addstringarrayparam) | - | Adds a parameter of the string array type to the parameter list.| 69| [int OH_HiAppEvent_Write(const char* domain, const char* name, enum EventType type, const ParamList list)](#oh_hiappevent_write) | - | Logs application events whose parameters are of the list type. Before 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.| 70| [bool OH_HiAppEvent_Configure(const char* name, const char* value)](#oh_hiappevent_configure) | - | Configures the application event logging function. This function is used to configure the event logging function and the storage quota of the event file directory.| 71| [HiAppEvent_Watcher* OH_HiAppEvent_CreateWatcher(const char* name)](#oh_hiappevent_createwatcher) | - | Creates a watcher for application events. Note: If a created watcher is no longer used, you are required to destroy it by calling OH_HiAppEvent_DestroyWatcher.| 72| [void OH_HiAppEvent_DestroyWatcher(HiAppEvent_Watcher* watcher)](#oh_hiappevent_destroywatcher) | - | Destroys a created watcher. Note: If a created watcher is no longer used, destroy it to release memory to prevent memory leaks. After the watcher is destroyed, set its pointer to null.| 73| [int OH_HiAppEvent_SetTriggerCondition(HiAppEvent_Watcher* watcher, int row, int size, int timeOut)](#oh_hiappevent_settriggercondition) | - | Sets the trigger condition of the **OH_HiAppEvent_OnTrigger** callback.<br> You can set the trigger condition by the number and size of new events received by the watcher, and **onTrigger** timeout interval. Ensure that at least one of the trigger conditions is set on the caller side.| 74| [int OH_HiAppEvent_SetAppEventFilter(HiAppEvent_Watcher* watcher, const char* domain, uint8_t eventTypes,const char* const *names, int namesLen)](#oh_hiappevent_setappeventfilter) | - | Sets the type of events to listen for. This function can be called repeatedly. You can add multiple filtering conditions instead of replacing them. The watcher will receive notifications of events that meet any of the filtering conditions.| 75| [int OH_HiAppEvent_SetWatcherOnTrigger(HiAppEvent_Watcher* watcher, OH_HiAppEvent_OnTrigger onTrigger)](#oh_hiappevent_setwatcherontrigger) | - | Sets the **onTrigger** callback.<br> If **OnReceive** is not set or is set to **nullptr**, the application events received by the watcher will be saved. If the saved application events meet the trigger conditions of the **onTrigger** callback, the **onTrigger** callback will be called.| 76| [int OH_HiAppEvent_SetWatcherOnReceive(HiAppEvent_Watcher* watcher, OH_HiAppEvent_OnReceive onReceive)](#oh_hiappevent_setwatcheronreceive) | - | Sets the **onReceive** callback. When the listener detects the corresponding event, the onReceive callback is called.| 77| [int OH_HiAppEvent_TakeWatcherData(HiAppEvent_Watcher* watcher, uint32_t eventNum, OH_HiAppEvent_OnTake onTake)](#oh_hiappevent_takewatcherdata) | - | Obtains the event saved by the watcher.| 78| [int OH_HiAppEvent_AddWatcher(HiAppEvent_Watcher* watcher)](#oh_hiappevent_addwatcher) | - | Adds a watcher. Once a watcher is added, it starts to listen for system messages.| 79| [int OH_HiAppEvent_RemoveWatcher(HiAppEvent_Watcher* watcher)](#oh_hiappevent_removewatcher) | - | Removes a watcher. Once a watcher is removed, it stops listening for system messages. Note: This API only enables the watcher to stop listening for system messages. It does not destroy the watcher. The watcher still resides in the memory until the OH_HiAppEvent_DestroyWatcher API is called.| 80| [void OH_HiAppEvent_ClearData()](#oh_hiappevent_cleardata) | - | Clears the events saved by all watchers.| 81| [HiAppEvent_Processor* OH_HiAppEvent_CreateProcessor(const char* name)](#oh_hiappevent_createprocessor) | - | Creates a processor for application events. Note: If a processor is no longer used, call **OH_HiAppEvent_DestroyProcessor** to destroy it.| 82| [int OH_HiAppEvent_SetReportRoute(HiAppEvent_Processor* processor, const char* appId, const char* routeInfo)](#oh_hiappevent_setreportroute) | - | Sets the report route for the processor.| 83| [int OH_HiAppEvent_SetReportPolicy(HiAppEvent_Processor* processor, int periodReport, int batchReport,bool onStartReport, bool onBackgroundReport)](#oh_hiappevent_setreportpolicy) | - | Sets the report policy for the processor.| 84| [int OH_HiAppEvent_SetReportEvent(HiAppEvent_Processor* processor, const char* domain, const char* name,bool isRealTime)](#oh_hiappevent_setreportevent) | - | Sets the report event for the processor.| 85| [int OH_HiAppEvent_SetCustomConfig(HiAppEvent_Processor* processor, const char* key, const char* value)](#oh_hiappevent_setcustomconfig) | - | Sets the custom extension parameters of the processor.| 86| [int OH_HiAppEvent_SetConfigId(HiAppEvent_Processor* processor, int configId)](#oh_hiappevent_setconfigid) | - | Sets the configuration ID of the processor.| 87| [int OH_HiAppEvent_SetConfigName(HiAppEvent_Processor* processor, const char* configName)](#oh_hiappevent_setconfigname) | - | Sets the configuration name of the processor.| 88| [int OH_HiAppEvent_SetReportUserId(HiAppEvent_Processor* processor, const char* const * userIdNames, int size)](#oh_hiappevent_setreportuserid) | - | Sets the report user ID of the processor.| 89| [int OH_HiAppEvent_SetReportUserProperty(HiAppEvent_Processor* processor, const char* const * userPropertyNames,int size)](#oh_hiappevent_setreportuserproperty) | - | Sets the report user property of the processor.| 90| [int64_t OH_HiAppEvent_AddProcessor(HiAppEvent_Processor* processor)](#oh_hiappevent_addprocessor) | - | Adds a processor. You can add a processor to migrate event data to the cloud. You can preset the implementation of the processor on the device and set its properties based on its constraints. Note that the configuration information of **Processor** must be provided by the data processor. Yet, as no data processor is preset in the device for interaction for the moment, migrating events to the cloud is unavailable.| 91| [void OH_HiAppEvent_DestroyProcessor(HiAppEvent_Processor* processor)](#oh_hiappevent_destroyprocessor) | - | Destroys a processor. Note: If a processor is no longer used, destroy it to release memory to prevent memory leaks. After the processor is destroyed, set its pointer to null.| 92| [int OH_HiAppEvent_RemoveProcessor(int64_t processorId)](#oh_hiappevent_removeprocessor) | - | Removes a processor. Once a processor is removed, it stops reporting events. Note: This API only stops the processor reporting events but does not destroy the processor. You can call **OH_HiAppEvent_DestroyProcessor** to destroy the processor and release the memory.| 93| [HiAppEvent_Config* OH_HiAppEvent_CreateConfig(void)](#oh_hiappevent_createconfig) | - | Creates a pointer to the configuration object that sets the conditions for triggering system events.| 94| [void OH_HiAppEvent_DestroyConfig(HiAppEvent_Config* config)](#oh_hiappevent_destroyconfig) | - | Destroys a configuration object. Note: If a configuration object is no longer used, destroy it to release memory to prevent memory leaks. After the object is destroyed, set its pointer to null.| 95| [int OH_HiAppEvent_SetConfigItem(HiAppEvent_Config* config, const char* itemName, const char* itemValue)](#oh_hiappevent_setconfigitem) | - | Sets the items in the configuration object.| 96| [int OH_HiAppEvent_SetEventConfig(const char* name, HiAppEvent_Config* config)](#oh_hiappevent_seteventconfig) | - | Sets the conditions for triggering system event subscription.| 97 98## Enum Description 99 100### HiAppEvent_ErrorCode 101 102``` 103enum HiAppEvent_ErrorCode 104``` 105 106**Description** 107 108Enumerates the error codes used in the HiAppEvent module. 109 110**Since**: 15 111 112| Enum Item| Description | 113| -- |-------------------------| 114| HIAPPEVENT_SUCCESS = 0 | The operation is successful. | 115| HIAPPEVENT_INVALID_PARAM_VALUE_LENGTH = 4 | The parameter value length is invalid.<br>**Since**: 18| 116| HIAPPEVENT_PROCESSOR_IS_NULL = -7 | The processor is null.<br>**Since**: 18 | 117| HIAPPEVENT_PROCESSOR_NOT_FOUND = -8 | The processor is not found.<br>**Since**: 18 | 118| HIAPPEVENT_INVALID_PARAM_VALUE = -9 | The parameter value is invalid. | 119| HIAPPEVENT_EVENT_CONFIG_IS_NULL = -10 | The event configuration is null. | 120| HIAPPEVENT_OPERATE_FAILED = -100 | The operation failed.<br>**Since**: 18 | 121| HIAPPEVENT_INVALID_UID = -200 | The user ID is invalid.<br>**Since**: 18 | 122 123### EventType 124 125``` 126enum EventType 127``` 128 129**Description** 130 131Enumerates the event types. You are advised to select different event types based on application scenarios. 132 133**Since**: 8 134 135| Enum Item| Description| 136| -- | -- | 137| FAULT = 1 | Fault event.| 138| STATISTIC = 2 | Statistics event.| 139| SECURITY = 3 | Security event.| 140| BEHAVIOR = 4 | Behavior event.| 141 142 143## Function Description 144 145### OH_HiAppEvent_OnReceive() 146 147``` 148typedef void (*OH_HiAppEvent_OnReceive)(const char* domain, const struct HiAppEvent_AppEventGroup* appEventGroups, uint32_t groupLen) 149``` 150 151**Description** 152 153Defines a callback invoked to pass event content to the caller. Note: The lifecycle of the object pointed by the pointer in the callback is limited to the callback function. Do not use the pointer outside of the callback function. If the information needs to be cached, perform a deep copy of the content pointed by the pointer. 154 155**Since**: 12 156 157 158**Parameters** 159 160| Name| Description| 161| -- | -- | 162| const char* domain | Domain of the received application event.| 163| [ const struct HiAppEvent_AppEventGroup](capi-hiappevent-hiappevent-appeventgroup.md)* appEventGroups | Event group array.| 164| uint32_t groupLen | Length of the event group array.| 165 166### OH_HiAppEvent_OnTrigger() 167 168``` 169typedef void (*OH_HiAppEvent_OnTrigger)(int row, int size) 170``` 171 172**Description** 173 174Defines a callback invoked if the event received by the watcher meets the conditions specified by **OH_HiAppEvent_SetTriggerCondition**. When the **OH_HiAppEvent_OnReceive** callback is not set in the watcher, the event received by the watcher will be saved.<br> After the callback is complete, if a newly saved event meets the specified condition, the callback is invoked again. 175 176**Since**: 12 177 178 179**Parameters** 180 181| Name| Description| 182| -- | -- | 183| int row | Number of events newly received by the watcher.| 184| int size | Total size of events newly received by the watcher. The size of a single event is the length of the JSON string converted from the event.| 185 186### OH_HiAppEvent_OnTake() 187 188``` 189typedef void (*OH_HiAppEvent_OnTake)(const char* const *events, uint32_t eventLen) 190``` 191 192**Description** 193 194Invoked to pass the events received by the watcher to the caller when **OH_HiAppEvent_TakeWatcherData** is used to obtain the events. Note: The lifecycle of the object pointed by the pointer in the callback is limited to the callback function. Do not use the pointer outside of the callback function. If the information needs to be cached, perform a deep copy of the content pointed by the pointer. 195 196**Since**: 12 197 198 199**Parameters** 200 201| Name| Description| 202| -- | -- | 203| const char* const *events | Event array in JSON string format.| 204| uint32_t eventLen | Size of the event array.| 205 206### OH_HiAppEvent_CreateParamList() 207 208``` 209ParamList OH_HiAppEvent_CreateParamList(void) 210``` 211 212**Description** 213 214Creates a pointer to a parameter list object. 215 216**Since**: 8 217 218**Returns** 219 220| Type| Description| 221| -- | -- | 222| [ParamList](capi-hiappevent-paramlistnode8h.md) | Pointer to the parameter list object.| 223 224### OH_HiAppEvent_DestroyParamList() 225 226``` 227void OH_HiAppEvent_DestroyParamList(ParamList list) 228``` 229 230**Description** 231 232Destroys a pointer to a parameter list object and releases its allocated memory. 233 234**Since**: 8 235 236 237**Parameters** 238 239| Name| Description| 240| -- | -- | 241| [ParamList](capi-hiappevent-paramlistnode8h.md) list | Pointer to the parameter list object.| 242 243### OH_HiAppEvent_AddBoolParam() 244 245``` 246ParamList OH_HiAppEvent_AddBoolParam(ParamList list, const char* name, bool boolean) 247``` 248 249**Description** 250 251Adds an event parameter of the Boolean type to the parameter list. 252 253**Since**: 8 254 255 256**Parameters** 257 258| Name| Description| 259| -- | -- | 260| [ParamList](capi-hiappevent-paramlistnode8h.md) list | Pointer to the parameter list to which parameters need to be added.| 261| const char* name | Name of the parameter to be added.| 262| bool boolean | Value of the parameter to be added.| 263 264**Returns** 265 266| Type| Description| 267| -- | -- | 268| [ParamList](capi-hiappevent-paramlistnode8h.md) | Pointer to the parameter list that contains the parameters added.| 269 270### OH_HiAppEvent_AddBoolArrayParam() 271 272``` 273ParamList OH_HiAppEvent_AddBoolArrayParam(ParamList list, const char* name, const bool* booleans, int arrSize) 274``` 275 276**Description** 277 278Adds an event parameter of the Boolean array type to the parameter list. 279 280**Since**: 8 281 282 283**Parameters** 284 285| Name| Description| 286| -- | -- | 287| [ParamList](capi-hiappevent-paramlistnode8h.md) list | Pointer to the parameter list to which parameters need to be added.| 288| const char* name | Name of the parameter to be added.| 289| const bool* booleans | Value of the parameter to be added.| 290| int arrSize | Size of the parameter array to be added.| 291 292**Returns** 293 294| Type| Description| 295| -- | -- | 296| [ParamList](capi-hiappevent-paramlistnode8h.md) | Pointer to the parameter list that contains the parameters added.| 297 298### OH_HiAppEvent_AddInt8Param() 299 300``` 301ParamList OH_HiAppEvent_AddInt8Param(ParamList list, const char* name, int8_t num) 302``` 303 304**Description** 305 306Adds an event parameter of the int8_t type to the parameter list. 307 308**Since**: 8 309 310 311**Parameters** 312 313| Name| Description| 314| -- | -- | 315| [ParamList](capi-hiappevent-paramlistnode8h.md) list | Pointer to the parameter list to which parameters need to be added.| 316| const char* name | Name of the parameter to be added.| 317| int8_t num | Value of the parameter to be added.| 318 319**Returns** 320 321| Type| Description| 322| -- | -- | 323| [ParamList](capi-hiappevent-paramlistnode8h.md) | Pointer to the parameter list that contains the parameters added.| 324 325### OH_HiAppEvent_AddInt8ArrayParam() 326 327``` 328ParamList OH_HiAppEvent_AddInt8ArrayParam(ParamList list, const char* name, const int8_t* nums, int arrSize) 329``` 330 331**Description** 332 333Adds an event parameter of the int8_t array type to the parameter list. 334 335**Since**: 8 336 337 338**Parameters** 339 340| Name| Description| 341| -- | -- | 342| [ParamList](capi-hiappevent-paramlistnode8h.md) list | Pointer to the parameter list to which parameters need to be added.| 343| const char* name | Name of the parameter to be added.| 344| const int8_t* nums | Value of the parameter to be added.| 345| int arrSize | Size of the parameter array to be added.| 346 347**Returns** 348 349| Type| Description| 350| -- | -- | 351| [ParamList](capi-hiappevent-paramlistnode8h.md) | Pointer to the parameter list that contains the parameters added.| 352 353### OH_HiAppEvent_AddInt16Param() 354 355``` 356ParamList OH_HiAppEvent_AddInt16Param(ParamList list, const char* name, int16_t num) 357``` 358 359**Description** 360 361Adds an event parameter of the int16_t type to the parameter list. 362 363**Since**: 8 364 365 366**Parameters** 367 368| Name| Description| 369| -- | -- | 370| [ParamList](capi-hiappevent-paramlistnode8h.md) list | Pointer to the parameter list to which parameters need to be added.| 371| const char* name | Name of the parameter to be added.| 372| int16_t num | Value of the parameter to be added.| 373 374**Returns** 375 376| Type| Description| 377| -- | -- | 378| [ParamList](capi-hiappevent-paramlistnode8h.md) | Pointer to the parameter list that contains the parameters added.| 379 380### OH_HiAppEvent_AddInt16ArrayParam() 381 382``` 383ParamList OH_HiAppEvent_AddInt16ArrayParam(ParamList list, const char* name, const int16_t* nums, int arrSize) 384``` 385 386**Description** 387 388Adds an event parameter of the int16_t array type to the parameter list. 389 390**Since**: 8 391 392 393**Parameters** 394 395| Name| Description| 396| -- | -- | 397| [ParamList](capi-hiappevent-paramlistnode8h.md) list | Pointer to the parameter list to which parameters need to be added.| 398| const char* name | Name of the parameter to be added.| 399| const int16_t* nums | Value of the parameter to be added.| 400| int arrSize | Size of the parameter array to be added.| 401 402**Returns** 403 404| Type| Description| 405| -- | -- | 406| [ParamList](capi-hiappevent-paramlistnode8h.md) | Pointer to the parameter list that contains the parameters added.| 407 408### OH_HiAppEvent_AddInt32Param() 409 410``` 411ParamList OH_HiAppEvent_AddInt32Param(ParamList list, const char* name, int32_t num) 412``` 413 414**Description** 415 416Adds an event parameter of the int32_t type to the parameter list. 417 418**Since**: 8 419 420 421**Parameters** 422 423| Name| Description| 424| -- | -- | 425| [ParamList](capi-hiappevent-paramlistnode8h.md) list | Pointer to the parameter list to which parameters need to be added.| 426| const char* name | Name of the parameter to be added.| 427| int32_t num | Value of the parameter to be added.| 428 429**Returns** 430 431| Type| Description| 432| -- | -- | 433| [ParamList](capi-hiappevent-paramlistnode8h.md) | Pointer to the parameter list that contains the parameters added.| 434 435### OH_HiAppEvent_AddInt32ArrayParam() 436 437``` 438ParamList OH_HiAppEvent_AddInt32ArrayParam(ParamList list, const char* name, const int32_t* nums, int arrSize) 439``` 440 441**Description** 442 443Adds an event parameter of the int32_t array type to the parameter list. 444 445**Since**: 8 446 447 448**Parameters** 449 450| Name| Description| 451| -- | -- | 452| [ParamList](capi-hiappevent-paramlistnode8h.md) list | Pointer to the parameter list to which parameters need to be added.| 453| const char* name | Name of the parameter to be added.| 454| const int32_t* nums | Value of the parameter to be added.| 455| int arrSize | Size of the parameter array to be added.| 456 457**Returns** 458 459| Type| Description| 460| -- | -- | 461| [ParamList](capi-hiappevent-paramlistnode8h.md) | Pointer to the parameter list that contains the parameters added.| 462 463### OH_HiAppEvent_AddInt64Param() 464 465``` 466ParamList OH_HiAppEvent_AddInt64Param(ParamList list, const char* name, int64_t num) 467``` 468 469**Description** 470 471Adds an event parameter of the int64_t type to the parameter list. 472 473**Since**: 8 474 475 476**Parameters** 477 478| Name| Description| 479| -- | -- | 480| [ParamList](capi-hiappevent-paramlistnode8h.md) list | Pointer to the parameter list to which parameters need to be added.| 481| const char* name | Name of the parameter to be added.| 482| int64_t num | Value of the parameter to be added.| 483 484**Returns** 485 486| Type| Description| 487| -- | -- | 488| [ParamList](capi-hiappevent-paramlistnode8h.md) | Pointer to the parameter list that contains the parameters added.| 489 490### OH_HiAppEvent_AddInt64ArrayParam() 491 492``` 493ParamList OH_HiAppEvent_AddInt64ArrayParam(ParamList list, const char* name, const int64_t* nums, int arrSize) 494``` 495 496**Description** 497 498Adds an event parameter of the int64_t array type to the parameter list. 499 500**Since**: 8 501 502 503**Parameters** 504 505| Name| Description| 506| -- | -- | 507| [ParamList](capi-hiappevent-paramlistnode8h.md) list | Pointer to the parameter list to which parameters need to be added.| 508| const char* name | Name of the parameter to be added.| 509| const int64_t* nums | Value of the parameter to be added.| 510| int arrSize | Size of the parameter array to be added.| 511 512**Returns** 513 514| Type| Description| 515| -- | -- | 516| [ParamList](capi-hiappevent-paramlistnode8h.md) | Pointer to the parameter list that contains the parameters added.| 517 518### OH_HiAppEvent_AddFloatParam() 519 520``` 521ParamList OH_HiAppEvent_AddFloatParam(ParamList list, const char* name, float num) 522``` 523 524**Description** 525 526Adds an event parameter of the float type to the parameter list. 527 528**Since**: 8 529 530 531**Parameters** 532 533| Name| Description| 534| -- | -- | 535| [ParamList](capi-hiappevent-paramlistnode8h.md) list | Pointer to the parameter list to which parameters need to be added.| 536| const char* name | Name of the parameter to be added.| 537| float num | Value of the parameter to be added.| 538 539**Returns** 540 541| Type| Description| 542| -- | -- | 543| [ParamList](capi-hiappevent-paramlistnode8h.md) | Pointer to the parameter list that contains the parameters added.| 544 545### OH_HiAppEvent_AddFloatArrayParam() 546 547``` 548ParamList OH_HiAppEvent_AddFloatArrayParam(ParamList list, const char* name, const float* nums, int arrSize) 549``` 550 551**Description** 552 553Adds an event parameter of the float array type to the parameter list. 554 555**Since**: 8 556 557 558**Parameters** 559 560| Name| Description| 561| -- | -- | 562| [ParamList](capi-hiappevent-paramlistnode8h.md) list | Pointer to the parameter list to which parameters need to be added.| 563| const char* name | Name of the parameter to be added.| 564| const float* nums | Value of the parameter to be added.| 565| int arrSize | Size of the parameter array to be added.| 566 567**Returns** 568 569| Type| Description| 570| -- | -- | 571| [ParamList](capi-hiappevent-paramlistnode8h.md) | Pointer to the parameter list that contains the parameters added.| 572 573### OH_HiAppEvent_AddDoubleParam() 574 575``` 576ParamList OH_HiAppEvent_AddDoubleParam(ParamList list, const char* name, double num) 577``` 578 579**Description** 580 581Adds an event parameter of the Double type to the parameter list. 582 583**Since**: 8 584 585 586**Parameters** 587 588| Name| Description| 589| -- | -- | 590| [ParamList](capi-hiappevent-paramlistnode8h.md) list | Pointer to the parameter list to which parameters need to be added.| 591| const char* name | Name of the parameter to be added.| 592| double num | Value of the parameter to be added.| 593 594**Returns** 595 596| Type| Description| 597| -- | -- | 598| [ParamList](capi-hiappevent-paramlistnode8h.md) | Pointer to the parameter list that contains the parameters added.| 599 600### OH_HiAppEvent_AddDoubleArrayParam() 601 602``` 603ParamList OH_HiAppEvent_AddDoubleArrayParam(ParamList list, const char* name, const double* nums, int arrSize) 604``` 605 606**Description** 607 608Adds an event parameter of the double array type to the parameter list. 609 610**Since**: 8 611 612 613**Parameters** 614 615| Name| Description| 616| -- | -- | 617| [ParamList](capi-hiappevent-paramlistnode8h.md) list | Pointer to the parameter list to which parameters need to be added.| 618| const char* name | Name of the parameter to be added.| 619| const double* nums | Value of the parameter to be added.| 620| int arrSize | Size of the parameter array to be added.| 621 622**Returns** 623 624| Type| Description| 625| -- | -- | 626| [ParamList](capi-hiappevent-paramlistnode8h.md) | Pointer to the parameter list that contains the parameters added.| 627 628### OH_HiAppEvent_AddStringParam() 629 630``` 631ParamList OH_HiAppEvent_AddStringParam(ParamList list, const char* name, const char* str) 632``` 633 634**Description** 635 636Adds a parameter of the string type to the parameter list. 637 638**Since**: 8 639 640 641**Parameters** 642 643| Name| Description| 644| -- | -- | 645| [ParamList](capi-hiappevent-paramlistnode8h.md) list | Pointer to the parameter list to which parameters need to be added.| 646| const char* name | Name of the parameter to be added.| 647| const char* str | Value of the parameter to be added.| 648 649**Returns** 650 651| Type| Description| 652| -- | -- | 653| [ParamList](capi-hiappevent-paramlistnode8h.md) | Pointer to the parameter list that contains the parameters added.| 654 655### OH_HiAppEvent_AddStringArrayParam() 656 657``` 658ParamList OH_HiAppEvent_AddStringArrayParam(ParamList list, const char* name, const char * const *strs, int arrSize) 659``` 660 661**Description** 662 663Adds a parameter of the string array type to the parameter list. 664 665**Since**: 8 666 667 668**Parameters** 669 670| Name| Description| 671| -- | -- | 672| [ParamList](capi-hiappevent-paramlistnode8h.md) list | Pointer to the parameter list to which parameters need to be added.| 673| const char* name | Name of the parameter to be added.| 674| const char * const *strs | Value of the parameter to be added.| 675| int arrSize | Size of the parameter array to be added.| 676 677**Returns** 678 679| Type| Description| 680| -- | -- | 681| [ParamList](capi-hiappevent-paramlistnode8h.md) | Pointer to the parameter list that contains the parameters added.| 682 683### OH_HiAppEvent_Write() 684 685``` 686int OH_HiAppEvent_Write(const char* domain, const char* name, enum EventType type, const ParamList list) 687``` 688 689**Description** 690 691Logs application events whose parameters are of the list type. Before 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. 692 693**Since**: 8 694 695 696**Parameters** 697 698| Name| Description| 699| -- | -- | 700| const char* domain | Event domain. You can customize event domains as required.<br> The value is a string that contains a maximum of 32 characters, including digits (0 to 9), letters (a to z), and underscore (\_). It must start with a letter and cannot end with an underscore (\_).| 701| const char* name | Event name. You can customize event names as required.<br> The value is a string that contains a maximum of 48 characters, including digits (0 to 9), letters (a to z), underscore (\_), and dollar sign (`$`). It must start with a letter or dollar sign (`$`) and end with a digit or letter.| 702| enum [EventType](capi-hiappevent-h.md#eventtype) type | Event type. For details, see [EventType](capi-hiappevent-h.md#eventtype).| 703| [const ParamList](capi-hiappevent-paramlistnode8h.md) list | List of event parameters, each of which consists of a parameter name and a parameter value. The specifications are as follows:<br> 1.<br> The value is a string that contains a maximum of 32 characters, including digits (0 to 9), letters (a to z), underscore (_), and dollar sign (`$`). It must start with a letter or dollar sign (`$`) and end with a digit or letter.<br> 2. The parameter value can be a string, number, Boolean, or array. The length of a string must be less than 8 × 1024 characters. If this limit is exceeded, excess characters will be truncated.<br> The element type of an array parameter can only be a string, number, or Boolean, and the number of elements must be less than 100. If this limit is exceeded, excess elements will be discarded.<br> 3. The maximum number of parameters is 32. If this limit is exceeded, excess parameters will be discarded.| 704 705**Returns** 706 707| Type| Description| 708| -- | -- | 709| int | If the event parameters are successfully verified, **0** is returned and the event is written into the event file.<br> If an event contains invalid parameters, a positive value is returned. The event is written into the event file after the invalid parameters are discarded.<br> If the event parameter fails to be verified, a negative value is returned and the event is not written to the event file.<br> **0**: Parameter verification successful.<br> **-1**: Invalid event name.<br> **-4**: Invalid event domain name.<br> **-99**: Application event logging disabled.<br> **1**: Invalid event parameter name.<br> **4**: Invalid event parameter string length.<br> **5**: Invalid number of event parameters.<br> **6**: Invalid event parameter array length.<br> **8**: Duplicate event parameter name.| 710 711### OH_HiAppEvent_Configure() 712 713``` 714bool OH_HiAppEvent_Configure(const char* name, const char* value) 715``` 716 717**Description** 718 719Configures the application event logging function. This function is used to configure the event logging function and the storage quota of the event file directory. 720 721**Since**: 8 722 723 724**Parameters** 725 726| Name| Description| 727| -- | -- | 728| const char* name | Configuration item name The value can be [DISABLE](capi-hiappevent-cfg-h.md#disable) or [MAX_STORAGE](capi-hiappevent-cfg-h.md#max_storage).| 729| const char* value | Configuration item value. If the configuration item name is [DISABLE](capi-hiappevent-cfg-h.md#disable), the value can be **true** or **false**.<br> If the configuration item name is [MAX_STORAGE](capi-hiappevent-cfg-h.md#max_storage), the quota value can contain only digits and the unit character. The unit character can be **b**\|**k**\|**kb**\|**m**\|**mb**\|**g**\|**gb**\|**t**\|**tb**, which is case insensitive.<br> The quota value must start with a digit. You can determine whether to pass the unit. If the unit is left empty, **b** (that is, byte) is used by default.| 730 731**Returns** 732 733| Type| Description| 734| -- | -- | 735| bool | Configuration result. The value **true** indicates that the configuration is successful, and the value **false** indicates the opposite.| 736 737### OH_HiAppEvent_CreateWatcher() 738 739``` 740HiAppEvent_Watcher* OH_HiAppEvent_CreateWatcher(const char* name) 741``` 742 743**Description** 744 745Creates a watcher for application events. Note: If a created watcher is no longer used, you are required to destroy it by calling OH_HiAppEvent_DestroyWatcher. 746 747**Since**: 12 748 749 750**Parameters** 751 752| Name| Description| 753| -- | -- | 754| const char* name | Watcher name.| 755 756**Returns** 757 758| Type | Description| 759|-------------------------| -- | 760| [HiAppEvent_Watcher](capi-hiappevent-hiappevent-watcher.md)* | Pointer to the new watcher if the API is called successfully; **nullptr** if the **name** parameter is invalid.| 761 762### OH_HiAppEvent_DestroyWatcher() 763 764``` 765void OH_HiAppEvent_DestroyWatcher(HiAppEvent_Watcher* watcher) 766``` 767 768**Description** 769 770Destroys a created watcher. Note: If a created watcher is no longer used, destroy it to release memory to prevent memory leaks. After the watcher is destroyed, set its pointer to null. 771 772**Since**: 12 773 774 775**Parameters** 776 777| Name| Description| 778| -- | -- | 779| [HiAppEvent_Watcher](capi-hiappevent-hiappevent-watcher.md)* watcher | Pointer to the watcher (that is, the pointer returned by OH_HiAppEvent_CreateWatcher).| 780 781### OH_HiAppEvent_SetTriggerCondition() 782 783``` 784int OH_HiAppEvent_SetTriggerCondition(HiAppEvent_Watcher* watcher, int row, int size, int timeOut) 785``` 786 787**Description** 788 789Sets the trigger condition of the **OH_HiAppEvent_OnTrigger** callback.<br> You can set the trigger condition by the number and size of new events received by the watcher, and **onTrigger** timeout interval. Ensure that at least one of the trigger conditions is set on the caller side. 790 791**Since**: 12 792 793 794**Parameters** 795 796| Name| Description| 797| -- | -- | 798| [HiAppEvent_Watcher](capi-hiappevent-hiappevent-watcher.md)* watcher | Pointer to the watcher (that is, the pointer returned by OH_HiAppEvent_CreateWatcher).| 799| int row | Row count. If the input value is greater than 0 and the number of newly received events is greater than or equal to the value of this parameter, the configured **onTrigger** callback is called.<br> If the input value is less than or equal to 0, the number of received events is not used as the condition to trigger the **onTrigger** callback.| 800| int size | Size value. If the input value is greater than 0 and the size of the newly received event is greater than or equal to the value of this parameter, the configured **onTrigger** callback is called. The size of a single event is the length of the JSON string converted from the event. <br> If the input value is less than or equal to 0, the size of received events is not used as the condition to trigger the **onTrigger** callback.| 801| int timeOut | Timeout value, in seconds. If the input value is greater than 0, the system checks the watcher for newly received events based on the timeout interval. If there are any newly received events, the configured onTrigger callback is triggered.<br> After the callback is complete, the system checks the watcher for newly received events when the timeout value expires.<br> If the input value is less than or equal to 0, the timeout interval is not used as the condition to trigger the onTrigger callback.| 802 803**Returns** 804 805| Type| Description| 806| -- | -- | 807| int | **0** if the API is called successfully; **-5** if the pointer to an input parameter is null.| 808 809### OH_HiAppEvent_SetAppEventFilter() 810 811``` 812int OH_HiAppEvent_SetAppEventFilter(HiAppEvent_Watcher* watcher, const char* domain, uint8_t eventTypes,const char* const *names, int namesLen) 813``` 814 815**Description** 816 817Sets the type of events to listen for. This function can be called repeatedly. You can add multiple filtering conditions instead of replacing them. The watcher will receive notifications of events that meet any of the filtering conditions. 818 819**Since**: 12 820 821 822**Parameters** 823 824| Name| Description| 825| -- | -- | 826| [HiAppEvent_Watcher](capi-hiappevent-hiappevent-watcher.md)* watcher | Pointer to the watcher (that is, the pointer returned by OH_HiAppEvent_CreateWatcher).| 827| const char* domain | Domain of events to be listened for.| 828| uint8_t eventTypes | Types of events to be listened for. The bitwise AND matching mode is used. Multiple types of events can be listened for. If the first bit is **1** (the value is **1**), fault events can be listened for.<br> If the second bit is **1** (the value is **2**), statistics events can be listened for.<br> If the third bit is **1** (the value is **4**), security events can be listened for.<br> If the fourth digit is **1** (the value is **8**), events of the listening behavior type can be listened for.<br> If four digits are **1** (the value is **15**) or 0 (the value is **0**), events of all types can be listened for.| 829| const char* const *names | Array of the event names.| 830| int namesLen | Length of the event name array.| 831 832**Returns** 833 834| Type| Description| 835| -- | -- | 836| int | **0** if the API is called successfully; **-1** if the **names** parameter is invalid; **-4** if the **domain** parameter is invalid; **-5** if the pointer to an input parameter is null.| 837 838### OH_HiAppEvent_SetWatcherOnTrigger() 839 840``` 841int OH_HiAppEvent_SetWatcherOnTrigger(HiAppEvent_Watcher* watcher, OH_HiAppEvent_OnTrigger onTrigger) 842``` 843 844**Description** 845 846Sets the **onTrigger** callback.<br> If **OnReceive** is not set or is set to **nullptr**, the application events received by the watcher will be saved. If the saved application events meet the trigger conditions of the **onTrigger** callback, the **onTrigger** callback will be called. 847 848**Since**: 12 849 850 851**Parameters** 852 853| Name| Description| 854| -- | -- | 855| [HiAppEvent_Watcher](capi-hiappevent-hiappevent-watcher.md)* watcher | Pointer to the watcher (that is, the pointer returned by OH_HiAppEvent_CreateWatcher).| 856| [OH_HiAppEvent_OnTrigger](capi-hiappevent-h.md#oh_hiappevent_ontrigger) onTrigger | Callback to be set.| 857 858**Returns** 859 860| Type| Description| 861| -- | -- | 862| int | **0** if the API is called successfully; **-5** if the pointer to an input parameter is null.| 863 864### OH_HiAppEvent_SetWatcherOnReceive() 865 866``` 867int OH_HiAppEvent_SetWatcherOnReceive(HiAppEvent_Watcher* watcher, OH_HiAppEvent_OnReceive onReceive) 868``` 869 870**Description** 871 872Sets the **onReceive** callback. When the listener detects the corresponding event, the onReceive callback is called. 873 874**Since**: 12 875 876 877**Parameters** 878 879| Name| Description| 880| -- | -- | 881| [HiAppEvent_Watcher](capi-hiappevent-hiappevent-watcher.md)* watcher | Pointer to the watcher (that is, the pointer returned by OH_HiAppEvent_CreateWatcher).| 882| [OH_HiAppEvent_OnReceive](capi-hiappevent-h.md#oh_hiappevent_onreceive) onReceive | Pointer to the callback function.| 883 884**Returns** 885 886| Type| Description| 887| -- | -- | 888| int | **0** if the API is called successfully; **-5** if the pointer to an input parameter is null.| 889 890### OH_HiAppEvent_TakeWatcherData() 891 892``` 893int OH_HiAppEvent_TakeWatcherData(HiAppEvent_Watcher* watcher, uint32_t eventNum, OH_HiAppEvent_OnTake onTake) 894``` 895 896**Description** 897 898Obtains the event saved by the watcher. 899 900**Since**: 12 901 902 903**Parameters** 904 905| Name| Description| 906| -- | -- | 907| [HiAppEvent_Watcher](capi-hiappevent-hiappevent-watcher.md)* watcher | Pointer to the watcher (that is, the pointer returned by OH_HiAppEvent_CreateWatcher).| 908| uint32_t eventNum | If the input value is less than or equal to **0**, all saved events are obtained. If the input value is greater than **0**, events are sorted by time in descending order and a specified number of saved events are obtained.| 909| [OH_HiAppEvent_OnTake](capi-hiappevent-h.md#oh_hiappevent_ontake) onTake | Pointer to the callback. The event information is returned through this callback.| 910 911**Returns** 912 913| Type| Description| 914| -- | -- | 915| int | **0** if the API is called successfully; **-5** if the pointer to an input parameter is null; **-6** if **OH_HiAppEvent_AddWatcher** has not been called to add a watcher.| 916 917### OH_HiAppEvent_AddWatcher() 918 919``` 920int OH_HiAppEvent_AddWatcher(HiAppEvent_Watcher* watcher) 921``` 922 923**Description** 924 925Adds a watcher. Once a watcher is added, it starts to listen for system messages. 926 927**Since**: 12 928 929 930**Parameters** 931 932| Name| Description| 933| -- | -- | 934| [HiAppEvent_Watcher](capi-hiappevent-hiappevent-watcher.md)* watcher | Pointer to the watcher (that is, the pointer returned by OH_HiAppEvent_CreateWatcher).| 935 936**Returns** 937 938| Type| Description| 939| -- | -- | 940| int | **0** if the API is called successfully; **-5** if the pointer to an input parameter is null.| 941 942### OH_HiAppEvent_RemoveWatcher() 943 944``` 945int OH_HiAppEvent_RemoveWatcher(HiAppEvent_Watcher* watcher) 946``` 947 948**Description** 949 950Removes a watcher. Once a watcher is removed, it stops listening for system messages. Note: This API only enables the watcher to stop listening for system messages. It does not destroy the watcher. The watcher still resides in the memory until the OH_HiAppEvent_DestroyWatcher API is called. 951 952**Since**: 12 953 954 955**Parameters** 956 957| Name| Description| 958| -- | -- | 959| [HiAppEvent_Watcher](capi-hiappevent-hiappevent-watcher.md)* watcher | Pointer to the watcher (that is, the pointer returned by OH_HiAppEvent_CreateWatcher).| 960 961**Returns** 962 963| Type| Description| 964| -- | -- | 965| int | **0** if the API is called successfully; **-5** if the pointer to an input parameter is null; **-6** if **OH_HiAppEvent_AddWatcher** has not been called to add a watcher.| 966 967### OH_HiAppEvent_ClearData() 968 969``` 970void OH_HiAppEvent_ClearData() 971``` 972 973**Description** 974 975Clears the events saved by all watchers. 976 977**Since**: 12 978 979### OH_HiAppEvent_CreateProcessor() 980 981``` 982HiAppEvent_Processor* OH_HiAppEvent_CreateProcessor(const char* name) 983``` 984 985**Description** 986 987Creates a processor for application events. Note: If a processor is no longer used, call **OH_HiAppEvent_DestroyProcessor** to destroy it. 988 989**Since**: 18 990 991 992**Parameters** 993 994| Name| Description| 995| -- | -- | 996| const char* name | Processor name, which can contain only letters, digits, underscores (_), and dollar signs ($). It cannot start with a digit and cannot exceed 256 characters.| 997 998**Returns** 999 1000| Type | Description| 1001|---------------------------| -- | 1002| [HiAppEvent_Processor](capi-hiappevent-hiappevent-processor.md)* | Pointer to the new processor if the API is called successfully; **nullptr** if the **name** parameter is invalid.| 1003 1004### OH_HiAppEvent_SetReportRoute() 1005 1006``` 1007int OH_HiAppEvent_SetReportRoute(HiAppEvent_Processor* processor, const char* appId, const char* routeInfo) 1008``` 1009 1010**Description** 1011 1012Sets the report route for the processor. 1013 1014**Since**: 18 1015 1016 1017**Parameters** 1018 1019| Name| Description| 1020| -- | -- | 1021| [HiAppEvent_Processor](capi-hiappevent-hiappevent-processor.md)* processor | Pointer to the processor, that is, the pointer returned by **OH_HiAppEvent_CreateProcessor**.| 1022| const char* appId | Application ID of the processor.| 1023| const char* routeInfo | Server location information. The default value is an empty string. The string length cannot exceed 8 KB. Otherwise, the default value is used.| 1024 1025**Returns** 1026 1027| Type| Description| 1028| -- | -- | 1029| int | [HIAPPEVENT_SUCCESS](capi-hiappevent-h.md#hiappevent_errorcode): Operation successful.<br> [HIAPPEVENT_PROCESSOR_IS_NULL](capi-hiappevent-h.md#hiappevent_errorcode): The **processor** parameter is empty.<br> [HIAPPEVENT_INVALID_PARAM_VALUE](capi-hiappevent-h.md#hiappevent_errorcode): Invalid parameter value.<br> [HIAPPEVENT_INVALID_UID](capi-hiappevent-h.md#hiappevent_errorcode): Invalid user ID.<br> [HIAPPEVENT_INVALID_PARAM_VALUE_LENGTH](capi-hiappevent-h.md#hiappevent_errorcode): Invalid parameter value length.<br> For details, see [HiAppEvent_ErrorCode](capi-hiappevent-h.md#hiappevent_errorcode).| 1030 1031### OH_HiAppEvent_SetReportPolicy() 1032 1033``` 1034int OH_HiAppEvent_SetReportPolicy(HiAppEvent_Processor* processor, int periodReport, int batchReport,bool onStartReport, bool onBackgroundReport) 1035``` 1036 1037**Description** 1038 1039Sets the report policy for the processor. 1040 1041**Since**: 18 1042 1043 1044**Parameters** 1045 1046| Name| Description| 1047| -- | -- | 1048| [HiAppEvent_Processor](capi-hiappevent-hiappevent-processor.md)* processor | Pointer to the processor, that is, the pointer returned by **OH_HiAppEvent_CreateProcessor**.| 1049| int periodReport | Period for reporting events, in seconds.| 1050| int batchReport | Threshold for reporting events. When the number of events reaches the threshold, an event is reported.| 1051| bool onStartReport | Whether to report an event when the processor is started. The default value is **false**.| 1052| bool onBackgroundReport | Whether to report an event when an application enters the background. The default value is **false**.| 1053 1054**Returns** 1055 1056| Type| Description| 1057| -- | -- | 1058| int | [HIAPPEVENT_SUCCESS](capi-hiappevent-h.md#hiappevent_errorcode): Operation successful.<br> [HIAPPEVENT_PROCESSOR_IS_NULL](capi-hiappevent-h.md#hiappevent_errorcode): The **processor** parameter is empty.<br> [HIAPPEVENT_INVALID_PARAM_VALUE](capi-hiappevent-h.md#hiappevent_errorcode): Invalid parameter value.<br> [HIAPPEVENT_INVALID_UID](capi-hiappevent-h.md#hiappevent_errorcode): Invalid user ID.<br> For details, see [HiAppEvent_ErrorCode](capi-hiappevent-h.md#hiappevent_errorcode).| 1059 1060### OH_HiAppEvent_SetReportEvent() 1061 1062``` 1063int OH_HiAppEvent_SetReportEvent(HiAppEvent_Processor* processor, const char* domain, const char* name,bool isRealTime) 1064``` 1065 1066**Description** 1067 1068Sets the report event for the processor. 1069 1070**Since**: 18 1071 1072 1073**Parameters** 1074 1075| Name| Description| 1076| -- | -- | 1077| [HiAppEvent_Processor](capi-hiappevent-hiappevent-processor.md)* processor | Pointer to the processor, that is, the pointer returned by **OH_HiAppEvent_CreateProcessor**.| 1078| const char* domain | Domain of the report event.| 1079| const char* name | Name of the report event.| 1080| bool isRealTime | Whether to report events in real time.| 1081 1082**Returns** 1083 1084| Type| Description| 1085| -- | -- | 1086| int | [HIAPPEVENT_SUCCESS](capi-hiappevent-h.md#hiappevent_errorcode): Operation successful.<br> [HIAPPEVENT_PROCESSOR_IS_NULL](capi-hiappevent-h.md#hiappevent_errorcode): The **processor** parameter is empty.<br> [HIAPPEVENT_INVALID_PARAM_VALUE](capi-hiappevent-h.md#hiappevent_errorcode): Invalid parameter value.<br> [HIAPPEVENT_INVALID_UID](capi-hiappevent-h.md#hiappevent_errorcode): Invalid user ID.<br> For details, see [HiAppEvent_ErrorCode](capi-hiappevent-h.md#hiappevent_errorcode).| 1087 1088### OH_HiAppEvent_SetCustomConfig() 1089 1090``` 1091int OH_HiAppEvent_SetCustomConfig(HiAppEvent_Processor* processor, const char* key, const char* value) 1092``` 1093 1094**Description** 1095 1096Sets the custom extension parameters of the processor. 1097 1098**Since**: 18 1099 1100 1101**Parameters** 1102 1103| Name| Description| 1104| -- | -- | 1105| [HiAppEvent_Processor](capi-hiappevent-hiappevent-processor.md)* processor | Pointer to the processor, that is, the pointer returned by **OH_HiAppEvent_CreateProcessor**.| 1106| const char* key | Parameter name, which contains a maximum of 32 characters.| 1107| const char* value | Parameter value, which contains a maximum of 1024 characters.| 1108 1109**Returns** 1110 1111| Type| Description| 1112| -- | -- | 1113| int | [HIAPPEVENT_SUCCESS](capi-hiappevent-h.md#hiappevent_errorcode): Operation successful.<br> [HIAPPEVENT_PROCESSOR_IS_NULL](capi-hiappevent-h.md#hiappevent_errorcode): The **processor** parameter is empty.<br> [HIAPPEVENT_INVALID_PARAM_VALUE](capi-hiappevent-h.md#hiappevent_errorcode): Invalid parameter value.<br> [HIAPPEVENT_INVALID_UID](capi-hiappevent-h.md#hiappevent_errorcode): Invalid user ID.<br> [HIAPPEVENT_INVALID_PARAM_VALUE_LENGTH](capi-hiappevent-h.md#hiappevent_errorcode): Invalid parameter value length.<br> For details, see [HiAppEvent_ErrorCode](capi-hiappevent-h.md#hiappevent_errorcode).| 1114 1115### OH_HiAppEvent_SetConfigId() 1116 1117``` 1118int OH_HiAppEvent_SetConfigId(HiAppEvent_Processor* processor, int configId) 1119``` 1120 1121**Description** 1122 1123Sets the configuration ID of the processor. 1124 1125**Since**: 18 1126 1127 1128**Parameters** 1129 1130| Name| Description| 1131| -- | -- | 1132| [HiAppEvent_Processor](capi-hiappevent-hiappevent-processor.md)* processor | Pointer to the processor, that is, the pointer returned by **OH_HiAppEvent_CreateProcessor**.| 1133| int configId | Configuration ID of the processor, which is a natural number.| 1134 1135**Returns** 1136 1137| Type| Description| 1138| -- | -- | 1139| int | [HIAPPEVENT_SUCCESS](capi-hiappevent-h.md#hiappevent_errorcode): Operation successful.<br> [HIAPPEVENT_PROCESSOR_IS_NULL](capi-hiappevent-h.md#hiappevent_errorcode): The **processor** parameter is empty.<br> [HIAPPEVENT_INVALID_PARAM_VALUE](capi-hiappevent-h.md#hiappevent_errorcode): Invalid parameter value.<br> [HIAPPEVENT_INVALID_UID](capi-hiappevent-h.md#hiappevent_errorcode): Invalid user ID.<br> For details, see [HiAppEvent_ErrorCode](capi-hiappevent-h.md#hiappevent_errorcode).| 1140 1141### OH_HiAppEvent_SetConfigName() 1142 1143``` 1144int OH_HiAppEvent_SetConfigName(HiAppEvent_Processor* processor, const char* configName) 1145``` 1146 1147**Description** 1148 1149Sets the configuration name of the processor. 1150 1151**Since**: 20 1152 1153 1154**Parameters** 1155 1156| Name| Description| 1157| -- | -- | 1158| [HiAppEvent_Processor](capi-hiappevent-hiappevent-processor.md)* processor | Pointer to the processor, that is, the pointer returned by **OH_HiAppEvent_CreateProcessor**.| 1159| const char* configName | Configuration name of the data processor. which can contain only letters, digits, underscores (_), and dollar signs ($). It cannot start with a digit and cannot exceed 256 characters.| 1160 1161**Returns** 1162 1163| Type| Description| 1164| -- | -- | 1165| int | [HIAPPEVENT_SUCCESS](capi-hiappevent-h.md#hiappevent_errorcode): Operation successful.<br> [HIAPPEVENT_PROCESSOR_IS_NULL](capi-hiappevent-h.md#hiappevent_errorcode): The **processor** parameter is empty.<br> [HIAPPEVENT_INVALID_PARAM_VALUE](capi-hiappevent-h.md#hiappevent_errorcode): Invalid parameter value.<br> [HIAPPEVENT_INVALID_UID](capi-hiappevent-h.md#hiappevent_errorcode): Invalid user ID.<br> [HIAPPEVENT_INVALID_PARAM_VALUE_LENGTH](capi-hiappevent-h.md#hiappevent_errorcode): Invalid parameter value length.<br> For details, see [HiAppEvent_ErrorCode](capi-hiappevent-h.md#hiappevent_errorcode).| 1166 1167### OH_HiAppEvent_SetReportUserId() 1168 1169``` 1170int OH_HiAppEvent_SetReportUserId(HiAppEvent_Processor* processor, const char* const * userIdNames, int size) 1171``` 1172 1173**Description** 1174 1175Sets the report user ID of the processor. 1176 1177**Since**: 18 1178 1179 1180**Parameters** 1181 1182| Name| Description| 1183| -- | -- | 1184| [HiAppEvent_Processor](capi-hiappevent-hiappevent-processor.md)* processor | Pointer to the processor, that is, the pointer returned by **OH_HiAppEvent_CreateProcessor**.| 1185| const char* const * userIdNames | Name array of user IDs that can be reported by the processor.| 1186| int size | Length of the name array of user IDs.| 1187 1188**Returns** 1189 1190| Type| Description| 1191| -- | -- | 1192| int | [HIAPPEVENT_SUCCESS](capi-hiappevent-h.md#hiappevent_errorcode): Operation successful.<br> [HIAPPEVENT_PROCESSOR_IS_NULL](capi-hiappevent-h.md#hiappevent_errorcode): The **processor** parameter is empty.<br> [HIAPPEVENT_INVALID_PARAM_VALUE](capi-hiappevent-h.md#hiappevent_errorcode): Invalid parameter value.<br> [HIAPPEVENT_INVALID_UID](capi-hiappevent-h.md#hiappevent_errorcode): Invalid user ID.<br> [HIAPPEVENT_INVALID_PARAM_VALUE_LENGTH](capi-hiappevent-h.md#hiappevent_errorcode): Invalid parameter value length.<br> For details, see [HiAppEvent_ErrorCode](capi-hiappevent-h.md#hiappevent_errorcode).| 1193 1194### OH_HiAppEvent_SetReportUserProperty() 1195 1196``` 1197int OH_HiAppEvent_SetReportUserProperty(HiAppEvent_Processor* processor, const char* const * userPropertyNames,int size) 1198``` 1199 1200**Description** 1201 1202Sets the report user property of the processor. 1203 1204**Since**: 18 1205 1206 1207**Parameters** 1208 1209| Name| Description| 1210| -- | -- | 1211| [HiAppEvent_Processor](capi-hiappevent-hiappevent-processor.md)* processor | Pointer to the processor, that is, the pointer returned by **OH_HiAppEvent_CreateProcessor**.| 1212| const char* const * userPropertyNames | Name array of user properties that can be reported by the processor.| 1213| int size | Length of the name array of user properties.| 1214 1215**Returns** 1216 1217| Type| Description| 1218| -- | -- | 1219| int | [HIAPPEVENT_SUCCESS](capi-hiappevent-h.md#hiappevent_errorcode): Operation successful.<br> [HIAPPEVENT_PROCESSOR_IS_NULL](capi-hiappevent-h.md#hiappevent_errorcode): The **processor** parameter is empty.<br> [HIAPPEVENT_INVALID_PARAM_VALUE](capi-hiappevent-h.md#hiappevent_errorcode): Invalid parameter value.<br> [HIAPPEVENT_INVALID_UID](capi-hiappevent-h.md#hiappevent_errorcode): Invalid user ID.<br> [HIAPPEVENT_INVALID_PARAM_VALUE_LENGTH](capi-hiappevent-h.md#hiappevent_errorcode): Invalid parameter value length.<br> For details, see [HiAppEvent_ErrorCode](capi-hiappevent-h.md#hiappevent_errorcode).| 1220 1221### OH_HiAppEvent_AddProcessor() 1222 1223``` 1224int64_t OH_HiAppEvent_AddProcessor(HiAppEvent_Processor* processor) 1225``` 1226 1227**Description** 1228 1229Adds a processor. You can add a processor to migrate event data to the cloud. You can preset the implementation of the processor on the device and set its properties based on its constraints. Note that the configuration information of **Processor** must be provided by the data processor. Yet, as no data processor is preset in the device for interaction for the moment, migrating events to the cloud is unavailable. 1230 1231**Since**: 18 1232 1233 1234**Parameters** 1235 1236| Name| Description| 1237| -- | -- | 1238| [HiAppEvent_Processor](capi-hiappevent-hiappevent-processor.md)* processor | Pointer to the processor, that is, the pointer returned by **OH_HiAppEvent_CreateProcessor**.| 1239 1240**Returns** 1241 1242| Type| Description| 1243| -- | -- | 1244| int64_t | Unique ID of the processor is returned when the API is successfully called. The value is greater than 0.<br> [HIAPPEVENT_PROCESSOR_IS_NULL](capi-hiappevent-h.md#hiappevent_errorcode): The **processor** parameter is empty.<br> [HIAPPEVENT_INVALID_PARAM_VALUE](capi-hiappevent-h.md#hiappevent_errorcode): Invalid parameter value.<br> [HIAPPEVENT_OPERATE_FAILED](capi-hiappevent-h.md#hiappevent_errorcode): Failed to find or register the data processor name.<br> [HIAPPEVENT_INVALID_UID](capi-hiappevent-h.md#hiappevent_errorcode): Invalid user ID.<br> For details, see [HiAppEvent_ErrorCode](capi-hiappevent-h.md#hiappevent_errorcode).| 1245 1246### OH_HiAppEvent_DestroyProcessor() 1247 1248``` 1249void OH_HiAppEvent_DestroyProcessor(HiAppEvent_Processor* processor) 1250``` 1251 1252**Description** 1253 1254Destroys a processor. Note: If a processor is no longer used, destroy it to release memory to prevent memory leaks. After the processor is destroyed, set its pointer to null. 1255 1256**Since**: 18 1257 1258 1259**Parameters** 1260 1261| Name| Description| 1262| -- | -- | 1263| [HiAppEvent_Processor](capi-hiappevent-hiappevent-processor.md)* processor | Pointer to the processor, that is, the pointer returned by **OH_HiAppEvent_CreateProcessor**.| 1264 1265### OH_HiAppEvent_RemoveProcessor() 1266 1267``` 1268int OH_HiAppEvent_RemoveProcessor(int64_t processorId) 1269``` 1270 1271**Description** 1272 1273Removes a processor. Once a processor is removed, it stops reporting events. Note: This API only stops the processor reporting events but does not destroy the processor. You can call **OH_HiAppEvent_DestroyProcessor** to destroy the processor and release the memory. 1274 1275**Since**: 18 1276 1277 1278**Parameters** 1279 1280| Name| Description| 1281| -- | -- | 1282| int64_t processorId | Unique ID of a processor.| 1283 1284**Returns** 1285 1286| Type| Description| 1287| -- | -- | 1288| int | [HIAPPEVENT_SUCCESS](capi-hiappevent-h.md#hiappevent_errorcode): Operation successful.<br> [HIAPPEVENT_PROCESSOR_NOT_FOUND](capi-hiappevent-h.md#hiappevent_errorcode): Failed to find the processor.<br> [HIAPPEVENT_OPERATE_FAILED](capi-hiappevent-h.md#hiappevent_errorcode): Operation failed.<br> [HIAPPEVENT_INVALID_UID](capi-hiappevent-h.md#hiappevent_errorcode): Invalid user ID.<br> For details, see [HiAppEvent_ErrorCode](capi-hiappevent-h.md#hiappevent_errorcode).| 1289 1290### OH_HiAppEvent_CreateConfig() 1291 1292``` 1293HiAppEvent_Config* OH_HiAppEvent_CreateConfig(void) 1294``` 1295 1296**Description** 1297 1298Creates a pointer to the configuration object that sets the conditions for triggering system events. 1299 1300**Since**: 15 1301 1302**Returns** 1303 1304| Type | Description| 1305|------------------------| -- | 1306| [HiAppEvent_Config](capi-hiappevent-hiappevent-config.md)* | Pointer to the configuration object that sets the conditions for triggering system events.| 1307 1308### OH_HiAppEvent_DestroyConfig() 1309 1310``` 1311void OH_HiAppEvent_DestroyConfig(HiAppEvent_Config* config) 1312``` 1313 1314**Description** 1315 1316Destroys a configuration object. Note: If a configuration object is no longer used, destroy it to release memory to prevent memory leaks. After the object is destroyed, set its pointer to null. 1317 1318**Since**: 15 1319 1320 1321**Parameters** 1322 1323| Name| Description| 1324| -- | -- | 1325| [HiAppEvent_Config](capi-hiappevent-hiappevent-config.md)* config | Pointer to the configuration object, that is, the pointer returned by the **OH_HiAppEvent_CreateConfig** API.| 1326 1327### OH_HiAppEvent_SetConfigItem() 1328 1329``` 1330int OH_HiAppEvent_SetConfigItem(HiAppEvent_Config* config, const char* itemName, const char* itemValue) 1331``` 1332 1333**Description** 1334 1335Sets the items in the configuration object. 1336 1337**Since**: 15 1338 1339 1340**Parameters** 1341 1342| Name| Description| 1343| -- | -- | 1344| [HiAppEvent_Config](capi-hiappevent-hiappevent-config.md)* config | Pointer to the configuration object, that is, the pointer returned by the **OH_HiAppEvent_CreateConfig** API.| 1345| const char* itemName | Name of the configuration item.| 1346| const char* itemValue | Value of the configuration item.| 1347 1348**Returns** 1349 1350| Type| Description| 1351| -- | -- | 1352| int | [HIAPPEVENT_SUCCESS](capi-hiappevent-h.md#hiappevent_errorcode): Operation successful.<br> [HIAPPEVENT_EVENT_CONFIG_IS_NULL](capi-hiappevent-h.md#hiappevent_errorcode): The input pointer to the configuration object is null.<br> [HIAPPEVENT_INVALID_PARAM_VALUE](capi-hiappevent-h.md#hiappevent_errorcode): Invalid configuration item.<br> For details, see [HiAppEvent_ErrorCode](capi-hiappevent-h.md#hiappevent_errorcode).| 1353 1354### OH_HiAppEvent_SetEventConfig() 1355 1356``` 1357int OH_HiAppEvent_SetEventConfig(const char* name, HiAppEvent_Config* config) 1358``` 1359 1360**Description** 1361 1362Sets the conditions for triggering system event subscription. 1363 1364**Since**: 15 1365 1366 1367**Parameters** 1368 1369| Name| Description| 1370| -- | -- | 1371| const char* name | Name of the system event.| 1372| [HiAppEvent_Config](capi-hiappevent-hiappevent-config.md)* config | Pointer to the configuration object, that is, the pointer returned by the **OH_HiAppEvent_CreateConfig** API.| 1373 1374**Returns** 1375 1376| Type| Description| 1377| -- | -- | 1378| int | [HIAPPEVENT_SUCCESS](capi-hiappevent-h.md#hiappevent_errorcode): Operation successful.<br> [HIAPPEVENT_INVALID_PARAM_VALUE](capi-hiappevent-h.md#hiappevent_errorcode): Invalid parameter.<br> For details, see [HiAppEvent_ErrorCode](capi-hiappevent-h.md#hiappevent_errorcode).| 1379