事件路由
1. 概述
业务软件设计开发过程中会依赖一些基础组件， 事件路由就是常见的基础组件。 本模块结合业务场景， 定制了一个基本的事件路由模块。
本文主要介绍了事件路由模块及其使用方法， 用于指导用户开发。
2. 架构原理
事件路由模块， 提供了一种事件分发的框架。 用户可以自己定义事件以及事件的处理策略。 具体系统框图组成及对外接口关系如图 15-1 所示。
图15-1 事件路由模块系统框图
概括来说， 事件路由模块主要由以下部分构成：
- 订阅者
用户自定义订阅者： 订阅者名称， 事件处理函数， 用户扩展参数， 事件是否同步处理。
- 事件定义
用户自定义事件：事件 ID， 参数 1， 参数 2， 处理结果， 创建时间， 负载。
- 事件发布
支持事件统一发布。
- 事件处理者
订阅者支持异步处理事件， 内部启动线程独立处理。
- 历史事件
支持上一次事件的查询。
3. API 参考
该功能模块为用户提供以下 API：
- HI_EVTHUB_Init： 初始化事件路由模块。
- HI_EVTHUB_Deinit： 去初始化事件路由模块。
- HI_EVTHUB_Register： 注册事件。
- HI_EVTHUB_UnRegister： 解注册事件。
- HI_EVTHUB_Publish： 发布事件。
- HI_EVTHUB_CreateSubscriber： 创建订阅者。
- HI_EVTHUB_DestroySubscriber：销毁订阅者。
- HI_EVTHUB_Subscribe： 订阅事件。
- HI_EVTHUB_UnSubscribe：解订阅事件。
- HI_EVTHUB_GetEventHistory：获取历史事件。
- HI_EVTHUB_SetEnabled：设置使能标记。
- HI_EVTHUB_GetEnabled：获取使能标记。
HI_EVTHUB_Init
【描述】
初始化事件路由模块。
【定义】
HI_S32 HI_EVTHUB_Init();
【参数】
无。
【返回值】
| 返回值 | 描述 |
|---|---|
| 0 | 成功。 |
| 非 0 | 失败，参见错误码。 |
【需求】
- 头文件： hi_eventhub.h
- 库文件： libeventhub.a/ libeventhub.so
【注意】
该模块是单实例， 仅需一次初始化。
【举例】
无。
HI_EVTHUB_Deinit
【描述】
去初始化事件路由模块。
【定义】
HI_S32 HI_EVTHUB_Deinit();
【参数】
无。
【返回值】
| 返回值 | 描述 |
|---|---|
| 0 | 成功。 |
| 非 0 | 失败，参见错误码。 |
【需求】
- 头文件： hi_eventhub.h
- 库文件： libeventhub.a/ libeventhub.so
【注意】
无。
【举例】
无。
HI_EVTHUB_Register
【描述】
注册事件。
【定义】
HI_S32 HI_EVTHUB_Register(HI_EVENT_ID EventID);
【参数】
| 参数名称 | 描述 | 输入/输出 |
|---|---|---|
| EventID | 事件 ID。 | 输入 |
【返回值】
| 返回值 | 描述 |
|---|---|
| 0 | 成功。 |
| 非 0 | 失败，参见错误码。 |
【需求】
- 头文件： hi_eventhub.h
- 库文件： libeventhub.a/ libeventhub.so
【注意】
无。
【举例】
无。
HI_EVTHUB_UnRegister
【描述】
解注册事件。
【定义】
HI_S32 HI_EVTHUB_UnRegister(HI_EVENT_ID EventID);
【参数】
| 参数名称 | 描述 | 输入/输出 |
|---|---|---|
| EventID | 事件 ID。 | 输入 |
【返回值】
| 返回值 | 描述 |
|---|---|
| 0 | 成功。 |
| 非 0 | 失败，参见错误码。 |
【需求】
- 头文件： hi_eventhub.h
- 库文件： libeventhub.a/ libeventhub.so
【注意】
无。
【举例】
无。
HI_EVTHUB_Publish
【描述】
发布事件。
【定义】
HI_S32 HI_EVTHUB_Publish(HI_EVENT_S *pEvent);
【参数】
| 参数名称 | 描述 | 输入/输出 |
|---|---|---|
| pEvent | 事件指针。 | 输入 |
【返回值】
| 返回值 | 描述 |
|---|---|
| 0 | 成功。 |
| 非 0 | 失败，参见错误码。 |
【需求】
- 头文件： hi_eventhub.h
- 库文件： libeventhub.a/ libeventhub.so
【注意】
无。
【举例】
无。
HI_EVTHUB_CreateSubscriber
【描述】
创建订阅者。
【定义】
HI_S32 HI_EVTHUB_CreateSubscriber(HI_SUBSCRIBER_S *pstSubscriber,HI_MW_PTR *ppSubscriber);
【参数】
| 参数名称 | 描述 | 输入/输出 |
|---|---|---|
| pstSubscriber | 订阅者参数。 | 输入 |
| ppSubscriber | 订阅者句柄指针。 | 输出 |
【返回值】
| 返回值 | 描述 |
|---|---|
| 0 | 成功。 |
| 非 0 | 失败，参见错误码。 |
【需求】
- 头文件： hi_eventhub.h
- 库文件： libeventhub.a/ libeventhub.so
【注意】
无。
【举例】
无。
HI_EVTHUB_DestroySubscriber
【描述】
销毁订阅者。
【定义】
HI_S32 HI_EVTHUB_DestroySubscriber(HI_MW_PTR pSubscriber);
【参数】
| 参数名称 | 描述 | 输入/输出 |
|---|---|---|
| pSubscriber | 订阅者句柄。 | 输入 |
【返回值】
| 返回值 | 描述 |
|---|---|
| 0 | 成功。 |
| 非 0 | 失败，参见错误码。 |
HI_EVTHUB_Subscribe
【描述】
订阅事件。
【定义】
HI_S32 HI_EVTHUB_Subscribe(HI_MW_PTR pSubscriber,HI_EVENT_ID EventID);
【参数】
| 参数名称 | 描述 | 输入/输出 |
|---|---|---|
| pSubscriber | 订阅者句柄。 | 输入 |
| EventID | 事件 ID。 | 输入 |
【返回值】
| 返回值 | 描述 |
|---|---|
| 0 | 成功。 |
| 非 0 | 失败，参见错误码。 |
【需求】
- 头文件： hi_eventhub.h
- 库文件： libeventhub.a/ libeventhub.so
【注意】
无。
【举例】
无。
HI_EVTHUB_UnSubscribe
【描述】
解订阅事件。
【定义】
HI_S32 HI_EVTHUB_UnSubscribe(HI_MW_PTR pSubscriber,HI_EVENT_ID EventID);
【参数】
| 参数名称 | 描述 | 输入/输出 |
|---|---|---|
| pSubscriber | 订阅者句柄。 | 输入 |
| EventID | 事件 ID。 | 输入 |
【返回值】
| 返回值 | 描述 |
|---|---|
| 0 | 成功。 |
| 非 0 | 失败，参见错误码。 |
【需求】
- 头文件： hi_eventhub.h
- 库文件： libeventhub.a/ libeventhub.so
【注意】
无。
【举例】
无。
HI_EVTHUB_GetEventHistory
【描述】
获取历史事件。
【定义】
HI_S32 HI_EVTHUB_GetEventHistory(HI_S32 EventID,HI_EVENT_S *pEvent);
【参数】
| 参数名称 | 描述 | 输入/输出 |
|---|---|---|
| EventID | 事件 ID。 | 输入 |
| pEvent | 事件指针。 | 输出 |
【返回值】
| 返回值 | 描述 |
|---|---|
| 0 | 成功。 |
| 非 0 | 失败，参见错误码。 |
【需求】
- 头文件： hi_eventhub.h
- 库文件： libeventhub.a/ libeventhub.so
【注意】
无。
【举例】
无。
HI_EVTHUB_SetEnabled
【描述】
设置使能标记。
【定义】
HI_S32 HI_EVTHUB_SetEnabled(HI_BOOL bFlag);
【参数】
| 参数名称 | 描述 | 输入/输出 |
|---|---|---|
| bFlag | 使能标记。 | 输入 |
【返回值】
| 返回值 | 描述 |
|---|---|
| 0 | 成功。 |
| 非 0 | 失败，参见错误码。 |
【需求】
- 头文件： hi_eventhub.h
- 库文件： libeventhub.a/ libeventhub.so
【注意】
无。
【举例】
无。
HI_EVTHUB_GetEnabled
【描述】
获取使能标记。
【定义】
HI_S32 HI_EVTHUB_GetEnabled(HI_BOOL *pFlag);
【参数】
| 参数名称 | 描述 | 输入/输出 |
|---|---|---|
| pFlag | 使能标记指针。 | 输出 |
【返回值】
| 返回值 | 描述 |
|---|---|
| 0 | 成功。 |
| 非 0 | 失败，参见错误码。 |
【需求】
- 头文件： hi_eventhub.h
- 库文件： libeventhub.a/ libeventhub.so
【注意】
无。
【举例】
无。
4. 数据类型
事件路由模块相关数据类型定义如下：
- EVENT_PAYLOAD_LEN： 事件负载数据最大长度。
- HI_EVTHUB_SUBSCRIBE_NAME_LEN： 订阅者名称最大长度。
- HI_EVTHUB_MESSAGEQURUR_MAX_SIZE： 消息队列最大值。
- HI_EVENT_ID： 事件 ID。
- HI_EVENT_S： 事件结构体。
- HI_SUBSCRIBER_S： 订阅者结构体。
EVENT_PAYLOAD_LEN
【说明】
事件负载数据最大长度。
【定义】
#define EVENT_PAYLOAD_LEN (512)
【注意事项】
无。
【相关数据结构及接口】
无。
HI_EVTHUB_SUBSCRIBE_NAME_LEN
【说明】
订阅者名称的最大长度。
【定义】
#define HI_EVTHUB_SUBSCRIBE_NAME_LEN (16)
【注意事项】
无。
【相关数据类型及接口】
无
HI_EVTHUB_SUBSCRIBE_NAME_LEN
【说明】
订阅者名称的最大长度。
【定义】
#define HI_EVTHUB_SUBSCRIBE_NAME_LEN (16)
【注意事项】
无。
【相关数据类型及接口】
无
HI_EVTHUB_MESSAGEQURUR_MAX_SIZE
【说明】
消息队列最大值。
【定义】
#define HI_EVTHUB_MESSAGEQURUR_MAX_SIZE (32)
【注意事项】
无。
【相关数据类型及接口】
无。
HI_EVTHUB_MESSAGEQURUR_MAX_SIZE
【说明】
消息队列最大值。
【定义】
#define HI_EVTHUB_MESSAGEQURUR_MAX_SIZE (32)
【注意事项】
无。
【相关数据类型及接口】
无。
HI_EVENT_S
【说明】
定义事件结构体。
【定义】
typedef struct hiEVENT_S
{
HI_EVENT_ID EventID;
HI_S32 arg1;
HI_S32 arg2;
HI_S32 s32Result;
HI_U64 u64CreateTime;
HI_CHAR aszPayload[EVENT_PAYLOAD_LEN];
} HI_EVENT_S;
【成员】
| 成员名称 | 描述 |
|---|---|
| EventID | 事件 ID |
| arg1 | 参数一 |
| arg2 | 参数二 |
| s32Result | 处理结果 |
| u64CreateTime | 创建时间 |
| aszPayload | 负载数据 |
【注意事项】
创建时间在事件发布时， 由模块内部获取系统 clock 时间填充， 单位秒/s。
【相关数据类型及接口】
无
HI_SUBSCRIBER_S
【说明】
定义订阅者结构体。
【定义】
typedef struct hiSUBSCRIBER_S
{
HI_CHAR azName[HI_EVTHUB_SUBSCRIBE_NAME_LEN];
HI_S32 (*HI_EVTHUB_EVENTPROC_FN_PTR)(HI_EVENT_S* pEvent, HI_VOID* argv);
HI_VOID* argv;
HI_BOOL bSync;
}HI_SUBSCRIBER_S;
【成员】
| 成员名称 | 描述 |
|---|---|
| azName | 订阅者名称。 |
| HI_EVTHUB_EVENTPROC_FN_PTR | 订阅者事件处理函数。 |
| argv | 用户定义私有参数指针。 |
| bSync | 事件处理是否同步。 |
【注意事项】
无。
【相关数据类型及接口】
无。
5 错误码
事件路由模块 API 错误码如表 15-1 所示。
表15-1 事件路由 API 错误码
| 错误代码 | 宏定义 | 描述 |
|---|---|---|
| 0xA1328002 | HI_ERR_EVTHUB_NULL_PTR | 空指针错误 |
| 0xA1328008 | HI_ERR_EVTHUB_NOT_INIT | 未初始化错误 |
| 0xA1328040 | HI_ERR_EVTHUB_HANDLE_INVALID | 非法句柄错误。 |
| 0xA1328041 | HI_ERR_EVTHUB_INVALIDARG | 非法参数 |
| 0xA1328042 | HI_ERR_EVTHUB_MALLOC | 内存申请错误 |
| 0xA1328043 | HI_ERR_EVTHUB_CREATE | 创建错误 |
| 0xA1328044 | HI_ERR_EVTHUB_DESTROY | 销毁错误 |
| 0xA1328045 | HI_ERR_EVTHUB_NOT_CREATE | 对象没有创建 |
| 0xA1328046 | HI_ERR_EVTHUB_EVENT_NO_RIGEST | 事件未注册 |
| 0xA1328047 | HI_ERR_EVTHUB_NO_EVENT_HISTORY | 历史事件不存在 |
| 0xA1328048 | HI_ERR_EVTHUB_MSGHDL_SEND | 事件路由消息发送错误 |
