Files
STM32F4-Base/IEC60870-Slave/common/IEC60870_History.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

248 lines
16 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 历史记录核心:事件循环记录、定点冻结、日极值及启动恢复。
* 本模块不分配堆内存,不依赖操作系统或传输层;介质访问由存储回调完成。
* 提交成功必须表示一个槽已原子、持久替换;提交失败后实例进入故障态,
* 必须重新 Init 核对实际存储结果,不能直接重试同一条记录。
* 实例、点表和存储均由调用方持有;包括查询、导出在内的所有访问须串行。 */
#ifndef IEC60870_HISTORY_H
#define IEC60870_HISTORY_H
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#ifdef __cplusplus
extern "C" {
#endif
/* 事件容量按条数保留;日记录槽覆盖当前日和之前 31 个自然日。
* WIRE_MAX 是单条内部编码的工作区上限,不是历史总容量。 */
#define IEC60870_HISTORY_MAX_ANALOG 32U
#define IEC60870_HISTORY_SOE_CAPACITY 1024U
#define IEC60870_HISTORY_CO_CAPACITY 30U
#define IEC60870_HISTORY_DAYS 32U
#define IEC60870_HISTORY_SLOTS_PER_DAY 96U
#define IEC60870_HISTORY_WIRE_MAX 1024U
/* 类别值同时用于持久记录标识;存储后端按类别划分独立槽空间。 */
typedef enum {
IEC60870_HISTORY_SOE = 1, IEC60870_HISTORY_CO = 2,
IEC60870_HISTORY_FIXPT = 3, IEC60870_HISTORY_EXV = 4
} IEC60870_HistoryKind_t;
/* ERROR 为存储/状态错误,INVALID 为调用参数错误,CONFIG 为点表指纹不符;
* TIME_REVERSED 表示观测时刻回退。EMPTY 表示没有对应记录或没有配置遥测点,
* OK 表示操作成功;Observe 的 OK 不保证本次一定产生了新定点或新极值。 */
typedef enum {
IEC60870_HISTORY_ERROR = -1, IEC60870_HISTORY_INVALID = -2,
IEC60870_HISTORY_CONFIG = -3, IEC60870_HISTORY_TIME_REVERSED = -4,
IEC60870_HISTORY_EMPTY = 0, IEC60870_HISTORY_OK = 1
} IEC60870_HistoryResult_t;
/* 遥控操作阶段分别记条;它们不表示设备动作成功,也不等同网络应答状态。 */
typedef enum {
IEC60870_HISTORY_SELECT = 0, IEC60870_HISTORY_OPER = 1,
IEC60870_HISTORY_CANCEL = 2
} IEC60870_HistoryCommand_t;
/* 存储回调约定:
* read 按 kind/index 读取一个逻辑槽,最多写 capacity 字节,仅在 OK 时填写
* 实际 size;EMPTY 只用于没有已提交记录的槽,坏记录及读取失败必须报 ERROR。
* commit 完整接收 bytes/size,成功返回前须完成介质同步。提交前中断必须仍能
* 恢复旧记录;返回 false 也可能已经落盘,因此核心会锁住后续操作并要求恢复。
* context 只借用;字节缓冲只在回调期间有效,回调不得保存指针或重入本实例。 */
typedef struct {
void *context;
IEC60870_HistoryResult_t (*read)(void *context, IEC60870_HistoryKind_t kind,
uint32_t index, uint8_t *bytes, size_t capacity, size_t *size);
bool (*commit)(void *context, IEC60870_HistoryKind_t kind, uint32_t index,
const uint8_t *bytes, size_t size);
} IEC60870_HistoryStore_t;
/* 三组点表在实例整个使用期间借用,不得修改;组内地址须唯一且为非零 24 位值。
* 遥测数组顺序决定定点及极值数组的顺序,也参与持久记录指纹;改变点表后不能
* 用新配置解释旧存储,调用方须另行处理迁移或使用新的存储空间。
* freeze_grace_ms 为 0..1000 毫秒,允许在每刻钟边界后的窗口内取首个有效快照;
* 0 表示只接受精确边界。错过窗口保留缺测,不拿后来的值补写旧时段。 */
typedef struct {
const uint32_t *soe_ioas;
size_t soe_count;
const uint32_t *co_ioas;
size_t co_count;
const uint32_t *analog_ioas;
size_t analog_count;
uint32_t freeze_grace_ms;
} IEC60870_HistoryConfig_t;
/* 一条 SOE 或遥控记录的值副本。sequence 按类别递增,与墙钟是否回拨无关;
* quality 与 time_valid 保留采集事实,XML 未定义的字段不会被编码器擅自扩展。 */
typedef struct {
uint64_t sequence;
uint64_t utc_ms;
uint32_t ioa;
uint8_t value;
uint8_t quality;
IEC60870_HistoryCommand_t command;
bool time_valid;
} IEC60870_HistoryEvent_t;
/* day 是 UTC+8 本地日期对应的自 1970-01-01 起日序,slot 为当天第 1..96 节。
* 第 1 节对应 00:15,第 96 节对应归属日的 24:00;即使采样已到次日零点,
* 该定点仍保存在前一日。utc_ms 保留实际采样时刻,包含允许的调度迟到量。
* values/quality 的前 count 项与配置的 analog_ioas 一一对应。 */
typedef struct {
uint32_t day;
uint16_t slot;
uint64_t utc_ms;
size_t count;
float values[IEC60870_HISTORY_MAX_ANALOG];
uint8_t quality[IEC60870_HISTORY_MAX_ANALOG];
} IEC60870_HistoryFixed_t;
/* 单点当天的极值及其首次达到该值的时刻;相等值不更新时标。
* valid=false 表示当天尚无有效样本,此时不能解释其数值或发生时刻。 */
typedef struct {
float max;
float min;
uint64_t max_utc_ms;
uint64_t min_utc_ms;
bool valid;
} IEC60870_HistoryExtremePoint_t;
/* 一天全部遥测点的累计状态。utc_ms 是最近一次持久化变更的观测时刻,
* 不是文件生成时间;points 顺序沿用点表,当前日也保存以支持重启续算。 */
typedef struct {
uint32_t day;
uint64_t utc_ms;
size_t count;
IEC60870_HistoryExtremePoint_t points[IEC60870_HISTORY_MAX_ANALOG];
} IEC60870_HistoryExtrema_t;
/* 调用方持有的实例及固定工作区。公开布局用于静态分配,业务不得修改内部状态。
* config/store 是浅拷贝,数组和 context 的生命周期仍由调用方负责。
* wire/work_extrema 会在读写时复用,不是可跨调用借用的历史快照。 */
typedef struct {
IEC60870_HistoryConfig_t config;
IEC60870_HistoryStore_t store;
uint32_t fingerprint;
uint64_t event_sequence[2];
size_t event_count[2];
uint32_t latest_day;
uint64_t observed_utc_ms;
bool have_day;
bool initialized;
bool faulted;
uint8_t wire[IEC60870_HISTORY_WIRE_MAX];
IEC60870_HistoryExtrema_t work_extrema;
} IEC60870_History_t;
/**
* 功能:返回指定类别所需的逻辑槽数,供存储后端布局使用;未知类别返回 0。
* 输入参数:kind——记录或文件类别。
* 输出参数:无。
* 返回值:该类别的逻辑槽容量;未知类别返回0。
* 说明:冗余副本、提交元数据和介质对齐空间由后端在此槽数之外自行预留。
*/
uint32_t IEC60870_History_Slot_Count(IEC60870_HistoryKind_t kind);
/**
* 功能:UTC 毫秒转换成本地日序,不读取系统时间,不修改任何实例。
* 输入参数:utc_ms——UTC纪元毫秒。
* 输出参数:无。
* 返回值:固定UTC+8本地日序;超出支持历法范围返回UINT32_MAX。
* 说明:全模块接受的日历范围是 UTC+8 的 2000-01-01 00:00:00.000 至 2099-12-31 23:59:59.999,即 UTC 毫秒
* 946656000000..4102415999999。 超出范围返回 UINT32_MAX;事件 time_valid=false 也不能绕过此日历限制。
*/
uint32_t IEC60870_History_Local_Day(uint64_t utc_ms);
/**
* 功能:校验配置后扫描全部槽,恢复事件序号/条数、最新测量日及已保存的时间下界。
* 输入参数:self——调用方持有的模块实例及当前状态;config——配置及调用期间借用的元数据;store——同步存储回调表及其上下文。
* 输出参数:self——本次操作后的运行状态及复用工作区。
* 返回值:OK表示操作完成;INVALID表示参数或操作状态非法;CONFIG表示持久记录与当前配置指纹不符;ERROR表示实例不可用、I/O失败或内容损坏。
* 说明:self 由调用方提供;复制配置及回调表,但不接管其中指针。允许使用实例自身 config/store 字段作为重建输入。参数校验失败返回 INVALID 且不重置旧实例;
* 进入恢复后失败则实例不可用:CONFIG 为点表不匹配,ERROR 为损坏或读取失败。 本接口不清空存储、不修复坏记录,也不创建系统资源。
*/
IEC60870_HistoryResult_t IEC60870_History_Init(IEC60870_History_t *self,
const IEC60870_HistoryConfig_t *config, const IEC60870_HistoryStore_t *store);
/**
* 功能:追加一次已确认的遥信变位;ioa 必须属于 SOE 点表,value 为 0..3 的状态码。
* 输入参数:self——调用方持有的模块实例及当前状态;ioa——信息对象地址;value——待处理数值;quality——事件品质字节;utc_ms——UTC纪元毫秒;
* time_valid——事件原始时标是否有效。
* 输出参数:self——本次操作后的运行状态及复用工作区。
* 返回值:OK表示操作完成;INVALID表示参数或操作状态非法;ERROR表示实例不可用、I/O失败或内容损坏。
* 说明:quality 与 time_valid 原样保留;utc_ms 是事件发生时间,不能改用发送重试时间。 成功后递增序号并按容量覆盖最旧记录;非法输入返回 INVALID,存储或实例问题
* 返回 ERROR。函数不做变位检测或重复消除,调用方须保证每个实际事件只追加一次。
*/
IEC60870_HistoryResult_t IEC60870_History_Append_Soe(IEC60870_History_t *self,
uint32_t ioa, uint8_t value, uint8_t quality, uint64_t utc_ms, bool time_valid);
/**
* 功能:追加指定遥控阶段;ioa 必须属于遥控点表,command 为选择/执行/撤销,value 为 0..3。
* 输入参数:self——调用方持有的模块实例及当前状态;ioa——信息对象地址;command——遥控操作阶段;value——待处理数值;utc_ms——UTC纪元毫秒;
* time_valid——事件原始时标是否有效。
* 输出参数:self——本次操作后的运行状态及复用工作区。
* 返回值:OK表示操作完成;INVALID表示参数或操作状态非法;ERROR表示实例不可用、I/O失败或内容损坏。
* 说明:时标及循环提交规则同 SOE;本接口只保存操作事实,不判设备执行结果。 参数只按值使用,无借用输出;返回 OK、INVALID 或 ERROR。
*/
IEC60870_HistoryResult_t IEC60870_History_Append_Control(IEC60870_History_t *self,
uint32_t ioa, IEC60870_HistoryCommand_t command, uint8_t value,
uint64_t utc_ms, bool time_valid);
/**
* 功能:提供同一实际观测时刻的遥测数组,count 必须等于配置点数;输入数组仅本次借用。
* 输入参数:self——调用方持有的模块实例及当前状态;utc_ms——UTC纪元毫秒;values——按配置点序排列的值;quality——与值数组同序的品质;count——数组项数。
* 输出参数:self——本次操作后的运行状态及复用工作区。
* 返回值:OK表示操作完成;EMPTY表示没有所需记录或到期任务;INVALID表示参数或操作状态非法;CONFIG表示持久记录与当前配置指纹不符;ERROR表示实例不可用、I/O失败或内容损坏;
* TIME_REVERSED表示观测时间低于高水位。
* 说明:仅品质为 0 的有限浮点数参加极值统计;定点则要求本次全部点有效。应持续调用 以捕获日极值,并保证每个冻结宽限窗口至少有一次有效调用,才能得到每日 96 节。 只接受可信墙钟;
* 小于实例已观测时刻返回 TIME_REVERSED,不改历史;零遥测点返回 EMPTY。OK 也可能只是时间推进,没有新记录。非法输入返回 INVALID。 定点和极值各自提交,非跨类型事务;
* 若后一次提交失败,前一次已落盘记录仍保留, 返回 ERROR 并须 Init 恢复,不能因为整次 Observe 失败而回滚已提交数据。
*/
IEC60870_HistoryResult_t IEC60870_History_Observe(IEC60870_History_t *self,
uint64_t utc_ms, const float *values, const uint8_t *quality, size_t count);
/**
* 功能:返回恢复/提交后缓存的事件条数,不访问存储;仅接受 SOE/CO。
* 输入参数:self——只读模块实例;kind——记录或文件类别。
* 输出参数:无。
* 返回值:指定SOE/CO环的保留条数;类别或实例不可用时返回0。
* 说明:空记录、未知类别、未初始化或故障实例均返回 0,不能据此区分存储故障与空库。
*/
size_t IEC60870_History_Event_Count(const IEC60870_History_t *self,
IEC60870_HistoryKind_t kind);
/**
* 功能:按从旧到新的下标读取事件,oldest_index=0 是当前保留的最旧条目。
* 输入参数:self——调用方持有的模块实例及当前状态;kind——记录或文件类别;oldest_index——按提交顺序从最旧记录起的零基索引。
* 输出参数:self——复用工作区及读取校验可能锁存的故障状态;out——成功时写入的独立结果副本。
* 返回值:OK表示操作完成;EMPTY表示没有所需记录或到期任务;INVALID表示参数或操作状态非法;CONFIG表示持久记录与当前配置指纹不符;ERROR表示实例不可用、I/O失败或内容损坏。
* 说明:out 由调用方持有,只有 OK 才填写;越界/缺槽返回 EMPTY,参数错误为 INVALID, 存储异常为 ERROR/CONFIG。输出是独立值副本;查询期间必须禁止同实例追加/轮转。
*/
IEC60870_HistoryResult_t IEC60870_History_Get_Event(IEC60870_History_t *self,
IEC60870_HistoryKind_t kind, size_t oldest_index, IEC60870_HistoryEvent_t *out);
/**
* 功能:读取归属日 day 的第 slot 节;slot 只能为 1..96,不按已有条目重新编号。
* 输入参数:self——调用方持有的模块实例及当前状态;day——相对1970-01-01的本地日序;slot——定点节号1..96;事件及极值公共头使用0。
* 输出参数:self——复用工作区及读取校验可能锁存的故障状态;out——成功时写入的独立结果副本。
* 返回值:OK表示操作完成;EMPTY表示没有所需记录或到期任务;INVALID表示参数或操作状态非法;CONFIG表示持久记录与当前配置指纹不符;ERROR表示实例不可用、I/O失败或内容损坏。
* 说明:不在 32 日保留窗口、该节缺测或物理槽已归属其他日期时返回 EMPTY。 out 仅在 OK 时填写完整值副本;其他失败返回 INVALID、ERROR 或 CONFIG。
*/
IEC60870_HistoryResult_t IEC60870_History_Read_Fixed(IEC60870_History_t *self,
uint32_t day, uint16_t slot, IEC60870_HistoryFixed_t *out);
/**
* 功能:读取一天的累计极值,也可读取未结束的当前日;是否导出该日由文件层决定。
* 输入参数:self——调用方持有的模块实例及当前状态;day——相对1970-01-01的本地日序。
* 输出参数:self——复用工作区及读取校验可能锁存的故障状态;out——成功时写入的独立结果副本。
* 返回值:OK表示操作完成;EMPTY表示没有所需记录或到期任务;INVALID表示参数或操作状态非法;CONFIG表示持久记录与当前配置指纹不符;ERROR表示实例不可用、I/O失败或内容损坏。
* 说明:无记录/超保留窗口返回 EMPTY;参数或存储失败返回 INVALID、ERROR、CONFIG。 out 仅在 OK 时填写;逐点 valid 才能判定该点是否曾有有效样本。
*/
IEC60870_HistoryResult_t IEC60870_History_Read_Extrema(IEC60870_History_t *self,
uint32_t day, IEC60870_HistoryExtrema_t *out);
/**
* 功能:输出已恢复或观测到的最新测量日,不等于调用瞬间系统日期,也不由事件时间推进。
* 输入参数:self——只读模块实例。
* 输出参数:day——成功时写入的本地日序。
* 返回值:true表示已有最近测量日并填写day;false表示实例不可用或尚无测量日。
* 说明:未有测量日、实例不可用或 day=NULL 返回 false 并保留输出;true 时仅写 *day。
*/
bool IEC60870_History_Latest_Day(const IEC60870_History_t *self, uint32_t *day);
#ifdef __cplusplus
}
#endif
#endif