/**
 * IEC104_Log.h —— IEC 60870-5-104 通用日志接口。
 *
 * 本模块独立于报文解析和链路状态，只负责：
 * 1. 按最低日志级别过滤消息；
 * 2. 为消息添加本地时间和级别前缀；
 * 3. 将完整消息交给用户回调或默认标准流。
 *
 * 公共名称全部使用 IEC104_ 前缀，可与 POSIX <syslog.h> 同时使用。
 * 构建与测试命令见 IEC104测试文档.md。
 */
#ifndef IEC104_LOG_H
#define IEC104_LOG_H

#ifdef __cplusplus
extern "C" {
#endif

/**
 * 日志级别。
 *
 * 数值必须按严重程度递增，因为过滤条件为：
 *     message_level >= minimum_level
 */
typedef enum {
    IEC104_LOG_LEVEL_DEBUG = 0,
    IEC104_LOG_LEVEL_INFO  = 1,
    IEC104_LOG_LEVEL_WARN  = 2,
    IEC104_LOG_LEVEL_ERR   = 3
} IEC104_LogLevel_t;

/**
 * 日志回调。
 *
 * level：本条消息的 IEC104_LOG_LEVEL_* 级别。
 * msg 指向已经拼接时间戳和级别、但不含行末换行的临时字符串；
 * 字符串只在本次回调期间有效，需要保留时应由回调自行复制。
 * 回调可能从不同调用线程执行，如需共享数据应自行同步。
 */
typedef void (*IEC104_LogCb_t)(int level, const char *msg);

/**
 * 功能：设置日志输出回调。
 * 输入参数：cb——回调函数；传入空指针时恢复默认标准流输出。
 * 输出参数：无。
 * 返回值：无。
 * 说明：应在开始并发输出日志之前完成配置。
 */
extern void IEC104_Set_Log_Callback(IEC104_LogCb_t cb);

/**
 * 功能：设置允许输出的最低日志级别。
 * 输入参数：min_level——IEC104_LOG_LEVEL_* 之一。
 * 输出参数：无。
 * 返回值：无。
 * 说明：应在开始并发输出日志之前完成配置。
 */
extern void IEC104_Set_Log_Level(int min_level);

/**
 * 功能：格式化并输出一条日志。
 * 输入参数：level——日志级别；fmt——非空且不含行末换行的 printf 风格格式串；
 *           其后为格式化参数。
 * 输出参数：无；日志交给回调，或默认写入 stdout/stderr。
 * 返回值：无。
 * 说明：时间戳、级别与正文合计最多保留511字节，不含结尾空字符及默认输出追加的换行；
 *       超出部分按字节截断，不保证UTF-8等多字节字符的边界完整。
 */
#if defined(__GNUC__) || defined(__clang__)
extern void IEC104_Log_Emit(int level, const char *fmt, ...)
    __attribute__((format(printf, 2, 3)));
#else
extern void IEC104_Log_Emit(int level, const char *fmt, ...);
#endif

/*
 * 便捷输出宏。
 *
 * 使用模块前缀，避免与 POSIX <syslog.h> 的 LOG_DEBUG、LOG_INFO、
 * LOG_ERR 等常量冲突。宏至少需要传入一个格式串参数。
 */
#define IEC104_LOG_DEBUG(...) \
    IEC104_Log_Emit(IEC104_LOG_LEVEL_DEBUG, __VA_ARGS__)
#define IEC104_LOG_INFO(...) \
    IEC104_Log_Emit(IEC104_LOG_LEVEL_INFO, __VA_ARGS__)
#define IEC104_LOG_WARN(...) \
    IEC104_Log_Emit(IEC104_LOG_LEVEL_WARN, __VA_ARGS__)
#define IEC104_LOG_ERR(...) \
    IEC104_Log_Emit(IEC104_LOG_LEVEL_ERR, __VA_ARGS__)

#ifdef __cplusplus
}
#endif

#endif /* IEC104_LOG_H */