65 lines
4.5 KiB
C
65 lines
4.5 KiB
C
/*
|
||
* 附录 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 */
|