# HiSysEvent订阅
## 概述
### 功能简介
HiSysEvent提供了跨进程订阅机制，开发者可以通过注册订阅接口实时获取关注的事件，例如电池模块订阅功耗相关的事件，用于分析耗电情况。
### 约束与限制
在订阅HiSysEvent事件之前，需要先完成HiSysEvent打点配置，具体配置方法请参考[《HiSysEvent打点配置指导》](../subsystems/subsys-dfx-hisysevent-logging-config.md)。
## 开发指导
### 接口说明
#### C++接口说明
C++ HiSysEvent订阅开发能力如下：HiSysEventManager类，具体API详见接口目录（/base/hiviewdfx/hisysevent/interfaces/native/innerkits/hisysevent_manager/include/）。
>  **说明：**
>
> ListenerRule订阅规则对象构造函数形参类型RuleType请参考[HiSysEvent查询](subsys-dfx-hisysevent-query.md)中的“表4 RuleType匹配规则类型枚举”说明。
**表1** HiSysEvent订阅接口
| 接口名称 | 描述 |
| -------- | -------- |
| int32_t HiSysEventManager::AddListener(std::shared_ptr<HiSysEventListener> listener,
std::vector<ListenerRule>& rules) | 接口功能：添加对系统事件的订阅，通过设置规则订阅某些特定的事件。
输入参数：
- listener：订阅回调对象。
- rules：事件订阅规则。
返回值：
- 0：订阅添加成功。
- 负值：订阅添加失败。 |
| int32_t HiSysEventManager::RemoveListener(std::shared_ptr<HiSysEventListener> listener) | 接口功能：移除对系统事件的订阅。
输入参数：
- listener：订阅回调对象。
返回值：
- 0：订阅移除成功。
- 负值：订阅移除失败。 |
**表2** ListenerRule订阅规则对象
| 接口名称 | 描述 |
| -------- | -------- |
| ListenerRule(const std::string& tag,
RuleType ruleType = RuleType::WHOLE_WORD) | 接口功能：订阅规则构造函数，创建事件标签订阅规则对象。
输入参数：
- tag：订阅规则中指定的系统事件标签，字符串类型，最大长度16个字符（含），有效字符包含大小写字母及数字。
- ruleType：订阅规则的规则类型，RuleType枚举类型(参考表3)。 |
| ListenerRule(const std::string& domain,
const std::string& eventName,
RuleType ruleType = RuleType::WHOLE_WORD) | 接口功能：订阅规则构造函数，创建事件领域与事件名称订阅规则对象。
输入参数：
- domain：订阅规则中指定的系统事件领域，字符串类型，最大长度16个字符（含），有效字符包含大写字母、数字及下划线。
- eventName：订阅规则中指定的系统事件名称，字符串类型，最大长度32个字符（含），有效字符包含大写字母、数字及下划线。
- ruleType：订阅规则的规则类型，RuleType枚举类型(参考表3)。 |
| ListenerRule(const std::string& domain,
const std::string& eventName,
const std::string& tag,
RuleType ruleType = RuleType::WHOLE_WORD) | 接口功能：订阅规则构造函数，创建事件领域、事件名称，事件标签订阅规则对象。
输入参数：
- domain：订阅规则中指定的系统事件领域，字符串类型，最大长度16个字符（含），有效字符包含大写字母、数字及下划线。
- eventName：订阅规则中指定的系统事件名称，字符串类型，最大长度32个字符（含），有效字符包含大写字母、数字及下划线。
- tag：订阅规则中指定的系统事件标签，字符串类型，最大长度16个字符（含），有效字符包含大小写字母及数字。
- ruleType：订阅规则的规则类型，RuleType枚举类型。 |
**表3** HiSysEventListener订阅对象
| 接口名称 | 描述 |
| -------- | -------- |
| void HiSysEventListener::OnEvent(std::shared_ptr<HiSysEventRecord> sysEvent) | 接口功能：订阅事件的回调接口。
输入参数：
- sysEvent：订阅到的实时系统事件。
返回值：
无。 |
| void HiSysEventListener::OnServiceDied() | 接口功能：服务异常回调。
输入参数：
无。
返回值：
无。 |
**表4** HiSysEventRecord系统事件对象
| 接口名称 | 描述 |
| -------- | -------- |
|std::string HiSysEventRecord::AsJson()|接口功能：获取该系统事件的内容。
输入参数：
无。
返回值：
该系统事件的内容。|
|std::string HiSysEventRecord::GetDomain()|接口功能：获取该系统事件的域名。
输入参数：
无。
返回值：
该系统事件的域名。|
|std::string HiSysEventRecord::GetEventName()|接口功能：获取该系统事件的名称。
输入参数：
无。
返回值：
该系统事件的名称。|
|HiSysEvent::EventType HiSysEventRecord::GetEventType()|接口功能：获取该系统事件的类型。
输入参数：
无。
返回值：
该系统事件的类型。|
|std::string HiSysEventRecord::GetLevel()|接口功能：获取该系统事件的级别。
输入参数：
无。
返回值：
该系统事件的级别。|
|std::string HiSysEventRecord::GetTag()|接口功能：获取该系统事件的标签。
输入参数：
无。
返回值：
该系统事件的标签。|
|std::string HiSysEventRecord::GetTimeZone()|接口功能：获取该系统事件的时区。
输入参数：
无。
返回值：
时区内容，格式为“+0800”。|
|int HiSysEventRecord::GetTraceFlag()|接口功能：获取该系统事件的分布式跟踪标志位。
输入参数：
无。
返回值：
分布式跟踪标志位。|
|int64_t HiSysEventRecord::GetPid()|接口功能：获取落盘该系统事件的进程ID。
输入参数：
无。
返回值：
进程ID。|
|int64_t HiSysEventRecord::GetTid()|接口功能：获取落盘该系统事件的线程ID。
输入参数：
无。
返回值：
线程ID。|
|int64_t HiSysEventRecord::GetUid()|接口功能：获取落盘该系统事件的用户ID。
输入参数：
无。
返回值：
用户ID。|
|uint64_t HiSysEventRecord::GetPspanId()|接口功能：获取该系统事件的分布式跟踪父分支ID。
输入参数：
无。
返回值：
分布式跟踪父分支ID。|
|uint64_t HiSysEventRecord::GetSpandId()|接口功能：获取该系统事件的分布式跟踪分支ID。
输入参数：
无。
返回值：
分布式跟踪分支ID。|
|uint64_t HiSysEventRecord::GetTime()|接口功能：获取该系统事件的时间戳。
输入参数：
无。
返回值：
时间戳。|
|uint64_t HiSysEventRecord::GetTraceId()|接口功能：获取该系统事件的分布式跟踪链ID。
输入参数：
无。
返回值：
分布式跟踪链ID。|
|void HiSysEventRecord::GetParamNames(std::vector<std::string>& params)|接口功能：获取该系统事件的所有键名。
输入参数：
- params：键名数组引用。
返回值：
无。|
|int HiSysEventRecord::GetParamValue(const std::string& param, int64_t& value)|接口功能：将该系统事件键名为param的值解析为int64_t类型的值。
输入参数：
- param：键名。
- value：int64_t类型引用。
返回值：
- 0：解析成功。
- -1：该系统事件初始化失败，无法解析。
- -2：不存在的键名。
- -3：类型不匹配，无法转换成int64_t类型的值。|
|int HiSysEventRecord::GetParamValue(const std::string& param, uint64_t& value)|接口功能：将该系统事件键名为param的值解析为uint64_t类型的值。
输入参数：
- param：键名。
- value：uint64_t类型引用。
返回值：
- 0：解析成功。
- -1：该系统事件初始化失败，无法解析。
- -2：不存在的键名。
- -3：类型不匹配，无法转换成uint64_t类型的值。|
|int HiSysEventRecord::GetParamValue(const std::string& param, double& value)|接口功能：将该系统事件键名为param的值解析为double类型的值。
输入参数：
- param：键名。
- value：double类型引用。
返回值：
- 0：解析成功。
- -1：该系统事件初始化失败，无法解析。
- -2：不存在的键名。
- -3：类型不匹配，无法转换成double类型的值。|
|int HiSysEventRecord::GetParamValue(const std::string& param, std::string& value)|接口功能：将该系统事件键名为param的值解析为string类型的值。
输入参数：
- param：键名。
- value：std::string类型引用。
返回值：
- 0：解析成功。
- -1：该系统事件初始化失败，无法解析。
- -2：不存在的键名。
- -3：类型不匹配，无法转换成std::string类型的值。|
|int HiSysEventRecord::GetParamValue(const std::string& param, std::vector<int64_t>& value)|接口功能：将该系统事件键名为param的值解析为int64_t类型的数组。
输入参数：
- param：键名。
- value：int64_t类型数组引用。
返回值：
- 0：解析成功。
- -1：该系统事件初始化失败，无法解析。
- -2：不存在的键名。
- -3：类型不匹配，无法转换成int64_t类型的数组。|
|int HiSysEventRecord::GetParamValue(const std::string& param, std::vector<uint64_t>& value)|接口功能：将该系统事件键名为param的值解析为uint64_t类型的数组。
输入参数：
- param：键名。
- value：uint64_t类型数组引用。
返回值：
- 0：解析成功。
- -1：该系统事件初始化失败，无法解析。
- -2：不存在的键名。
- -3：类型不匹配，无法转换成uint64_t类型的数组。|
|int HiSysEventRecord::GetParamValue(const std::string& param, std::vector<double>& value)|接口功能：将该系统事件键名为param的值解析为double类型的数组。
输入参数：
- param：键名。
- value：double类型数组引用。
返回值：
- 0：解析成功。
- -1：该系统事件初始化失败，无法解析。
- -2：不存在的键名。
- -3：类型不匹配，无法转换成double类型的数组。|
|int HiSysEventRecord::GetParamValue(const std::string& param, std::vector<std::string>& value)|接口功能：将该系统事件键名为param的值解析为string类型的数组。
输入参数：
- param：键名。
- value：std::string类型数组引用。
返回值：
- 0：解析成功。
- -1：该系统事件初始化失败，无法解析。
- -2：不存在的键名。
- -3：类型不匹配，无法转换成std::string类型的数组。|
#### C接口说明
C HiSysEvent订阅开发能力如下：具体API详见接口目录（/base/hiviewdfx/hisysevent/interfaces/native/innerkits/hisysevent_manager/include/）。
>  **说明：**
>
> HiSysEventWatcher订阅回调结构体OnEvent回调方法形参类型HiSysEventRecord请参考[HiSysEvent查询](subsys-dfx-hisysevent-query.md)中的“表11 HiSysEventRecord事件结构体”及“表12 HiSysEventRecord解析接口”说明。
**表5** HiSysEvent订阅接口
| 接口名称 | 描述 |
| ------------------------------------------------------------ | ------------------------------------------------------------ |
| int OH_HiSysEvent_Add_Watcher(HiSysEventWatcher* watcher,
HiSysEventWatchRule rules[],
size_t ruleSize); | 接口功能：添加对系统事件的订阅，通过设置规则订阅某些特定的事件。
输入参数：
- watcher：订阅回调对象。
- rules：事件订阅规则数组。
- ruleSize：事件订阅规则数组长度。
返回值：
- 0：订阅添加成功。
- 负值：订阅添加失败。 |
| int OH_HiSysEvent_Remove_Watcher(HiSysEventWatcher* watcher); | 接口功能：移除对系统事件的订阅。
输入参数：
- watcher：订阅回调对象。
返回值：
- 0：订阅移除成功。
- 负值：订阅移除失败。 |
**表6** HiSysEventWatcher订阅回调结构体
| 属性名称 | 属性类型 | 描述 |
| ------------- | -------------------------------------------------- | ------------------------------------------------------------ |
| OnEvent | void (*)(HiSysEventRecord record); | 接口功能：订阅事件的回调接口。
输入参数：
- record：订阅到的实时系统事件。
返回值：
无。 |
| OnServiceDied | void (*)(); | 接口功能：服务异常回调。
输入参数：
无。
返回值：
无。 |
**表7** HiSysEventWatchRule订阅规则结构体
| 属性名称 | 属性类型 | 描述 |
| ------------- | --------- | ---------------------------------- |
| domain | char[] | 用来指定订阅的系统事件领域。 |
| name | char[] | 用来指定订阅的系统事件名称。 |
| tag | char[] | 用来指定订阅的系统事件标签。 |
| ruleType | int | 用于指定订阅事件的匹配规则，取值请参考[HiSysEvent查询](subsys-dfx-hisysevent-query.md)中的“表4 RuleType匹配规则类型枚举”。 |
| eventType | int | 用于指定订阅事件的事件类型，取值请参考[HiSysEvent查询](subsys-dfx-hisysevent-query.md)中的“表3 EventType事件类型枚举”，当取值0，表示订阅所有的事件类型。 |
### 开发步骤
#### C++ HiSysEvent订阅开发步骤
1. 引入对应的头文件。
```c++
#include "hisysevent_manager.h"
```
2. 业务领域实现对应的订阅回调接口。
```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. 在订阅事件的地方调用订阅接口，并传入相应的订阅回调参数、订阅规则列表，在业务结束，注销此次订阅。
```c++
auto testListener = std::make_shared();
// 事件标签规则订阅，规则类型为默认的全词匹配类型
ListenerRule tagRule("dfx");
// 事件标签规则订阅，规则类型为正则匹配类型
ListenerRule regRule("dfx.*", RuleType::REGULAR);
// 事件领域及事件名称规则订阅，规则类型为前缀匹配类型
ListenerRule domainNameRule("HIVIEWDFX", "APP_USAGE", RuleType::PREFIX);
std::vector sysRules;
sysRules.push_back(tagRule);
sysRules.push_back(regRule);
sysRules.push_back(domainNameRule);
// 开始系统事件订阅
auto ret = HiSysEventManager::AddListener(testListener, sysRules);
// 订阅结束，移除订阅回调参数。
if (ret == 0) {
HiSysEventManager::RemoveListener(testListener);
}
```
#### C HiSysEvent订阅开发步骤
1. 引入对应的头文件。
```c++
#include "hisysevent_manager_c.h"
```
2. 业务领域实现对应的订阅回调接口。
```c++
void OnEventTest(HiSysEventRecord record)
{
printf("OnEventTest: event=%s", record.jsonStr);
}
void OnServiceDiedTest()
{
printf("OnServiceDied");
}
```
3. 在订阅事件的地方调用订阅接口，并传入相应的订阅回调参数、订阅规则列表，在业务结束，注销此次订阅。
```c++
HiSysEventWatcher watcher;
watcher.OnEvent = OnEventTest;
watcher.OnServiceDied = OnServiceDiedTest;
// 事件标签规则订阅，规则类型为默认的全词匹配类型
constexpr char DFX_TAG[] = "dfx";
HiSysEventWatchRule tagRule;
(void)strcpy_s(tagRule.tag, strlen(DFX_TAG) + 1, DFX_TAG);
tagRule.ruleType = 1;
tagRule.eventType = 0;
// 事件标签规则订阅，规则类型为正则匹配类型
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;
// 事件领域及事件名称规则订阅，规则类型为前缀匹配类型
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;
// 开始系统事件订阅
HiSysEventWatchRule rules[] = {tagRule, regRule, domainNameRule};
int ret = OH_HiSysEvent_Add_Watcher(&watcher, rules, sizeof(rules) / sizeof(HiSysEventWatchRule));
// 订阅结束，移除订阅回调参数。
if (ret == 0) {
ret = OH_HiSysEvent_Remove_Watcher(&watcher);
}
```
### 开发实例
#### C++ HiSysEvent订阅开发实例
假设业务模块需要订阅事件领域为HIVIEWDFX、事件名称为PLUGIN_LOAD的所有事件，其完整使用示例如下所示：
1. 在业务模块的在BUILD.gn里增加hisysevent部件的libhisysevent及libhisyseventmanager依赖。
```c++
external_deps = [
"hisysevent:libhisysevent",
"hisysevent:libhisyseventmanager",
]
```
2. 在业务模块的TestEventListening()函数中，调用订阅接口去订阅事件，业务结束时移除事件订阅。
```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订阅开发实例
假设业务模块需要订阅事件领域为HIVIEWDFX、事件名称为PLUGIN_LOAD的所有事件，其完整使用示例如下所示：
1. 在业务模块的在BUILD.gn里增加hisysevent部件的libhisysevent及libhisyseventmanager依赖。
```c++
external_deps = [ "hisysevent:libhisyseventmanager" ]
// for strcpy_s
deps = [ "//third_party/bounds_checking_function:libsec_shared" ]
```
2. 在业务模块的TestEventListening()函数中，调用订阅接口去订阅事件，业务结束时移除事件订阅。
```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);
}
}
```