harmony 鸿蒙hiappevent.h

2025-06-12
浏览 (6)

hiappevent.h

Overview

Defines 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.

Event domain: domain associated with the application event.

Event name: name of the application event.

Event type: fault, statistics, security, or behavior.

Parameter list: a linked list used to store event parameters. Each parameter consists of a parameter name and a parameter value.

Example:

Import the header file.
```
#include "hiappevent/hiappevent.h"
```

Create a parameter list pointer.

ParamList list = OH_HiAppEvent_CreateParamList();

Add parameters to the parameter list.

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]));

Perform event logging.

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

Destroy the parameter list pointer and release its allocated memory.
```
OH_HiAppEvent_DestroyParamList(list);
```

File to include:

Library: libhiappevent_ndk.z.so

System capability: SystemCapability.HiviewDFX.HiAppEvent

Since: 8

Related module: HiAppEvent

Summary

Structs

Name	Description
struct  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.
struct  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.

Types

Name	Description
typedef struct HiAppEvent_AppEventInfo HiAppEvent_AppEventInfo	Defines a struct for the information about a single event, including the event domain, event name, event type, and custom parameter list in JSON string format.
typedef struct HiAppEvent_AppEventGroup HiAppEvent_AppEventGroup	Defines a struct for the information about an event group, including its name, the array of event information grouped by name, and the length of the event array.
typedef struct ParamListNode * ParamList	Defines a struct for the event parameter list node.
typedef struct HiAppEvent_Watcher HiAppEvent_Watcher	Defines a struct for the watcher for application events.
typedef struct HiAppEvent_Processor HiAppEvent_Processor	Defines a struct for the processor for application events.
typedef struct HiAppEvent_Config HiAppEvent_Config	Defines a struct for the configuration object used to set the conditions for triggering system events.
typedef void(* OH_HiAppEvent_OnReceive) (const char domain, const struct HiAppEvent_AppEventGroup appEventGroups, uint32_t groupLen)	Defines a callback invoked to pass event content to the caller.
typedef void(* OH_HiAppEvent_OnTrigger) (int row, int size)	Defines 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. If the saved event meets the conditions specified by OH_HiAppEvent_SetTriggerCondition, the callback is triggered. After the callback is complete, if a newly saved event meets the specified condition, the callback is invoked again.
typedef void(* OH_HiAppEvent_OnTake) (const char const events, uint32_t eventLen)	Defines a callback invoked to pass the events received by the watcher to the caller when OH_HiAppEvent_TakeWatcherData is used to obtain the events.

Enums

Name	Description
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 }	Enumerates the error codes used in the HiAppEvent module.
EventType { FAULT = 1, STATISTIC = 2, SECURITY = 3, BEHAVIOR = 4 }	Enumerates the event types.

Callback

Name	Description
ParamList OH_HiAppEvent_CreateParamList (void)	Creates a pointer to a parameter list object.
void OH_HiAppEvent_DestroyParamList (ParamList list)	Destroys a pointer to a parameter list object and releases its allocated memory.
ParamList OH_HiAppEvent_AddBoolParam (ParamList list, const char *name, bool boolean)	Adds an event parameter of the Boolean type to the parameter list.
ParamList OH_HiAppEvent_AddBoolArrayParam (ParamList list, const char name, const bool booleans, int arrSize)	Adds an event parameter of the Boolean array type to the parameter list.
ParamList OH_HiAppEvent_AddInt8Param (ParamList list, const char *name, int8_t num)	Adds an event parameter of the int8_t type to the parameter list.
ParamList OH_HiAppEvent_AddInt8ArrayParam (ParamList list, const char name, const int8_t nums, int arrSize)	Adds an event parameter of the int8_t array type to the parameter list.
ParamList OH_HiAppEvent_AddInt16Param (ParamList list, const char *name, int16_t num)	Adds an event parameter of the int16_t type to the parameter list.
ParamList OH_HiAppEvent_AddInt16ArrayParam (ParamList list, const char name, const int16_t nums, int arrSize)	Adds an event parameter of the int16_t array type to the parameter list.
ParamList OH_HiAppEvent_AddInt32Param (ParamList list, const char *name, int32_t num)	Adds an event parameter of the int32_t type to the parameter list.
ParamList OH_HiAppEvent_AddInt32ArrayParam (ParamList list, const char name, const int32_t nums, int arrSize)	Adds an event parameter of the int32_t array type to the parameter list.
ParamList OH_HiAppEvent_AddInt64Param (ParamList list, const char *name, int64_t num)	Adds an event parameter of the int64_t type to the parameter list.
ParamList OH_HiAppEvent_AddInt64ArrayParam (ParamList list, const char name, const int64_t nums, int arrSize)	Adds an event parameter of the int64_t array type to the parameter list.
ParamList OH_HiAppEvent_AddFloatParam (ParamList list, const char *name, float num)	Adds an event parameter of the float type to the parameter list.
ParamList OH_HiAppEvent_AddFloatArrayParam (ParamList list, const char name, const float nums, int arrSize)	Adds an event parameter of the float array type to the parameter list.
ParamList OH_HiAppEvent_AddDoubleParam (ParamList list, const char *name, double num)	Adds an event parameter of the Double type to the parameter list.
ParamList OH_HiAppEvent_AddDoubleArrayParam (ParamList list, const char name, const double nums, int arrSize)	Adds an event parameter of the double array type to the parameter list.
ParamList OH_HiAppEvent_AddStringParam (ParamList list, const char name, const char str)	Adds a parameter of the string type to the parameter list.
ParamList OH_HiAppEvent_AddStringArrayParam (ParamList list, const char name, const char const *strs, int arrSize)	Adds a parameter of the string array type to the parameter list.
int OH_HiAppEvent_Write (const char domain, const char name, enum EventType type, const ParamList list)	Logs application events whose parameters are of the list type.
bool OH_HiAppEvent_Configure (const char name, const char value)	Configures the application event logging function.
HiAppEvent_Watcher * OH_HiAppEvent_CreateWatcher (const char *name)	Creates a watcher for application events.
void OH_HiAppEvent_DestroyWatcher (HiAppEvent_Watcher *watcher)	Destroys a created watcher.
int OH_HiAppEvent_SetTriggerCondition (HiAppEvent_Watcher *watcher, int row, int size, int timeOut)	Sets the trigger condition of the OH_HiAppEvent_OnTrigger callback. 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.
int OH_HiAppEvent_SetAppEventFilter (HiAppEvent_Watcher watcher, const char domain, uint8_t eventTypes, const char const names, int namesLen)	Sets the type of events to listen for.
int OH_HiAppEvent_SetWatcherOnTrigger (HiAppEvent_Watcher *watcher, OH_HiAppEvent_OnTrigger onTrigger)	Sets the onTrigger callback. 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.
int OH_HiAppEvent_SetWatcherOnReceive (HiAppEvent_Watcher *watcher, OH_HiAppEvent_OnReceive onReceive)	Sets the onReceive callback. When the watcher detects the corresponding event, the onReceive callback is called.
int OH_HiAppEvent_TakeWatcherData (HiAppEvent_Watcher *watcher, uint32_t eventNum, OH_HiAppEvent_OnTake onTake)	Obtains the event saved by the watcher.
int OH_HiAppEvent_AddWatcher (HiAppEvent_Watcher *watcher)	Adds a watcher. Once a watcher is added, it starts to listen for system messages.
int OH_HiAppEvent_RemoveWatcher (HiAppEvent_Watcher *watcher)	Removes a watcher. Once a watcher is removed, it stops listening for system messages.
void OH_HiAppEvent_ClearData ()	Clears the events saved by all watchers.
HiAppEvent_Processor * OH_HiAppEvent_CreateProcessor (const char *name)	Creates a processor for application events.
int OH_HiAppEvent_SetReportRoute (HiAppEvent_Processor processor, const char appId, const char *routeInfo)	Sets the report route for a processor.
int OH_HiAppEvent_SetReportPolicy (HiAppEvent_Processor *processor, int periodReport, int batchReport, bool onStartReport, bool onBackgroundReport)	Sets the report policy for a processor.
int OH_HiAppEvent_SetReportEvent (HiAppEvent_Processor processor, const char domain, const char *name, bool isRealTime)	Sets the report event for a processor.
int OH_HiAppEvent_SetCustomConfig (HiAppEvent_Processor processor, const char key, const char *value)	Sets the custom extension parameters of a processor.
int OH_HiAppEvent_SetConfigId (HiAppEvent_Processor *processor, int configId)	Sets the configuration ID of a processor.
int OH_HiAppEvent_SetReportUserId (HiAppEvent_Processor processor, const char const *userIdNames, int size)	Sets the report user ID of a processor.
int OH_HiAppEvent_SetReportUserProperty (HiAppEvent_Processor processor, const char const *userPropertyNames, int size)	Sets the report user property of the processor.
int64_t OH_HiAppEvent_AddProcessor (HiAppEvent_Processor *processor)	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.
void OH_HiAppEvent_DestroyProcessor (HiAppEvent_Processor *processor)	Destroys a processor.
int OH_HiAppEvent_RemoveProcessor (int64_t processorId)	Removes a processor. Once a processor is removed, it stops reporting events.
HiAppEvent_Config * OH_HiAppEvent_CreateConfig (void)	Creates a pointer to the configuration object that sets the conditions for triggering system events.
void OH_HiAppEvent_DestroyConfig (HiAppEvent_Config *config)	Destroys a configuration object.
int OH_HiAppEvent_SetConfigItem (HiAppEvent_Config config, const char itemName, const char *itemValue)	Sets the items in the configuration object.
int OH_HiAppEvent_SetEventConfig (const char name, HiAppEvent_Config config)	Sets the conditions for triggering system event subscription.