/**
 * @file datarouter.h
 * @brief 数据路由库 —— 公共接口
 *
 * ## 概念
 *
 * - **发送能力 (Send Capability)**：编译期声明的可发送报文类型
 * - **接收能力 (Recv Capability)**：编译期声明的可接收报文类型
 * - **端口 (Port)**：运行期连接点，独立设置 send_type + recv_type + 外设 handler 列表
 *
 * ## 使用流程
 *
 * 1. 创建 datarouter_config.h 声明发送和接收能力（见 datarouter_config_template.h）
 * 2. 编译时通过 -I 指向你的配置目录；若无，库使用内置默认配置
 * 3. datarouter_init() 初始化
 * 4. port_create() 创建端口
 * 5. port_set_send_type() 设置发送类型 / port_set_recv_type() 设置接收类型
 * 6. port_add_handler() 注册外设发送函数
 * 7. 调 datarouter_send_<id>() 触发发送（库调用所有 handler）
 * 8. 实现 datarouter_on_recv_<id>() 处理接收数据
 */

#ifndef DATAROUTER_H
#define DATAROUTER_H

#include <stdint.h>
#include <stddef.h>

/*
 * 配置加载策略：
 *   1. 优先从 include path 搜索 <datarouter_config.h>（用户提供的版本）
 *   2. 找不到则回退到库自带的 "datarouter_config.h"（默认配置）
 *
 * 用户只需将自己的 datarouter_config.h 放到项目目录，
 * 编译时添加 -I /path/to/your/config 即可覆盖内置配置。
 */
#if defined(__has_include)
#  if __has_include(<datarouter_config.h>)
#    include <datarouter_config.h>
#  else
#    include "datarouter_config.h"
#  endif
#else
#  include "datarouter_config.h"
#endif

#ifdef __cplusplus
extern "C" {
#endif

/* ========== 发送能力枚举 ========== */

enum datarouter_send_cap {
#define DATAROUTER_SEND(id, desc) DATAROUTER_SEND_##id,
    DATAROUTER_SEND_CAPABILITIES
#undef DATAROUTER_SEND
    DATAROUTER_SEND_CAP_COUNT
};

/* ========== 接收能力枚举 ========== */

enum datarouter_recv_cap {
#define DATAROUTER_RECV(id, desc) DATAROUTER_RECV_##id,
    DATAROUTER_RECV_CAPABILITIES
#undef DATAROUTER_RECV
    DATAROUTER_RECV_CAP_COUNT
};

/* ========== 外设发送 handler 类型 ========== */

typedef void (*datarouter_send_handler_t)(uint32_t port_id, const void *data, size_t len);

#ifndef DATAROUTER_MAX_HANDLERS_PER_PORT
#define DATAROUTER_MAX_HANDLERS_PER_PORT 4
#endif

/* ========== 发送触发函数（每个发送能力生成一个） ========== */

#define DATAROUTER_SEND(id, desc) \
    int datarouter_send_##id(uint32_t port_id, const void *data, size_t len);
DATAROUTER_SEND_CAPABILITIES
#undef DATAROUTER_SEND

/* ========== 接收回调声明（每个接收能力生成一个，用户实现） ========== */

#define DATAROUTER_RECV(id, desc) \
    void datarouter_on_recv_##id(uint32_t port_id, const void *data, size_t len);
DATAROUTER_RECV_CAPABILITIES
#undef DATAROUTER_RECV

/* ========== 端口管理 API ========== */

typedef int32_t datarouter_port_t;
#define DATAROUTER_INVALID_PORT ((datarouter_port_t)-1)

void datarouter_init(void);
void datarouter_reset(void);

datarouter_port_t datarouter_port_create(void);
void datarouter_port_delete(datarouter_port_t port);

void datarouter_port_set_send_type(datarouter_port_t port, int cap_id);
int  datarouter_port_get_send_type(datarouter_port_t port);
void datarouter_port_set_recv_type(datarouter_port_t port, int cap_id);
int  datarouter_port_get_recv_type(datarouter_port_t port);

int  datarouter_port_add_handler(datarouter_port_t port, datarouter_send_handler_t handler);
int  datarouter_port_remove_handler(datarouter_port_t port, datarouter_send_handler_t handler);
void datarouter_port_clear_handlers(datarouter_port_t port);
int  datarouter_port_handler_count(datarouter_port_t port);

/* ========== 能力元数据查询 ========== */

int         datarouter_send_cap_count(void);
const char *datarouter_send_cap_name(int cap_id);
const char *datarouter_send_cap_desc(int cap_id);

int         datarouter_recv_cap_count(void);
const char *datarouter_recv_cap_name(int cap_id);
const char *datarouter_recv_cap_desc(int cap_id);

#ifdef __cplusplus
}
#endif

#endif /* DATAROUTER_H */