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

1240 lines
71 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.
/* 电能量冻结核心:配置/时间校验 -> 逻辑槽编解码 -> 记录与封存 -> 启动恢复。
* v1持久格式显式使用小端字段,不写C结构体镜像,避免填充与对齐差异。
* 每个逻辑槽自带CRC;SEAL再对日序、存在位图及有序记录正文作整体摘要。
* 整体摘要排除每条记录尾CRC:把合法记录及其CRC一并累积会落入固定余数,
* 从而失去区分同长度记录内容的能力。原子落盘由调用方提供的store保证。 */
#include "IEC60870_EnergyFreeze.h"
#include <math.h>
#include <string.h>
#define EF_HEADER 44U /* 公共头长度,载荷从此偏移开始。 */
#define EF_GRID UINT64_C(900000) /* 15分钟网格,单位ms。 */
#define EF_DAY_MS UINT64_C(86400000) /* 固定24小时业务窗口,不受夏令时影响。 */
#define EF_OFFSET UINT64_C(28800000) /* UTC转固定UTC+8本地日期的偏移。 */
#define EF_FIRST_DAY 10957U /* 2000-01-01相对1970-01-01的日序。 */
#define EF_LAST_DAY 47481U /* 2099-12-31的日序。 */
/* 仅供编解码的字段视图;不是可直接写入介质的布局。
* freeze在FLOWREV中表示occur,在SEAL中表示窗口结束时刻。 */
typedef struct {
uint64_t sequence, freeze, observed;
uint32_t day;
uint16_t slot;
uint8_t count;
} EfHeader;
/**
* 功能:将v的低n字节按小端写入p,支持未对齐地址;n由格式限定为1..8。
* 输入参数:v——待编码整数;n——参与处理的字节数。
* 输出参数:p——编码或复制结果的目标字节区。
* 返回值:无。
* 说明:调用方保证目标至少有n字节,高于n字节的整数部分不写入。
*/
static void Put(uint8_t *p, uint64_t v, size_t n)
{
size_t i;
for (i = 0U; i < n; ++i) { p[i] = (uint8_t)(v >> (i * 8U)); }
}
/**
* 功能:从p按小端读取n字节无符号整数,高位补零,不依赖宿主字节序或对齐。
* 输入参数:p——待处理的字节区;n——参与处理的字节数。
* 输出参数:无。
* 返回值:按小端还原的无符号整数。
* 说明:n由格式限定为1..8,调用方保证源缓冲足够。
*/
static uint64_t Get(const uint8_t *p, size_t n)
{
uint64_t v = 0U;
size_t i;
for (i = 0U; i < n; ++i) { v |= (uint64_t)p[i] << (i * 8U); }
return v;
}
/**
* 功能:将p的n字节并入CRC-32反射多项式递推,可跨片段累积。
* 输入参数:crc——当前未取反的CRC递推状态;p——待处理的字节区;n——参与处理的字节数。
* 输出参数:无。
* 返回值:更新后的未取反CRC状态。
* 说明:首段crc使用UINT32_MAX,返回未取反状态;全部片段结束后由调用方取反。
*/
static uint32_t Crc_Update(uint32_t crc, const uint8_t *p, size_t n)
{
size_t i;
unsigned bit;
for (i = 0U; i < n; ++i) {
crc ^= p[i];
for (bit = 0U; bit < 8U; ++bit) {
crc = (crc >> 1) ^ ((crc & 1U) != 0U ? UINT32_C(0xedb88320) : 0U);
}
}
return crc;
}
/**
* 功能:检查UTC纪元毫秒是否位于公开历法范围内,UTC_MIN和UTC_MAX两端均包含。
* 输入参数:time——待检查的UTC毫秒或日历值。
* 输出参数:无。
* 返回值:true表示时刻位于支持的UTC闭区间,false表示越界。
* 说明:只根据传入数据计算或判定,不改写输入对象。
*/
static bool Utc_Valid(uint64_t time)
{
return time >= IEC60870_ENERGY_FREEZE_UTC_MIN && time <= IEC60870_ENERGY_FREEZE_UTC_MAX;
}
/**
* 功能:检查业务日期是否在2000-01-01至2099-12-31之间。
* 输入参数:day——相对1970-01-01的本地日序。
* 输出参数:无。
* 返回值:true表示本地日序在2000..2099年内,false表示越界。
* 说明:day是相对1970-01-01的本地日序,不是YYYYMMDD。
*/
static bool Day_Valid(uint32_t day)
{
return day >= EF_FIRST_DAY && day <= EF_LAST_DAY;
}
/**
* 功能:业务日界以固定UTC+8本地午夜起算,须为0..1425分钟且能被15整除。
* 输入参数:offset——UTC+8午夜起算的业务日界分钟偏移。
* 输出参数:无。
* 返回值:true表示偏移在0..1425分钟且为15的倍数,false表示不满足日界约束。
* 说明:只根据传入数据计算或判定,不改写输入对象。
*/
static bool Offset_Valid(uint16_t offset)
{
return offset <= 1425U && offset % 15U == 0U;
}
/**
* 功能:将名义UTC时刻按固定UTC+8及业务日界映射为窗口起始日序。
* 输入参数:nominal——名义UTC毫秒,本入口不进行15分钟取整;offset——UTC+8午夜起算的业务日界分钟偏移。
* 输出参数:无。
* 返回值:业务窗口起始日序;时刻、日界偏移或归属日非法时返回UINT32_MAX。
* 说明:本函数不做15分钟取整;时刻、偏移或所得日期非法时返回UINT32_MAX。
*/
uint32_t IEC60870_EnergyFreeze_Window_Day(uint64_t nominal, uint16_t offset)
{
uint64_t day;
if (!Utc_Valid(nominal) || !Offset_Valid(offset)) { return UINT32_MAX; }
/* 先转本地时间再减业务起点;起点之前的时刻归前一天窗口。 */
day = (nominal + EF_OFFSET - (uint64_t)offset * 60000U) / EF_DAY_MS;
return Day_Valid((uint32_t)day) ? (uint32_t)day : UINT32_MAX;
}
/**
* 功能:由业务日序及日界分钟偏移计算窗口起点的UTC纪元毫秒。
* 输入参数:day——相对1970-01-01的本地日序;offset——UTC+8午夜起算的业务日界分钟偏移。
* 输出参数:out——成功写入窗口起点UTC毫秒;失败保持原值。
* 返回值:true表示起点已计算并写回;false表示参数无效且输出不变。
* 说明:日期、偏移或out无效时返回false且不改写输出,成功才填写*out。
*/
bool IEC60870_EnergyFreeze_Window_Start(uint32_t day, uint16_t offset, uint64_t *out)
{
if (out == NULL || !Day_Valid(day) || !Offset_Valid(offset)) { return false; }
*out = (uint64_t)day * EF_DAY_MS - EF_OFFSET + (uint64_t)offset * 60000U;
return true;
}
/**
* 功能:返回指定持久类别的逻辑槽数,未知类别返回0。
* 输入参数:kind——记录或文件类别。
* 输出参数:无。
* 返回值:该类别的逻辑槽容量;未知类别返回0。
* 说明:不包含后端双bank等冗余,存储后端据此为各类别分配逻辑区域。
*/
uint32_t IEC60870_EnergyFreeze_Slot_Count(IEC60870_EnergyFreezeKind_t kind)
{
switch (kind) {
case IEC60870_ENERGY_FREEZE_INTERVAL: return 3072U;
case IEC60870_ENERGY_FREEZE_DAY: case IEC60870_ENERGY_FREEZE_SEAL: return 32U;
case IEC60870_ENERGY_FREEZE_FLOWREV: return 256U;
case IEC60870_ENERGY_FREEZE_META: return 1U;
default: return 0U;
}
}
/**
* 功能:清零配置,并将网格容差、最大迟到时间设为1000ms;NULL不操作。
* 输入参数:无。
* 输出参数:config——写入默认配置;NULL时不操作。
* 返回值:无。
* 说明:默认点表为空,应用在Init前填写需要启用的点表和语义版本。
*/
void IEC60870_EnergyFreeze_Config_Default(IEC60870_EnergyFreezeConfig_t *config)
{
if (config != NULL) {
memset(config, 0, sizeof(*config));
config->grid_tolerance_ms = 1000U;
config->max_delay_ms = 1000U;
}
}
/**
* 功能:校验一张点表的容量、非零24位地址及组内唯一性,不检查跨表重复。
* 输入参数:addresses——组内地址表;count——数组项数。
* 输出参数:无。
* 返回值:true表示点数、地址范围及组内唯一性全部满足,false表示不满足。
* 说明:count为0时允许addresses为空;非空表须提供至少count项有效存储。
*/
static bool Addresses_Valid(const uint32_t *addresses, size_t count)
{
size_t i, j;
if (count > IEC60870_ENERGY_FREEZE_MAX_POINTS || (count != 0U && addresses == NULL)) { return false; }
for (i = 0U; i < count; ++i) {
if (addresses[i] == 0U || addresses[i] > UINT32_C(0xffffff)) { return false; }
for (j = 0U; j < i; ++j) { if (addresses[i] == addresses[j]) { return false; } }
}
return true;
}
/**
* 功能:检查三张点表、业务日界、容差/延迟上限和本机4字节float条件。
* 输入参数:c——冻结配置及点表。
* 输出参数:无。
* 返回值:true表示冻结配置满足本机表示及各字段限制,false表示配置无效。
* 说明:NULL配置无效;不读介质或比较旧指纹,sizeof检查也不验证全部浮点特性。
*/
static bool Config_Valid(const IEC60870_EnergyFreezeConfig_t *c)
{
return c != NULL && sizeof(float) == 4U && Offset_Valid(c->day_start_minutes) &&
c->grid_tolerance_ms <= 60000U && c->max_delay_ms <= 900000U &&
Addresses_Valid(c->interval_ioas, c->point_count) &&
Addresses_Valid(c->day_ioas, c->point_count) &&
Addresses_Valid(c->flowrev_ioas, c->flowrev_count);
}
/**
* 功能:点序也是持久语义:按三张表的长度、逐项IOA、值语义版本和日界计算指纹。
* 输入参数:c——冻结配置及点表。
* 输出参数:无。
* 返回值:按配置内容和顺序计算的32位指纹。
* 说明:输入配置须已校验;字段显式按小端累计CRC,最终取反。 容差/延迟影响当前准入及封存时机,不参与指纹。
*/
static uint32_t Fingerprint(const IEC60870_EnergyFreezeConfig_t *c)
{
const uint32_t *arrays[3];
size_t counts[3], i, j;
uint8_t bytes[4];
uint32_t crc = UINT32_MAX;
arrays[0] = c->interval_ioas; arrays[1] = c->day_ioas; arrays[2] = c->flowrev_ioas;
counts[0] = counts[1] = c->point_count; counts[2] = c->flowrev_count;
for (i = 0U; i < 3U; ++i) {
Put(bytes, counts[i], 4U); crc = Crc_Update(crc, bytes, 4U);
for (j = 0U; j < counts[i]; ++j) {
Put(bytes, arrays[i][j], 4U); crc = Crc_Update(crc, bytes, 4U);
}
}
Put(bytes, c->value_semantics, 4U); crc = Crc_Update(crc, bytes, 4U);
Put(bytes, c->day_start_minutes, 2U); crc = Crc_Update(crc, bytes, 2U);
return ~crc;
}
/**
* 功能:只有非NULL、已初始化且未锁存故障的实例才能正常读写;本检查不访问介质。
* 输入参数:self——只读模块实例。
* 输出参数:无。
* 返回值:true表示实例非空、已初始化且未故障,false表示不能正常访问。
* 说明:只根据传入数据计算或判定,不改写输入对象。
*/
static bool Ready(const IEC60870_EnergyFreeze_t *self)
{
return self != NULL && self->initialized && !self->faulted;
}
/**
* 功能:将非NULL实例的faulted置位并原样返回result,不回滚RAM或已提交介质内容。
* 输入参数:self——调用方持有的模块实例及当前状态;result——待原样传回的冻结结果码。
* 输出参数:self——置位后的故障标志。
* 返回值:原样返回传入的result。
* 说明:用于读坏或提交结果不确定的路径;须重新Init成功后恢复正常服务。
*/
static IEC60870_EnergyFreezeResult_t Fault(IEC60870_EnergyFreeze_t *self,
IEC60870_EnergyFreezeResult_t result)
{
self->faulted = true;
return result;
}
/**
* 功能:将已校验的实际采样UTC毫秒归到最近15分钟网格,等距时取较晚网格。
* 输入参数:freeze——实际采样UTC毫秒。
* 输出参数:无。
* 返回值:就近舍入后的15分钟UTC网格,等距时选择较晚网格。
* 说明:只用于定位和比较,不改写持久freeze;所得网格仍须检查历法及窗口范围。
*/
static uint64_t Nominal(uint64_t freeze)
{
return ((freeze + EF_GRID / 2U) / EF_GRID) * EF_GRID;
}
/**
* 功能:INTERVAL每窗96槽,slot须为1..96;DAY/SEAL每窗1槽并忽略slot。
* 输入参数:kind——记录或文件类别;day——相对1970-01-01的本地日序;slot——冻结节号;INTERVAL为1..96,DAY为0。
* 输出参数:无。
* 返回值:按类别、日序及节号计算的复用逻辑槽索引。
* 说明:只计算逻辑索引,不检查保留或封存状态;复用写入前须经Prepare_Window推进边界。
*/
static uint32_t Index(IEC60870_EnergyFreezeKind_t kind, uint32_t day, uint16_t slot)
{
return kind == IEC60870_ENERGY_FREEZE_INTERVAL ? (day % 32U) * 96U + slot - 1U : day % 32U;
}
/**
* 功能:读取13字节窗口位图中已校验的0..96位:0..95为INTERVAL,96为DAY。
* 输入参数:bitmap——97位记录存在位图;bit——位号,0..96。
* 输出参数:无。
* 返回值:true表示指定位置已置位,false表示未置位。
* 说明:只根据传入数据计算或判定,不改写输入对象。
*/
static bool Bit(const uint8_t bitmap[13], unsigned bit)
{
return (bitmap[bit / 8U] & (uint8_t)(1U << (bit % 8U))) != 0U;
}
/**
* 功能:标记窗口位图中的一个记录位置,保留其余位;bit须为0..96。
* 输入参数:bitmap——97位记录存在位图;bit——位号,0..96。
* 输出参数:bitmap——置位后的存在位图,其余位保持不变。
* 返回值:无。
* 说明:仅在记录提交成功或恢复校验确认存在后发布,不在此处访问介质。
*/
static void Set_Bit(uint8_t bitmap[13], unsigned bit)
{
bitmap[bit / 8U] |= (uint8_t)(1U << (bit % 8U));
}
/**
* 功能:统计前97位的置位数,返回0..97条记录位置数,不是测点数。
* 输入参数:bitmap——97位记录存在位图。
* 输出参数:无。
* 返回值:前97个位中置1的数量,范围0..97。
* 说明:末字节其余7位不参与计数,其合法性由记录校验负责。
*/
static uint8_t Bit_Count(const uint8_t bitmap[13])
{
unsigned bit;
uint8_t count = 0U;
for (bit = 0U; bit < 97U; ++bit) { if (Bit(bitmap, bit)) { ++count; } }
return count;
}
/**
* 功能:从至少4字节的小端缓冲还原binary32值,不进行单位换算或有限性检查。
* 输入参数:p——待处理的字节区。
* 输出参数:无。
* 返回值:从原始binary32位模式还原的浮点值,不保证有限。
* 说明:memcpy避免类型别名和未对齐访问,调用环境须使用4字节binary32表示。
*/
static float Read_Float(const uint8_t *p)
{
uint32_t bits = (uint32_t)Get(p, 4U);
float value;
memcpy(&value, &bits, 4U);
return value;
}
/**
* 功能:将非NULL的binary32源原始位写入至少4字节的小端目标缓冲。
* 输入参数:value——待处理数值。
* 输出参数:p——编码或复制结果的目标字节区。
* 返回值:无。
* 说明:不舍入、不筛选品质或有限性;memcpy避免别名违规并保留正负零等位差。
*/
static void Write_Float(uint8_t *p, const float *value)
{
uint32_t bits;
memcpy(&bits, value, 4U);
Put(p, bits, 4U);
}
/**
* 功能:读入共用wire后,验证公共头/CRC、配置指纹、类别字段及逻辑槽归属。
* 输入参数:self——调用方持有的模块实例及当前状态;kind——记录或文件类别;index——零基索引。
* 输出参数:self——复用wire工作区及可能锁存的故障状态;h——解析头;失败时可能部分填写;length——仅OK时写入当前记录字节数。
* 返回值:OK表示操作完成;EMPTY表示没有所需记录或到期任务;CONFIG表示持久记录与当前配置指纹不符;ERROR表示实例不可用、I/O失败或内容损坏。
* 说明:self须已配置回调和指纹,允许Init内部调用;成功后h和length描述当前wire。 返回OK、无已提交记录的EMPTY、指纹不符的CONFIG或读取/内容错误的ERROR。
* 损坏及指纹错误锁存faulted;过期记录也先校验,不能将损坏解释为EMPTY。 失败时h可能已部分填写,length仅OK时改写;下一次Load/Header等会覆盖wire。
*/
static IEC60870_EnergyFreezeResult_t Load(IEC60870_EnergyFreeze_t *self,
IEC60870_EnergyFreezeKind_t kind, uint32_t index, EfHeader *h, size_t *length)
{
uint8_t *p = self->wire;
size_t size = 0U, expected = 0U, i;
uint64_t start = 0U, nominal, error;
IEC60870_EnergyFreezeResult_t result = self->store.read(self->store.context,
kind, index, p, sizeof(self->wire), &size);
if (result == IEC60870_ENERGY_FREEZE_EMPTY) { return result; }
if (result != IEC60870_ENERGY_FREEZE_OK || size < 48U || size > sizeof(self->wire) ||
memcmp(p, "EFZ1", 4U) != 0 || p[4] != 1U || p[5] != (uint8_t)kind ||
p[7] != 0U || p[42] != 0U || p[43] != 0U ||
Get(p + size - 4U, 4U) != (uint64_t)~Crc_Update(UINT32_MAX, p, size - 4U)) {
return Fault(self, IEC60870_ENERGY_FREEZE_ERROR);
}
if (Get(p + 8U, 4U) != self->fingerprint) { return Fault(self, IEC60870_ENERGY_FREEZE_CONFIG); }
h->count = p[6]; h->sequence = Get(p + 12U, 8U); h->freeze = Get(p + 20U, 8U);
h->observed = Get(p + 28U, 8U); h->day = (uint32_t)Get(p + 36U, 4U);
h->slot = (uint16_t)Get(p + 40U, 2U);
if (kind == IEC60870_ENERGY_FREEZE_INTERVAL || kind == IEC60870_ENERGY_FREEZE_DAY) {
expected = 48U + 5U * h->count;
if (h->count == 0U || h->count != self->config.point_count || h->sequence != 0U ||
!Utc_Valid(h->freeze) || !Utc_Valid(h->observed) ||
!IEC60870_EnergyFreeze_Window_Start(h->day, self->config.day_start_minutes, &start)) {
return Fault(self, IEC60870_ENERGY_FREEZE_ERROR);
}
nominal = Nominal(h->freeze);
error = nominal > h->freeze ? nominal - h->freeze : h->freeze - nominal;
/* 读历史使用格式允许的最大容差,不按当前配置重新裁定过去的准入结果。
* observed可因Derive_Day远晚于freeze,因此也不套当前max_delay_ms。 */
if (error > 60000U || IEC60870_EnergyFreeze_Window_Day(nominal,
self->config.day_start_minutes) != h->day ||
(h->freeze > h->observed && h->freeze - h->observed > 60000U) ||
(kind == IEC60870_ENERGY_FREEZE_DAY && (h->slot != 0U || nominal != start)) ||
(kind == IEC60870_ENERGY_FREEZE_INTERVAL && (h->slot == 0U || h->slot > 96U ||
nominal != start + (uint64_t)(h->slot - 1U) * EF_GRID)) ||
Index(kind, h->day, h->slot) != index || size != expected) {
return Fault(self, IEC60870_ENERGY_FREEZE_ERROR);
}
for (i = 0U; i < h->count; ++i) {
if (!isfinite(Read_Float(p + EF_HEADER + i * 5U)) || p[EF_HEADER + i * 5U + 4U] != 0U) {
return Fault(self, IEC60870_ENERGY_FREEZE_ERROR);
}
}
} else if (kind == IEC60870_ENERGY_FREEZE_FLOWREV) {
/* 事件仅校验结构和索引序;坏品质/非有限值仍是可保留的原始事件内容。 */
expected = 48U + 6U * h->count;
if (h->count == 0U || h->count > IEC60870_ENERGY_FREEZE_EVENT_POINTS ||
h->count > self->config.flowrev_count || h->sequence == 0U ||
(h->sequence - 1U) % 256U != index || !Utc_Valid(h->freeze) ||
h->observed != 0U || h->day != 0U || h->slot != 0U || size != expected) {
return Fault(self, IEC60870_ENERGY_FREEZE_ERROR);
}
for (i = 0U; i < h->count; ++i) {
uint8_t point = p[EF_HEADER + i * 6U];
if (point >= self->config.flowrev_count || (i != 0U && point <= p[EF_HEADER + (i - 1U) * 6U])) {
return Fault(self, IEC60870_ENERGY_FREEZE_ERROR);
}
}
} else if (kind == IEC60870_ENERGY_FREEZE_SEAL) {
expected = 66U;
if (size != expected || h->count != 0U || h->sequence != 0U || h->slot != 0U ||
!Utc_Valid(h->observed) || !IEC60870_EnergyFreeze_Window_Start(h->day,
self->config.day_start_minutes, &start) || h->freeze != start + EF_DAY_MS ||
h->observed < h->freeze || index != h->day % 32U || (p[56] & 0xfeU) != 0U ||
p[57] != Bit_Count(p + EF_HEADER)) { return Fault(self, IEC60870_ENERGY_FREEZE_ERROR); }
} else if (kind == IEC60870_ENERGY_FREEZE_META) {
uint8_t flags = p[56];
expected = 72U;
if (size != expected || h->count != 0U || h->sequence != 0U || h->freeze != 0U ||
h->day != 0U || h->slot != 0U || (h->observed != 0U && !Utc_Valid(h->observed)) ||
(flags & 0xfcU) != 0U || p[57] != 0U || p[58] != 0U || p[59] != 0U ||
((flags & 1U) != 0U ? !Day_Valid((uint32_t)Get(p + 48U, 4U)) : Get(p + 48U, 4U) != 0U) ||
((flags & 2U) != 0U ? (!Day_Valid((uint32_t)Get(p + 44U, 4U)) || (flags & 1U) == 0U) :
Get(p + 44U, 4U) != 0U)) { return Fault(self, IEC60870_ENERGY_FREEZE_ERROR); }
}
if (expected == 0U || size != expected) { return Fault(self, IEC60870_ENERGY_FREEZE_ERROR); }
*length = size;
return IEC60870_ENERGY_FREEZE_OK;
}
/**
* 功能:在wire构造44字节公共头,不写载荷和尾CRC;h须已按类别填写并将未用字段清零。
* 输入参数:self——调用方持有的模块实例及当前状态;kind——记录或文件类别;h——已校验或待编码的记录头。
* 输出参数:self——wire中的记录公共头。
* 返回值:无。
* 说明:偏移0魔数、4版本、5类别、6点数、8指纹、12序号、20冻结时刻、28观测时刻、 36日序、40节号;7及42..43清零。载荷由各类写入函数随后填充。
*/
static void Header(IEC60870_EnergyFreeze_t *self, IEC60870_EnergyFreezeKind_t kind,
const EfHeader *h)
{
uint8_t *p = self->wire;
memset(p, 0, EF_HEADER);
memcpy(p, "EFZ1", 4U); p[4] = 1U; p[5] = (uint8_t)kind; p[6] = h->count;
Put(p + 8U, self->fingerprint, 4U); Put(p + 12U, h->sequence, 8U);
Put(p + 20U, h->freeze, 8U); Put(p + 28U, h->observed, 8U);
Put(p + 36U, h->day, 4U); Put(p + 40U, h->slot, 2U);
}
/**
* 功能:为已准备好的wire附加尾CRC,再同步提交到指定kind/index逻辑槽。
* 输入参数:self——调用方持有的模块实例及当前状态;kind——记录或文件类别;index——零基索引;length——字节数。
* 输出参数:self——本次操作后的运行状态及复用工作区。
* 返回值:OK表示操作完成;ERROR表示实例不可用、I/O失败或内容损坏。
* 说明:length包含预留的4字节CRC且须在wire容量内;后端承诺持久提交才返回OK。 后端commit返回false时锁存faulted并返回ERROR;可能已经落盘,不能原地重试。
*/
static IEC60870_EnergyFreezeResult_t Commit(IEC60870_EnergyFreeze_t *self,
IEC60870_EnergyFreezeKind_t kind, uint32_t index, size_t length)
{
Put(self->wire + length - 4U, ~Crc_Update(UINT32_MAX, self->wire, length - 4U), 4U);
if (!self->store.commit(self->store.context, kind, index, self->wire, length)) {
return Fault(self, IEC60870_ENERGY_FREEZE_ERROR);
}
return IEC60870_ENERGY_FREEZE_OK;
}
/**
* 功能:将封存前沿提示、保留下界、淘汰计数、有效位、FLOW序号及观测时间提交到META槽0。
* 输入参数:self——调用方持有的模块实例及当前状态。
* 输出参数:self——本次操作后的运行状态及复用工作区。
* 返回值:OK表示操作完成;ERROR表示实例不可用、I/O失败或内容损坏。
* 说明:覆盖wire,成功置have_meta并返回OK;失败锁存故障,不撤销之前的其他槽提交。 SEAL/FLOW事实可先于META更新,恢复不能把META当成完整事实目录。
*/
static IEC60870_EnergyFreezeResult_t Meta(IEC60870_EnergyFreeze_t *self)
{
EfHeader h;
memset(&h, 0, sizeof(h)); h.observed = self->observed_utc_ms;
Header(self, IEC60870_ENERGY_FREEZE_META, &h);
Put(self->wire + 44U, self->sealed_valid ? self->sealed_day : 0U, 4U);
Put(self->wire + 48U, self->retained_valid ? self->retained_from : 0U, 4U);
Put(self->wire + 52U, self->evicted_unsealed, 4U);
self->wire[56] = (uint8_t)((self->retained_valid ? 1U : 0U) | (self->sealed_valid ? 2U : 0U));
memset(self->wire + 57U, 0, 3U); Put(self->wire + 60U, self->flow_sequence, 8U);
if (Commit(self, IEC60870_ENERGY_FREEZE_META, 0U, 72U) != IEC60870_ENERGY_FREEZE_OK) {
return IEC60870_ENERGY_FREEZE_ERROR;
}
self->have_meta = true;
return IEC60870_ENERGY_FREEZE_OK;
}
/**
* 功能:查询day是否位于已建立的保留区[R, R+31],不访问介质。
* 输入参数:self——只读模块实例;day——相对1970-01-01的本地日序。
* 输出参数:无。
* 返回值:true表示日期落在当前保留窗口内;不保证该日期已有记录。
* 说明:true仅表示日期仍在范围内,不代表已有数据或SEAL。
*/
static bool Retained(const IEC60870_EnergyFreeze_t *self, uint32_t day)
{
return self->retained_valid && day >= self->retained_from && day - self->retained_from < 32U;
}
/**
* 功能:先持久提交淘汰边界,再允许覆盖复用的数据或SEAL槽;此顺序用于掉电恢复。
* 输入参数:self——调用方持有的模块实例及当前状态;day——相对1970-01-01的本地日序。
* 输出参数:self——本次操作后的运行状态及复用工作区。
* 返回值:OK表示操作完成;TIME_REJECTED表示网格、延迟或窗口顺序不允许;ERROR表示实例不可用、I/O失败或内容损坏。
* 说明:目标日序须已校验;早于R返回TIME_REJECTED,META提交失败返回ERROR。 前移时只清RAM位图,旧介质记录留待覆盖;有数据但未封存的淘汰窗计入损失。 提交失败即faulted,
* 临时RAM状态只供Status诊断,不再用于正常读写。
*/
static IEC60870_EnergyFreezeResult_t Prepare_Window(IEC60870_EnergyFreeze_t *self, uint32_t day)
{
uint32_t old, next, i;
if (self->retained_valid && day < self->retained_from) { return IEC60870_ENERGY_FREEZE_TIME_REJECTED; }
if (!self->retained_valid) {
self->retained_valid = true; self->retained_from = day;
return Meta(self);
}
old = self->retained_from;
if (day - old < 32U) { return self->have_meta ? IEC60870_ENERGY_FREEZE_OK : Meta(self); }
next = day - 31U;
for (i = 0U; i < 32U && old + i < next; ++i) {
uint32_t slot = (old + i) % 32U;
/* 只统计实际丢失的未封存数据窗,空窗不计,计数饱和而不回绕。 */
if (!self->seals[slot] && Bit_Count(self->present[slot]) != 0U && self->evicted_unsealed != UINT32_MAX) {
++self->evicted_unsealed;
}
memset(self->present[slot], 0, 13U); self->seals[slot] = false;
}
self->retained_from = next;
if (self->sealed_valid && self->sealed_day < next) { self->sealed_valid = false; }
return Meta(self);
}
/**
* 功能:将Load已校验的INTERVAL/DAY解码为独立副本,先清零out再填写字段和点值。
* 输入参数:self——只读模块实例;h——已校验或待编码的记录头。
* 输出参数:out——解码后的独立记录副本。
* 返回值:无。
* 说明:h须对应当前wire且count已受容量约束;不重新校验,调用前不能覆盖wire。
*/
static void Decode_Record(const IEC60870_EnergyFreeze_t *self, const EfHeader *h,
IEC60870_EnergyFreezeRecord_t *out)
{
size_t i;
memset(out, 0, sizeof(*out)); out->day = h->day; out->slot = h->slot;
out->freeze_utc_ms = h->freeze; out->observed_utc_ms = h->observed; out->count = h->count;
for (i = 0U; i < h->count; ++i) {
out->values[i] = Read_Float(self->wire + EF_HEADER + 5U * i);
out->quality[i] = self->wire[EF_HEADER + 5U * i + 4U];
}
}
/**
* 功能:读取INTERVAL/DAY副本,仅OK时填写out;INTERVAL的slot为1..96,DAY传0。
* 输入参数:self——调用方持有的模块实例及当前状态;kind——记录或文件类别;day——相对1970-01-01的本地日序;slot——冻结节号;INTERVAL为1..96,DAY为0。
* 输出参数:self——复用工作区及读取校验可能锁存的故障状态;out——成功时写入的独立结果副本。
* 返回值:OK表示操作完成;EMPTY表示没有所需记录或到期任务;INVALID表示参数或操作状态非法;ERROR表示实例不可用、I/O失败或内容损坏;CONFIG表示持久记录与当前配置指纹不符。
* 说明:普通缺测或保留范围外返回EMPTY;参数非法或读取校验失败返回相应错误。 其他日期残留可表示本日缺测,但RAM位图已知存在的本日记录丢失会锁存故障。 读取复用wire,未封存数据也可读;
* kind由内部调用限定为INTERVAL或DAY。
*/
static IEC60870_EnergyFreezeResult_t Read_Record(IEC60870_EnergyFreeze_t *self,
IEC60870_EnergyFreezeKind_t kind, uint32_t day, uint16_t slot, IEC60870_EnergyFreezeRecord_t *out)
{
EfHeader h;
size_t size;
unsigned bit = kind == IEC60870_ENERGY_FREEZE_INTERVAL ? slot - 1U : 96U;
IEC60870_EnergyFreezeResult_t result;
if (!Ready(self)) { return IEC60870_ENERGY_FREEZE_ERROR; }
if (out == NULL || !Day_Valid(day) || (kind == IEC60870_ENERGY_FREEZE_INTERVAL &&
(slot == 0U || slot > 96U))) { return IEC60870_ENERGY_FREEZE_INVALID; }
if (!Retained(self, day)) { return IEC60870_ENERGY_FREEZE_EMPTY; }
result = Load(self, kind, Index(kind, day, slot), &h, &size);
/* 环槽中可能残留旧日期;但若RAM已知本日此位存在,缺失/错日就是数据丢失。 */
if (result == IEC60870_ENERGY_FREEZE_EMPTY || (result == IEC60870_ENERGY_FREEZE_OK && h.day != day)) {
return Bit(self->present[day % 32U], bit) ? Fault(self, IEC60870_ENERGY_FREEZE_ERROR) :
IEC60870_ENERGY_FREEZE_EMPTY;
}
if (result != IEC60870_ENERGY_FREEZE_OK) { return result; }
Decode_Record(self, &h, out);
return IEC60870_ENERGY_FREEZE_OK;
}
/**
* 功能:读取指定业务日序的第1..96节冻结副本,第1节对应窗口起点。
* 输入参数:self——调用方持有的模块实例及当前状态;day——相对1970-01-01的本地日序;slot——冻结节号;INTERVAL为1..96,DAY为0。
* 输出参数:self——复用工作区及读取校验可能锁存的故障状态;out——成功时写入的独立结果副本。
* 返回值:OK表示操作完成;EMPTY表示没有所需记录或到期任务;INVALID表示参数或操作状态非法;ERROR表示实例不可用、I/O失败或内容损坏;CONFIG表示持久记录与当前配置指纹不符。
* 说明:透传Read_Record结果,仅OK时填写out;未封存记录也可读,损坏读取可锁存故障。
*/
IEC60870_EnergyFreezeResult_t IEC60870_EnergyFreeze_Read_Interval(IEC60870_EnergyFreeze_t *self,
uint32_t day, uint16_t slot, IEC60870_EnergyFreezeRecord_t *out)
{
return Read_Record(self, IEC60870_ENERGY_FREEZE_INTERVAL, day, slot, out);
}
/**
* 功能:读取指定业务窗口起点的DAY示值,返回记录slot为0,不计算日用电量。
* 输入参数:self——调用方持有的模块实例及当前状态;day——相对1970-01-01的本地日序。
* 输出参数:self——复用工作区及读取校验可能锁存的故障状态;out——成功时写入的独立结果副本。
* 返回值:OK表示操作完成;EMPTY表示没有所需记录或到期任务;INVALID表示参数或操作状态非法;ERROR表示实例不可用、I/O失败或内容损坏;CONFIG表示持久记录与当前配置指纹不符。
* 说明:透传Read_Record结果,仅OK时填写out;普通缺测或保留范围外返回EMPTY。
*/
IEC60870_EnergyFreezeResult_t IEC60870_EnergyFreeze_Read_Day(IEC60870_EnergyFreeze_t *self,
uint32_t day, IEC60870_EnergyFreezeRecord_t *out)
{
return Read_Record(self, IEC60870_ENERGY_FREEZE_DAY, day, 0U, out);
}
/**
* 功能:读取保留范围内的SEAL自身,仅OK时填写out;count为0也表示合法封存。
* 输入参数:self——调用方持有的模块实例及当前状态;day——相对1970-01-01的本地日序。
* 输出参数:self——复用工作区及读取校验可能锁存的故障状态;out——成功时写入的独立结果副本。
* 返回值:OK表示操作完成;EMPTY表示没有所需记录或到期任务;INVALID表示参数或操作状态非法;ERROR表示实例不可用、I/O失败或内容损坏。
* 说明:无封存返回EMPTY,参数非法返回INVALID;应有SEAL却无法验证时锁存故障并返回ERROR。 本函数不扫描正文,整体内容校验由Validate_Seal或XML导出完成。
*/
IEC60870_EnergyFreezeResult_t IEC60870_EnergyFreeze_Get_Seal(IEC60870_EnergyFreeze_t *self,
uint32_t day, IEC60870_EnergyFreezeSeal_t *out)
{
EfHeader h;
IEC60870_EnergyFreezeSeal_t value;
size_t length;
IEC60870_EnergyFreezeResult_t result;
if (!Ready(self)) { return IEC60870_ENERGY_FREEZE_ERROR; }
if (out == NULL || !Day_Valid(day)) { return IEC60870_ENERGY_FREEZE_INVALID; }
if (!Retained(self, day) || !self->sealed_valid || day > self->sealed_day) { return IEC60870_ENERGY_FREEZE_EMPTY; }
result = Load(self, IEC60870_ENERGY_FREEZE_SEAL, day % 32U, &h, &length);
if (result != IEC60870_ENERGY_FREEZE_OK || h.day != day) { return Fault(self, IEC60870_ENERGY_FREEZE_ERROR); }
memset(&value, 0, sizeof(value)); value.day = day; value.observed_utc_ms = h.observed;
memcpy(value.bitmap, self->wire + 44U, 13U); value.count = self->wire[57];
value.content_crc = (uint32_t)Get(self->wire + 58U, 4U); *out = value;
return IEC60870_ENERGY_FREEZE_OK;
}
/**
* 功能:将4字节小端日序及完整13字节存在位图纳入摘要前缀。
* 输入参数:day——相对1970-01-01的本地日序;bitmap——97位记录存在位图。
* 输出参数:无。
* 返回值:包含日序和位图前缀的未取反CRC状态。
* 说明:返回未取反CRC,随后严格按INTERVAL 1..96、DAY顺序追加记录正文。
*/
static uint32_t Digest_Start(uint32_t day, const uint8_t bitmap[13])
{
uint8_t bytes[4];
uint32_t crc;
Put(bytes, day, 4U); crc = Crc_Update(UINT32_MAX, bytes, 4U);
return Crc_Update(crc, bitmap, 13U);
}
/**
* 功能:核对全部97个位置与bitmap一致并计算正文摘要,正常完成读取97次,遇错提前返回。
* 输入参数:self——调用方持有的模块实例及当前状态;day——相对1970-01-01的本地日序;bitmap——97位记录存在位图。
* 输出参数:self——本次操作后的运行状态及复用工作区;digest——仅OK时写入最终取反的整体摘要。
* 返回值:OK表示操作完成;ERROR表示实例不可用、I/O失败或内容损坏;CONFIG表示持久记录与当前配置指纹不符。
* 说明:bitmap须独立于会被覆盖的wire;仅OK时填写最终取反的digest,读取错误透传。 空位也读取以检出意外增添;合法的其他日期残留视为本日不存在,已提交损坏仍报错。 存在位不符锁存故障;
* 摘要排除各记录尾CRC。
*/
static IEC60870_EnergyFreezeResult_t Window_Digest(IEC60870_EnergyFreeze_t *self,
uint32_t day, const uint8_t bitmap[13], uint32_t *digest)
{
unsigned bit;
uint32_t crc = Digest_Start(day, bitmap);
for (bit = 0U; bit < 97U; ++bit) {
IEC60870_EnergyFreezeKind_t kind = bit == 96U ? IEC60870_ENERGY_FREEZE_DAY : IEC60870_ENERGY_FREEZE_INTERVAL;
uint16_t slot = bit == 96U ? 0U : (uint16_t)(bit + 1U);
EfHeader h;
size_t length;
IEC60870_EnergyFreezeResult_t result = Load(self, kind, Index(kind, day, slot), &h, &length);
bool present = result == IEC60870_ENERGY_FREEZE_OK && h.day == day;
if (result != IEC60870_ENERGY_FREEZE_OK && result != IEC60870_ENERGY_FREEZE_EMPTY) { return result; }
if (present != Bit(bitmap, bit)) { return Fault(self, IEC60870_ENERGY_FREEZE_ERROR); }
if (present) { crc = Crc_Update(crc, self->wire, length - 4U); }
}
*digest = ~crc;
return IEC60870_ENERGY_FREEZE_OK;
}
/**
* 功能:验证SEAL的存在位图及正文摘要,空封存同样验证;整个过程须串行独占。
* 输入参数:self——调用方持有的模块实例及当前状态;day——相对1970-01-01的本地日序。
* 输出参数:self——复用工作区及读取校验可能锁存的故障状态。
* 返回值:OK表示操作完成;EMPTY表示没有所需记录或到期任务;INVALID表示参数或操作状态非法;ERROR表示实例不可用、I/O失败或内容损坏;CONFIG表示持久记录与当前配置指纹不符。
* 说明:全部一致返回OK,无封存返回EMPTY,参数/读取错误透传;摘要不符返回ERROR。 不修改介质,但正文缺失、意外增添或摘要不符会锁存faulted。
*/
IEC60870_EnergyFreezeResult_t IEC60870_EnergyFreeze_Validate_Seal(IEC60870_EnergyFreeze_t *self, uint32_t day)
{
IEC60870_EnergyFreezeSeal_t seal;
uint32_t digest;
IEC60870_EnergyFreezeResult_t result = IEC60870_EnergyFreeze_Get_Seal(self, day, &seal);
if (result != IEC60870_ENERGY_FREEZE_OK) { return result; }
result = Window_Digest(self, day, seal.bitmap, &digest);
if (result != IEC60870_ENERGY_FREEZE_OK) { return result; }
if (digest != seal.content_crc) { return Fault(self, IEC60870_ENERGY_FREEZE_ERROR); }
return IEC60870_ENERGY_FREEZE_OK;
}
/**
* 功能:只读扫描META、SEAL及记录,重建保留边界、高水位、封存前沿和事件序号。
* 输入参数:self——调用方持有的模块实例及当前状态;config——配置及调用期间借用的元数据;store——同步存储回调表及其上下文。
* 输出参数:self——本次操作后的运行状态及复用工作区。
* 返回值:OK表示操作完成;INVALID表示参数或操作状态非法;CONFIG表示持久记录与当前配置指纹不符;ERROR表示实例不可用、I/O失败或内容损坏。
* 说明:config/store结构按值复制,点表及context仍借用;回调须持续有效且不可重入。 参数非法在清空实例前返回INVALID;有效参数通过后清空旧RAM状态,
* 全部校验成功才置initialized。 指纹不符返回CONFIG,持久校验失败返回ERROR并锁存faulted,可能保留部分恢复状态。 不修复或清空介质,也不回填滞后META。
*/
IEC60870_EnergyFreezeResult_t IEC60870_EnergyFreeze_Init(IEC60870_EnergyFreeze_t *self,
const IEC60870_EnergyFreezeConfig_t *config, const IEC60870_EnergyFreezeStore_t *store)
{
IEC60870_EnergyFreezeConfig_t saved_config;
IEC60870_EnergyFreezeStore_t saved_store;
uint8_t seal_bitmap[32][13];
uint32_t seal_crc[32], computed_crc[32];
uint32_t index, day, hint = 0U;
uint64_t meta_sequence = 0U, first_sequence = UINT64_MAX;
bool hint_valid = false, found = false, gap = false;
EfHeader h;
size_t length;
IEC60870_EnergyFreezeResult_t result;
unsigned pass;
const IEC60870_EnergyFreezeKind_t order[4] = {
IEC60870_ENERGY_FREEZE_SEAL, IEC60870_ENERGY_FREEZE_INTERVAL,
IEC60870_ENERGY_FREEZE_DAY, IEC60870_ENERGY_FREEZE_FLOWREV
};
if (self == NULL || !Config_Valid(config) || store == NULL || store->read == NULL || store->commit == NULL) {
return IEC60870_ENERGY_FREEZE_INVALID;
}
/* 支持传入self内原有config/store恢复实例,须在清零前保存结构副本。 */
saved_config = *config; saved_store = *store;
memset(self, 0, sizeof(*self)); self->config = saved_config; self->store = saved_store;
self->fingerprint = Fingerprint(&self->config);
memset(seal_bitmap, 0, sizeof(seal_bitmap));
memset(seal_crc, 0, sizeof(seal_crc)); memset(computed_crc, 0, sizeof(computed_crc));
result = Load(self, IEC60870_ENERGY_FREEZE_META, 0U, &h, &length);
if (result != IEC60870_ENERGY_FREEZE_OK && result != IEC60870_ENERGY_FREEZE_EMPTY) { return result; }
if (result == IEC60870_ENERGY_FREEZE_OK) {
self->have_meta = true; self->observed_utc_ms = h.observed;
self->retained_valid = (self->wire[56] & 1U) != 0U;
self->retained_from = (uint32_t)Get(self->wire + 48U, 4U);
self->evicted_unsealed = (uint32_t)Get(self->wire + 52U, 4U);
hint_valid = (self->wire[56] & 2U) != 0U;
hint = (uint32_t)Get(self->wire + 44U, 4U);
meta_sequence = Get(self->wire + 60U, 8U);
}
/* 先读SEAL以取得位图和期望摘要,随后扫描数据时直接累积,避免第二遍读源。
* INTERVAL物理槽保持每窗I1..I96顺序,DAY统一在后;FLOW不参与窗口摘要。 */
for (pass = 0U; pass < 4U; ++pass) {
IEC60870_EnergyFreezeKind_t kind = order[pass];
for (index = 0U; index < IEC60870_EnergyFreeze_Slot_Count(kind); ++index) {
uint32_t physical;
result = Load(self, kind, index, &h, &length);
if (result == IEC60870_ENERGY_FREEZE_EMPTY) { continue; }
if (result != IEC60870_ENERGY_FREEZE_OK) { return result; }
found = true;
if (kind == IEC60870_ENERGY_FREEZE_FLOWREV) {
++self->flow_count;
if (h.sequence < first_sequence) { first_sequence = h.sequence; }
if (h.sequence > self->flow_sequence) { self->flow_sequence = h.sequence; }
continue;
}
/* 旧窗虽可被淘汰,其有效持久观测时间仍用于重建高水位W。 */
if (h.observed > self->observed_utc_ms) { self->observed_utc_ms = h.observed; }
if (!self->retained_valid) { return Fault(self, IEC60870_ENERGY_FREEZE_ERROR); }
if (h.day < self->retained_from) { continue; }
if (h.day - self->retained_from >= 32U) { return Fault(self, IEC60870_ENERGY_FREEZE_ERROR); }
physical = h.day % 32U;
if (kind == IEC60870_ENERGY_FREEZE_SEAL) {
self->seals[physical] = true;
memcpy(seal_bitmap[physical], self->wire + 44U, 13U);
seal_crc[physical] = (uint32_t)Get(self->wire + 58U, 4U);
computed_crc[physical] = Digest_Start(h.day, seal_bitmap[physical]);
} else {
uint64_t nominal = Nominal(h.freeze);
Set_Bit(self->present[physical], kind == IEC60870_ENERGY_FREEZE_DAY ? 96U : h.slot - 1U);
if (self->seals[physical]) {
computed_crc[physical] = Crc_Update(computed_crc[physical], self->wire, length - 4U);
}
if (kind == IEC60870_ENERGY_FREEZE_INTERVAL) {
if (!self->have_interval || nominal > self->latest_interval) { self->latest_interval = nominal; }
self->have_interval = true;
} else {
if (!self->have_day || nominal > self->latest_day) { self->latest_day = nominal; }
self->have_day = true;
}
}
}
}
/* 所有首次写入都先建立META;有事实却无META不能当成全新空库。 */
if (!self->have_meta && found) { return Fault(self, IEC60870_ENERGY_FREEZE_ERROR); }
/* 最大序号、最小序号、条数及Load的取模槽检查共同约束最近连续事件段。
* 事实可领先META,但不得落后其序号下界,以免静默丢失已提交尾部。 */
if (self->flow_sequence < meta_sequence ||
self->flow_count != (self->flow_sequence < 256U ? (size_t)self->flow_sequence : 256U) ||
(self->flow_count != 0U && first_sequence != self->flow_sequence - self->flow_count + 1U)) {
return Fault(self, IEC60870_ENERGY_FREEZE_ERROR);
}
/* 保留范围内的SEAL须从R开始连续;空窗也有SEAL,因此不能跳过缺口。 */
if (self->retained_valid) {
for (index = 0U; index < 32U; ++index) {
day = self->retained_from + index;
if (!self->seals[day % 32U]) { gap = true; continue; }
if (gap || !Day_Valid(day) ||
memcmp(seal_bitmap[day % 32U], self->present[day % 32U], 13U) != 0 ||
seal_crc[day % 32U] != ~computed_crc[day % 32U]) {
return Fault(self, IEC60870_ENERGY_FREEZE_ERROR);
}
self->sealed_valid = true; self->sealed_day = day;
}
}
/* META前沿仅为提示:允许滞后SEAL事实,不允许声称已封存却无法验证。 */
if (hint_valid && hint >= self->retained_from &&
(!self->sealed_valid || hint > self->sealed_day)) {
return Fault(self, IEC60870_ENERGY_FREEZE_ERROR);
}
self->initialized = true;
return IEC60870_ENERGY_FREEZE_OK;
}
/**
* 功能:比较记录与输入的count、float原始字节及品质,输入数组须至少有count项。
* 输入参数:record——记录值副本;values——按配置点序排列的值;quality——与值数组同序的品质;count——数组项数。
* 输出参数:无。
* 返回值:true表示点数、float原始字节及品质全部相同,false表示存在差异。
* 说明:不比较采样/提交时刻;正负零也视为不同,不能用浮点数值相等替代。
*/
static bool Same_Values(const IEC60870_EnergyFreezeRecord_t *record,
const float *values, const uint8_t *quality, size_t count)
{
return record->count == count && memcmp(record->values, values, count * sizeof(float)) == 0 &&
memcmp(record->quality, quality, count) == 0;
}
/**
* 功能:提交已通过准入或由第1节派生的INTERVAL/DAY,成功后发布存在位及最大名义网格。
* 输入参数:self——调用方持有的模块实例及当前状态;kind——记录或文件类别;record——记录值副本。
* 输出参数:self——本次操作后的运行状态及复用工作区。
* 返回值:OK表示操作完成;TIME_REJECTED表示网格、延迟或窗口顺序不允许;ERROR表示实例不可用、I/O失败或内容损坏。
* 说明:先经Prepare_Window保证边界,再序列化和提交;OK表示记录已提交,其他错误透传。 不重复检查品质或迟到时间,补旧DAY时最大网格只取max;失败不撤销此前META提交。
*/
static IEC60870_EnergyFreezeResult_t Write_Record(IEC60870_EnergyFreeze_t *self,
IEC60870_EnergyFreezeKind_t kind, const IEC60870_EnergyFreezeRecord_t *record)
{
EfHeader h;
size_t i;
uint64_t nominal = Nominal(record->freeze_utc_ms);
IEC60870_EnergyFreezeResult_t result = Prepare_Window(self, record->day);
if (result != IEC60870_ENERGY_FREEZE_OK) { return result; }
memset(&h, 0, sizeof(h)); h.count = (uint8_t)record->count;
h.day = record->day; h.slot = record->slot; h.freeze = record->freeze_utc_ms;
h.observed = record->observed_utc_ms; Header(self, kind, &h);
for (i = 0U; i < record->count; ++i) {
Write_Float(self->wire + EF_HEADER + i * 5U, &record->values[i]);
self->wire[EF_HEADER + i * 5U + 4U] = record->quality[i];
}
result = Commit(self, kind, Index(kind, record->day, record->slot), 48U + 5U * record->count);
if (result != IEC60870_ENERGY_FREEZE_OK) { return result; }
/* 正文成功提交后才发布存在位;补旧DAY时最大名义网格保持单调。 */
Set_Bit(self->present[record->day % 32U], kind == IEC60870_ENERGY_FREEZE_DAY ? 96U : record->slot - 1U);
if (kind == IEC60870_ENERGY_FREEZE_DAY) {
if (!self->have_day || nominal > self->latest_day) { self->latest_day = nominal; }
self->have_day = true;
} else {
if (!self->have_interval || nominal > self->latest_interval) { self->latest_interval = nominal; }
self->have_interval = true;
}
return IEC60870_ENERGY_FREEZE_OK;
}
/**
* 功能:INTERVAL/DAY共用准入:now为观测UTC毫秒,freeze为实际采样UTC毫秒,归槽后仍保存原时刻。
* 输入参数:self——调用方持有的模块实例及当前状态;kind——记录或文件类别;now——本次观测UTC毫秒;freeze——实际采样UTC毫秒;values——按配置点序排列的值;
* quality——与值数组同序的品质;count——数组项数。
* 输出参数:self——本次操作后的运行状态及复用工作区。
* 返回值:OK表示操作完成;DUPLICATE表示已有相同内容,未重复提交;SKIPPED表示整条冻结品质不合格;INVALID表示参数或操作状态非法;ERROR表示实例不可用、I/O失败或内容损坏;
* CONFIG表示持久记录与当前配置指纹不符;TIME_REVERSED表示观测时间低于高水位;TIME_REJECTED表示网格、延迟或窗口顺序不允许;CONFLICT表示已有记录内容不同。
* 说明:values/quality按对应点表排列,count须非零且等于point_count。 依次检查时间、整组品质、最新网格重复/冲突后提交;坏品质或非有限值整条SKIPPED。
* 新写入返回OK,同内容返回DUPLICATE,其他情况返回相应准入/存储错误。 基本参数及回拨检查通过即推进RAM高水位,后续拒绝不回退;DAY还须命中窗口起点。
*/
static IEC60870_EnergyFreezeResult_t Record(IEC60870_EnergyFreeze_t *self,
IEC60870_EnergyFreezeKind_t kind, uint64_t now, uint64_t freeze,
const float *values, const uint8_t *quality, size_t count)
{
uint64_t nominal, start, difference, latest;
uint32_t day;
bool have_latest;
size_t i;
IEC60870_EnergyFreezeRecord_t record;
IEC60870_EnergyFreezeResult_t result;
if (!Ready(self)) { return IEC60870_ENERGY_FREEZE_ERROR; }
if (!Utc_Valid(now) || !Utc_Valid(freeze) || count == 0U || count != self->config.point_count ||
values == NULL || quality == NULL) { return IEC60870_ENERGY_FREEZE_INVALID; }
if (now < self->observed_utc_ms) { return IEC60870_ENERGY_FREEZE_TIME_REVERSED; }
/* 通过基本参数及回拨检查即接受此次观测;后续拒绝/跳过也不回退RAM高水位。 */
self->observed_utc_ms = now;
nominal = Nominal(freeze);
difference = nominal > freeze ? nominal - freeze : freeze - nominal;
day = IEC60870_EnergyFreeze_Window_Day(nominal, self->config.day_start_minutes);
latest = kind == IEC60870_ENERGY_FREEZE_DAY ? self->latest_day : self->latest_interval;
have_latest = kind == IEC60870_ENERGY_FREEZE_DAY ? self->have_day : self->have_interval;
if (difference > self->config.grid_tolerance_ms ||
(freeze > now ? freeze - now > self->config.grid_tolerance_ms : now - freeze > self->config.max_delay_ms) ||
!IEC60870_EnergyFreeze_Window_Start(day, self->config.day_start_minutes, &start) ||
(kind == IEC60870_ENERGY_FREEZE_DAY && nominal != start) ||
(self->retained_valid && day < self->retained_from) ||
(Retained(self, day) && self->seals[day % 32U]) || (have_latest && nominal < latest)) {
return IEC60870_ENERGY_FREEZE_TIME_REJECTED;
}
/* 冻结记录要求整组有效,不能仅保存其中若干点而破坏固定点序。 */
for (i = 0U; i < count; ++i) {
if (quality[i] != 0U || !isfinite(values[i])) { return IEC60870_ENERGY_FREEZE_SKIPPED; }
}
/* 只有该类最新网格可幂等重交;更旧网格已在时间准入阶段拒绝。 */
if (have_latest && nominal == latest) {
result = Read_Record(self, kind, day, kind == IEC60870_ENERGY_FREEZE_DAY ? 0U :
(uint16_t)((nominal - start) / EF_GRID + 1U), &record);
if (result != IEC60870_ENERGY_FREEZE_OK) { return Fault(self, IEC60870_ENERGY_FREEZE_ERROR); }
return Same_Values(&record, values, quality, count) ? IEC60870_ENERGY_FREEZE_DUPLICATE :
IEC60870_ENERGY_FREEZE_CONFLICT;
}
memset(&record, 0, sizeof(record)); record.day = day;
record.slot = kind == IEC60870_ENERGY_FREEZE_DAY ? 0U : (uint16_t)((nominal - start) / EF_GRID + 1U);
record.freeze_utc_ms = freeze; record.observed_utc_ms = now; record.count = count;
memcpy(record.values, values, count * sizeof(float)); memcpy(record.quality, quality, count);
return Write_Record(self, kind, &record);
}
/**
* 功能:按interval_ioas点序写入完整冻结快照,count须非零且等于point_count。
* 输入参数:self——调用方持有的模块实例及当前状态;now——本次观测UTC毫秒;freeze——实际采样UTC毫秒;values——按配置点序排列的值;quality——与值数组同序的品质;
* count——数组项数。
* 输出参数:self——本次操作后的运行状态及复用工作区。
* 返回值:OK表示操作完成;DUPLICATE表示已有相同内容,未重复提交;SKIPPED表示整条冻结品质不合格;INVALID表示参数或操作状态非法;ERROR表示实例不可用、I/O失败或内容损坏;
* CONFIG表示持久记录与当前配置指纹不符;TIME_REVERSED表示观测时间低于高水位;TIME_REJECTED表示网格、延迟或窗口顺序不允许;CONFLICT表示已有记录内容不同。
* 说明:now用于观测/延迟检查,freeze须为实际采样UTC毫秒,不能以Due名义网格冒充。 透传Record结果;可能推进高水位、保留边界及提交记录,失败不承诺无状态变化。
*/
IEC60870_EnergyFreezeResult_t IEC60870_EnergyFreeze_Record_Interval(IEC60870_EnergyFreeze_t *self,
uint64_t now, uint64_t freeze, const float *values, const uint8_t *quality, size_t count)
{
return Record(self, IEC60870_ENERGY_FREEZE_INTERVAL, now, freeze, values, quality, count);
}
/**
* 功能:按day_ioas点序直接提交窗口起点DAY示值,不计算日增量。
* 输入参数:self——调用方持有的模块实例及当前状态;now——本次观测UTC毫秒;freeze——实际采样UTC毫秒;values——按配置点序排列的值;quality——与值数组同序的品质;
* count——数组项数。
* 输出参数:self——本次操作后的运行状态及复用工作区。
* 返回值:OK表示操作完成;DUPLICATE表示已有相同内容,未重复提交;SKIPPED表示整条冻结品质不合格;INVALID表示参数或操作状态非法;ERROR表示实例不可用、I/O失败或内容损坏;
* CONFIG表示持久记录与当前配置指纹不符;TIME_REVERSED表示观测时间低于高水位;TIME_REJECTED表示网格、延迟或窗口顺序不允许;CONFLICT表示已有记录内容不同。
* 说明:freeze归槽后的名义网格须为窗口起点;count须非零且等于point_count。 其余时间、品质、重复/冲突及状态副作用与Record_Interval一致,透传Record结果。
*/
IEC60870_EnergyFreezeResult_t IEC60870_EnergyFreeze_Record_Day(IEC60870_EnergyFreeze_t *self,
uint64_t now, uint64_t freeze, const float *values, const uint8_t *quality, size_t count)
{
return Record(self, IEC60870_ENERGY_FREEZE_DAY, now, freeze, values, quality, count);
}
/**
* 功能:从指定未封存窗口已存第1节派生DAY,保留原示值、品质及freeze,observed取now。
* 输入参数:self——调用方持有的模块实例及当前状态;now——本次观测UTC毫秒;day——相对1970-01-01的本地日序。
* 输出参数:self——本次操作后的运行状态及复用工作区。
* 返回值:OK表示操作完成;DUPLICATE表示已有相同内容,未重复提交;EMPTY表示没有所需记录或到期任务;INVALID表示参数或操作状态非法;ERROR表示实例不可用、I/O失败或内容损坏;
* CONFIG表示持久记录与当前配置指纹不符;TIME_REVERSED表示观测时间低于高水位;TIME_REJECTED表示网格、延迟或窗口顺序不允许;CONFLICT表示已有记录内容不同。
* 说明:新写入OK、已有同内容DUPLICATE、不同内容CONFLICT、无源EMPTY;其他准入/读取/提交错误透传。 不重新采样、不套当前迟到上限,可补较早DAY而不降低最大DAY网格。
* 基本参数及回拨检查通过后,即使缺源或拒绝也可能已推进RAM高水位。
*/
IEC60870_EnergyFreezeResult_t IEC60870_EnergyFreeze_Derive_Day(IEC60870_EnergyFreeze_t *self,
uint64_t now, uint32_t day)
{
IEC60870_EnergyFreezeRecord_t source, existing;
IEC60870_EnergyFreezeResult_t result;
if (!Ready(self)) { return IEC60870_ENERGY_FREEZE_ERROR; }
if (!Utc_Valid(now) || !Day_Valid(day) || self->config.point_count == 0U) { return IEC60870_ENERGY_FREEZE_INVALID; }
if (now < self->observed_utc_ms) { return IEC60870_ENERGY_FREEZE_TIME_REVERSED; }
self->observed_utc_ms = now;
if ((self->retained_valid && day < self->retained_from) ||
(Retained(self, day) && self->seals[day % 32U])) { return IEC60870_ENERGY_FREEZE_TIME_REJECTED; }
result = IEC60870_EnergyFreeze_Read_Interval(self, day, 1U, &source);
if (result != IEC60870_ENERGY_FREEZE_OK) { return result; }
result = IEC60870_EnergyFreeze_Read_Day(self, day, &existing);
if (result == IEC60870_ENERGY_FREEZE_OK) {
return Same_Values(&existing, source.values, source.quality, source.count) ?
IEC60870_ENERGY_FREEZE_DUPLICATE : IEC60870_ENERGY_FREEZE_CONFLICT;
}
if (result != IEC60870_ENERGY_FREEZE_EMPTY) { return result; }
/* 从持久第1节派生,不重新采当前值,也不让当前延迟门限拒绝这份历史快照。 */
source.slot = 0U; source.observed_utc_ms = now;
return Write_Record(self, IEC60870_ENERGY_FREEZE_DAY, &source);
}
/**
* 功能:计算满足“窗口结束+允许延迟<=W”的最后窗口,不查询实际数据或封存前沿。
* 输入参数:self——只读模块实例。
* 输出参数:day——成功时写入的本地日序。
* 返回值:true表示已找到可表示的到期窗口;false表示没有且不改写day。
* 说明:有可表示的到期窗口才填写day并返回true,false时输出不变;结果上限截到公开末日。
*/
static bool Last_Expired(const IEC60870_EnergyFreeze_t *self, uint32_t *day)
{
uint64_t shifted, number;
uint64_t offset = (uint64_t)self->config.day_start_minutes * 60000U;
if (self->observed_utc_ms < self->config.max_delay_ms + offset) { return false; }
shifted = self->observed_utc_ms - self->config.max_delay_ms + EF_OFFSET - offset;
number = shifted / EF_DAY_MS;
if (number == 0U || number - 1U < EF_FIRST_DAY) { return false; }
*day = number - 1U > EF_LAST_DAY ? EF_LAST_DAY : (uint32_t)(number - 1U);
return true;
}
/**
* 功能:用now推进观测高水位,按连续前沿至多封存一个到期窗口,空窗口也可封存。
* 输入参数:self——调用方持有的模块实例及当前状态;now——本次观测UTC毫秒。
* 输出参数:self——本次操作后的运行状态及复用工作区。
* 返回值:OK表示操作完成;INVALID表示参数或操作状态非法;ERROR表示实例不可用、I/O失败或内容损坏;CONFIG表示持久记录与当前配置指纹不符;
* TIME_REVERSED表示观测时间低于高水位;TIME_REJECTED表示网格、延迟或窗口顺序不允许。
* 说明:OK不保证产生新SEAL;尚未建立保留区时不创建历史空窗,回拨返回TIME_REVERSED。 先SEAL后META,跨环复用前还会提交新边界;后续错误不撤销已提交事实。
*/
IEC60870_EnergyFreezeResult_t IEC60870_EnergyFreeze_Advance(IEC60870_EnergyFreeze_t *self, uint64_t now)
{
uint32_t last, day, digest;
uint64_t start;
uint8_t bitmap[13];
EfHeader h;
IEC60870_EnergyFreezeResult_t result;
if (!Ready(self)) { return IEC60870_ENERGY_FREEZE_ERROR; }
if (!Utc_Valid(now)) { return IEC60870_ENERGY_FREEZE_INVALID; }
if (now < self->observed_utc_ms) { return IEC60870_ENERGY_FREEZE_TIME_REVERSED; }
self->observed_utc_ms = now;
if (self->config.point_count == 0U || !self->retained_valid || !Last_Expired(self, &last)) {
return IEC60870_ENERGY_FREEZE_OK;
}
/* 一次仅处理前沿之后一窗,包含空窗;积压由应用后续调用逐步追平。 */
day = self->sealed_valid ? self->sealed_day + 1U : self->retained_from;
if (day < self->retained_from) { day = self->retained_from; }
if (day > last) { return IEC60870_ENERGY_FREEZE_OK; }
result = Prepare_Window(self, day);
if (result != IEC60870_ENERGY_FREEZE_OK) { return result; }
if (day > last) { return IEC60870_ENERGY_FREEZE_OK; }
memcpy(bitmap, self->present[day % 32U], sizeof(bitmap));
result = Window_Digest(self, day, bitmap, &digest);
if (result != IEC60870_ENERGY_FREEZE_OK) { return result; }
if (!IEC60870_EnergyFreeze_Window_Start(day, self->config.day_start_minutes, &start)) {
return Fault(self, IEC60870_ENERGY_FREEZE_ERROR);
}
memset(&h, 0, sizeof(h)); h.day = day; h.freeze = start + EF_DAY_MS; h.observed = now;
Header(self, IEC60870_ENERGY_FREEZE_SEAL, &h);
memcpy(self->wire + 44U, bitmap, 13U); self->wire[57] = Bit_Count(bitmap);
Put(self->wire + 58U, digest, 4U);
result = Commit(self, IEC60870_ENERGY_FREEZE_SEAL, day % 32U, 66U);
if (result != IEC60870_ENERGY_FREEZE_OK) { return result; }
/* SEAL成功即不可再补写;即使随后META失败,Init也会以SEAL事实恢复前沿。 */
self->seals[day % 32U] = true; self->sealed_valid = true; self->sealed_day = day;
return Meta(self);
}
/**
* 功能:纯查询当前向下网格的冻结任务及最早可派生DAY窗口,不读介质、不推进W。
* 输入参数:self——只读模块实例;now——本次观测UTC毫秒。
* 输出参数:out——仅OK时写入到期名义网格及窗口任务。
* 返回值:OK表示有任务并写出结果;EMPTY表示无任务;INVALID表示参数非法;ERROR表示实例不可用;TIME_REVERSED表示now低于观测高水位。
* 说明:有任务返回OK并填写out,interval和derive_day可同时成立;EMPTY或错误保持输出不变。 只提示当前网格之后容差内的采样,不补造漏采值;
* 刚写第1节后需再次查询以发现DAY任务。
*/
IEC60870_EnergyFreezeResult_t IEC60870_EnergyFreeze_Due(const IEC60870_EnergyFreeze_t *self,
uint64_t now, IEC60870_EnergyFreezeDue_t *out)
{
IEC60870_EnergyFreezeDue_t due;
uint32_t day, i;
uint64_t nominal, start;
if (!Ready(self)) { return IEC60870_ENERGY_FREEZE_ERROR; }
if (out == NULL || !Utc_Valid(now)) { return IEC60870_ENERGY_FREEZE_INVALID; }
if (now < self->observed_utc_ms) { return IEC60870_ENERGY_FREEZE_TIME_REVERSED; }
memset(&due, 0, sizeof(due));
if (self->config.point_count != 0U) {
/* 调度只看已经到达的当前网格,不向上取整、不为错过的时刻补采当前值。 */
nominal = (now / EF_GRID) * EF_GRID;
day = IEC60870_EnergyFreeze_Window_Day(nominal, self->config.day_start_minutes);
if (now - nominal <= self->config.grid_tolerance_ms &&
IEC60870_EnergyFreeze_Window_Start(day, self->config.day_start_minutes, &start) &&
(!self->retained_valid || day >= self->retained_from) &&
(!self->have_interval || nominal > self->latest_interval) &&
(!Retained(self, day) || !self->seals[day % 32U]) &&
(!Retained(self, day) || !Bit(self->present[day % 32U], (unsigned)((nominal - start) / EF_GRID)))) {
due.interval = true; due.grid_utc_ms = nominal;
}
/* 另一独立任务:寻找最早已存第1节但缺DAY的未封存窗口。 */
if (self->retained_valid) {
for (i = 0U; i < 32U; ++i) {
day = self->retained_from + i;
if (!self->seals[day % 32U] && Bit(self->present[day % 32U], 0U) &&
!Bit(self->present[day % 32U], 96U)) {
due.derive_day = true; due.day = day; break;
}
}
}
}
if (!due.interval && !due.derive_day) { return IEC60870_ENERGY_FREEZE_EMPTY; }
*out = due;
return IEC60870_ENERGY_FREEZE_OK;
}
/**
* 功能:只读内存查询当前保留事件数;正常为0..256,NULL、未初始化或故障时也返回0。
* 输入参数:self——只读模块实例。
* 输出参数:无。
* 返回值:当前保留的FLOWREV事件数;实例不可用时返回0。
* 说明:不能以0单独判断空库,应结合Get_Status检查健康状态。
*/
size_t IEC60870_EnergyFreeze_FlowReverse_Count(const IEC60870_EnergyFreeze_t *self)
{
return Ready(self) ? self->flow_count : 0U;
}
/**
* 功能:把Load已校验的FLOWREV解码为独立事件副本,h须对应当前wire且点数不超EVENT_POINTS。
* 输入参数:self——只读模块实例;h——已校验或待编码的记录头。
* 输出参数:out——解码后的独立记录副本。
* 返回值:无。
* 说明:先清零out,再复制时标、索引、原始float位及品质;不筛除坏品质或非有限值。
*/
static void Decode_Flow(const IEC60870_EnergyFreeze_t *self, const EfHeader *h,
IEC60870_EnergyFreezeFlowReverse_t *out)
{
size_t i;
memset(out, 0, sizeof(*out)); out->sequence = h->sequence; out->occur_utc_ms = h->freeze; out->count = h->count;
for (i = 0U; i < h->count; ++i) {
uint32_t bits = (uint32_t)Get(self->wire + EF_HEADER + i * 6U + 1U, 4U);
out->indices[i] = self->wire[EF_HEADER + i * 6U];
memcpy(&out->values[i], &bits, 4U);
out->quality[i] = self->wire[EF_HEADER + i * 6U + 5U];
}
}
/**
* 功能:按持久序号由旧到新读出事件副本,oldest_index为0表示当前最旧事件,不是物理槽0。
* 输入参数:self——调用方持有的模块实例及当前状态;oldest_index——按提交顺序从最旧记录起的零基索引。
* 输出参数:self——复用工作区及读取校验可能锁存的故障状态;out——成功时写入的独立结果副本。
* 返回值:OK表示操作完成;EMPTY表示没有所需记录或到期任务;INVALID表示参数或操作状态非法;ERROR表示实例不可用、I/O失败或内容损坏。
* 说明:仅OK时填写out,越界返回EMPTY,参数或实例/读取错误返回相应结果。 应存在的事件读取失败或序号不符会锁存故障;不按occur墙钟排序。
*/
IEC60870_EnergyFreezeResult_t IEC60870_EnergyFreeze_Get_FlowReverse(IEC60870_EnergyFreeze_t *self,
size_t oldest_index, IEC60870_EnergyFreezeFlowReverse_t *out)
{
EfHeader h;
size_t length;
uint64_t sequence;
IEC60870_EnergyFreezeResult_t result;
if (!Ready(self)) { return IEC60870_ENERGY_FREEZE_ERROR; }
if (out == NULL) { return IEC60870_ENERGY_FREEZE_INVALID; }
if (oldest_index >= self->flow_count) { return IEC60870_ENERGY_FREEZE_EMPTY; }
/* 对外按持久序号而非物理槽号排序;环满后第0项不再对应物理槽0。 */
sequence = self->flow_sequence - self->flow_count + oldest_index + 1U;
result = Load(self, IEC60870_ENERGY_FREEZE_FLOWREV, (uint32_t)((sequence - 1U) % 256U), &h, &length);
if (result != IEC60870_ENERGY_FREEZE_OK || h.sequence != sequence) { return Fault(self, IEC60870_ENERGY_FREEZE_ERROR); }
Decode_Flow(self, &h, out);
return IEC60870_ENERGY_FREEZE_OK;
}
/**
* 功能:对最近16条按完整内容去重,再按到达顺序追加事件;环满覆盖最旧事件。
* 输入参数:self——调用方持有的模块实例及当前状态;occur——事件发生UTC毫秒;indices——FLOWREV点表的索引数组;values——与indices同序排列的事件值;
* quality——与值数组同序的品质;count——数组项数。
* 输出参数:self——本次操作后的运行状态及复用工作区。
* 返回值:OK表示操作完成;DUPLICATE表示已有相同内容,未重复提交;INVALID表示参数或操作状态非法;ERROR表示实例不可用、I/O失败或内容损坏。
* 说明:indices是flowrev_ioas的严格递增下标,count为1..8;值/品质原样保留,允许非有限值及坏品质。 occur为实际发生UTC毫秒,可回拨或乱序,不推进冻结观测高水位。
* 完整提交OK、去重DUPLICATE、参数INVALID;实例、持久或序号耗尽返回ERROR。 首次先建立META,常规先事件后META;失败不撤销事件,序号耗尽不回绕且该分支不锁存故障。
*/
IEC60870_EnergyFreezeResult_t IEC60870_EnergyFreeze_Append_FlowReverse(IEC60870_EnergyFreeze_t *self,
uint64_t occur, const uint8_t *indices, const float *values, const uint8_t *quality, size_t count)
{
size_t i, remaining;
EfHeader h;
IEC60870_EnergyFreezeFlowReverse_t previous;
IEC60870_EnergyFreezeResult_t result;
if (!Ready(self)) { return IEC60870_ENERGY_FREEZE_ERROR; }
if (!Utc_Valid(occur) || indices == NULL || values == NULL || quality == NULL ||
count == 0U || count > 8U || count > self->config.flowrev_count) { return IEC60870_ENERGY_FREEZE_INVALID; }
for (i = 0U; i < count; ++i) {
if (indices[i] >= self->config.flowrev_count || (i != 0U && indices[i] <= indices[i - 1U])) {
return IEC60870_ENERGY_FREEZE_INVALID;
}
}
/* 有界去重仅检查最新16条,允许旧发生时刻晚到;不以墙钟排序丢弃事件。 */
remaining = self->flow_count < 16U ? self->flow_count : 16U;
for (i = 0U; i < remaining; ++i) {
result = IEC60870_EnergyFreeze_Get_FlowReverse(self, self->flow_count - 1U - i, &previous);
if (result != IEC60870_ENERGY_FREEZE_OK) { return result; }
if (previous.occur_utc_ms == occur && previous.count == count &&
memcmp(previous.indices, indices, count) == 0 && memcmp(previous.values, values, count * sizeof(float)) == 0 &&
memcmp(previous.quality, quality, count) == 0) { return IEC60870_ENERGY_FREEZE_DUPLICATE; }
}
if (self->flow_sequence == UINT64_MAX) { return IEC60870_ENERGY_FREEZE_ERROR; }
if (!self->have_meta && Meta(self) != IEC60870_ENERGY_FREEZE_OK) { return IEC60870_ENERGY_FREEZE_ERROR; }
memset(&h, 0, sizeof(h)); h.sequence = self->flow_sequence + 1U;
h.freeze = occur; h.count = (uint8_t)count; Header(self, IEC60870_ENERGY_FREEZE_FLOWREV, &h);
for (i = 0U; i < count; ++i) {
self->wire[EF_HEADER + i * 6U] = indices[i];
Write_Float(self->wire + EF_HEADER + i * 6U + 1U, &values[i]);
self->wire[EF_HEADER + i * 6U + 5U] = quality[i];
}
result = Commit(self, IEC60870_ENERGY_FREEZE_FLOWREV, (uint32_t)((h.sequence - 1U) % 256U), 48U + count * 6U);
if (result != IEC60870_ENERGY_FREEZE_OK) { return result; }
/* 事件事实先提交,再持久更新META序号下界;后者失败时不能撤回事件。 */
self->flow_sequence = h.sequence; if (self->flow_count < 256U) { ++self->flow_count; }
return Meta(self);
}
/**
* 功能:复制RAM状态并按当前高水位计算封存积压,不访问介质或修改核心。
* 输入参数:self——只读模块实例。
* 输出参数:out——诊断快照,允许Init失败后faulted的部分状态;失败不变。
* 返回值:true表示已复制诊断快照;false表示指针无效或实例既未初始化也未故障。
* 说明:仅成功时填写out;指针无效或实例既未初始化也未故障时返回false。 允许诊断faulted实例,包括Init失败后的部分恢复字段,但不代表完整恢复已通过。
*/
bool IEC60870_EnergyFreeze_Get_Status(const IEC60870_EnergyFreeze_t *self, IEC60870_EnergyFreezeStatus_t *out)
{
IEC60870_EnergyFreezeStatus_t status;
uint32_t last, next;
if (self == NULL || out == NULL || (!self->initialized && !self->faulted)) { return false; }
memset(&status, 0, sizeof(status)); status.sealed_valid = self->sealed_valid;
status.sealed_day = self->sealed_day; status.retained_valid = self->retained_valid;
status.retained_from = self->retained_from; status.evicted_unsealed = self->evicted_unsealed;
status.observed_utc_ms = self->observed_utc_ms; status.flow_sequence = self->flow_sequence;
status.flow_count = self->flow_count; status.faulted = self->faulted;
if (self->config.point_count != 0U && self->retained_valid && Last_Expired(self, &last)) {
next = self->sealed_valid ? self->sealed_day + 1U : self->retained_from;
if (next < self->retained_from) { next = self->retained_from; }
if (last >= next) { status.seal_backlog = last - next + 1U; }
}
*out = status;
return true;
}