Files
STM32F4-Base/IEC60870-Slave/common/IEC60870_HistoryFile.h
T
STF bdcc8b6500
CI / L0 静态门禁 (pre-commit) (push) Failing after 7m46s
CI / L0.5 主机侧单测 (MSVC) (push) Successful in 21s
添加遥控、参数装载、文件传输等业务
2026-11-16 22:19:17 -08:00

65 lines
4.5 KiB
C
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
/*
* 附录 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 */