248 lines
16 KiB
C
248 lines
16 KiB
C
/* 附录 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
|