事件订阅（C/C++）
===========

HiAppEvent提供了事件订阅接口，用于订阅并接收应用产生的事件。

#### 接口说明

API接口的使用说明，包括参数使用限制和取值范围，请参考[hiappevent.h](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-hiappevent-h)。

**订阅接口功能介绍**：

| 接口名 | 描述 |
| :-- | :-- |
| int OH\_HiAppEvent\_AddWatcher(HiAppEvent\_Watcher\* watcher) | 添加应用的事件观察者。 |
| int OH\_HiAppEvent\_RemoveWatcher(HiAppEvent\_Watcher\* watcher) | 移除应用的事件观察者。 |

**打点接口功能介绍**：

| 接口名 | 描述 |
| :-- | :-- |
| int OH\_HiAppEvent\_Write(const char\* domain, const char\* name, enum EventType type, const ParamList list) | 实现对参数为列表类型的应用事件打点。 |

#### 事件订阅开发指导

以订阅崩溃事件（系统事件）和按钮点击事件（应用事件）为例，说明开发步骤。

#### \[h2\]步骤一：新建工程及编译配置

1.  将示例工程依赖的jsoncpp库文件复制到新建工程中。
    
    打开链接[HiAppEvent示例工程EventSub](https://gitcode.com/openharmony/applications_app_samples/tree/master/code/DocsSample/PerformanceAnalysisKit/HiAppEvent/EventSub)，并点击“下载当前目录”，下载EventSub工程文件。
    
    新建一个Native C++工程。从解压后的EventSub文件夹中拷贝jsoncpp库文件（entry/libs和entry/src/main/cpp/thirdparty整个目录）到新建的工程中，得到的目录结构如下：
    
    entry
    ├── libs        // 自行创建文件夹,放入相关的三方库
    └── src
        ├── main
        │   ├── cpp
        │   │   ├── CMakeLists.txt       // 导入so链接
        │   │   ├── napi\_init.cpp        // 功能函数，观察者定义
        │   │   ├── thirdparty    // 自行创建文件夹,放入相关的三方库
        │   │   │   └── jsoncpp
        │   │   └── types
        │   │       └── libentry
        │   │           ├── Index.d.ts        // 定义ArkTS接口
        │   │           └── oh-package.json5
        │   ├── ets
        │   │   ├── entryability
        │   │   │   └── EntryAbility.ets    // 新增接口调用
        │   │   ├── entrybackupability
        │   │   │   └── EntryBackupAbility.ets
        │   │   └── pages
        │   │       └── Index.ets        // 主页
    
    该示例工程中jsoncpp库文件对应的源码来自[三方开源库jsoncpp](https://github.com/open-source-parsers/jsoncpp/archive/refs/tags/1.9.6.tar.gz)。
    
2.  编辑“CMakeLists.txt”文件，添加所需的源文件和动态库。
    
    set(GZ\_FILE "${CMAKE\_CURRENT\_SOURCE\_DIR}/thirdparty/jsoncpp/src/jsoncpp-1.9.6.tar.gz")
    set(DEST\_DIR "${CMAKE\_CURRENT\_SOURCE\_DIR}/../../../build")
    # 检查是否存在entry/build目录
    execute\_process(COMMAND ${CMAKE\_COMMAND} -E make\_directory ${DEST\_DIR})
    # 解压jsoncpp-1.9.6.tar.gz到entry/build，得到jsoncpp头文件的目录
    execute\_process(COMMAND tar -xzf ${GZ\_FILE} -C ${DEST\_DIR}
        WORKING\_DIRECTORY ${DEST\_DIR})
    
    add\_library(entry SHARED napi\_init.cpp)
    # 新增动态库依赖libhiappevent\_ndk.z.so和libhilog\_ndk.z.so(日志输出)
    target\_link\_libraries(entry PUBLIC libace\_napi.z.so libhilog\_ndk.z.so libhiappevent\_ndk.z.so)
    # 新增三方库依赖libjsoncpp.so(解析订阅事件中的json字符串)
    target\_link\_libraries(entry PRIVATE ${CMAKE\_CURRENT\_SOURCE\_DIR}/thirdparty/jsoncpp/${OHOS\_ARCH}/lib/libjsoncpp.so)
    target\_include\_directories(entry PRIVATE ${DEST\_DIR}/jsoncpp-1.9.6/include/json)
    
3.  编辑“napi\_init.cpp”文件，导入依赖的文件并定义LOG\_TAG：
    
    #include "napi/native\_api.h"
    // 根据工程中三方库jsoncpp的位置适配引用json.h的路径
    #include "../../../build/jsoncpp-1.9.6/include/json/json.h"
    #include "hiappevent/hiappevent.h"
    #include "hilog/log.h"
    
    #undef LOG\_TAG
    #define LOG\_TAG "testTag"
    

#### \[h2\]步骤二：订阅事件

1.  订阅事件。分别使用OnReceive类型观察者、OnTrigger类型观察者的订阅方式。
    
    *   订阅崩溃事件（系统事件），采用OnReceive类型观察者的订阅方式，观察者接收到事件后会立即触发OnReceive()回调。编辑“napi\_init.cpp”文件，定义OnReceive类型观察者相关方法：
    
    // 定义变量，用来缓存创建的观察者的指针。
    static HiAppEvent\_Watcher \*eventWatcherR1;
    
    static void OnReceive1(const char \*domain, const struct HiAppEvent\_AppEventGroup \*appEventGroups, uint32\_t groupLen)
    {
        OH\_LOG\_INFO(LogType::LOG\_APP, "AppEvents HiAppEvent success to read events with onReceive callback from C API \\n");
        for (int i = 0; i < groupLen; ++i) {
            for (int j = 0; j < appEventGroups\[i\].infoLen; ++j) {
                OH\_LOG\_INFO(LogType::LOG\_APP, "AppEvents HiAppEvent eventInfo.domain=%{public}s",
                    appEventGroups\[i\].appEventInfos\[j\].domain);
                OH\_LOG\_INFO(LogType::LOG\_APP, "AppEvents HiAppEvent eventInfo.name=%{public}s",
                    appEventGroups\[i\].appEventInfos\[j\].name);
                OH\_LOG\_INFO(LogType::LOG\_APP, "AppEvents HiAppEvent eventInfo.eventType=%{public}d",
                    appEventGroups\[i\].appEventInfos\[j\].type);
                if (strcmp(appEventGroups\[i\].appEventInfos\[j\].domain, DOMAIN\_OS) != 0 ||
                    strcmp(appEventGroups\[i\].appEventInfos\[j\].name, EVENT\_APP\_CRASH) != 0) {
                    continue;
                }
                Json::Value params;
                Json::Reader reader(Json::Features::strictMode());
                Json::FastWriter writer;
                if (reader.parse(appEventGroups\[i\].appEventInfos\[j\].params, params)) {
                    // 开发者可以获取到崩溃事件发生的时间戳
                    OH\_LOG\_INFO(LogType::LOG\_APP, "AppEvents HiAppEvent eventInfo.params.time=%{public}lld",
                        params\["time"\].asInt64());
                    // 开发者可以获取到崩溃应用的包名
                    OH\_LOG\_INFO(LogType::LOG\_APP, "AppEvents HiAppEvent eventInfo.params.bundle\_name=%{public}s",
                        params\["bundle\_name"\].asString().c\_str());
                    auto external\_log = writer.write(params\["external\_log"\]);
                    // 开发者可以获取到崩溃事件发生时的故障日志文件
                    OH\_LOG\_INFO(LogType::LOG\_APP, "AppEvents HiAppEvent eventInfo.params.external\_log=%{public}s",
                        external\_log.c\_str());
                }
            }
        }
    }
    static napi\_value RegisterWatcherCrash(napi\_env env, napi\_callback\_info info)
    {
        // 开发者自定义观察者名称，系统根据不同的名称来识别不同的观察者。
        eventWatcherR1 = OH\_HiAppEvent\_CreateWatcher("AppCrashWatcher1");
        // 设置订阅的事件名称为EVENT\_APP\_CRASH，即崩溃事件。
        const char \*names\[\] = {EVENT\_APP\_CRASH};
        // 开发者订阅感兴趣的事件，此处订阅了系统事件。
        OH\_HiAppEvent\_SetAppEventFilter(eventWatcherR1, DOMAIN\_OS, 0, names, 1);
        // 开发者设置已实现的回调函数，观察者接收到事件后会立即触发OnReceive1回调。
        OH\_HiAppEvent\_SetWatcherOnReceive(eventWatcherR1, OnReceive1);
        // 使观察者开始监听订阅的事件。
        OH\_HiAppEvent\_AddWatcher(eventWatcherR1);
        return {};
    }
    
    *   订阅按钮点击事件（应用事件），采用OnTrigger类型观察者的订阅方式。需满足OH\_HiAppEvent\_SetTriggerCondition()设置的条件，才能触发OnTrigger()回调。编辑 “napi\_init.cpp”文件，定义OnTrigger类型观察者相关方法：
    
    // 定义变量，用来缓存创建的观察者的指针。
    static HiAppEvent\_Watcher \*eventWatcherT1;
    // 开发者可以自行实现获取已监听到事件的回调函数，其中events指针指向内容仅在该函数内有效。
    static void OnTake1(const char \*const \*events, uint32\_t eventLen)
    {
        Json::Reader reader(Json::Features::strictMode());
        OH\_LOG\_INFO(LogType::LOG\_APP, "AppEvents HiAppEvent success to read events with onTrigger callback from C API \\n");
        for (int i = 0; i < eventLen; ++i) {
            OH\_LOG\_INFO(LogType::LOG\_APP, "AppEvents HiAppEvent eventInfo=%{public}s", events\[i\]);
            Json::Value eventInfo;
            if (reader.parse(events\[i\], eventInfo)) {
                auto domain = eventInfo\["domain\_"\].asString();
                auto name = eventInfo\["name\_"\].asString();
                auto type = eventInfo\["type\_"\].asInt();
                OH\_LOG\_INFO(LogType::LOG\_APP, "AppEvents HiAppEvent eventInfo.domain=%{public}s", domain.c\_str());
                OH\_LOG\_INFO(LogType::LOG\_APP, "AppEvents HiAppEvent eventInfo.name=%{public}s", name.c\_str());
                OH\_LOG\_INFO(LogType::LOG\_APP, "AppEvents HiAppEvent eventInfo.eventType=%{public}d", type);
                if (domain == "button" && name == "click") {
                    auto clickTime = eventInfo\["clickTime"\].asInt64();
                    OH\_LOG\_INFO(LogType::LOG\_APP, "AppEvents HiAppEvent eventInfo.params.clickTime=%{public}lld",
                        clickTime);
                }
            }
        }
    }
    
    // 开发者可以自行实现订阅回调函数，以便对获取到的事件打点数据进行自定义处理。
    static void OnTrigger1(int row, int size)
    {
        // 接收回调后，获取指定数量的已接收事件。
        OH\_HiAppEvent\_TakeWatcherData(eventWatcherT1, row, OnTake1);
    }
    
    static napi\_value RegisterWatcherClick(napi\_env env, napi\_callback\_info info)
    {
        // 开发者自定义观察者名称，系统根据不同的名称来识别不同的观察者。
        eventWatcherT1 = OH\_HiAppEvent\_CreateWatcher("ButtonClickWatcher1");
        // 设置订阅的事件名称为click。
        const char \*names\[\] = {"click"};
        // 开发者订阅感兴趣的应用事件，此处订阅了button相关事件。
        OH\_HiAppEvent\_SetAppEventFilter(eventWatcherT1, "button", 0, names, 1);
        // 开发者设置已实现的回调函数，需OH\_HiAppEvent\_SetTriggerCondition设置的条件满足方可触发。
        OH\_HiAppEvent\_SetWatcherOnTrigger(eventWatcherT1, OnTrigger1);
        // 开发者可以设置订阅触发回调的条件，此处是设置新增事件打点数量为1个时，触发onTrigger回调。
        OH\_HiAppEvent\_SetTriggerCondition(eventWatcherT1, 1, 0, 0);
        // 使观察者开始监听订阅的事件。
        OH\_HiAppEvent\_AddWatcher(eventWatcherT1);
        return {};
    }
    
2.  编辑“napi\_init.cpp”文件，添加按钮点击事件的打点接口：
    
    static napi\_value WriteAppEvent(napi\_env env, napi\_callback\_info info)
    {
        auto params = OH\_HiAppEvent\_CreateParamList();
        OH\_HiAppEvent\_AddInt64Param(params, "clickTime", time(nullptr));
        OH\_HiAppEvent\_Write("button", "click", EventType::BEHAVIOR, params);
        OH\_HiAppEvent\_DestroyParamList(params);
        OH\_LOG\_INFO(LogType::LOG\_APP, "writeEvent C++ success");
        return {};
    }
    
3.  编辑“napi\_init.cpp”文件，注册RegisterWatcherCrash()(订阅崩溃事件)、RegisterWatcherClick()（订阅按钮点击事件）、WriteAppEvent()(按钮点击事件打点接口)为ArkTS接口：
    
    // ...
    
    static napi\_value Init(napi\_env env, napi\_value exports)
    {
        napi\_property\_descriptor desc\[\] = {
            // ...
            { "registerWatcherCrash", nullptr, RegisterWatcherCrash, nullptr, nullptr, nullptr, napi\_default, nullptr },
            { "registerWatcherClick", nullptr, RegisterWatcherClick, nullptr, nullptr, nullptr, napi\_default, nullptr },
            { "writeAppEvent", nullptr, WriteAppEvent, nullptr, nullptr, nullptr, napi\_default, nullptr },
            // ...
        };
        napi\_define\_properties(env, exports, sizeof(desc) / sizeof(desc\[0\]), desc);
        return exports;
    }
    
4.  编辑“index.d.ts”文件，定义ArkTS接口：
    
    export const registerWatcherCrash: () => void;
    export const registerWatcherClick: () => void;
    export const writeAppEvent: () => void;
    
5.  编辑“EntryAbility.ets”文件，在onCreate()函数中添加接口调用：
    
    import testNapi from 'libentry.so';
    
    // 在onCreate()函数中添加C API接口调用
    // 启动时，注册崩溃事件观察者
    testNapi.registerWatcherCrash();
    // 启动时，注册按钮点击事件观察者
    testNapi.registerWatcherClick();
    

#### \[h2\]步骤三：触发事件

编辑“Index.ets”文件，新增“WatchAppCrash ArkTS&C++”按钮以触发崩溃事件；新增“writeEvent C++”按钮，在按钮点击函数中进行事件打点。示例代码如下：

import testNapi from 'libentry.so';

Button('WatchAppCrash ArkTS&C++')
  .type(ButtonType.Capsule)
  .margin({
    top: 20
  })
  .backgroundColor('#0D9FFB')
  .width('80%')
  .height('5%')
  .onClick(() => {
    // 在按钮点击函数中构造一个crash场景，触发崩溃事件
    let result: object = JSON.parse('');
  })

Button('writeEvent C++')
  .type(ButtonType.Capsule)
  .margin({
    top: 20
  })
  .backgroundColor('#0D9FFB')
  .width('80%')
  .height('5%')
  .onClick(() => {
    testNapi.writeAppEvent();
  })

#### 调测验证

1.  点击DevEco Studio界面中的运行按钮，运行应用工程。在应用界面中点击“WatchAppCrash ArkTS&C++”按钮，触发崩溃事件。应用退出后重新打开应用。
    
2.  搜索关键字“AppEvents”，在HiLog窗口查看应用处理崩溃事件数据的日志：
    
    AppEvents HiAppEvent success to read events with onReceive callback from C API
    AppEvents HiAppEvent eventInfo.domain=OS
    AppEvents HiAppEvent eventInfo.name=APP\_CRASH
    AppEvents HiAppEvent eventInfo.eventType=1
    AppEvents HiAppEvent eventInfo.params.time=1750946685473
    AppEvents HiAppEvent eventInfo.params.bundle\_name=com.example.cxxxx
    AppEvents HiAppEvent eventInfo.params.external\_log=\["/data/storage/el2/log/hiappevent/APP\_CRASH\_1750946685805\_64003.log"\]
    
3.  点击“writeEvent C++”按钮，触发按钮点击事件。搜索关键字“AppEvents”，在HiLog窗口查看应用处理按钮点击事件数据的日志：
    
    AppEvents HiAppEvent success to read events with onTrigger callback from C API
    AppEvents HiAppEvent eventInfo={"domain\_":"button","name\_":"click","type\_":4,"time\_":1750947007108,"tz\_":"","pid\_":64750,"tid\_":64750,"clickTime":1750947007}
    AppEvents HiAppEvent eventInfo.domain=button
    AppEvents HiAppEvent eventInfo.name=click
    AppEvents HiAppEvent eventInfo.eventType=4
    AppEvents HiAppEvent eventInfo.params.clickTime=1750947007
    
4.  移除应用的事件观察者：
    
    static napi\_value RemoveWatcher(napi\_env env, napi\_callback\_info info)
    {
        // 使观察者停止监听事件
        // ...
        OH\_HiAppEvent\_RemoveWatcher(eventWatcherT1);
        OH\_HiAppEvent\_RemoveWatcher(eventWatcherR1);
        // ...
        return {};
    }
    
5.  销毁应用的事件观察者：
    
    static napi\_value DestroyWatcher(napi\_env env, napi\_callback\_info info)
    {
        // 销毁创建的观察者，并置eventWatcher为nullptr。
        // ...
        OH\_HiAppEvent\_DestroyWatcher(eventWatcherT1);
        OH\_HiAppEvent\_DestroyWatcher(eventWatcherR1);
        eventWatcherT1 = nullptr;
        eventWatcherR1 = nullptr;
        // ...
        return {};
    }