HiSysEvent订阅

概述

功能简介

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

约束与限制

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

开发指导

接口说明

C++接口说明

C++ HiSysEvent订阅开发能力如下：HiSysEventManager类，具体API详见接口目录（/base/hiviewdfx/hisysevent/interfaces/native/innerkits/hisysevent_manager/include/）。

icon-note.gif 说明：

ListenerRule订阅规则对象构造函数形参类型RuleType请参考HiSysEvent查询中的“表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：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接口说明

C HiSysEvent订阅开发能力如下：具体API详见接口目录（/base/hiviewdfx/hisysevent/interfaces/native/innerkits/hisysevent_manager/include/）。

icon-note.gif 说明：

HiSysEventWatcher订阅回调结构体OnEvent回调方法形参类型HiSysEventRecord请参考HiSysEvent查询中的“表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查询中的“表4 RuleType匹配规则类型枚举”。
eventType int 用于指定订阅事件的事件类型，取值请参考HiSysEvent查询中的“表3 EventType事件类型枚举”，当取值0，表示订阅所有的事件类型。

开发步骤

C++ HiSysEvent订阅开发步骤

  1. 引入对应的头文件。

    #include "hisysevent_manager.h"

  2. 业务领域实现对应的订阅回调接口。

    class TestListener : public OHOS::HiviewDFX::HiSysEventListener {
public:
    void OnEvent(std::shared_ptr<HiSysEventRecord> 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. 在订阅事件的地方调用订阅接口，并传入相应的订阅回调参数、订阅规则列表，在业务结束，注销此次订阅。

    auto testListener = std::make_shared<TestListener>();
// 事件标签规则订阅，规则类型为默认的全词匹配类型
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);
// 开始系统事件订阅
auto ret = HiSysEventManager::AddListener(testListener, sysRules);
// 订阅结束，移除订阅回调参数。
if (ret == 0) {
   HiSysEventManager::RemoveListener(testListener);
}

C HiSysEvent订阅开发步骤

  1. 引入对应的头文件。

    #include "hisysevent_manager_c.h"

  2. 业务领域实现对应的订阅回调接口。

    void OnEventTest(HiSysEventRecord record)
{
    printf("OnEventTest: event=%s", record.jsonStr);
}

void OnServiceDiedTest()
{
    printf("OnServiceDied");
}

  3. 在订阅事件的地方调用订阅接口，并传入相应的订阅回调参数、订阅规则列表，在业务结束，注销此次订阅。

    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依赖。

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

  2. 在业务模块的TestEventListening()函数中，调用订阅接口去订阅事件，业务结束时移除事件订阅。

    #include <iostream>

#include "hisysevent_manager.h"

using namespace OHOS::HiviewDFX;

class TestListener : public HiSysEventQueryCallback {
public:
    void OnEvent(std::shared_ptr<HiSysEventRecord> 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<TestListener>();
    ListenerRule domainNameRule("HIVIEWDFX", "PLUGIN_LOAD", RuleType::WHOLE_WORD);
    std::vector<ListenerRule> 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依赖。

    external_deps = [ "hisysevent:libhisyseventmanager" ]

// for strcpy_s
deps = [ "//third_party/bounds_checking_function:libsec_shared" ]

  2. 在业务模块的TestEventListening()函数中，调用订阅接口去订阅事件，业务结束时移除事件订阅。

    #include <securec.h>

#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);
   }
}