137 lines
4.2 KiB
C
137 lines
4.2 KiB
C
/**
|
||
* @file lisa_evt_pub.h
|
||
* @brief LISA 事件发布器 API
|
||
*
|
||
* 此文件提供线程安全的LISA 事件发布器接口，实现观察者模式的发布-订阅机制，
|
||
* 支持事件的发布、订阅和回调处理，为组件间通信提供解耦的事件驱动架构。
|
||
*/
|
||
|
||
#ifndef __LISA_EVT_PUBLISHER_H__
|
||
#define __LISA_EVT_PUBLISHER_H__
|
||
|
||
#include <stdint.h>
|
||
#include <stddef.h>
|
||
|
||
/**
|
||
* @brief 事件发布器句柄
|
||
*
|
||
* 表示事件发布器实例的句柄类型，用于标识一个事件发布器。
|
||
*/
|
||
typedef void *lisa_evt_publisher_t;
|
||
|
||
/**
|
||
* @brief 事件发布器回调函数类型
|
||
*
|
||
* 事件订阅者的回调函数类型定义，当发布的事件被订阅时，将调用此回调函数。
|
||
*
|
||
* @param evt 事件ID，用于标识具体的事件类型
|
||
* @param data 事件数据指针，可能为 NULL
|
||
* @param data_len 事件数据长度（字节），当 data 为 NULL 时此值为 0
|
||
* @param user_data 用户自定义数据，在订阅时传入
|
||
*/
|
||
typedef void (*lisa_evt_publisher_cb_t)(uint32_t evt, void *data, uint32_t data_len,
|
||
void *user_data);
|
||
|
||
/**
|
||
* @brief 创建新的事件发布器
|
||
*
|
||
* 创建一个新的事件发布器实例，用于事件的发布和订阅管理。
|
||
* 事件按照BIT位进行管理
|
||
*
|
||
* @return 事件发布器句柄，失败时返回 NULL
|
||
*/
|
||
lisa_evt_publisher_t lisa_evt_publisher_new();
|
||
|
||
/**
|
||
* @brief 创建基于事件队列的发布器
|
||
*
|
||
* 创建一个使用事件队列的新事件发布器实例。
|
||
* 与 `lisa_evt_publisher_new()` 不同，此函数创建的发布器按照订阅事件的数值进行匹配发布，
|
||
*
|
||
*
|
||
* @return 事件发布器句柄，失败时返回 NULL
|
||
*/
|
||
lisa_evt_publisher_t lisa_evt_publisher_new_eq();
|
||
|
||
/**
|
||
* @brief 发布事件
|
||
*
|
||
* 向指定的发布器发布一个事件，所有订阅了该事件的订阅者都会收到通知。
|
||
*
|
||
* @param p 事件发布器句柄
|
||
* @param evt 事件ID，用于标识具体的事件类型
|
||
* @param data 事件数据指针，可以为 NULL
|
||
* @param len 事件数据长度（字节），当 data 为 NULL 时此值应为 0
|
||
*/
|
||
void lisa_evt_publisher_publish(lisa_evt_publisher_t p, uint32_t evt, void *data, uint32_t len);
|
||
|
||
/**
|
||
* @brief 添加事件订阅
|
||
*
|
||
* 为指定的事件ID添加订阅者，当该事件被发布时，回调函数将被调用。
|
||
*
|
||
* @param p 事件发布器句柄
|
||
* @param evt 要订阅的事件ID
|
||
* @param cb 事件回调函数指针
|
||
* @param user_data 用户自定义数据，将在回调时传递给回调函数
|
||
* @return 0 表示成功，非 0 表示失败
|
||
*/
|
||
int lisa_evt_publisher_evt_add(lisa_evt_publisher_t p, uint32_t evt, lisa_evt_publisher_cb_t cb,
|
||
void *user_data);
|
||
|
||
/**
|
||
* @brief 移除回调订阅
|
||
*
|
||
* 移除指定的回调函数订阅，该回调函数将不再接收任何事件通知。
|
||
*
|
||
* @param p 事件发布器句柄
|
||
* @param cb 要移除的回调函数指针
|
||
*/
|
||
void lisa_evt_publisher_cb_remove(lisa_evt_publisher_t p, lisa_evt_publisher_cb_t cb);
|
||
|
||
/**
|
||
* @brief 清空所有订阅
|
||
*
|
||
* 清空事件发布器中的所有事件订阅，移除所有订阅者。
|
||
*
|
||
* @param p 事件发布器句柄
|
||
* @return 0 表示成功，非 0 表示失败
|
||
*/
|
||
int lisa_evt_publisher_clear(lisa_evt_publisher_t p);
|
||
|
||
/**
|
||
* @brief 销毁事件发布器
|
||
*
|
||
* 销毁指定的事件发布器，释放所有相关资源。
|
||
* 销毁后会自动清理所有的事件订阅。
|
||
*
|
||
* @param p 事件发布器句柄
|
||
*/
|
||
void lisa_evt_publisher_destroy(lisa_evt_publisher_t p);
|
||
|
||
/**
|
||
* @brief 发布无数据事件
|
||
*
|
||
* 便利函数，用于发布不携带任何数据的事件。
|
||
* 相当于调用 `lisa_evt_publisher_publish(p, evt, NULL, 0)`。
|
||
*
|
||
* @param p 事件发布器句柄
|
||
* @param evt 事件ID，用于标识具体的事件类型
|
||
*/
|
||
static inline void lisa_evt_publisher_publish_without_data(lisa_evt_publisher_t p, uint32_t evt)
|
||
{
|
||
lisa_evt_publisher_publish(p, evt, NULL, 0);
|
||
}
|
||
|
||
/**
|
||
* @brief 检查事件是否有订阅者
|
||
*
|
||
* 检查指定的事件ID是否已被订阅，即是否有订阅者会接收该事件的通知。
|
||
*
|
||
* @param p 事件发布器句柄
|
||
* @param evt 要检查的事件ID
|
||
* @return 1 表示有订阅者，0 表示无订阅者
|
||
*/
|
||
int lisa_evt_publisher_has_subscriber(lisa_evt_publisher_t p, uint32_t evt);
|
||
#endif
|