# HiSysEvent Listening
## Overview
### Function 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 subscribe to power consumption events for power usage analysis.
### Constraints
Before listening for system events, you need to configure HiSysEvent logging. For details, see [HiSysEvent Logging Configuration](../subsystems/subsys-dfx-hisysevent-logging-config.md).
## How to Develop
### Available APIs
#### C++ APIs
HiSysEvent is implemented using the APIs provided by the **HiSysEventManager** class. For details, see the [API Header Files](/base/hiviewdfx/hisysevent/interfaces/native/innerkits/hisysevent_manager/include/).
> **NOTE**
>
> For details about the **RuleType** argument in the constructor of **ListenerRule**, see Table 4 in [HiSysEvent Query](subsys-dfx-hisysevent-query.md).
**Table 1** Description of C++ HiSysEventManager APIs
| Name| Description|
| -------- | -------- |
| int32_t HiSysEventManager::AddListener(std::shared_ptr<HiSysEventListener> listener,
std::vector<ListenerRule>& rules) | Adds a listener to listen for system events based on the specified rules.
Input arguments:
- **listener**: listener for system events.
- **rules**: event listening rules.
Return value:
- **0**: The listener is added successfully.
- A negative value: The listener fails to be added.|
| int32_t HiSysEventManager::RemoveListener(std::shared_ptr<HiSysEventListener> listener) | Removes the listener for system events.
Input arguments:
- **listener**: listener for system events.
Return value:
- **0**: The listener is removed successfully.
- A negative value: The listener fails to be removed. |
**Table 2** Description of ListenerRule
| Name| 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:
- **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.
- **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**.|
**Table 3** Description of HiSysEventListener
| Name| Description|
| -------- | -------- |
| void HiSysEventListener::OnEvent(std::shared_ptr<HiSysEventRecord> sysEvent) | Callback object for system events.
Input arguments:
- **sysEvent**: real-time system event.
Return value:
None.|
| void HiSysEventListener::OnServiceDied() | Callback object for service exceptions.
Input arguments:
None.
Return value:
None.|
**Table 4** Description of HiSysEventRecord
| Name| 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.|
|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.|
#### C APIs
HiSysEvent listening is implemented using the API provided in the following table. For details, see the [API Header Files](/base/hiviewdfx/hisysevent/interfaces/native/innerkits/hisysevent_manager/include/).
> **NOTE**
>
> For details about the **HiSysEventRecord** argument in the **OnEvent** callback of **HiSysEventWatcher**, see Table 11 and Table 12 in [HiSysEvent Query](subsys-dfx-hisysevent-query.md).
**Table 5** Description of C HiSysEventManager APIs
| Name | Description |
| ------------------------------------------------------------ | ------------------------------------------------------------ |
| int OH_HiSysEvent_Add_Watcher(HiSysEventWatcher* watcher,
HiSysEventWatchRule rules[],
size_t ruleSize); | Adds a listener to listen for system events based on the specified rules.
Input arguments:
- **watcher**: watcher for system events.
- **rules**: array of event listening rules.
- **ruleSize**: length of the array of event listening rules.
Return value:
- **0**: The listener is added successfully.
- A negative value: The listener fails to be added.|
| int OH_HiSysEvent_Remove_Watcher(HiSysEventWatcher* watcher); | Remove the watcher for system events.
Input arguments:
- **watcher**: watcher for system events.
Return value:
- **0**: The watcher is removed successfully.
- A negative value: The watcher fails to be removed. |
**Table 6** Description of the HiSysEventWatcher structure
| Field | Type | Description |
| ------------- | -------------------------------------------------- | ------------------------------------------------------------ |
| OnEvent | void (*)(HiSysEventRecord record); | Callback object for system events.
Input arguments:
- **record**: real-time system event.
Return value:
None.|
| OnServiceDied | void (*)(); | Callback object for service exceptions.
Input arguments:
None.
Return value:
None. |
**Table 7** Description of the HiSysEventWatchRule structure
| Field | Type | Description |
| ------------- | --------- | ---------------------------------- |
| domain | char[] | Event domain. |
| name | char[] | Event name. |
| tag | char[] | Event tag. |
| ruleType | int | Event matching rule. For details about the values, see Table 4 in [HiSysEvent Query](subsys-dfx-hisysevent-query.md). |
| eventType | int | Event type. For details about the values, see Table 3 in [HiSysEvent Query](subsys-dfx-hisysevent-query.md). The value **0** indicates all event types. |
### How to Develop
#### C++ HiSysEvent Listening
1. Import the corresponding header file.
```c++
#include "hisysevent_manager.h"
```
2. Implement the callback API for the service domain.
```c++
class TestListener : public OHOS::HiviewDFX::HiSysEventListener {
public:
void OnEvent(std::shared_ptr record)
{
if (record == nullptr) {
return;
}
std::cout << record->AsJson() << std::endl;
}
void OnServiceDied()
{
std::cout << std::string("service disconnect, exit") << std::endl;
exit(0);
}
};
```
3. Call the listening API while passing in parameters such as **listener** and **rules**. When the service ends, disable event listening.
```c++
auto testListener = 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);
// Start event listening.
auto ret = HiSysEventManager::AddListener(testListener, sysRules);
// Remove the listener when the service ends.
if (ret == 0) {
HiSysEventManager::RemoveListener(testListener);
}
```
#### C HiSysEvent Listening
1. Import the corresponding header file.
```c++
#include "hisysevent_manager_c.h"
```
2. Implement the callback API for the service domain.
```c++
void OnEventTest(HiSysEventRecord record)
{
printf("OnEventTest: event=%s", record.jsonStr);
}
void OnServiceDiedTest()
{
printf("OnServiceDied");
}
```
3. Call the listening API while passing in parameters such as **watcher** and **rules**. When the service ends, disable event listening.
```c++
HiSysEventWatcher watcher;
watcher.OnEvent = OnEventTest;
watcher.OnServiceDied = OnServiceDiedTest;
// Add a HiSysEventWatchRule object based on the event tag, with RuleType left unspecified (in this case, ruleType is defaulted to WHOLE_WORD).
constexpr char DFX_TAG[] = "dfx";
HiSysEventWatchRule tagRule;
(void)strcpy_s(tagRule.tag, strlen(DFX_TAG) + 1, DFX_TAG);
tagRule.ruleType = 1;
tagRule.eventType = 0;
// Add a HiSysEventWatchRule object based on the event tag, with RuleType set as REGULAR.
constexpr char DFX_PATTERN_TAG[] = "dfx.*";
HiSysEventWatchRule regRule;
(void)strcpy_s(regRule.tag, strlen(DFX_PATTERN_TAG) + 1, DFX_PATTERN_TAG);
regRule.ruleType = 3;
regRule.eventType = 0;
// Add a HiSysEventWatchRule object based on the event domain and event name, with RuleType set as PREFIX.
constexpr char DOMAIN[] = "HIVIEWDFX";
constexpr char NAME[] = "APP_USAGE";
HiSysEventWatchRule domainNameRule;
(void)strcpy_s(domainNameRule.domain, strlen(DOMAIN) + 1, DOMAIN);
(void)strcpy_s(domainNameRule.name, strlen(NAME) + 1, NAME);
domainNameRule.ruleType = 2;
domainNameRule.eventType = 0;
// Start event listening.
HiSysEventWatchRule rules[] = {tagRule, regRule, domainNameRule};
int ret = OH_HiSysEvent_Add_Watcher(&watcher, rules, sizeof(rules) / sizeof(HiSysEventWatchRule));
// Remove the watcher when the service ends.
if (ret == 0) {
ret = OH_HiSysEvent_Remove_Watcher(&watcher);
}
```
### Development Examples
#### C++ HiSysEvent Listening
Suppose you want to enable listening for all events whose domain is **HIVIEWDFX** and name is **PLUGIN_LOAD**. The sample code is as follows:
1. Add the **libhisysevent** and **libhisyseventmanager** dependencies of the **hisysevent** component to the **BUILD.gn** file of the service module.
```c++
external_deps = [
"hisysevent:libhisysevent",
"hisysevent:libhisyseventmanager",
]
```
2. Call the listening API in the **TestEventListening()** function. When the service ends, disable event listening.
```c++
#include
#include "hisysevent_manager.h"
using namespace OHOS::HiviewDFX;
class TestListener : public HiSysEventQueryCallback {
public:
void OnEvent(std::shared_ptr record)
{
if (record == nullptr) {
return;
}
std::cout << record->AsJson() << std::endl;
}
void OnServiceDied()
{
std::cout << std::string("service disconnect, exit") << std::endl;
exit(0);
}
};
void TestEventListening()
{
auto testListener = std::make_shared();
ListenerRule domainNameRule("HIVIEWDFX", "PLUGIN_LOAD", RuleType::WHOLE_WORD);
std::vector sysRules;
sysRules.push_back(domainNameRule);
auto ret = HiSysEventManager::AddListener(testListener, sysRules);
if (ret == 0) {
HiSysEventManager::RemoveListener(testListener);
}
}
```
#### C HiSysEvent Listening
Suppose you want to enable listening for all events whose domain is **HIVIEWDFX** and name is **PLUGIN_LOAD**. The sample code is as follows:
1. Add the **libhisysevent** and **libhisyseventmanager** dependencies of the **hisysevent** component to the **BUILD.gn** file of the service module.
```c++
external_deps = [ "hisysevent:libhisyseventmanager" ]
// for strcpy_s
deps = [ "//third_party/bounds_checking_function:libsec_shared" ]
```
2. Call the listening API in the **TestEventListening()** function. When the service ends, disable event listening.
```c++
#include
#include "hisysevent_manager_c.h"
void OnEventTest(HiSysEventRecord record)
{
printf("OnEventTest: event=%s", record.jsonStr);
}
void OnServiceDiedTest()
{
printf("OnServiceDied");
}
void TestEventListening()
{
HiSysEventWatcher watcher;
watcher.OnEvent = OnEventTest;
watcher.OnServiceDied = OnServiceDiedTest;
constexpr char DOMAIN[] = "HIVIEWDFX";
constexpr char NAME[] = "PLUGIN_LOAD";
HiSysEventWatchRule domainNameRule;
(void)strcpy_s(domainNameRule.domain, strlen(DOMAIN) + 1, DOMAIN);
(void)strcpy_s(domainNameRule.name, strlen(NAME) + 1, NAME);
domainNameRule.ruleType = 1;
domainNameRule.eventType = 0;
HiSysEventWatchRule rules[] = {domainNameRule};
int ret = OH_HiSysEvent_Add_Watcher(&watcher, rules, sizeof(rules) / sizeof(HiSysEventWatchRule));
if (ret == 0) {
ret = OH_HiSysEvent_Remove_Watcher(&watcher);
}
}
```