harmony 鸿蒙hiappevent.h

2025-06-16
浏览 (3)

hiappevent.h

概述

HiAppEvent模块的应用事件打点函数定义。

在执行应用事件打点之前，您必须先构造一个参数列表对象来存储输入的事件参数，并指定事件领域、事件名称和事件类型。

事件领域：用于标识事件打点的领域的字符串。

事件名称：用于标识事件打点的名称的字符串。

事件类型：故障、统计、安全、行为。

参数列表：用于存储事件参数的链表，每个参数由参数名和参数值组成。

示例代码：

引入头文件：
```
#include "hiappevent/hiappevent.h"
```

创建一个参数列表指针：

ParamList list = OH_HiAppEvent_CreateParamList();

添加参数到参数列表中：

bool boolean = true;
OH_HiAppEvent_AddBoolParam(list, "bool_key", boolean);
int32_t nums[] = {1, 2, 3};
OH_HiAppEvent_AddInt32ArrayParam(list, "int32_arr_key", nums, sizeof(nums) / sizeof(nums[0]));

执行事件打点：

int res = OH_HiAppEvent_Write("test_domain", "test_event", BEHAVIOR, list);

销毁参数列表指针，释放其分配内存：
```
OH_HiAppEvent_DestroyParamList(list);
```

引用文件： <hiappevent/hiappevent.h>

库： libhiappevent_ndk.z.so

系统能力： SystemCapability.HiviewDFX.HiAppEvent

起始版本： 8

相关模块：HiAppEvent

汇总

结构体

名称	描述
struct  HiAppEvent_AppEventInfo	单个事件信息，包含事件领域，事件名称，事件类型和json格式字符串表示的事件中携带的自定义参数列表。
struct  HiAppEvent_AppEventGroup	一组事件信息，包含事件组的名称，按名称分组的单个事件信息数组，事件数组的长度。

类型定义

名称	描述
typedef struct HiAppEvent_AppEventInfo HiAppEvent_AppEventInfo	单个事件信息，包含事件领域，事件名称，事件类型和json格式字符串表示的事件中携带的自定义参数列表。
typedef struct HiAppEvent_AppEventGroup HiAppEvent_AppEventGroup	一组事件信息，包含事件组的名称，按名称分组的单个事件信息数组，事件数组的长度。
typedef struct ParamListNode * ParamList	事件参数列表节点。
typedef struct HiAppEvent_Watcher HiAppEvent_Watcher	用于接收app事件的监听器。
typedef struct HiAppEvent_Processor HiAppEvent_Processor	用于处理app事件上报的处理者。
typedef struct HiAppEvent_Config HiAppEvent_Config	用于设置系统事件触发条件的配置对象。
typedef void(* OH_HiAppEvent_OnReceive) (const char domain, const struct HiAppEvent_AppEventGroup appEventGroups, uint32_t groupLen)	监听器接收到事件后，将触发该回调，将事件内容传递给调用方。
typedef void(* OH_HiAppEvent_OnTrigger) (int row, int size)	监听器收到事件后，若监听器中未设置OH_HiAppEvent_OnReceive回调，将保存该事件。当保存的事件满足通过OH_HiAppEvent_SetTriggerCondition设定的条件后，将触发该回调。回调结束后，当新保存的事件消息再次满足设定的条件后，将再次进行回调。
typedef void(* OH_HiAppEvent_OnTake) (const char const events, uint32_t eventLen)	使用OH_HiAppEvent_TakeWatcherData获取监听器接收到的事件时，监听器接收到的事件将通过该回调函数传递给调用者。

枚举

名称	描述
HiAppEvent_ErrorCode { HIAPPEVENT_SUCCESS = 0, HIAPPEVENT_INVALID_PARAM_VALUE_LENGTH = 4, HIAPPEVENT_PROCESSOR_IS_NULL = -7, HIAPPEVENT_PROCESSOR_NOT_FOUND = -8, HIAPPEVENT_INVALID_PARAM_VALUE = -9, HIAPPEVENT_EVENT_CONFIG_IS_NULL = -10, HIAPPEVENT_OPERATE_FAILED = -100, HIAPPEVENT_INVALID_UID = -200 }	错误码定义。
EventType { FAULT = 1, STATISTIC = 2, SECURITY = 3, BEHAVIOR = 4 }	事件类型。

函数

名称	描述
ParamList OH_HiAppEvent_CreateParamList (void)	创建一个指向参数列表对象的指针。
void OH_HiAppEvent_DestroyParamList (ParamList list)	销毁一个指向参数列表对象的指针，释放其分配内存。
ParamList OH_HiAppEvent_AddBoolParam (ParamList list, const char *name, bool boolean)	添加一个布尔参数到参数列表中。
ParamList OH_HiAppEvent_AddBoolArrayParam (ParamList list, const char name, const bool booleans, int arrSize)	添加一个布尔数组参数到参数列表中。
ParamList OH_HiAppEvent_AddInt8Param (ParamList list, const char *name, int8_t num)	添加一个int8_t参数到参数列表中。
ParamList OH_HiAppEvent_AddInt8ArrayParam (ParamList list, const char name, const int8_t nums, int arrSize)	添加一个int8_t数组参数到参数列表中。
ParamList OH_HiAppEvent_AddInt16Param (ParamList list, const char *name, int16_t num)	添加一个int16_t参数到参数列表中。
ParamList OH_HiAppEvent_AddInt16ArrayParam (ParamList list, const char name, const int16_t nums, int arrSize)	添加一个int16_t数组参数到参数列表中。
ParamList OH_HiAppEvent_AddInt32Param (ParamList list, const char *name, int32_t num)	添加一个int32_t参数到参数列表中。
ParamList OH_HiAppEvent_AddInt32ArrayParam (ParamList list, const char name, const int32_t nums, int arrSize)	添加一个int32_t数组参数到参数列表中。
ParamList OH_HiAppEvent_AddInt64Param (ParamList list, const char *name, int64_t num)	添加一个int64_t参数到参数列表中。
ParamList OH_HiAppEvent_AddInt64ArrayParam (ParamList list, const char name, const int64_t nums, int arrSize)	添加一个int64_t数组参数到参数列表中。
ParamList OH_HiAppEvent_AddFloatParam (ParamList list, const char *name, float num)	添加一个float参数到参数列表中。
ParamList OH_HiAppEvent_AddFloatArrayParam (ParamList list, const char name, const float nums, int arrSize)	添加一个float数组参数到参数列表中。
ParamList OH_HiAppEvent_AddDoubleParam (ParamList list, const char *name, double num)	添加一个double参数到参数列表中。
ParamList OH_HiAppEvent_AddDoubleArrayParam (ParamList list, const char name, const double nums, int arrSize)	添加一个double数组参数到参数列表中。
ParamList OH_HiAppEvent_AddStringParam (ParamList list, const char name, const char str)	添加一个字符串参数到参数列表中。
ParamList OH_HiAppEvent_AddStringArrayParam (ParamList list, const char name, const char const *strs, int arrSize)	添加一个字符串数组参数到参数列表中。
int OH_HiAppEvent_Write (const char domain, const char name, enum EventType type, const ParamList list)	实现对参数为列表类型的应用事件打点。
bool OH_HiAppEvent_Configure (const char name, const char value)	实现应用事件打点的配置功能。
HiAppEvent_Watcher * OH_HiAppEvent_CreateWatcher (const char *name)	创建一个用于监听app事件的监听器。
void OH_HiAppEvent_DestroyWatcher (HiAppEvent_Watcher *watcher)	销毁已创建的监听器。
int OH_HiAppEvent_SetTriggerCondition (HiAppEvent_Watcher *watcher, int row, int size, int timeOut)	用于设置监听器OH_HiAppEvent_OnTrigger回调的触发条件。分别可以从监视器新接收事件数量、新接收事件大小、onTrigger触发超时时间，设置触发条件。调用方应至少保证从一个方面设置触发条件。
int OH_HiAppEvent_SetAppEventFilter (HiAppEvent_Watcher watcher, const char domain, uint8_t eventTypes, const char const names, int namesLen)	用于设置监听器需要监听的事件的类型。
int OH_HiAppEvent_SetWatcherOnTrigger (HiAppEvent_Watcher *watcher, OH_HiAppEvent_OnTrigger onTrigger)	用于设置监听器onTrigger回调的接口。如果未设置OnReceive回调或已将其设置为nullptr，则将保存观察者接收到的应用事件。当保存的应用事件满足onTrigger回调的触发条件时，将调用onTrigger回调。
int OH_HiAppEvent_SetWatcherOnReceive (HiAppEvent_Watcher *watcher, OH_HiAppEvent_OnReceive onReceive)	用于设置监听器onReceive回调函数的接口。当监听器监听到相应事件后，onReceive回调函数将被调用。
int OH_HiAppEvent_TakeWatcherData (HiAppEvent_Watcher *watcher, uint32_t eventNum, OH_HiAppEvent_OnTake onTake)	用于获取监听器收到后保存的事件。
int OH_HiAppEvent_AddWatcher (HiAppEvent_Watcher *watcher)	添加监听器的接口，监听器开始监听系统消息。
int OH_HiAppEvent_RemoveWatcher (HiAppEvent_Watcher *watcher)	移除监听器的接口，监听器停止监听系统消息。
void OH_HiAppEvent_ClearData ()	清除所有监视器保存的所有事件。
HiAppEvent_Processor * OH_HiAppEvent_CreateProcessor (const char *name)	创建一个用于处理app事件上报的处理者。
int OH_HiAppEvent_SetReportRoute (HiAppEvent_Processor processor, const char appId, const char *routeInfo)	设置处理者事件上报路由的接口。
int OH_HiAppEvent_SetReportPolicy (HiAppEvent_Processor *processor, int periodReport, int batchReport, bool onStartReport, bool onBackgroundReport)	设置处理者事件上报策略的接口。
int OH_HiAppEvent_SetReportEvent (HiAppEvent_Processor processor, const char domain, const char *name, bool isRealTime)	设置处理者上报事件的接口。
int OH_HiAppEvent_SetCustomConfig (HiAppEvent_Processor processor, const char key, const char *value)	设置处理者自定义扩展参数的接口。
int OH_HiAppEvent_SetConfigId (HiAppEvent_Processor *processor, int configId)	设置处理者配置id的接口。
int OH_HiAppEvent_SetReportUserId (HiAppEvent_Processor processor, const char const *userIdNames, int size)	设置处理者用户ID的接口。
int OH_HiAppEvent_SetReportUserProperty (HiAppEvent_Processor processor, const char const *userPropertyNames, int size)	设置处理者用户属性的接口。
int64_t OH_HiAppEvent_AddProcessor (HiAppEvent_Processor *processor)	添加数据处理者的接口。开发者可添加数据处理者，用于提供事件上云功能。数据处理者的实现可预置在设备中，开发者可根据数据处理者的约束设置属性。
void OH_HiAppEvent_DestroyProcessor (HiAppEvent_Processor *processor)	销毁已创建的数据处理者。
int OH_HiAppEvent_RemoveProcessor (int64_t processorId)	移除数据处理者的接口，处理者停止上报事件。
HiAppEvent_Config * OH_HiAppEvent_CreateConfig (void)	创建一个指向设置系统事件触发条件的配置对象的指针。
void OH_HiAppEvent_DestroyConfig (HiAppEvent_Config *config)	销毁已创建的配置对象。
int OH_HiAppEvent_SetConfigItem (HiAppEvent_Config config, const char itemName, const char *itemValue)	设置配置对象中的配置项。
int OH_HiAppEvent_SetEventConfig (const char name, HiAppEvent_Config config)	设定系统事件订阅触发条件。