/* * 附录 B 历史 XML 编码:将 SOE、遥控操作、日极值和定点记录转换为传输文件。 * 编码器分片输出、不分配堆内存,不访问文件系统或传输层。 * 记录持久化由历史核心/后端负责;对外可重复读取的冻结文件由调用方保存。 */ #ifndef IEC60870_HISTORY_FILE_H #define IEC60870_HISTORY_FILE_H #include "IEC60870_History.h" #ifdef __cplusplus extern "C" { #endif /* 路径容量包含末尾 NUL;属性上限按原始 UTF-8 字节计,不含 NUL。 * XML 转义后可能变长,编码器逐片输出,不要求调用方准备等大的整行缓冲。 */ #define IEC60870_HISTORY_FILE_PATH_CAPACITY 48U #define IEC60870_HISTORY_FILE_ATTRIBUTE_MAX 255U typedef struct { const char *device_name; /* 借用有效 UTF-8/XML 文本,最多 ATTRIBUTE_MAX 字节。 */ const char *const *analog_units; /* 可空;非空须按点表顺序提供 analog_count 个单位字符串。 */ } IEC60870_HistoryFileConfig_t; /* 同步接收且保存全部 length 字节才返回 true;短写或其他失败必须返回 false。 * bytes 仅在回调期间借用,可能是临时栈缓冲或一个 UTF-8 字符的部分字节,不能 * 保留指针,也不能假设每片自带 NUL。合并全部分片后才构成完整 UTF-8 XML。 * 失败时可能已经输出文件前缀,调用方须丢弃整个候选文件,不能把前缀发布出去。 * 回调不得修改历史记录、点表或编码配置,也不得重入同一历史实例。 */ typedef bool (*IEC60870_HistoryFileWriteFn)(void *context, const uint8_t *bytes, size_t length); /** * 功能:生成大小写固定的完整虚拟路径,供目录项与读文件请求共同使用。 * 输入参数:kind——记录或文件类别;day——相对1970-01-01的本地日序;capacity——缓冲可用容量。 * 输出参数:name——成功生成的NUL结尾相对文件名;失败不变。 * 返回值:true表示文件名已完整生成;false表示参数非法或容量不足,输出不变。 * 说明:day 是 UTC+8 本地日序;SOE/CO 忽略 day,日文件只接受可表示的 2000..2099 日期。 name/capacity 由调用方提供,容量含 NUL;true * 时填写结果,false 时不修改输出。 失败包括未知类别、日期无效或容量不足;这里只生成名称,不查询存在性/保留窗口。 */ bool IEC60870_HistoryFile_Name(IEC60870_HistoryKind_t kind, uint32_t day, char *name, size_t capacity); /** * 功能:通过 write/context 输出一份附录 B.3.2 XML,整个调用期间须独占历史实例。 * 输入参数:history——历史核心实例;kind——记录或文件类别;day——相对1970-01-01的本地日序;config——配置及调用期间借用的元数据;write——同步接收输出片段的回调; * context——传给输出回调的调用方上下文。 * 输出参数:history——复用读取工作区及读取错误可能锁存的故障状态;size——仅完整成功时写入文件字节数,不含NUL;允许NULL的入口不强制输出。 * 返回值:true表示完整文件已输出;false表示参数、读取校验或输出回调失败,候选内容不可发布。 * 说明:history、config 及其字符串/数组都由调用方持有,编码器仅在本次调用中借用; 不消费记录、不改变保留策略。调用方须将成功输出冻结后再交给文件服务下载。 SOE/CO * 从旧到新输出当前保留事件,允许 num=0;day 对这两类不起作用。 日文件仅开放最新测量日前的 30 个完整自然日。EXV 同时从属性表和数据表省略 没有有效样本的点;FIXPT * 省略含失效值的快照,sectNum 写实际节数,sect 保留 原来的 1..96 节编号,不能因缺测重新编号;第 96 节写归属日 24:00。 规范 XML * 没有定义独立品质/时间有效位属性,这些信息仍保留在内部持久记录中。 无日数据、输入无效、存储读取失败、输出失败或长度溢出均返回 false;已输出的 前缀须整体废弃。size 可为 NULL, * 仅在完整成功后写入文件字节数,不包含 NUL。 */ bool IEC60870_HistoryFile_Write(IEC60870_History_t *history, IEC60870_HistoryKind_t kind, uint32_t day, const IEC60870_HistoryFileConfig_t *config, IEC60870_HistoryFileWriteFn write, void *context, uint32_t *size); #ifdef __cplusplus } #endif #endif /* IEC60870_HISTORY_FILE_H */