# HiSysEvent Listening
## Overview
### Introduction
HiSysEvent supports listening for events across processes. You can register a listener to listen for concerned events on a real-time basis. For example, you can enable the battery module to listen for power consumption events for power usage analysis.
### Constraints
Before subscribing to system events, you need to configure HiSysEvent logging. For details, see [HiSysEvent Logging Configuration](../subsystems/subsys-dfx-hisysevent-logging-config.md).
## Development Guidelines
### Available APIs
**Table 1** Description of HiSysEventListener APIs
| API| Description|
| -------- | -------- |
| int32_t HiSysEventManager::AddListener(std::shared_ptr<HiSysEventListener> listener, std::vector<ListenerRule>& rules) | Registers a listener for system events. You can listen for certain events by specifying rules.
Input arguments:
- **listener**: callback object for system events.
- **rules**: rules for event listening.
Return value:
- **0**: Registration is successful.
- A negative value: Registration has failed.|
| int32_t HiSysEventManager::RemoveListener(std::shared_ptr<HiSysEventListener> listener) | Removes the listener for system events.
Input arguments:
- **listener**: callback object for system events.
Return value:
- **0**: Canceling registration is successful.
- A negative value: Canceling registration has failed. |
**Table 2** Description of ListenerRule
| API| Description|
| -------- | -------- |
| ListenerRule(const std::string& tag, RuleType ruleType = RuleType::WHOLE_WORD) | Constructor used to create a **ListenerRule** object based on the event tag.
Input arguments:
- **tag**: event tag for the **ListenerRule** object. The value is a string of 1 to 16 characters, including uppercase letters, lowercase letters, and digits.
- **ruleType**: type of the **ListenerRule** object. The value is an enum defined by **RuleType**.|
| ListenerRule(const std::string& domain, const std::string& eventName, RuleType ruleType = RuleType::WHOLE_WORD) | Constructor used to create a **ListenerRule** object based on the event domain and event name.
Input arguments:
- **domain**: event domain for the **ListenerRule** object. The value is a string of 1 to 16 characters, including uppercase letters, digits, and underscores.
- **eventName**: event name for the **ListenerRule** object. The value is a string of 1 to 32 characters, including uppercase letters, digits, and underscores.
- **ruleType**: type of the **ListenerRule** object. The value is an enum defined by **RuleType**.|
| ListenerRule(const std::string& domain, const std::string& eventName, const std::string& tag, RuleType ruleType = RuleType::WHOLE_WORD) | Constructor used to create a **ListenerRule** object based on the event domain, event name, and event tag.
Input arguments:
- **tag**: event tag for the **ListenerRule** object. The value is a string of 1 to 16 characters, including uppercase letters, lowercase letters, and digits.
- **domain**: event domain for the **ListenerRule** object. The value is a string of 1 to 16 characters, including uppercase letters, digits, and underscores.
- **eventName**: event name for the **ListenerRule** object. The value is a string of 1 to 32 characters, including uppercase letters, digits, and underscores.
- **ruleType**: type of the **ListenerRule** object. The value is an enum defined by **RuleType**.|
**Table 3** Description of RuleType
| Value| Description|
| -------- | -------- |
| WHOLE_WORD | Whole word matching|
| PREFIX | Prefix matching|
| REGULAR | Regular expression matching|
**Table 4** Description of HiSysEventListener
| API| Description|
| -------- | -------- |
| void HiSysEventListener::OnEvent(std::shared_ptr<HiSysEventRecord> sysEvent) | Callback object for system events.
Input arguments:
- **sysEvent**: real-time system events.
Return value:
None.|
| void HiSysEventListener::OnServiceDied() | Callback object for service exceptions.
Input arguments:
None.
Return value:
None.|
**Table 5** Description of HiSysEventRecord
| API| Description|
| -------- | -------- |
|std::string HiSysEventRecord::AsJson()|Obtains the content of a system event.
Input arguments:
None.
Return value:
Content of the system event.|
|std::string HiSysEventRecord::GetDomain()|Obtains the domain name of a system event.
Input arguments:
None.
Return value:
Domain name of the system event.|
|std::string HiSysEventRecord::GetEventName()|Obtains the name of a system event.
Input arguments:
None.
Return value:
Name of the system event.|
|HiSysEvent::EventType HiSysEventRecord::GetEventType()|Obtains the type of a system event.
Input arguments:
None.
Return value:
Type of the system event.|
|std::string HiSysEventRecord::GetLevel()|Obtains the level of a system event.
Input arguments:
None.
Return value:
Level of the system event.|
|std::string HiSysEventRecord::GetTag()|Obtains the tag of a system event.
Input arguments:
None.
Return value:
Tag of the system event.|
|std::string HiSysEventRecord::GetTimeZone()|Obtains the time zone of a system event.
Input arguments:
None.
Return value:
Time zone, in the format of **+0800**.|
|int HiSysEventRecord::GetTraceFlag()|Obtains the distributed call chain tracing flag of a system event.
Input arguments:
None.
Return value:
Distributed call chain tracing flag.|
|int64_t HiSysEventRecord::GetPid()|Obtains the ID of the process that flushes a system event to the disk.
Input arguments:
None.
Return value:
Process ID.|
|int64_t HiSysEventRecord::GetTid()|Obtains the thread ID of the process that flushes a system event to the disk.
Input arguments:
None.
Return value:
Thread ID.|
|int64_t HiSysEventRecord::GetUid()|Obtains the user ID of the process that flushes a system event to the disk.
Input arguments:
None.
Return value:
User ID.|
|uint64_t HiSysEventRecord::GetPspanId()|Obtains the parent span ID of the distributed call chain tracing task.
Input arguments:
None.
Return value:
Parent span ID of the distributed call chain tracing task.|
|uint64_t HiSysEventRecord::GetSpandId()|Obtains the span ID of the distributed call chain tracing task.
Input arguments:
None.
Return value:
Span ID of the distributed call chain tracing task.|
|uint64_t HiSysEventRecord::GetTime()|Obtains the timestamp of a system event.
Input arguments:
None.
Return value:
Timestamp of the system event.|
|uint64_t HiSysEventRecord::GetTraceId()|Obtains the ID of the distributed call chain tracing task.
Input arguments:
None.
Return value:
ID of the distributed call chain tracing task.|
|void HiSysEventRecord::GetParamNames(std::vector<std::string>& params)|Obtains all key names of a system event.
Input arguments:
- **params**: key name array reference.
Return value:
None.|
|int HiSysEventRecord::GetParamValue(const std::string& param, int64_t& value)|Parses the value of the **param** key in a system event into an int64\_t value.
Input arguments:
- **param**: key name.
- **value**: int64\_t reference.
Return value:
- **0**: Parsing is successful.
- **-1**: Parsing failed due to initialization error.
- **-2**: Parsing failed due to nonexistent key name.
- **-3**: Parsing failed due to type mismatch.|
|int HiSysEventRecord::GetParamValue(const std::string& param, uint64_t& value)|Parses the value of the **param** key in a system event into a uint64\_t value.
Input arguments:
- **param**: key name.
- **value**: uint64\_t reference.
Return value:
- **0**: Parsing is successful.
- **-1**: Parsing failed due to initialization error.
- **-2**: Parsing failed due to nonexistent key name.
- **-3**: Parsing failed due to type mismatch.|
|int HiSysEventRecord::GetParamValue(const std::string& param, double& value)|Parses the value of the **param** key in a system event into a double value.
Input arguments:
- **param**: key name.
- **value**: double reference.
Return value:
- **0**: Parsing is successful.
- **-1**: Parsing failed due to initialization error.
- **-2**: Parsing failed due to nonexistent key name.
- **-3**: Parsing failed due to type mismatch.|
|int HiSysEventRecord::GetParamValue(const std::string& param, std::string& value)|Parses the value of the **param** key in a system event into a string value.
Input arguments:
- **param**: key name.
- **value**: std::string reference.
Return value:
- **0**: Parsing is successful.
- **-1**: Parsing failed due to initialization error.
- **-2**: Parsing failed due to nonexistent key name.
- **-3**: Parsing failed due to type mismatch.|
|int HiSysEventRecord::GetParamValue(const std::string& param, std::vector<int64_t>& value)|Parses the value of the **param** key in a system event into an int64\_t array.
Input arguments:
- **param**: key name.
- **value**: int64\_t array reference.
Return value:
- **0**: Parsing is successful.
- **-1**: Parsing failed due to initialization error.
- **-2**: Parsing failed due to nonexistent key name.
- **-3**: Parsing failed due to type mismatch.|
|int HiSysEventRecord::GetParamValue(const std::string& param, std::vector<uint64_t>& value)|Parses the value of the **param** key in a system event into a uint64\_t array.
Input arguments:
- **param**: key name.
- **value**: uint64\_t array reference.
Return value:
- **0**: Parsing is successful.
- **-1**: Parsing failed due to initialization error.
- **-2**: Parsing failed due to nonexistent key name.
- **-3**: Parsing failed due to type mismatch.|
|int HiSysEventRecord::GetParamValue(const std::string& param, std::vector<double>& value)|Parses the value of the **param** key in a system event into a double array.
Input arguments:
- **param**: key name.
- **value**: double array reference.
Return value:
- **0**: Parsing is successful.
- **-1**: Parsing failed due to initialization error.
- **-2**: Parsing failed due to nonexistent key name.
- **-3**: Parsing failed due to type mismatch.|
|int HiSysEventRecord::GetParamValue(const std::string& param, std::vector<std::string>& value)|Parses the value of the **param** key in a system event into a string array.
Input arguments:
- **param**: key name.
- **value**: std::string array reference.
Return value:
- **0**: Parsing is successful.
- **-1**: Parsing failed due to initialization error.
- **-2**: Parsing failed due to nonexistent key name.
- **-3**: Parsing failed due to type mismatch.|
## How to Develop
### **C++**
The following provides an example of how to use C++ APIs of **HiSysEvent**.
1. Develop the source code.
Import the **DemoListener.h** header file, which contains the **DemoListener** class for implementing the custom event callback.
```
#ifndef DEMO_LISTENER_H
#define DEMO_LISTENER_H
#include "hisysevent_listener.h"
#include
class DemoListener : public OHOS::HiviewDFX::HiSysEventListener {
public:
explicit DemoListener() : HiSysEventListener() {}
virtual ~DemoListener() {}
public:
void OnEvent(std::shared_ptr sysEvent);
void OnServiceDied();
};
#endif // DEMO_LISTENER_H
```
Create the **DemoListener.cpp** file, and add the implementation logic of the custom event callback API in the **DemoListener** class.
```
#include "demo_listener.h"
#include
void DemoListener::OnEvent(std::shared_ptr sysEvent)
{
if (sysEvent == nullptr) {
return;
}
std::cout << sysEvent.AsJson() << std::endl;
}
void DemoListener::OnServiceDied()
{
std::cout << std::string("service disconnect, exit") << std::endl;
exit(0);
}
```
Call the **AddEventListener** API of the **HiSysEventManager** class to add a listener for system events.
```
auto demoListener = std::make_shared();
// Add a ListenerRule object based on the event tag, with RuleType left unspecified (in this case, ruleType is defaulted to WHOLE_WORD).
ListenerRule tagRule("dfx");
// Add a ListenerRule object based on the event tag, with RuleType set as REGULAR.
ListenerRule regRule("dfx.*", RuleType::REGULAR);
// Add a ListenerRule object based on the event domain and event name, with RuleType set as PREFIX.
ListenerRule domainNameRule("HIVIEWDFX", "APP_USAGE", RuleType::PREFIX);
std::vector sysRules;
sysRules.push_back(tagRule);
sysRules.push_back(regRule);
sysRules.push_back(domainNameRule);
HiSysEventManager::AddEventListener(demoListener, sysRules);
```
2. Configure the **BUILD.gn** file.
In the **BUILD.gn** file, add the **libhisysevent** and **libhisyseventmanager** libraries that depend on the **hisysevent_native** component.
```
external_deps = [
"hisysevent_native:libhisysevent",
"hisysevent_native:libhisyseventmanager",
]
```