1# HiSysEvent订阅 2 3 4## 概述 5 6 7### 功能简介 8 9HiSysEvent提供了跨进程订阅机制，开发者可以通过注册订阅接口实时获取关注的事件，例如电池模块侦听功耗相关的事件，用于分析耗电情况。 10 11 12### 约束与限制 13 14在订阅HiSysEvent事件之前，需要先完成HiSysEvent打点配置，具体配置方法请参考[《HiSysEvent打点配置指导》](../subsystems/subsys-dfx-hisysevent-logging-config.md)。 15 16 17## 开发指导 18 19 20### 接口说明 21 22 **表1** HiSysEvent订阅接口 23 24| 接口名称 | 描述 | 25| -------- | -------- | 26| int32_t HiSysEventManager::AddListener(std::shared_ptr<HiSysEventListener> listener,<br/> std::vector<ListenerRule>& rules) | 接口功能：注册订阅HiSysEvent系统事件侦听对象，可设置规则订阅某些事件。<br/>输入参数：<br/>- listener：订阅回调对象。<br/>- rules：事件订阅规则。<br/>返回值：<br/>- 0：订阅成功。<br/>- 负值：订阅失败。 | 27| int32_t HiSysEventManager::RemoveListener(std::shared_ptr<HiSysEventListener> listener) | 接口功能：移除订阅hisysevent系统事件侦听对象。<br/>输入参数：<br/>- listener：订阅回调对象。<br/>返回值：<br/>- 0：取消订阅成功。<br/>- 负值：取消订阅失败。 | 28 29 **表2** ListenerRule订阅规则对象 30 31| 接口名称 | 描述 | 32| -------- | -------- | 33| ListenerRule(const std::string& tag,<br/> RuleType ruleType = RuleType::WHOLE_WORD) | 接口功能：订阅规则构造函数，创建事件标签订阅规则对象。<br/>输入参数：<br/>- tag：订阅规则的HisysEvent事件标签，字符串类型，最大长度16个字符（含），有效字符包含大小写字母及数字。<br/>- ruleType：订阅规则的规则类型，RuleType枚举类型(参考表3)。 | 34| ListenerRule(const std::string& domain,<br/> const std::string& eventName,<br/> RuleType ruleType = RuleType::WHOLE_WORD) | 接口功能：订阅规则构造函数，创建事件领域与事件名称订阅规则对象。<br/>输入参数：<br/>- domain：订阅规则的HisysEvent事件领域，字符串类型，最大长度16个字符（含），有效字符包含大写字母、数字及下划线。<br/>- eventName：订阅规则的HisysEvent事件名称，字符串类型，最大长度32个字符（含），有效字符包含大写字母、数字及下划线。<br/>- ruleType：订阅规则的规则类型，RuleType枚举类型(参考表3)。 | 35| ListenerRule(const std::string& domain,<br/> const std::string& eventName,<br/> const std::string& tag,<br/> RuleType ruleType = RuleType::WHOLE_WORD) | 接口功能：订阅规则构造函数，创建事件领域、事件名称，事件标签订阅规则对象。<br/>输入参数：<br/>- tag：订阅规则的HisysEvent事件标签，字符串类型，最大长度16个字符（含），有效字符包含大小写字母及数字。<br/>- domain：订阅规则的HisysEvent事件领域，字符串类型，最大长度16个字符（含），有效字符包含大写字母、数字及下划线。<br/>- eventName：订阅规则的HisysEvent事件名称，字符串类型，最大长度32个字符（含），有效字符包含大写字母、数字及下划线。<br/>- ruleType：订阅规则的规则类型，RuleType枚举类型(参考表3)。 | 36 37 **表3** RuleType类型 38 39| 枚举值 | 描述 | 40| -------- | -------- | 41| WHOLE_WORD | 全词匹配类型 | 42| PREFIX | 前缀匹配类型 | 43| REGULAR | 正则匹配类型 | 44 45 **表4** HiSysEventListener订阅对象 46 47| 接口名称 | 描述 | 48| -------- | -------- | 49| void HiSysEventListener::OnEvent(std::shared_ptr<HiSysEventRecord> sysEvent) | 接口功能：订阅事件的回调接口。<br/>输入参数：<br/>- sysEvent：监听到的实时HiSysEvent事件。<br/>返回值：<br/>无。 | 50| void HiSysEventListener::OnServiceDied() | 接口功能：服务异常回调。<br/>输入参数：<br/>无。<br/>返回值：<br/>无。 | 51 52**表5** HiSysEventRecord系统事件对象 53| 接口名称 | 描述 | 54| -------- | -------- | 55|std::string HiSysEventRecord::AsJson()|接口功能：获取该系统事件的内容。<br/>输入参数：<br/>无。<br/>返回值：<br/>该系统事件的内容。| 56|std::string HiSysEventRecord::GetDomain()|接口功能：获取该系统事件的域名。<br/>输入参数：<br/>无。<br/>返回值：<br/>该系统事件的域名。| 57|std::string HiSysEventRecord::GetEventName()|接口功能：获取该系统事件的名称。<br/>输入参数：<br/>无。<br/>返回值：<br/>该系统事件的名称。| 58|HiSysEvent::EventType HiSysEventRecord::GetEventType()|接口功能：获取该系统事件的类型。<br/>输入参数：<br/>无。<br/>返回值：<br/>该系统事件的类型。| 59|std::string HiSysEventRecord::GetLevel()|接口功能：获取该系统事件的级别。<br/>输入参数：<br/>无。<br/>返回值：<br/>该系统事件的级别。| 60|std::string HiSysEventRecord::GetTag()|接口功能：获取该系统事件的标签。<br/>输入参数：<br/>无。<br/>返回值：<br/>该系统事件的标签。| 61|std::string HiSysEventRecord::GetTimeZone()|接口功能：获取该系统事件的时区。<br/>输入参数：<br/>无。<br/>返回值：<br/>时区内容，格式为“+0800”。| 62|int HiSysEventRecord::GetTraceFlag()|接口功能：获取该系统事件的分布式跟踪标志位。<br/>输入参数：<br/>无。<br/>返回值：<br/>分布式跟踪标志位。| 63|int64_t HiSysEventRecord::GetPid()|接口功能：获取落盘该系统事件的进程ID。<br/>输入参数：<br/>无。<br/>返回值：<br/>进程ID。| 64|int64_t HiSysEventRecord::GetTid()|接口功能：获取落盘该系统事件的线程ID。<br/>输入参数：<br/>无。<br/>返回值：<br/>线程ID。| 65|int64_t HiSysEventRecord::GetUid()|接口功能：获取落盘该系统事件的用户ID。<br/>输入参数：<br/>无。<br/>返回值：<br/>用户ID。| 66|uint64_t HiSysEventRecord::GetPspanId()|接口功能：获取该系统事件的分布式跟踪父分支ID。<br/>输入参数：<br/>无。<br/>返回值：<br/>分布式跟踪父分支ID。| 67|uint64_t HiSysEventRecord::GetSpandId()|接口功能：获取该系统事件的分布式跟踪分支ID。<br/>输入参数：<br/>无。<br/>返回值：<br/>分布式跟踪分支ID。| 68|uint64_t HiSysEventRecord::GetTime()|接口功能：获取该系统事件的时间戳。<br/>输入参数：<br/>无。<br/>返回值：<br/>时间戳。| 69|uint64_t HiSysEventRecord::GetTraceId()|接口功能：获取该系统事件的分布式跟踪链ID。<br/>输入参数：<br/>无。<br/>返回值：<br/>分布式跟踪链ID。| 70|void HiSysEventRecord::GetParamNames(std::vector<std::string>& params)|接口功能：获取该系统事件的所有键名。<br/>输入参数：<br/>- params：键名数组引用。<br/>返回值：<br/>无。| 71|int HiSysEventRecord::GetParamValue(const std::string& param, int64_t& value)|接口功能：将该系统事件键名为param的值解析为int64_t类型的值。<br/>输入参数：<br/>- param：键名。<br/>- value：int64_t类型引用。<br/>返回值：<br/>- 0：解析成功。<br/>- -1：该系统事件初始化失败，无法解析。<br/>- -2：不存在的键名。<br/>- -3：类型不匹配，无法转换成int64_t类型的值。| 72|int HiSysEventRecord::GetParamValue(const std::string& param, uint64_t& value)|接口功能：将该系统事件键名为param的值解析为uint64_t类型的值。<br/>输入参数：<br/>- param：键名。<br/>- value：uint64_t类型引用。<br/>返回值：<br/>- 0：解析成功。<br/>- -1：该系统事件初始化失败，无法解析。<br/>- -2：不存在的键名。<br/>- -3：类型不匹配，无法转换成uint64_t类型的值。| 73|int HiSysEventRecord::GetParamValue(const std::string& param, double& value)|接口功能：将该系统事件键名为param的值解析为double类型的值。<br/>输入参数：<br/>- param：键名。<br/>- value：double类型引用。<br/>返回值：<br/>- 0：解析成功。<br/>- -1：该系统事件初始化失败，无法解析。<br/>- -2：不存在的键名。<br/>- -3：类型不匹配，无法转换成double类型的值。| 74|int HiSysEventRecord::GetParamValue(const std::string& param, std::string& value)|接口功能：将该系统事件键名为param的值解析为string类型的值。<br/>输入参数：<br/>- param：键名。<br/>- value：std::string类型引用。<br/>返回值：<br/>- 0：解析成功。<br/>- -1：该系统事件初始化失败，无法解析。<br/>- -2：不存在的键名。<br/>- -3：类型不匹配，无法转换成std::string类型的值。| 75|int HiSysEventRecord::GetParamValue(const std::string& param, std::vector<int64_t>& value)|接口功能：将该系统事件键名为param的值解析为int64_t类型的数组。<br/>输入参数：<br/>- param：键名。<br/>- value：int64_t类型数组引用。<br/>返回值：<br/>- 0：解析成功。<br/>- -1：该系统事件初始化失败，无法解析。<br/>- -2：不存在的键名。<br/>- -3：类型不匹配，无法转换成int64_t类型的数组。| 76|int HiSysEventRecord::GetParamValue(const std::string& param, std::vector<uint64_t>& value)|接口功能：将该系统事件键名为param的值解析为uint64_t类型的数组。<br/>输入参数：<br/>- param：键名。<br/>- value：uint64_t类型数组引用。<br/>返回值：<br/>- 0：解析成功。<br/>- -1：该系统事件初始化失败，无法解析。<br/>- -2：不存在的键名。<br/>- -3：类型不匹配，无法转换成uint64_t类型的数组。| 77|int HiSysEventRecord::GetParamValue(const std::string& param, std::vector<double>& value)|接口功能：将该系统事件键名为param的值解析为double类型的数组。<br/>输入参数：<br/>- param：键名。<br/>- value：ouble类型数组引用。<br/>返回值：<br/>- 0：解析成功。<br/>- -1：该系统事件初始化失败，无法解析。<br/>- -2：不存在的键名。<br/>- -3：类型不匹配，无法转换成double类型的数组。| 78|int HiSysEventRecord::GetParamValue(const std::string& param, std::vector<std::string>& value)|接口功能：将该系统事件键名为param的值解析为string类型的数组。<br/>输入参数：<br/>- param：键名。<br/>- value：std::string类型数组引用。<br/>返回值：<br/>- 0：解析成功。<br/>- -1：该系统事件初始化失败，无法解析。<br/>- -2：不存在的键名。<br/>- -3：类型不匹配，无法转换成std::string类型的数组。| 79 80 81## 开发实例 82 83 84### C++接口实例 85 86订阅HiSysEvent事件C++接口实例。 87 881. 源代码开发 89 自定义订阅回调实现类头文件DemoListener.h： 90 91 ``` 92 #ifndef DEMO_LISTENER_H 93 #define DEMO_LISTENER_H 94 95 #include "hisysevent_listener.h" 96 97 #include <string> 98 99 class DemoListener : public OHOS::HiviewDFX::HiSysEventListener { 100 public: 101 explicit DemoListener() : HiSysEventListener() {} 102 virtual ~DemoListener() {} 103 104 public: 105 void OnEvent(std::shared_ptr<HiSysEventRecord> sysEvent); 106 void OnServiceDied(); 107 }; 108 109 #endif // DEMO_LISTENER_H 110 ``` 111 112 增加DemoListener.cpp文件，在DemoListener类中根据实际需求自定义订阅回调接口的实现逻辑： 113 114 ``` 115 #include "demo_listener.h" 116 117 #include <iostream> 118 119 void DemoListener::OnEvent(std::shared_ptr<HiSysEventRecord> sysEvent) 120 { 121 if (sysEvent == nullptr) { 122 return; 123 } 124 std::cout << sysEvent.AsJson() << std::endl; 125 } 126 127 void DemoListener::OnServiceDied() 128 { 129 std::cout << std::string("service disconnect, exit") << std::endl; 130 exit(0); 131 } 132 ``` 133 134 通过HiSysEventManager类提供的AddEventListener接口注册回调对象，完成对HiSysEvent的订阅： 135 136 ``` 137 auto demoListener = std::make_shared<DemoListener>(); 138 // 事件标签规则订阅，规则类型为默认的全词匹配类型 139 ListenerRule tagRule("dfx"); 140 // 事件标签规则订阅，规则类型为正则匹配类型 141 ListenerRule regRule("dfx.*", RuleType::REGULAR); 142 // 事件领域及事件名称规则订阅，规则类型为前缀匹配类型 143 ListenerRule domainNameRule("HIVIEWDFX", "APP_USAGE", RuleType::PREFIX); 144 std::vector<ListenerRule> sysRules; 145 sysRules.push_back(tagRule); 146 sysRules.push_back(regRule); 147 sysRules.push_back(domainNameRule); 148 HiSysEventManager::AddEventListener(demoListener, sysRules); 149 ``` 150 1512. 编译配置 152 在BUILD.gn编译文件中，需要添加依赖hisysevent_native组件的libhisysevent及libhisyseventmanager库： 153 154 ``` 155 external_deps = [ 156 "hisysevent_native:libhisysevent", 157 "hisysevent_native:libhisyseventmanager", 158 ] 159 ``` 160