HiSysEvent订阅

概述

功能简介

HiSysEvent提供了跨进程订阅机制，开发者可以通过注册订阅接口实时获取关注的事件，例如电池模块侦听功耗相关的事件，用于分析耗电情况。

约束与限制

在订阅HiSysEvent事件之前，需要先完成HiSysEvent打点配置，具体配置方法请参考《HiSysEvent打点配置指导》。

开发指导

接口说明

表1 HiSysEvent订阅接口

接口名称 描述
int32_t HiSysEventManager::AddListener(std::shared_ptr<HiSysEventListener> listener,
 std::vector<ListenerRule>& rules)		 接口功能：注册订阅HiSysEvent系统事件侦听对象，可设置规则订阅某些事件。
输入参数：
- listener：订阅回调对象。
- rules：事件订阅规则。
返回值：
- 0：订阅成功。
- 负值：订阅失败。
int32_t HiSysEventManager::RemoveListener(std::shared_ptr<HiSysEventListener> listener) 接口功能：移除订阅hisysevent系统事件侦听对象。
输入参数：
- listener：订阅回调对象。
返回值：
- 0：取消订阅成功。
- 负值：取消订阅失败。

表2 ListenerRule订阅规则对象

接口名称 描述
ListenerRule(const std::string& tag,
 RuleType ruleType = RuleType::WHOLE_WORD)		 接口功能：订阅规则构造函数，创建事件标签订阅规则对象。
输入参数：
- tag：订阅规则的HisysEvent事件标签，字符串类型，最大长度16个字符（含），有效字符包含大小写字母及数字。
- ruleType：订阅规则的规则类型，RuleType枚举类型(参考表3)。
ListenerRule(const std::string& domain,
 const std::string& eventName,
 RuleType ruleType = RuleType::WHOLE_WORD)		 接口功能：订阅规则构造函数，创建事件领域与事件名称订阅规则对象。
输入参数：
- domain：订阅规则的HisysEvent事件领域，字符串类型，最大长度16个字符（含），有效字符包含大写字母、数字及下划线。
- eventName：订阅规则的HisysEvent事件名称，字符串类型，最大长度32个字符（含），有效字符包含大写字母、数字及下划线。
- ruleType：订阅规则的规则类型，RuleType枚举类型(参考表3)。
ListenerRule(const std::string& domain,
 const std::string& eventName,
 const std::string& tag,
 RuleType ruleType = RuleType::WHOLE_WORD)		 接口功能：订阅规则构造函数，创建事件领域、事件名称，事件标签订阅规则对象。
输入参数：
- tag：订阅规则的HisysEvent事件标签，字符串类型，最大长度16个字符（含），有效字符包含大小写字母及数字。
- domain：订阅规则的HisysEvent事件领域，字符串类型，最大长度16个字符（含），有效字符包含大写字母、数字及下划线。
- eventName：订阅规则的HisysEvent事件名称，字符串类型，最大长度32个字符（含），有效字符包含大写字母、数字及下划线。
- ruleType：订阅规则的规则类型，RuleType枚举类型(参考表3)。

表3 RuleType类型

枚举值 描述
WHOLE_WORD 全词匹配类型
PREFIX 前缀匹配类型
REGULAR 正则匹配类型

表4 HiSysEventListener订阅对象

接口名称 描述
void HiSysEventListener::OnEvent(std::shared_ptr<HiSysEventRecord> sysEvent) 接口功能：订阅事件的回调接口。
输入参数：
- sysEvent：监听到的实时HiSysEvent事件。
返回值：
无。
void HiSysEventListener::OnServiceDied() 接口功能：服务异常回调。
输入参数：
无。
返回值：
无。

表5 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：ouble类型数组引用。
返回值：
- 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++接口实例

订阅HiSysEvent事件C++接口实例。

  1. 源代码开发 自定义订阅回调实现类头文件DemoListener.h：

    #ifndef DEMO_LISTENER_H
#define DEMO_LISTENER_H

#include "hisysevent_listener.h"

#include <string>

class DemoListener : public OHOS::HiviewDFX::HiSysEventListener {
public:
    explicit DemoListener() : HiSysEventListener() {}
  virtual ~DemoListener() {}

public:
    void OnEvent(std::shared_ptr<HiSysEventRecord> sysEvent);
    void OnServiceDied();
};

#endif // DEMO_LISTENER_H

    增加DemoListener.cpp文件，在DemoListener类中根据实际需求自定义订阅回调接口的实现逻辑：

    #include "demo_listener.h"

#include <iostream>

void DemoListener::OnEvent(std::shared_ptr<HiSysEventRecord> 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);
}

    通过HiSysEventManager类提供的AddEventListener接口注册回调对象，完成对HiSysEvent的订阅：

    auto demoListener = std::make_shared<DemoListener>();
// 事件标签规则订阅，规则类型为默认的全词匹配类型
ListenerRule tagRule("dfx");
// 事件标签规则订阅，规则类型为正则匹配类型
ListenerRule regRule("dfx.*", RuleType::REGULAR);
// 事件领域及事件名称规则订阅，规则类型为前缀匹配类型
ListenerRule domainNameRule("HIVIEWDFX", "APP_USAGE", RuleType::PREFIX);
std::vector<ListenerRule> sysRules;
sysRules.push_back(tagRule);
sysRules.push_back(regRule);
sysRules.push_back(domainNameRule);
HiSysEventManager::AddEventListener(demoListener, sysRules);

  2. 编译配置 在BUILD.gn编译文件中，需要添加依赖hisysevent_native组件的libhisysevent及libhisyseventmanager库：

    external_deps = [
  "hisysevent_native:libhisysevent",
  "hisysevent_native:libhisyseventmanager",
]