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## 概述 11 12HiAppEvent模块的应用事件打点函数定义。在执行应用事件打点之前，开发者必须先构造一个参数列表对象来存储输入的事件参数，并指定事件领域、事件名称和事件类型。<p>事件领域：用于标识事件打点的领域的字符串。<p>事件名称：用于标识事件打点的名称的字符串。<p>事件类型：故障、统计、安全、行为。<p>参数列表：用于存储事件参数的链表，每个参数由参数名和参数值组成。 13 14**引用文件：** <hiappevent/hiappevent.h> 15 16**库：** libhiappevent_ndk.z.so 17 18**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 19 20**起始版本：** 8 21 22**相关模块：** [HiAppEvent](capi-hiappevent.md) 23 24## 汇总 25 26### 结构体 27 28| 名称 | typedef关键字 | 描述 | 29| -- | -- | -- | 30| [HiAppEvent_AppEventInfo](capi-hiappevent-hiappevent-appeventinfo.md) | HiAppEvent_AppEventInfo | 单个事件信息，包含事件领域，事件名称，事件类型和json格式字符串表示的事件中携带的自定义参数列表。 | 31| [HiAppEvent_AppEventGroup](capi-hiappevent-hiappevent-appeventgroup.md) | HiAppEvent_AppEventGroup | 一组事件信息，包含事件组的名称，按名称分组的单个事件信息数组，事件数组的长度。 | 32| [ParamListNode*](capi-hiappevent-paramlistnode8h.md) | ParamList | 事件参数列表节点。 | 33| [HiAppEvent_Watcher](capi-hiappevent-hiappevent-watcher.md) | HiAppEvent_Watcher | 用于接收app事件的监听器。 | 34| [HiAppEvent_Processor](capi-hiappevent-hiappevent-processor.md) | HiAppEvent_Processor | 用于处理app事件上报的处理者。 | 35| [HiAppEvent_Config](capi-hiappevent-hiappevent-config.md) | HiAppEvent_Config | 用于设置系统事件触发条件的配置对象。 | 36 37### 枚举 38 39| 名称 | typedef关键字 | 描述 | 40| -- | -- | -- | 41| [HiAppEvent_ErrorCode](#hiappevent_errorcode) | HiAppEvent_ErrorCode | 错误码定义。 | 42| [EventType](#eventtype) | - | 事件类型。建议开发者根据不同的使用场景选择不同的事件类型。 | 43 44### 函数 45 46| 名称 | typedef关键字 | 描述 | 47| -- | -- | -- | 48| [typedef void (\*OH_HiAppEvent_OnReceive)(const char* domain, const struct HiAppEvent_AppEventGroup* appEventGroups, uint32_t groupLen)](#oh_hiappevent_onreceive) | OH_HiAppEvent_OnReceive | 监听器接收到事件后，将触发该回调，将事件内容传递给调用方。注意：回调中的指针所指对象的生命周期仅限于该回调函数内，请勿在该回调函数外直接使用该指针，若需缓存该信息，请对指针指向的内容进行深拷贝。 | 49| [typedef void (\*OH_HiAppEvent_OnTrigger)(int row, int size)](#oh_hiappevent_ontrigger) | OH_HiAppEvent_OnTrigger | 监听器收到事件后，若监听器中未设置OH_HiAppEvent_OnReceive回调，将保存该事件。<br> 当保存的事件满足通过OH_HiAppEvent_SetTriggerCondition设定的条件后，将触发该回调。回调结束后，当新保存的事件消息再次满足设定的条件后，将再次进行回调。 | 50| [typedef void (\*OH_HiAppEvent_OnTake)(const char* const *events, uint32_t eventLen)](#oh_hiappevent_ontake) | OH_HiAppEvent_OnTake | 使用OH_HiAppEvent_TakeWatcherData获取监听器接收到的事件时，监听器接收到的事件将通过该回调函数传递给调用者。注意：回调中的指针所指对象的生命周期仅限于该回调函数内，请勿在该回调函数外直接使用该指针。若需缓存该信息，请对指针指向的内容进行深拷贝。 | 51| [ParamList OH_HiAppEvent_CreateParamList(void)](#oh_hiappevent_createparamlist) | - | 创建一个指向参数列表对象的指针。 | 52| [void OH_HiAppEvent_DestroyParamList(ParamList list)](#oh_hiappevent_destroyparamlist) | - | 销毁一个指向参数列表对象的指针，释放其分配内存。 | 53| [ParamList OH_HiAppEvent_AddBoolParam(ParamList list, const char* name, bool boolean)](#oh_hiappevent_addboolparam) | - | 添加一个布尔参数到参数列表中。 | 54| [ParamList OH_HiAppEvent_AddBoolArrayParam(ParamList list, const char* name, const bool* booleans, int arrSize)](#oh_hiappevent_addboolarrayparam) | - | 添加一个布尔数组参数到参数列表中。 | 55| [ParamList OH_HiAppEvent_AddInt8Param(ParamList list, const char* name, int8_t num)](#oh_hiappevent_addint8param) | - | 添加一个int8_t参数到参数列表中。 | 56| [ParamList OH_HiAppEvent_AddInt8ArrayParam(ParamList list, const char* name, const int8_t* nums, int arrSize)](#oh_hiappevent_addint8arrayparam) | - | 添加一个int8_t数组参数到参数列表中。 | 57| [ParamList OH_HiAppEvent_AddInt16Param(ParamList list, const char* name, int16_t num)](#oh_hiappevent_addint16param) | - | 添加一个int16_t参数到参数列表中。 | 58| [ParamList OH_HiAppEvent_AddInt16ArrayParam(ParamList list, const char* name, const int16_t* nums, int arrSize)](#oh_hiappevent_addint16arrayparam) | - | 添加一个int16_t数组参数到参数列表中。 | 59| [ParamList OH_HiAppEvent_AddInt32Param(ParamList list, const char* name, int32_t num)](#oh_hiappevent_addint32param) | - | 添加一个int32_t参数到参数列表中。 | 60| [ParamList OH_HiAppEvent_AddInt32ArrayParam(ParamList list, const char* name, const int32_t* nums, int arrSize)](#oh_hiappevent_addint32arrayparam) | - | 添加一个int32_t数组参数到参数列表中。 | 61| [ParamList OH_HiAppEvent_AddInt64Param(ParamList list, const char* name, int64_t num)](#oh_hiappevent_addint64param) | - | 添加一个int64_t参数到参数列表中。 | 62| [ParamList OH_HiAppEvent_AddInt64ArrayParam(ParamList list, const char* name, const int64_t* nums, int arrSize)](#oh_hiappevent_addint64arrayparam) | - | 添加一个int64_t数组参数到参数列表中。 | 63| [ParamList OH_HiAppEvent_AddFloatParam(ParamList list, const char* name, float num)](#oh_hiappevent_addfloatparam) | - | 添加一个float参数到参数列表中。 | 64| [ParamList OH_HiAppEvent_AddFloatArrayParam(ParamList list, const char* name, const float* nums, int arrSize)](#oh_hiappevent_addfloatarrayparam) | - | 添加一个float数组参数到参数列表中。 | 65| [ParamList OH_HiAppEvent_AddDoubleParam(ParamList list, const char* name, double num)](#oh_hiappevent_adddoubleparam) | - | 添加一个double参数到参数列表中。 | 66| [ParamList OH_HiAppEvent_AddDoubleArrayParam(ParamList list, const char* name, const double* nums, int arrSize)](#oh_hiappevent_adddoublearrayparam) | - | 添加一个double数组参数到参数列表中。 | 67| [ParamList OH_HiAppEvent_AddStringParam(ParamList list, const char* name, const char* str)](#oh_hiappevent_addstringparam) | - | 添加一个字符串参数到参数列表中。 | 68| [ParamList OH_HiAppEvent_AddStringArrayParam(ParamList list, const char* name, const char * const *strs, int arrSize)](#oh_hiappevent_addstringarrayparam) | - | 添加一个字符串数组参数到参数列表中。 | 69| [int OH_HiAppEvent_Write(const char* domain, const char* name, enum EventType type, const ParamList list)](#oh_hiappevent_write) | - | 实现对参数为列表类型的应用事件打点。在应用事件打点前，该接口会先对该事件的参数进行校验。如果校验成功，则接口会将事件写入事件文件。 | 70| [bool OH_HiAppEvent_Configure(const char* name, const char* value)](#oh_hiappevent_configure) | - | 实现应用事件打点的配置功能。应用事件打点配置接口，用于配置事件打点开关、事件文件目录存储配额大小等功能。 | 71| [HiAppEvent_Watcher* OH_HiAppEvent_CreateWatcher(const char* name)](#oh_hiappevent_createwatcher) | - | 创建一个用于监听app事件的监听器。注意：创建的监听器不再使用后必须通过调用OH_HiAppEvent_DestroyWatcher接口进行销毁。 | 72| [void OH_HiAppEvent_DestroyWatcher(HiAppEvent_Watcher* watcher)](#oh_hiappevent_destroywatcher) | - | 销毁已创建的监听器。注意：已创建的监听器不再使用后，需要将其销毁，释放内存，防止内存泄漏，销毁后需将对应指针置空。 | 73| [int OH_HiAppEvent_SetTriggerCondition(HiAppEvent_Watcher* watcher, int row, int size, int timeOut)](#oh_hiappevent_settriggercondition) | - | 用于设置监听器OH_HiAppEvent_OnTrigger回调的触发条件。<br> 分别可以从监视器新接收事件数量、新接收事件大小、onTrigger触发超时时间，设置触发条件。调用方应至少保证从一个方面设置触发条件。 | 74| [int OH_HiAppEvent_SetAppEventFilter(HiAppEvent_Watcher* watcher, const char* domain, uint8_t eventTypes,const char* const *names, int namesLen)](#oh_hiappevent_setappeventfilter) | - | 用于设置监听器需要监听的事件的类型。该函数可以重复调用，可添加多个过滤规则，而非替换，监听器将收到满足任一过滤规则的事件的通知。 | 75| [int OH_HiAppEvent_SetWatcherOnTrigger(HiAppEvent_Watcher* watcher, OH_HiAppEvent_OnTrigger onTrigger)](#oh_hiappevent_setwatcherontrigger) | - | 用于设置监听器onTrigger回调的接口。<br> 如果未设置OnReceive回调或已将其设置为nullptr，则将保存观察者接收到的应用事件。当保存的应用事件满足onTrigger回调的触发条件时，将调用onTrigger回调。 | 76| [int OH_HiAppEvent_SetWatcherOnReceive(HiAppEvent_Watcher* watcher, OH_HiAppEvent_OnReceive onReceive)](#oh_hiappevent_setwatcheronreceive) | - | 用于设置监听器onReceive回调函数的接口。当监听器监听到相应事件后，onReceive回调函数将被调用。 | 77| [int OH_HiAppEvent_TakeWatcherData(HiAppEvent_Watcher* watcher, uint32_t eventNum, OH_HiAppEvent_OnTake onTake)](#oh_hiappevent_takewatcherdata) | - | 用于获取监听器收到后保存的事件。 | 78| [int OH_HiAppEvent_AddWatcher(HiAppEvent_Watcher* watcher)](#oh_hiappevent_addwatcher) | - | 添加监听器的接口，监听器开始监听系统消息。 | 79| [int OH_HiAppEvent_RemoveWatcher(HiAppEvent_Watcher* watcher)](#oh_hiappevent_removewatcher) | - | 移除监听器的接口，监听器停止监听系统消息。注意：该接口仅仅使监听器停止监听系统消息，并未销毁该监听器，该监听器依然常驻内存，直至调用OH_HiAppEvent_DestroyWatcher接口，内存才会释放。 | 80| [void OH_HiAppEvent_ClearData()](#oh_hiappevent_cleardata) | - | 清除所有监视器保存的所有事件。 | 81| [HiAppEvent_Processor* OH_HiAppEvent_CreateProcessor(const char* name)](#oh_hiappevent_createprocessor) | - | 创建一个用于处理app事件上报的处理者。注意：创建的处理者不再使用后必须通过调用OH_HiAppEvent_DestroyProcessor接口进行销毁。 | 82| [int OH_HiAppEvent_SetReportRoute(HiAppEvent_Processor* processor, const char* appId, const char* routeInfo)](#oh_hiappevent_setreportroute) | - | 设置处理者事件上报路由的接口。 | 83| [int OH_HiAppEvent_SetReportPolicy(HiAppEvent_Processor* processor, int periodReport, int batchReport,bool onStartReport, bool onBackgroundReport)](#oh_hiappevent_setreportpolicy) | - | 设置处理者事件上报策略的接口。 | 84| [int OH_HiAppEvent_SetReportEvent(HiAppEvent_Processor* processor, const char* domain, const char* name,bool isRealTime)](#oh_hiappevent_setreportevent) | - | 设置处理者上报事件的接口。 | 85| [int OH_HiAppEvent_SetCustomConfig(HiAppEvent_Processor* processor, const char* key, const char* value)](#oh_hiappevent_setcustomconfig) | - | 设置处理者自定义扩展参数的接口。 | 86| [int OH_HiAppEvent_SetConfigId(HiAppEvent_Processor* processor, int configId)](#oh_hiappevent_setconfigid) | - | 设置处理者配置id的接口。 | 87| [int OH_HiAppEvent_SetConfigName(HiAppEvent_Processor* processor, const char* configName)](#oh_hiappevent_setconfigname) | - | 设置处理者的配置名称的接口。 | 88| [int OH_HiAppEvent_SetReportUserId(HiAppEvent_Processor* processor, const char* const * userIdNames, int size)](#oh_hiappevent_setreportuserid) | - | 设置处理者用户ID的接口。 | 89| [int OH_HiAppEvent_SetReportUserProperty(HiAppEvent_Processor* processor, const char* const * userPropertyNames,int size)](#oh_hiappevent_setreportuserproperty) | - | 设置处理者用户属性的接口。 | 90| [int64_t OH_HiAppEvent_AddProcessor(HiAppEvent_Processor* processor)](#oh_hiappevent_addprocessor) | - | 添加数据处理者的接口。开发者可添加数据处理者，用于提供事件上云功能。数据处理者的实现可预置在设备中，开发者可根据数据处理者的约束设置属性。注意：Processor的配置信息需要由数据处理者提供，目前设备内暂未预置可供交互的数据处理者，因此当前事件上云功能不可用。 | 91| [void OH_HiAppEvent_DestroyProcessor(HiAppEvent_Processor* processor)](#oh_hiappevent_destroyprocessor) | - | 销毁已创建的数据处理者。注意：已创建的处理者不再使用后，需要将其销毁，释放内存，防止内存泄漏，销毁后需将对应指针置空。 | 92| [int OH_HiAppEvent_RemoveProcessor(int64_t processorId)](#oh_hiappevent_removeprocessor) | - | 移除数据处理者的接口，处理者停止上报事件。注意：该接口仅仅使处理者停止上报事件，并未销毁该处理者，该处理者依然常驻内存，直至调用OH_HiAppEvent_DestroyProcessor接口，内存才会释放。 | 93| [HiAppEvent_Config* OH_HiAppEvent_CreateConfig(void)](#oh_hiappevent_createconfig) | - | 创建一个指向设置系统事件触发条件的配置对象的指针。 | 94| [void OH_HiAppEvent_DestroyConfig(HiAppEvent_Config* config)](#oh_hiappevent_destroyconfig) | - | 销毁已创建的配置对象。注意：已创建的配置对象不再使用后，需要将其销毁，释放内存，防止内存泄漏，销毁后需要将对应指针置空。 | 95| [int OH_HiAppEvent_SetConfigItem(HiAppEvent_Config* config, const char* itemName, const char* itemValue)](#oh_hiappevent_setconfigitem) | - | 设置配置对象中的配置项。 | 96| [int OH_HiAppEvent_SetEventConfig(const char* name, HiAppEvent_Config* config)](#oh_hiappevent_seteventconfig) | - | 设定系统事件订阅触发条件。 | 97 98## 枚举类型说明 99 100### HiAppEvent_ErrorCode 101 102``` 103enum HiAppEvent_ErrorCode 104``` 105 106**描述** 107 108错误码定义。 109 110**起始版本：** 15 111 112| 枚举项 | 描述 | 113| -- | -- | 114| HIAPPEVENT_SUCCESS = 0 | 操作成功。 | 115| HIAPPEVENT_INVALID_PARAM_VALUE_LENGTH = 4 | 参数值长度无效。<br>**起始版本：** 18 | 116| HIAPPEVENT_PROCESSOR_IS_NULL = -7 | 事件处理者为空。<br>**起始版本：** 18 | 117| HIAPPEVENT_PROCESSOR_NOT_FOUND = -8 | 事件处理者不存在。<br>**起始版本：** 18 | 118| HIAPPEVENT_INVALID_PARAM_VALUE = -9 | 参数值无效。 | 119| HIAPPEVENT_EVENT_CONFIG_IS_NULL = -10 | 事件配置为空。 | 120| HIAPPEVENT_OPERATE_FAILED = -100 | 操作失败。<br>**起始版本：** 18 | 121| HIAPPEVENT_INVALID_UID = -200 | 无效的用户标识。<br>**起始版本：** 18 | 122 123### EventType 124 125``` 126enum EventType 127``` 128 129**描述** 130 131事件类型。建议开发者根据不同的使用场景选择不同的事件类型。 132 133**起始版本：** 8 134 135| 枚举项 | 描述 | 136| -- | -- | 137| FAULT = 1 | 故障事件类型。 | 138| STATISTIC = 2 | 统计事件类型。 | 139| SECURITY = 3 | 安全事件类型。 | 140| BEHAVIOR = 4 | 行为事件类型。 | 141 142 143## 函数说明 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**描述** 152 153监听器接收到事件后，将触发该回调，将事件内容传递给调用方。注意：回调中的指针所指对象的生命周期仅限于该回调函数内，请勿在该回调函数外直接使用该指针，若需缓存该信息，请对指针指向的内容进行深拷贝。 154 155**起始版本：** 12 156 157 158**参数：** 159 160| 参数项 | 描述 | 161| -- | -- | 162| const char* domain | 接收到的app事件的领域。 | 163| [ const struct HiAppEvent_AppEventGroup](capi-hiappevent-hiappevent-appeventgroup.md)* appEventGroups | 按照不同事件名称分组的事件组数组。 | 164| uint32_t groupLen | 事件组数组的长度。 | 165 166### OH_HiAppEvent_OnTrigger() 167 168``` 169typedef void (*OH_HiAppEvent_OnTrigger)(int row, int size) 170``` 171 172**描述** 173 174监听器收到事件后，若监听器中未设置OH_HiAppEvent_OnReceive回调，将保存该事件。<br> 当保存的事件满足通过OH_HiAppEvent_SetTriggerCondition设定的条件后，将触发该回调。回调结束后，当新保存的事件消息再次满足设定的条件后，将再次进行回调。 175 176**起始版本：** 12 177 178 179**参数：** 180 181| 参数项 | 描述 | 182| -- | -- | 183| int row | 监听器新接收到的事件消息的数量。 | 184| int size | 监听器新接收的事件消息的大小总和（单个事件大小计算方式为：将消息转换为json字符串后，字符串的长度）。 | 185 186### OH_HiAppEvent_OnTake() 187 188``` 189typedef void (*OH_HiAppEvent_OnTake)(const char* const *events, uint32_t eventLen) 190``` 191 192**描述** 193 194使用OH_HiAppEvent_TakeWatcherData获取监听器接收到的事件时，监听器接收到的事件将通过该回调函数传递给调用者。注意：回调中的指针所指对象的生命周期仅限于该回调函数内，请勿在该回调函数外直接使用该指针。若需缓存该信息，请对指针指向的内容进行深拷贝。 195 196**起始版本：** 12 197 198 199**参数：** 200 201| 参数项 | 描述 | 202| -- | -- | 203| const char* const *events | json字符串格式的事件数组。 | 204| uint32_t eventLen | 事件数组大小。 | 205 206### OH_HiAppEvent_CreateParamList() 207 208``` 209ParamList OH_HiAppEvent_CreateParamList(void) 210``` 211 212**描述** 213 214创建一个指向参数列表对象的指针。 215 216**起始版本：** 8 217 218**返回：** 219 220| 类型 | 说明 | 221| -- | -- | 222| [ParamList](capi-hiappevent-paramlistnode8h.md) | 指向参数列表对象的指针。 | 223 224### OH_HiAppEvent_DestroyParamList() 225 226``` 227void OH_HiAppEvent_DestroyParamList(ParamList list) 228``` 229 230**描述** 231 232销毁一个指向参数列表对象的指针，释放其分配内存。 233 234**起始版本：** 8 235 236 237**参数：** 238 239| 参数项 | 描述 | 240| -- | -- | 241| [ParamList](capi-hiappevent-paramlistnode8h.md) list | 参数列表对象指针。 | 242 243### OH_HiAppEvent_AddBoolParam() 244 245``` 246ParamList OH_HiAppEvent_AddBoolParam(ParamList list, const char* name, bool boolean) 247``` 248 249**描述** 250 251添加一个布尔参数到参数列表中。 252 253**起始版本：** 8 254 255 256**参数：** 257 258| 参数项 | 描述 | 259| -- | -- | 260| [ParamList](capi-hiappevent-paramlistnode8h.md) list | 需要添加参数的参数列表指针。 | 261| const char* name | 需要添加的参数名称。 | 262| bool boolean | 需要添加的布尔参数值。 | 263 264**返回：** 265 266| 类型 | 说明 | 267| -- | -- | 268| [ParamList](capi-hiappevent-paramlistnode8h.md) | 添加参数后的参数列表指针。 | 269 270### OH_HiAppEvent_AddBoolArrayParam() 271 272``` 273ParamList OH_HiAppEvent_AddBoolArrayParam(ParamList list, const char* name, const bool* booleans, int arrSize) 274``` 275 276**描述** 277 278添加一个布尔数组参数到参数列表中。 279 280**起始版本：** 8 281 282 283**参数：** 284 285| 参数项 | 描述 | 286| -- | -- | 287| [ParamList](capi-hiappevent-paramlistnode8h.md) list | 需要添加参数的参数列表指针。 | 288| const char* name | 需要添加的参数名称。 | 289| const bool* booleans | 需要添加的布尔数组参数值。 | 290| int arrSize | 需要添加的参数数组大小。 | 291 292**返回：** 293 294| 类型 | 说明 | 295| -- | -- | 296| [ParamList](capi-hiappevent-paramlistnode8h.md) | 添加参数后的参数列表指针。 | 297 298### OH_HiAppEvent_AddInt8Param() 299 300``` 301ParamList OH_HiAppEvent_AddInt8Param(ParamList list, const char* name, int8_t num) 302``` 303 304**描述** 305 306添加一个int8_t参数到参数列表中。 307 308**起始版本：** 8 309 310 311**参数：** 312 313| 参数项 | 描述 | 314| -- | -- | 315| [ParamList](capi-hiappevent-paramlistnode8h.md) list | 需要添加参数的参数列表指针。 | 316| const char* name | 需要添加的参数名称。 | 317| int8_t num | 需要添加的int8_t参数值。 | 318 319**返回：** 320 321| 类型 | 说明 | 322| -- | -- | 323| [ParamList](capi-hiappevent-paramlistnode8h.md) | 添加参数后的参数列表指针。 | 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**描述** 332 333添加一个int8_t数组参数到参数列表中。 334 335**起始版本：** 8 336 337 338**参数：** 339 340| 参数项 | 描述 | 341| -- | -- | 342| [ParamList](capi-hiappevent-paramlistnode8h.md) list | 需要添加参数的参数列表指针。 | 343| const char* name | 需要添加的参数名称。 | 344| const int8_t* nums | 需要添加的int8_t数组参数值。 | 345| int arrSize | 需要添加的参数数组大小。 | 346 347**返回：** 348 349| 类型 | 说明 | 350| -- | -- | 351| [ParamList](capi-hiappevent-paramlistnode8h.md) | 添加参数后的参数列表指针。 | 352 353### OH_HiAppEvent_AddInt16Param() 354 355``` 356ParamList OH_HiAppEvent_AddInt16Param(ParamList list, const char* name, int16_t num) 357``` 358 359**描述** 360 361添加一个int16_t参数到参数列表中。 362 363**起始版本：** 8 364 365 366**参数：** 367 368| 参数项 | 描述 | 369| -- | -- | 370| [ParamList](capi-hiappevent-paramlistnode8h.md) list | 需要添加参数的参数列表指针。 | 371| const char* name | 需要添加的参数名称。 | 372| int16_t num | 需要添加的int16_t参数值。 | 373 374**返回：** 375 376| 类型 | 说明 | 377| -- | -- | 378| [ParamList](capi-hiappevent-paramlistnode8h.md) | 添加参数后的参数列表指针。 | 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**描述** 387 388添加一个int16_t数组参数到参数列表中。 389 390**起始版本：** 8 391 392 393**参数：** 394 395| 参数项 | 描述 | 396| -- | -- | 397| [ParamList](capi-hiappevent-paramlistnode8h.md) list | 需要添加参数的参数列表指针。 | 398| const char* name | 需要添加的参数名称。 | 399| const int16_t* nums | 需要添加的int16_t数组参数值。 | 400| int arrSize | 需要添加的参数数组大小。 | 401 402**返回：** 403 404| 类型 | 说明 | 405| -- | -- | 406| [ParamList](capi-hiappevent-paramlistnode8h.md) | 添加参数后的参数列表指针。 | 407 408### OH_HiAppEvent_AddInt32Param() 409 410``` 411ParamList OH_HiAppEvent_AddInt32Param(ParamList list, const char* name, int32_t num) 412``` 413 414**描述** 415 416添加一个int32_t参数到参数列表中。 417 418**起始版本：** 8 419 420 421**参数：** 422 423| 参数项 | 描述 | 424| -- | -- | 425| [ParamList](capi-hiappevent-paramlistnode8h.md) list | 需要添加参数的参数列表指针。 | 426| const char* name | 需要添加的参数名称。 | 427| int32_t num | 需要添加的int32_t参数值。 | 428 429**返回：** 430 431| 类型 | 说明 | 432| -- | -- | 433| [ParamList](capi-hiappevent-paramlistnode8h.md) | 添加参数后的参数列表指针。 | 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**描述** 442 443添加一个int32_t数组参数到参数列表中。 444 445**起始版本：** 8 446 447 448**参数：** 449 450| 参数项 | 描述 | 451| -- | -- | 452| [ParamList](capi-hiappevent-paramlistnode8h.md) list | 需要添加参数的参数列表指针。 | 453| const char* name | 需要添加的参数名称。 | 454| const int32_t* nums | 需要添加的int32_t数组参数值。 | 455| int arrSize | 需要添加的参数数组大小。 | 456 457**返回：** 458 459| 类型 | 说明 | 460| -- | -- | 461| [ParamList](capi-hiappevent-paramlistnode8h.md) | 添加参数后的参数列表指针。 | 462 463### OH_HiAppEvent_AddInt64Param() 464 465``` 466ParamList OH_HiAppEvent_AddInt64Param(ParamList list, const char* name, int64_t num) 467``` 468 469**描述** 470 471添加一个int64_t参数到参数列表中。 472 473**起始版本：** 8 474 475 476**参数：** 477 478| 参数项 | 描述 | 479| -- | -- | 480| [ParamList](capi-hiappevent-paramlistnode8h.md) list | 需要添加参数的参数列表指针。 | 481| const char* name | 需要添加的参数名称。 | 482| int64_t num | 需要添加的int64_t参数值。 | 483 484**返回：** 485 486| 类型 | 说明 | 487| -- | -- | 488| [ParamList](capi-hiappevent-paramlistnode8h.md) | 添加参数后的参数列表指针。 | 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**描述** 497 498添加一个int64_t数组参数到参数列表中。 499 500**起始版本：** 8 501 502 503**参数：** 504 505| 参数项 | 描述 | 506| -- | -- | 507| [ParamList](capi-hiappevent-paramlistnode8h.md) list | 需要添加参数的参数列表指针。 | 508| const char* name | 需要添加的参数名称。 | 509| const int64_t* nums | 需要添加的int64_t数组参数值。 | 510| int arrSize | 需要添加的参数数组大小。 | 511 512**返回：** 513 514| 类型 | 说明 | 515| -- | -- | 516| [ParamList](capi-hiappevent-paramlistnode8h.md) | 添加参数后的参数列表指针。 | 517 518### OH_HiAppEvent_AddFloatParam() 519 520``` 521ParamList OH_HiAppEvent_AddFloatParam(ParamList list, const char* name, float num) 522``` 523 524**描述** 525 526添加一个float参数到参数列表中。 527 528**起始版本：** 8 529 530 531**参数：** 532 533| 参数项 | 描述 | 534| -- | -- | 535| [ParamList](capi-hiappevent-paramlistnode8h.md) list | 需要添加参数的参数列表指针。 | 536| const char* name | 需要添加的参数名称。 | 537| float num | 需要添加的float参数值。 | 538 539**返回：** 540 541| 类型 | 说明 | 542| -- | -- | 543| [ParamList](capi-hiappevent-paramlistnode8h.md) | 添加参数后的参数列表指针。 | 544 545### OH_HiAppEvent_AddFloatArrayParam() 546 547``` 548ParamList OH_HiAppEvent_AddFloatArrayParam(ParamList list, const char* name, const float* nums, int arrSize) 549``` 550 551**描述** 552 553添加一个float数组参数到参数列表中。 554 555**起始版本：** 8 556 557 558**参数：** 559 560| 参数项 | 描述 | 561| -- | -- | 562| [ParamList](capi-hiappevent-paramlistnode8h.md) list | 需要添加参数的参数列表指针。 | 563| const char* name | 需要添加的参数名称。 | 564| const float* nums | 需要添加的float数组参数值。 | 565| int arrSize | 需要添加的参数数组大小。 | 566 567**返回：** 568 569| 类型 | 说明 | 570| -- | -- | 571| [ParamList](capi-hiappevent-paramlistnode8h.md) | 添加参数后的参数列表指针。 | 572 573### OH_HiAppEvent_AddDoubleParam() 574 575``` 576ParamList OH_HiAppEvent_AddDoubleParam(ParamList list, const char* name, double num) 577``` 578 579**描述** 580 581添加一个double参数到参数列表中。 582 583**起始版本：** 8 584 585 586**参数：** 587 588| 参数项 | 描述 | 589| -- | -- | 590| [ParamList](capi-hiappevent-paramlistnode8h.md) list | 需要添加参数的参数列表指针。 | 591| const char* name | 需要添加的参数名称。 | 592| double num | 需要添加的double参数值。 | 593 594**返回：** 595 596| 类型 | 说明 | 597| -- | -- | 598| [ParamList](capi-hiappevent-paramlistnode8h.md) | 添加参数后的参数列表指针。 | 599 600### OH_HiAppEvent_AddDoubleArrayParam() 601 602``` 603ParamList OH_HiAppEvent_AddDoubleArrayParam(ParamList list, const char* name, const double* nums, int arrSize) 604``` 605 606**描述** 607 608添加一个double数组参数到参数列表中。 609 610**起始版本：** 8 611 612 613**参数：** 614 615| 参数项 | 描述 | 616| -- | -- | 617| [ParamList](capi-hiappevent-paramlistnode8h.md) list | 需要添加参数的参数列表指针。 | 618| const char* name | 需要添加的参数名称。 | 619| const double* nums | 需要添加的double数组参数值。 | 620| int arrSize | 需要添加的参数数组大小。 | 621 622**返回：** 623 624| 类型 | 说明 | 625| -- | -- | 626| [ParamList](capi-hiappevent-paramlistnode8h.md) | 添加参数后的参数列表指针。 | 627 628### OH_HiAppEvent_AddStringParam() 629 630``` 631ParamList OH_HiAppEvent_AddStringParam(ParamList list, const char* name, const char* str) 632``` 633 634**描述** 635 636添加一个字符串参数到参数列表中。 637 638**起始版本：** 8 639 640 641**参数：** 642 643| 参数项 | 描述 | 644| -- | -- | 645| [ParamList](capi-hiappevent-paramlistnode8h.md) list | 需要添加参数的参数列表指针。 | 646| const char* name | 需要添加的参数名称。 | 647| const char* str | 需要添加的字符串参数值。 | 648 649**返回：** 650 651| 类型 | 说明 | 652| -- | -- | 653| [ParamList](capi-hiappevent-paramlistnode8h.md) | 添加参数后的参数列表指针。 | 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**描述** 662 663添加一个字符串数组参数到参数列表中。 664 665**起始版本：** 8 666 667 668**参数：** 669 670| 参数项 | 描述 | 671| -- | -- | 672| [ParamList](capi-hiappevent-paramlistnode8h.md) list | 需要添加参数的参数列表指针。 | 673| const char* name | 需要添加的参数名称。 | 674| const char * const *strs | 需要添加的字符串数组参数值。 | 675| int arrSize | 需要添加的参数数组大小。 | 676 677**返回：** 678 679| 类型 | 说明 | 680| -- | -- | 681| [ParamList](capi-hiappevent-paramlistnode8h.md) | 添加参数后的参数列表指针。 | 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**描述** 690 691实现对参数为列表类型的应用事件打点。在应用事件打点前，该接口会先对该事件的参数进行校验。如果校验成功，则接口会将事件写入事件文件。 692 693**起始版本：** 8 694 695 696**参数：** 697 698| 参数项 | 描述 | 699| -- | -- | 700| const char* domain | 事件领域。开发者可以根据需要自定义事件领域。<br> 事件领域名称支持数字、字母、下划线字符，需要以字母开头且不能以下划线结尾，长度非空且不超过32个字符。 | 701| const char* name | 事件名称。开发者可以根据需要自定义事件名称。<br> 首字符必须为字母字符或$字符，中间字符必须为数字字符、字母字符或下划线字符，结尾字符必须为数字字符或字母字符，长度非空且不超过48个字符。 | 702| enum [EventType](capi-hiappevent-h.md#eventtype) type | 事件类型，在[EventType](capi-hiappevent-h.md#eventtype)中定义。 | 703| [const ParamList](capi-hiappevent-paramlistnode8h.md) list | 事件参数列表，每个参数由参数名和参数值组成，其规格定义如下：<br> 1、参数名为字符串类型。<br> 首字符必须为字母字符或$字符，中间字符必须为数字字符、字母字符或下划线字符，结尾字符必须为数字字符或字母字符，长度非空且不超过32个字符。<br> 2、参数值支持字符串、数值、布尔、数组类型。字符串类型参数长度需在8*1024个字符以内，超出会做丢弃处理；<br> 数组类型参数中的元素类型只能为字符串、数值、布尔中的一种，且元素个数需在100以内，超出会做丢弃处理。<br> 3、参数个数需在32个以内，超出的参数会做丢弃处理。 | 704 705**返回：** 706 707| 类型 | 说明 | 708| -- | -- | 709| int | 如果事件参数校验成功，则返回0，将事件写入事件文件；<br> 如果事件中存在无效参数，则返回正值，丢弃无效参数后将事件写入事件文件；<br> 如果事件参数校验失败，则返回负值，并且事件将不会写入事件文件。<br> 0 事件参数校验成功。<br> -1 非法的事件名称。<br> -4 非法的事件领域名称。<br> -99 打点功能被关闭。<br> 1 非法的事件参数名称。<br> 4 非法的事件参数字符串长度。<br> 5 非法的事件参数数量。<br> 6 非法的事件参数数组长度。<br> 8 重复的事件参数名称。 | 710 711### OH_HiAppEvent_Configure() 712 713``` 714bool OH_HiAppEvent_Configure(const char* name, const char* value) 715``` 716 717**描述** 718 719实现应用事件打点的配置功能。应用事件打点配置接口，用于配置事件打点开关、事件文件目录存储配额大小等功能。 720 721**起始版本：** 8 722 723 724**参数：** 725 726| 参数项 | 描述 | 727| -- | -- | 728| const char* name | 配置项名称。名称可填[DISABLE](capi-hiappevent-cfg-h.md#disable)和[MAX_STORAGE](capi-hiappevent-cfg-h.md#max_storage)。 | 729| const char* value | 配置项值。如果配置项名称是[DISABLE](capi-hiappevent-cfg-h.md#disable)，值可以填“true”或者“false”；<br> 如果配置项名称是[MAX_STORAGE](capi-hiappevent-cfg-h.md#max_storage)，配额值字符串只由数字字符和大小单位字符（单位字符支持[b\|k\|kb\|m\|mb\|g\|gb\|t\|tb]，不区分大小写）构成。<br> 配额值字符串必须以数字开头，后面可以选择不传单位字符（默认使用byte作为单位），或者以单位字符结尾。 | 730 731**返回：** 732 733| 类型 | 说明 | 734| -- | -- | 735| bool | 配置结果。如果配置成功，则返回true；如果配置失败则返回false。 | 736 737### OH_HiAppEvent_CreateWatcher() 738 739``` 740HiAppEvent_Watcher* OH_HiAppEvent_CreateWatcher(const char* name) 741``` 742 743**描述** 744 745创建一个用于监听app事件的监听器。注意：创建的监听器不再使用后必须通过调用OH_HiAppEvent_DestroyWatcher接口进行销毁。 746 747**起始版本：** 12 748 749 750**参数：** 751 752| 参数项 | 描述 | 753| -- | -- | 754| const char* name | 监听器名称。 | 755 756**返回：** 757 758| 类型 | 说明 | 759| -- | -- | 760| [HiAppEvent_Watcher](capi-hiappevent-hiappevent-watcher.md)* | 接口调用成功时返回指向的新建监听器的指针，name参数异常时返回nullptr。 | 761 762### OH_HiAppEvent_DestroyWatcher() 763 764``` 765void OH_HiAppEvent_DestroyWatcher(HiAppEvent_Watcher* watcher) 766``` 767 768**描述** 769 770销毁已创建的监听器。注意：已创建的监听器不再使用后，需要将其销毁，释放内存，防止内存泄漏，销毁后需将对应指针置空。 771 772**起始版本：** 12 773 774 775**参数：** 776 777| 参数项 | 描述 | 778| -- | -- | 779| [HiAppEvent_Watcher](capi-hiappevent-hiappevent-watcher.md)* watcher | 指向监听器的指针（即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**描述** 788 789用于设置监听器OH_HiAppEvent_OnTrigger回调的触发条件。<br> 分别可以从监视器新接收事件数量、新接收事件大小、onTrigger触发超时时间，设置触发条件。调用方应至少保证从一个方面设置触发条件。 790 791**起始版本：** 12 792 793 794**参数：** 795 796| 参数项 | 描述 | 797| -- | -- | 798| [HiAppEvent_Watcher](capi-hiappevent-hiappevent-watcher.md)* watcher | 指向监听器的指针（即OH_HiAppEvent_CreateWatcher接口返回的指针）。 | 799| int row | 当输入值大于0，且新接收事件的数量大于等于该值时，将调用设置的onTrigger回调函数；<br> 当输入值小于等于0时，不再以接收数量多少为维度来触发onTrigger回调。 | 800| int size | 当输入值大于0，且新接收事件的大小(单个事件大小计算方式为，将事件转换为json字符串后，字符串的长度)大于等于该值时，将调用设置的onTrigger回调函数；<br> 当输入值小于等于0时，不再以新接收事件大小为维度触发onTrigger回调。 | 801| int timeOut | 单位秒，当输入值大于0，每经过timeout秒，将检查监视器是否存在新接收到的事件，如果存在将触发onTrigger回调。<br> 触发onTrigger后，经过timeOut秒后将再次检查是否存在新接收到的事件。<br> 当输入值小于等于0，不以超时时间为维度触发onTrigger回调。 | 802 803**返回：** 804 805| 类型 | 说明 | 806| -- | -- | 807| int | 0：接口调用成功；-5：watcher入参空指针。 | 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**描述** 816 817用于设置监听器需要监听的事件的类型。该函数可以重复调用，可添加多个过滤规则，而非替换，监听器将收到满足任一过滤规则的事件的通知。 818 819**起始版本：** 12 820 821 822**参数：** 823 824| 参数项 | 描述 | 825| -- | -- | 826| [HiAppEvent_Watcher](capi-hiappevent-hiappevent-watcher.md)* watcher | 指向监听器的指针（即OH_HiAppEvent_CreateWatcher接口返回的指针）。 | 827| const char* domain | 需要监听事件的领域。 | 828| uint8_t eventTypes | 需要监听事件的事件类型。使用按位与方式进行匹配，可支持监听多种类型的事件。第一位为1（数值为1）表示支持监听故障类型的事件；<br> 第二位为1（数值为2）表示支持监听统计类型的事件；<br> 第三位为1（数值为4）表示支持监听安全类型的事件；<br> 第四位为1（数值为8）表示支持监听行为类型的事件。<br> 都为1（数值为15）或者都为0（数值为0）表示支持所有类型事件。 | 829| const char* const *names | 需要监听的事件名称数组。 | 830| int namesLen | 监听的事件名称的数组长度。 | 831 832**返回：** 833 834| 类型 | 说明 | 835| -- | -- | 836| int | 0：接口调用成功；-1：names参数异常；-4：domain参数异常；-5：watcher入参空指针。 | 837 838### OH_HiAppEvent_SetWatcherOnTrigger() 839 840``` 841int OH_HiAppEvent_SetWatcherOnTrigger(HiAppEvent_Watcher* watcher, OH_HiAppEvent_OnTrigger onTrigger) 842``` 843 844**描述** 845 846用于设置监听器onTrigger回调的接口。<br> 如果未设置OnReceive回调或已将其设置为nullptr，则将保存观察者接收到的应用事件。当保存的应用事件满足onTrigger回调的触发条件时，将调用onTrigger回调。 847 848**起始版本：** 12 849 850 851**参数：** 852 853| 参数项 | 描述 | 854| -- | -- | 855| [HiAppEvent_Watcher](capi-hiappevent-hiappevent-watcher.md)* watcher | 指向监听器的指针（即OH_HiAppEvent_CreateWatcher接口返回的指针）。 | 856| [OH_HiAppEvent_OnTrigger](capi-hiappevent-h.md#oh_hiappevent_ontrigger) onTrigger | 需要设置的回调。 | 857 858**返回：** 859 860| 类型 | 说明 | 861| -- | -- | 862| int | 0：接口调用成功；-5：watcher入参空指针。 | 863 864### OH_HiAppEvent_SetWatcherOnReceive() 865 866``` 867int OH_HiAppEvent_SetWatcherOnReceive(HiAppEvent_Watcher* watcher, OH_HiAppEvent_OnReceive onReceive) 868``` 869 870**描述** 871 872用于设置监听器onReceive回调函数的接口。当监听器监听到相应事件后，onReceive回调函数将被调用。 873 874**起始版本：** 12 875 876 877**参数：** 878 879| 参数项 | 描述 | 880| -- | -- | 881| [HiAppEvent_Watcher](capi-hiappevent-hiappevent-watcher.md)* watcher | 指向监听器的指针（即OH_HiAppEvent_CreateWatcher接口返回的指针）。 | 882| [OH_HiAppEvent_OnReceive](capi-hiappevent-h.md#oh_hiappevent_onreceive) onReceive | 回调函数的函数指针。 | 883 884**返回：** 885 886| 类型 | 说明 | 887| -- | -- | 888| int | 0：接口调用成功；-5：watcher入参空指针。 | 889 890### OH_HiAppEvent_TakeWatcherData() 891 892``` 893int OH_HiAppEvent_TakeWatcherData(HiAppEvent_Watcher* watcher, uint32_t eventNum, OH_HiAppEvent_OnTake onTake) 894``` 895 896**描述** 897 898用于获取监听器收到后保存的事件。 899 900**起始版本：** 12 901 902 903**参数：** 904 905| 参数项 | 描述 | 906| -- | -- | 907| [HiAppEvent_Watcher](capi-hiappevent-hiappevent-watcher.md)* watcher | 指向监听器的指针（即OH_HiAppEvent_CreateWatcher接口返回的指针）。 | 908| uint32_t eventNum | 当输入值小于等于0时，取全部已保存事件；当输入值大于0时，按照事件发生时间倒序排列，取指定数量的已保存事件。 | 909| [OH_HiAppEvent_OnTake](capi-hiappevent-h.md#oh_hiappevent_ontake) onTake | 回调函数指针，事件通过调用该函数返回事件信息。 | 910 911**返回：** 912 913| 类型 | 说明 | 914| -- | -- | 915| int | 0：接口调用成功；-5：watcher入参空指针；-6：还未调用OH_HiAppEvent_AddWatcher，操作顺序有误。 | 916 917### OH_HiAppEvent_AddWatcher() 918 919``` 920int OH_HiAppEvent_AddWatcher(HiAppEvent_Watcher* watcher) 921``` 922 923**描述** 924 925添加监听器的接口，监听器开始监听系统消息。 926 927**起始版本：** 12 928 929 930**参数：** 931 932| 参数项 | 描述 | 933| -- | -- | 934| [HiAppEvent_Watcher](capi-hiappevent-hiappevent-watcher.md)* watcher | 指向监听器的指针（即OH_HiAppEvent_CreateWatcher接口返回的指针）。 | 935 936**返回：** 937 938| 类型 | 说明 | 939| -- | -- | 940| int | 0：接口调用成功；-5：watcher入参空指针。 | 941 942### OH_HiAppEvent_RemoveWatcher() 943 944``` 945int OH_HiAppEvent_RemoveWatcher(HiAppEvent_Watcher* watcher) 946``` 947 948**描述** 949 950移除监听器的接口，监听器停止监听系统消息。注意：该接口仅仅使监听器停止监听系统消息，并未销毁该监听器，该监听器依然常驻内存，直至调用OH_HiAppEvent_DestroyWatcher接口，内存才会释放。 951 952**起始版本：** 12 953 954 955**参数：** 956 957| 参数项 | 描述 | 958| -- | -- | 959| [HiAppEvent_Watcher](capi-hiappevent-hiappevent-watcher.md)* watcher | 指向监听器的指针（即OH_HiAppEvent_CreateWatcher接口返回的指针）。 | 960 961**返回：** 962 963| 类型 | 说明 | 964| -- | -- | 965| int | 0：接口调用成功；-5：watcher入参空指针；-6：还未调用OH_HiAppEvent_AddWatcher，操作顺序有误。 | 966 967### OH_HiAppEvent_ClearData() 968 969``` 970void OH_HiAppEvent_ClearData() 971``` 972 973**描述** 974 975清除所有监视器保存的所有事件。 976 977**起始版本：** 12 978 979### OH_HiAppEvent_CreateProcessor() 980 981``` 982HiAppEvent_Processor* OH_HiAppEvent_CreateProcessor(const char* name) 983``` 984 985**描述** 986 987创建一个用于处理app事件上报的处理者。注意：创建的处理者不再使用后必须通过调用OH_HiAppEvent_DestroyProcessor接口进行销毁。 988 989**起始版本：** 18 990 991 992**参数：** 993 994| 参数项 | 描述 | 995| -- | -- | 996| const char* name | 处理者名称。只能包含大小写字母、数字、下划线和$，不能以数字开头，长度非空且不超过256个字符。 | 997 998**返回：** 999 1000| 类型 | 说明 | 1001| -- | -- | 1002| [HiAppEvent_Processor](capi-hiappevent-hiappevent-processor.md)* | 接口调用成功时返回指向的新建处理者的指针，name参数异常时返回nullptr。 | 1003 1004### OH_HiAppEvent_SetReportRoute() 1005 1006``` 1007int OH_HiAppEvent_SetReportRoute(HiAppEvent_Processor* processor, const char* appId, const char* routeInfo) 1008``` 1009 1010**描述** 1011 1012设置处理者事件上报路由的接口。 1013 1014**起始版本：** 18 1015 1016 1017**参数：** 1018 1019| 参数项 | 描述 | 1020| -- | -- | 1021| [HiAppEvent_Processor](capi-hiappevent-hiappevent-processor.md)* processor | 指向处理者的指针（即OH_HiAppEvent_CreateProcessor接口返回的指针）。 | 1022| const char* appId | 处理者的应用ID。 | 1023| const char* routeInfo | 服务器位置信息，默认为空字符串。传入字符串长度不能超8KB，超过时会被置为默认值。 | 1024 1025**返回：** 1026 1027| 类型 | 说明 | 1028| -- | -- | 1029| int | [HIAPPEVENT_SUCCESS](capi-hiappevent-h.md#hiappevent_errorcode)：接口调用成功；<br> [HIAPPEVENT_PROCESSOR_IS_NULL](capi-hiappevent-h.md#hiappevent_errorcode)：processor入参为空；<br> [HIAPPEVENT_INVALID_PARAM_VALUE](capi-hiappevent-h.md#hiappevent_errorcode)：参数值无效；<br> [HIAPPEVENT_INVALID_UID](capi-hiappevent-h.md#hiappevent_errorcode)：用户标识无效；<br> [HIAPPEVENT_INVALID_PARAM_VALUE_LENGTH](capi-hiappevent-h.md#hiappevent_errorcode)：参数值长度无效。<br> 具体可参考[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**描述** 1038 1039设置处理者事件上报策略的接口。 1040 1041**起始版本：** 18 1042 1043 1044**参数：** 1045 1046| 参数项 | 描述 | 1047| -- | -- | 1048| [HiAppEvent_Processor](capi-hiappevent-hiappevent-processor.md)* processor | 指向处理者的指针（即OH_HiAppEvent_CreateProcessor接口返回的指针）。 | 1049| int periodReport | 事件定时上报周期，单位为秒。 | 1050| int batchReport | 事件上报阈值，当事件条数达到阈值时上报事件。 | 1051| bool onStartReport | 数据处理者在启动时是否上报事件，默认值为false。 | 1052| bool onBackgroundReport | 应用程序进入后台时，是否上报事件，默认值为false。 | 1053 1054**返回：** 1055 1056| 类型 | 说明 | 1057| -- | -- | 1058| int | [HIAPPEVENT_SUCCESS](capi-hiappevent-h.md#hiappevent_errorcode)：接口调用成功；<br> [HIAPPEVENT_PROCESSOR_IS_NULL](capi-hiappevent-h.md#hiappevent_errorcode)：processor入参为空；<br> [HIAPPEVENT_INVALID_PARAM_VALUE](capi-hiappevent-h.md#hiappevent_errorcode)：参数值无效；<br> [HIAPPEVENT_INVALID_UID](capi-hiappevent-h.md#hiappevent_errorcode)：用户标识无效。<br> 具体可参考[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**描述** 1067 1068设置处理者上报事件的接口。 1069 1070**起始版本：** 18 1071 1072 1073**参数：** 1074 1075| 参数项 | 描述 | 1076| -- | -- | 1077| [HiAppEvent_Processor](capi-hiappevent-hiappevent-processor.md)* processor | 指向处理者的指针（即OH_HiAppEvent_CreateProcessor接口返回的指针）。 | 1078| const char* domain | 上报事件的领域。 | 1079| const char* name | 上报事件的名称。 | 1080| bool isRealTime | 是否实时上报。 | 1081 1082**返回：** 1083 1084| 类型 | 说明 | 1085| -- | -- | 1086| int | [HIAPPEVENT_SUCCESS](capi-hiappevent-h.md#hiappevent_errorcode)：接口调用成功；<br> [HIAPPEVENT_PROCESSOR_IS_NULL](capi-hiappevent-h.md#hiappevent_errorcode)：processor入参为空；<br> [HIAPPEVENT_INVALID_PARAM_VALUE](capi-hiappevent-h.md#hiappevent_errorcode)：参数值无效；<br> [HIAPPEVENT_INVALID_UID](capi-hiappevent-h.md#hiappevent_errorcode)：用户标识无效。<br> 具体可参考[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**描述** 1095 1096设置处理者自定义扩展参数的接口。 1097 1098**起始版本：** 18 1099 1100 1101**参数：** 1102 1103| 参数项 | 描述 | 1104| -- | -- | 1105| [HiAppEvent_Processor](capi-hiappevent-hiappevent-processor.md)* processor | 指向处理者的指针（即OH_HiAppEvent_CreateProcessor接口返回的指针）。 | 1106| const char* key | 参数名，长度不超过32个字符。 | 1107| const char* value | 参数值，长度不超过1024个字符。 | 1108 1109**返回：** 1110 1111| 类型 | 说明 | 1112| -- | -- | 1113| int | [HIAPPEVENT_SUCCESS](capi-hiappevent-h.md#hiappevent_errorcode)：接口调用成功；<br> [HIAPPEVENT_PROCESSOR_IS_NULL](capi-hiappevent-h.md#hiappevent_errorcode)：processor入参为空；<br> [HIAPPEVENT_INVALID_PARAM_VALUE](capi-hiappevent-h.md#hiappevent_errorcode)：参数值无效；<br> [HIAPPEVENT_INVALID_UID](capi-hiappevent-h.md#hiappevent_errorcode)：用户标识无效；<br> [HIAPPEVENT_INVALID_PARAM_VALUE_LENGTH](capi-hiappevent-h.md#hiappevent_errorcode)：参数值长度无效。<br> 具体可参考[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**描述** 1122 1123设置处理者配置id的接口。 1124 1125**起始版本：** 18 1126 1127 1128**参数：** 1129 1130| 参数项 | 描述 | 1131| -- | -- | 1132| [HiAppEvent_Processor](capi-hiappevent-hiappevent-processor.md)* processor | 指向处理者的指针（即OH_HiAppEvent_CreateProcessor接口返回的指针）。 | 1133| int configId | 数据处理者配置id，自然数。 | 1134 1135**返回：** 1136 1137| 类型 | 说明 | 1138| -- | -- | 1139| int | [HIAPPEVENT_SUCCESS](capi-hiappevent-h.md#hiappevent_errorcode)：接口调用成功；<br> [HIAPPEVENT_PROCESSOR_IS_NULL](capi-hiappevent-h.md#hiappevent_errorcode)：processor入参为空；<br> [HIAPPEVENT_INVALID_PARAM_VALUE](capi-hiappevent-h.md#hiappevent_errorcode)：参数值无效；<br> [HIAPPEVENT_INVALID_UID](capi-hiappevent-h.md#hiappevent_errorcode)：用户标识无效。<br> 具体可参考[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**描述** 1148 1149设置处理者的配置名称的接口。 1150 1151**起始版本：** 20 1152 1153 1154**参数：** 1155 1156| 参数项 | 描述 | 1157| -- | -- | 1158| [HiAppEvent_Processor](capi-hiappevent-hiappevent-processor.md)* processor | 指向处理者的指针（即OH_HiAppEvent_CreateProcessor接口返回的指针）。 | 1159| const char* configName | 数据处理者的配置名称。只能包含大小写字母、数字、下划线和$，不能以数字开头，长度非空且不超过256个字符。 | 1160 1161**返回：** 1162 1163| 类型 | 说明 | 1164| -- | -- | 1165| int | [HIAPPEVENT_SUCCESS](capi-hiappevent-h.md#hiappevent_errorcode)：接口调用成功；<br> [HIAPPEVENT_PROCESSOR_IS_NULL](capi-hiappevent-h.md#hiappevent_errorcode)：processor入参为空；<br> [HIAPPEVENT_INVALID_PARAM_VALUE](capi-hiappevent-h.md#hiappevent_errorcode)：参数值无效；<br> [HIAPPEVENT_INVALID_UID](capi-hiappevent-h.md#hiappevent_errorcode)：用户标识无效。<br> [HIAPPEVENT_INVALID_PARAM_VALUE_LENGTH](capi-hiappevent-h.md#hiappevent_errorcode)：参数值长度无效。<br> 具体可参考[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**描述** 1174 1175设置处理者用户ID的接口。 1176 1177**起始版本：** 18 1178 1179 1180**参数：** 1181 1182| 参数项 | 描述 | 1183| -- | -- | 1184| [HiAppEvent_Processor](capi-hiappevent-hiappevent-processor.md)* processor | 指向处理者的指针（即OH_HiAppEvent_CreateProcessor接口返回的指针）。 | 1185| const char* const * userIdNames | 处理者可以上报的用户ID的name数组。 | 1186| int size | 用户ID的name数组长度。 | 1187 1188**返回：** 1189 1190| 类型 | 说明 | 1191| -- | -- | 1192| int | [HIAPPEVENT_SUCCESS](capi-hiappevent-h.md#hiappevent_errorcode)：接口调用成功；<br> [HIAPPEVENT_PROCESSOR_IS_NULL](capi-hiappevent-h.md#hiappevent_errorcode)：processor入参为空；<br> [HIAPPEVENT_INVALID_PARAM_VALUE](capi-hiappevent-h.md#hiappevent_errorcode)：参数值无效；<br> [HIAPPEVENT_INVALID_UID](capi-hiappevent-h.md#hiappevent_errorcode)：用户标识无效；<br> [HIAPPEVENT_INVALID_PARAM_VALUE_LENGTH](capi-hiappevent-h.md#hiappevent_errorcode)：参数值长度无效。<br> 具体可参考[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**描述** 1201 1202设置处理者用户属性的接口。 1203 1204**起始版本：** 18 1205 1206 1207**参数：** 1208 1209| 参数项 | 描述 | 1210| -- | -- | 1211| [HiAppEvent_Processor](capi-hiappevent-hiappevent-processor.md)* processor | 指向处理者的指针（即OH_HiAppEvent_CreateProcessor接口返回的指针）。 | 1212| const char* const * userPropertyNames | 处理者可以上报的用户属性数组。 | 1213| int size | 用户属性数组的长度。 | 1214 1215**返回：** 1216 1217| 类型 | 说明 | 1218| -- | -- | 1219| int | [HIAPPEVENT_SUCCESS](capi-hiappevent-h.md#hiappevent_errorcode)：接口调用成功；<br> [HIAPPEVENT_PROCESSOR_IS_NULL](capi-hiappevent-h.md#hiappevent_errorcode)：processor入参为空；<br> [HIAPPEVENT_INVALID_PARAM_VALUE](capi-hiappevent-h.md#hiappevent_errorcode)：参数值无效；<br> [HIAPPEVENT_INVALID_UID](capi-hiappevent-h.md#hiappevent_errorcode)：用户标识无效；<br> [HIAPPEVENT_INVALID_PARAM_VALUE_LENGTH](capi-hiappevent-h.md#hiappevent_errorcode)：参数值长度无效。<br> 具体可参考[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**描述** 1228 1229添加数据处理者的接口。开发者可添加数据处理者，用于提供事件上云功能。数据处理者的实现可预置在设备中，开发者可根据数据处理者的约束设置属性。注意：Processor的配置信息需要由数据处理者提供，目前设备内暂未预置可供交互的数据处理者，因此当前事件上云功能不可用。 1230 1231**起始版本：** 18 1232 1233 1234**参数：** 1235 1236| 参数项 | 描述 | 1237| -- | -- | 1238| [HiAppEvent_Processor](capi-hiappevent-hiappevent-processor.md)* processor | 指向处理者的指针（即OH_HiAppEvent_CreateProcessor接口返回的指针）。 | 1239 1240**返回：** 1241 1242| 类型 | 说明 | 1243| -- | -- | 1244| int64_t | 调用成功时返回处理者唯一ID，大于0；<br> [HIAPPEVENT_PROCESSOR_IS_NULL](capi-hiappevent-h.md#hiappevent_errorcode)：processor入参为空；<br> [HIAPPEVENT_INVALID_PARAM_VALUE](capi-hiappevent-h.md#hiappevent_errorcode)：参数值无效；<br> [HIAPPEVENT_OPERATE_FAILED](capi-hiappevent-h.md#hiappevent_errorcode)：数据处理者名称未找到或注册失败；<br> [HIAPPEVENT_INVALID_UID](capi-hiappevent-h.md#hiappevent_errorcode)：用户标识无效。<br> 具体可参考[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**描述** 1253 1254销毁已创建的数据处理者。注意：已创建的处理者不再使用后，需要将其销毁，释放内存，防止内存泄漏，销毁后需将对应指针置空。 1255 1256**起始版本：** 18 1257 1258 1259**参数：** 1260 1261| 参数项 | 描述 | 1262| -- | -- | 1263| [HiAppEvent_Processor](capi-hiappevent-hiappevent-processor.md)* processor | 指向处理者的指针（即OH_HiAppEvent_CreateProcessor接口返回的指针）。 | 1264 1265### OH_HiAppEvent_RemoveProcessor() 1266 1267``` 1268int OH_HiAppEvent_RemoveProcessor(int64_t processorId) 1269``` 1270 1271**描述** 1272 1273移除数据处理者的接口，处理者停止上报事件。注意：该接口仅仅使处理者停止上报事件，并未销毁该处理者，该处理者依然常驻内存，直至调用OH_HiAppEvent_DestroyProcessor接口，内存才会释放。 1274 1275**起始版本：** 18 1276 1277 1278**参数：** 1279 1280| 参数项 | 描述 | 1281| -- | -- | 1282| int64_t processorId | 处理者唯一ID。 | 1283 1284**返回：** 1285 1286| 类型 | 说明 | 1287| -- | -- | 1288| int | [HIAPPEVENT_SUCCESS](capi-hiappevent-h.md#hiappevent_errorcode)：接口调用成功；<br> [HIAPPEVENT_PROCESSOR_NOT_FOUND](capi-hiappevent-h.md#hiappevent_errorcode)：事件处理者不存在；<br> [HIAPPEVENT_OPERATE_FAILED](capi-hiappevent-h.md#hiappevent_errorcode)：操作失败；<br> [HIAPPEVENT_INVALID_UID](capi-hiappevent-h.md#hiappevent_errorcode)：用户标识无效。<br> 具体可参考[HiAppEvent_ErrorCode](capi-hiappevent-h.md#hiappevent_errorcode)。 | 1289 1290### OH_HiAppEvent_CreateConfig() 1291 1292``` 1293HiAppEvent_Config* OH_HiAppEvent_CreateConfig(void) 1294``` 1295 1296**描述** 1297 1298创建一个指向设置系统事件触发条件的配置对象的指针。 1299 1300**起始版本：** 15 1301 1302**返回：** 1303 1304| 类型 | 说明 | 1305| -- | -- | 1306| [HiAppEvent_Config](capi-hiappevent-hiappevent-config.md)* | 指向设置系统事件触发条件的配置对象的指针。 | 1307 1308### OH_HiAppEvent_DestroyConfig() 1309 1310``` 1311void OH_HiAppEvent_DestroyConfig(HiAppEvent_Config* config) 1312``` 1313 1314**描述** 1315 1316销毁已创建的配置对象。注意：已创建的配置对象不再使用后，需要将其销毁，释放内存，防止内存泄漏，销毁后需要将对应指针置空。 1317 1318**起始版本：** 15 1319 1320 1321**参数：** 1322 1323| 参数项 | 描述 | 1324| -- | -- | 1325| [HiAppEvent_Config](capi-hiappevent-hiappevent-config.md)* config | 指向配置对象的指针（即OH_HiAppEvent_CreateConfig接口返回的指针）。 | 1326 1327### OH_HiAppEvent_SetConfigItem() 1328 1329``` 1330int OH_HiAppEvent_SetConfigItem(HiAppEvent_Config* config, const char* itemName, const char* itemValue) 1331``` 1332 1333**描述** 1334 1335设置配置对象中的配置项。 1336 1337**起始版本：** 15 1338 1339 1340**参数：** 1341 1342| 参数项 | 描述 | 1343| -- | -- | 1344| [HiAppEvent_Config](capi-hiappevent-hiappevent-config.md)* config | 指向配置对象的指针（即OH_HiAppEvent_CreateConfig接口返回的指针）。 | 1345| const char* itemName | 待设定配置项的名称。 | 1346| const char* itemValue | 待设定配置项的值。 | 1347 1348**返回：** 1349 1350| 类型 | 说明 | 1351| -- | -- | 1352| int | [HIAPPEVENT_SUCCESS](capi-hiappevent-h.md#hiappevent_errorcode)：接口调用成功；<br> [HIAPPEVENT_EVENT_CONFIG_IS_NULL](capi-hiappevent-h.md#hiappevent_errorcode)：传入的指向配置对象的指针为空；<br> [HIAPPEVENT_INVALID_PARAM_VALUE](capi-hiappevent-h.md#hiappevent_errorcode)：设定的配置项无效。<br> 具体可参考[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**描述** 1361 1362事件相关的配置参数设置方法。 1363 1364不同的事件有不同的配置项，目前仅支持以下事件： 1365 1366MAIN_THREAD_JANK（参数配置详见[主线程超时事件检测](../../dfx/hiappevent-watcher-mainthreadjank-events.md#自定义参数)） 1367 1368**起始版本：** 15 1369 1370 1371**参数：** 1372 1373| 参数项 | 描述 | 1374| -- | -- | 1375| const char* name | 系统事件的名称。 | 1376| [HiAppEvent_Config](capi-hiappevent-hiappevent-config.md)* config | 指向配置对象的指针（即OH_HiAppEvent_CreateConfig接口返回的指针）。 | 1377 1378**返回：** 1379 1380| 类型 | 说明 | 1381| -- | -- | 1382| int | [HIAPPEVENT_SUCCESS](capi-hiappevent-h.md#hiappevent_errorcode)：接口调用成功；<br> [HIAPPEVENT_INVALID_PARAM_VALUE](capi-hiappevent-h.md#hiappevent_errorcode)：设置的参数无效。<br> 具体可参考[HiAppEvent_ErrorCode](capi-hiappevent-h.md#hiappevent_errorcode)。 | 1383 1384 1385