/* * 电能量文件流式编码:FRZ边读取边核验封存正文,FLOWREV按持久顺序展开有效点。 * SEAL摘要包含日期、位图和记录正文,不含各记录自身尾CRC;最终校验前不发布候选文件。 * 所有输出通过同步sink传递,不保存XML全文,也不接管文件系统或下载快照的生命周期。 */ #include "IEC60870_EnergyFreezeFile.h" #include "IEC60870_Time.h" #include #include #include #include #include /* size只累计sink已完整接收的字节;整个文件成功后才写回公开接口的size。 */ typedef struct { IEC60870_EnergyFreezeFileWriteFn write; void *context; uint32_t size; } EnergyXmlWriter; /** * 功能:同步输出以NUL结尾的文本,结尾NUL不传给sink;writer及回调须已初始化。 * 输入参数:writer——同步输出状态;调用方保证回调有效;text——文本或文本输出器。 * 输出参数:writer——输出器累计长度及其目标内容。 * 返回值:true表示本段内容已完整输出;false表示校验、格式化、读取或sink接收失败。 * 说明:长度溢出或sink拒收时返回false,只有完整接收后才累计size。 回调失败仍可能已有部分外部输出,不能据此回滚候选文件。 */ static bool Emit(EnergyXmlWriter *writer, const char *text) { size_t length = strlen(text); if (length > UINT32_MAX - writer->size || !writer->write(writer->context, (const uint8_t *)text, length)) { return false; } writer->size += (uint32_t)length; return true; } /** * 功能:输出无符号整数的十进制文本;格式化失败、截断或sink拒收时返回false。 * 输入参数:writer——同步输出状态;调用方保证回调有效;value——待处理数值。 * 输出参数:writer——输出器累计长度及其目标内容。 * 返回值:true表示本段内容已完整输出;false表示校验、格式化、读取或sink接收失败。 * 说明:写出片段通过同步回调交付;失败不撤回已经接收的前缀。 */ static bool Unsigned(EnergyXmlWriter *writer, uint32_t value) { char text[16]; int n = snprintf(text, sizeof(text), "%lu", (unsigned long)value); return n > 0 && (size_t)n < sizeof(text) && Emit(writer, text); } /** * 功能:以float32往返所需的9位有效数字输出有限值,要求二进制float且有效位为24位。 * 输入参数:writer——同步输出状态;调用方保证回调有效;value——待处理数值。 * 输出参数:writer——输出器累计长度及其目标内容。 * 返回值:true表示本段内容已完整输出;false表示校验、格式化、读取或sink接收失败。 * 说明:只替换本次结果的小数点为'.',不改变进程locale。 非有限值、浮点格式不符、格式化或输出失败均返回false。 */ static bool Number(EnergyXmlWriter *writer, float value) { char text[64], canonical[64]; const char *separator; char *where; size_t prefix; int n; if (!isfinite(value) || FLT_RADIX != 2 || FLT_MANT_DIG != 24) { return false; } n = snprintf(text, sizeof(text), "%.9g", (double)value); if (n <= 0 || (size_t)n >= sizeof(text)) { return false; } separator = localeconv()->decimal_point; if (separator == NULL || separator[0] == '\0') { return false; } where = strstr(text, separator); if (strcmp(separator, ".") == 0 || where == NULL) { return Emit(writer, text); } prefix = (size_t)(where - text); memcpy(canonical, text, prefix); canonical[prefix] = '.'; strcpy(canonical + prefix + 1U, where + strlen(separator)); return Emit(writer, canonical); } /** * 功能:验证属性原文:先按255字节限长,再检查UTF-8最短编码和XML允许的字符范围。 * 输入参数:value——待校验或输出的文本。 * 输出参数:无。 * 返回值:true表示文本满足长度、UTF-8及XML字符限制,false表示非法。 * 说明:NULL、截断序列、代理项和非法控制符均返回false,空字符串允许通过。 不修改或输出文本;仅转义五个XML特殊字符不足以替代本检查。 */ static bool Attribute_Valid(const char *value) { const unsigned char *p = (const unsigned char *)value; size_t i = 0U, length; if (value == NULL) { return false; } for (length = 0U; length <= IEC60870_ENERGY_FREEZE_FILE_ATTRIBUTE_MAX; ++length) { if (p[length] == 0U) { break; } } if (length > IEC60870_ENERGY_FREEZE_FILE_ATTRIBUTE_MAX) { return false; } while (i < length) { uint32_t code; unsigned extra, j; unsigned char first = p[i++]; if (first < 0x80U) { code = first; extra = 0U; } else if (first >= 0xc2U && first <= 0xdfU) { code = first & 0x1fU; extra = 1U; } else if (first >= 0xe0U && first <= 0xefU) { code = first & 0x0fU; extra = 2U; } else if (first >= 0xf0U && first <= 0xf4U) { code = first & 7U; extra = 3U; } else { return false; } if (extra > length - i) { return false; } for (j = 0U; j < extra; ++j) { unsigned char next = p[i++]; if ((next & 0xc0U) != 0x80U) { return false; } code = (code << 6) | (next & 0x3fU); } if ((extra == 1U && code < 0x80U) || (extra == 2U && code < 0x800U) || (extra == 3U && code < 0x10000U)) { return false; } if (!(code == 9U || code == 10U || code == 13U || (code >= 0x20U && code <= 0xd7ffU) || (code >= 0xe000U && code <= 0xfffdU) || (code >= 0x10000U && code <= 0x10ffffU))) { return false; } } return true; } /** * 功能:校验并转义UTF-8属性原文,不输出外层引号;制表符和换行使用字符引用,避免属性规范化改值。 * 输入参数:writer——同步输出状态;调用方保证回调有效;value——待校验或输出的文本。 * 输出参数:writer——输出器累计长度及其目标内容。 * 返回值:true表示本段内容已完整输出;false表示校验、格式化、读取或sink接收失败。 * 说明:非ASCII字节原样输出,sink须允许一个UTF-8字符拆成多个片段。 属性无效或输出失败时返回false,已接收的片段不会撤回。 */ static bool Attribute(EnergyXmlWriter *writer, const char *value) { char one[2] = {0, 0}; if (!Attribute_Valid(value)) { return false; } while (*value != '\0') { const char *escaped; switch (*value) { case '&': escaped = "&"; break; case '<': escaped = "<"; break; case '>': escaped = ">"; break; case '"': escaped = """; break; case '\'': escaped = "'"; break; case '\t': escaped = " "; break; case '\n': escaped = " "; break; case '\r': escaped = " "; break; default: one[0] = *value; escaped = one; break; } if (!Emit(writer, escaped)) { return false; } ++value; } return true; } /** * 功能:将业务窗口日序展开为路径所用的公历日期,不再次施加UTC+8偏移。 * 输入参数:day——相对1970-01-01的本地日序。 * 输出参数:time——转换后的日历;内部预检失败时不得使用。 * 返回值:true表示日期转换成功且年份受支持,false表示转换或范围检查失败。 * 说明:转换失败或年份不在2000..2099时返回false,此时time可能已被改写,不得使用。 */ static bool Date(uint32_t day, IEC60870_WallTime_t *time) { uint64_t seconds = (uint64_t)day * 86400U; return seconds <= IEC60870_TIME_MAX_SECONDS && IEC60870_Time_From_Seconds((uint32_t)seconds, 0U, time) && time->year >= 2000U && time->year <= 2099U; } /** * 功能:UTC毫秒转换为固定UTC+8时标:FRZ输出YYMMDD_HHMMSS,FLOWREV追加_mmm保留毫秒。 * 输入参数:writer——同步输出状态;调用方保证回调有效;utc_ms——UTC纪元毫秒;milliseconds——是否输出毫秒文本。 * 输出参数:writer——输出器累计长度及其目标内容。 * 返回值:true表示本段内容已完整输出;false表示校验、格式化、读取或sink接收失败。 * 说明:不读取系统时区,不对毫秒四舍五入;本地年份限2000..2099。 时间转换、格式化或输出失败时返回false。 */ static bool Timestamp(EnergyXmlWriter *writer, uint64_t utc_ms, bool milliseconds) { IEC60870_WallTime_t time; char text[24]; int n; if (utc_ms / 1000U > UINT32_MAX || !IEC60870_Time_Seconds_To_Local((uint32_t)(utc_ms / 1000U), (uint16_t)(utc_ms % 1000U), &time) || time.year < 2000U || time.year > 2099U) { return false; } if (milliseconds) { n = snprintf(text, sizeof(text), "%02u%02u%02u_%02u%02u%02u_%03u", (unsigned)(time.year - 2000U), (unsigned)time.month, (unsigned)time.day, (unsigned)time.hour, (unsigned)time.minute, (unsigned)time.second, (unsigned)time.ms); } else { n = snprintf(text, sizeof(text), "%02u%02u%02u_%02u%02u%02u", (unsigned)(time.year - 2000U), (unsigned)time.month, (unsigned)time.day, (unsigned)time.hour, (unsigned)time.minute, (unsigned)time.second); } return n > 0 && (size_t)n < sizeof(text) && Emit(writer, text); } /** * 功能:生成相对路径:FRZ按窗口日序生成HISTORY/FRZ/frzYYYYMMDD.xml, FLOWREV忽略day,固定为HISTORY/FLOWREV/flowrev.xml; * 不检查记录是否存在。 * 输入参数:kind——记录或文件类别;day——相对1970-01-01的本地日序;capacity——缓冲可用容量。 * 输出参数:name——成功生成的NUL结尾相对文件名;失败不变。 * 返回值:true表示文件名已完整生成;false表示参数非法或容量不足,输出不变。 * 说明:capacity包含结尾NUL;类别、日期无效或容量不足时返回false,并保持name原内容。 */ bool IEC60870_EnergyFreezeFile_Name(IEC60870_EnergyFreezeFileKind_t kind, uint32_t day, char *name, size_t capacity) { char text[IEC60870_ENERGY_FREEZE_FILE_PATH_CAPACITY]; IEC60870_WallTime_t date; int n; if (name == NULL || capacity == 0U) { return false; } if (kind == IEC60870_ENERGY_FREEZE_FILE_FLOWREV) { strcpy(text, "HISTORY/FLOWREV/flowrev.xml"); } else if (kind == IEC60870_ENERGY_FREEZE_FILE_FRZ && Date(day, &date)) { n = snprintf(text, sizeof(text), "HISTORY/FRZ/frz%04u%02u%02u.xml", (unsigned)date.year, (unsigned)date.month, (unsigned)date.day); if (n < 0 || (size_t)n >= sizeof(text)) { return false; } } else { return false; } if (strlen(text) >= capacity) { return false; } strcpy(name, text); return true; } /** * 功能:查询封存位图:位0..95对应第1..96节,位96对应DAY。 * 输入参数:seal——窗口封存信息;index——零基索引。 * 输出参数:无。 * 返回值:true表示指定位置已置位,false表示未置位。 * 说明:只读内存,不读介质;调用方保证seal有效且index不越界。 */ static bool Bit(const IEC60870_EnergyFreezeSeal_t *seal, unsigned index) { return (seal->bitmap[index / 8U] & (uint8_t)(1U << (index % 8U))) != 0U; } /** * 功能:与核心SEAL使用相同CRC-32递推,返回累计后的未取反状态;长度为零时原样返回crc。 * 输入参数:crc——当前未取反的CRC递推状态;bytes——字节数据;length——字节数。 * 输出参数:无。 * 返回值:更新后的未取反CRC状态。 * 说明:首段初值UINT32_MAX及最终取反由调用方处理,输入记录须排除各自尾CRC。 */ static uint32_t Digest_Update(uint32_t crc, const uint8_t *bytes, size_t length) { size_t i; for (i = 0U; i < length; ++i) { unsigned bit; crc ^= bytes[i]; for (bit = 0U; bit < 8U; ++bit) { crc = (crc >> 1) ^ ((crc & 1U) != 0U ? UINT32_C(0xedb88320) : 0U); } } return crc; } /** * 功能:输出FixFrz或DayFrz元数据,dataNum是每条记录的点数;两张IOA表按同索引使用units。 * 输入参数:writer——同步输出状态;调用方保证回调有效;freeze——电能冻结核心实例;config——配置及调用期间借用的元数据;daily——是否输出DAY点表; * count——实际存在的INTERVAL节数,daily为true时不使用。 * 输出参数:writer——输出器累计长度及其目标内容。 * 返回值:true表示本段内容已完整输出;false表示校验、格式化、读取或sink接收失败。 * 说明:FixFrz的sectNum取实际存在的INTERVAL节数count,不含DAY;DayFrz不使用count。 即使某类没有记录,调用方也保留其元数据;属性或输出失败返回false, * 可能已有部分输出。 */ static bool Data_Attributes(EnergyXmlWriter *writer, const IEC60870_EnergyFreeze_t *freeze, const IEC60870_EnergyFreezeFileConfig_t *config, bool daily, unsigned count) { size_t i; if (!Emit(writer, daily ? "config.point_count)) { return false; } if (!daily && (!Emit(writer, "\" sectNum=\"") || !Unsigned(writer, count) || !Emit(writer, "\" interval=\"15min"))) { return false; } if (!Emit(writer, "\">\n")) { return false; } for (i = 0U; i < freeze->config.point_count; ++i) { if (!Emit(writer, "config.day_ioas[i] : freeze->config.interval_ioas[i]) || !Emit(writer, "\" type=\"float\" unit=\"") || !Attribute(writer, config->units[i]) || !Emit(writer, "\"/>\n")) { return false; } } return Emit(writer, "\n"); } /** * 功能:输出已校验的冻结快照:slot为0表示DAY,1..96表示对应节,start是窗口起点UTC毫秒。 * 输入参数:writer——同步输出状态;调用方保证回调有效;record——记录值副本;slot——冻结节号;INTERVAL为1..96,DAY为0;start——首点或窗口起点。 * 输出参数:writer——输出器累计长度及其目标内容。 * 返回值:true表示本段内容已完整输出;false表示校验、格式化、读取或sink接收失败。 * 说明:XML使用标称网格,第1节和DAY均为窗口起点,不输出实际采样偏差,缺节也不重新编号。 时标或点值输出失败返回false;本函数不查询介质、不自行核验SEAL。 */ static bool Window_Record(EnergyXmlWriter *writer, const IEC60870_EnergyFreezeRecord_t *record, unsigned slot, uint64_t start) { size_t i; if (slot == 0U) { if (!Emit(writer, "\n")) { return false; } for (i = 0U; i < record->count; ++i) { if (!Emit(writer, "values[i]) || !Emit(writer, "\"/>\n")) { return false; } } return Emit(writer, "\n"); } /** * 功能:品质为零且数值有限的点才允许导出;FLOW可保存异常点,此处逐点过滤,不丢弃整条事件。 * 输入参数:event——事件值副本;point——事件内的零基测点下标。 * 输出参数:无。 * 返回值:true表示该事件点品质为0且数值有限,false表示该点不能导出。 * 说明:只检查内容,不修改事件;调用方保证point小于event->count。 */ static bool Flow_Valid(const IEC60870_EnergyFreezeFlowReverse_t *event, size_t point) { return event->quality[point] == 0U && isfinite(event->values[point]); } /** * 功能:输出FLOWREV记录主体,事件按持久序号、事件内按配置索引排列,无有效点时输出num=0。 * 输入参数:writer——同步输出状态;调用方保证回调有效;freeze——电能冻结核心实例。 * 输出参数:writer——输出器累计长度及其目标内容;freeze——复用读取工作区及完整性校验可能锁存的故障状态。 * 返回值:true表示本段内容已完整输出;false表示校验、格式化、读取或sink接收失败。 * 说明:核心须已就绪并启用反转点表;两遍读取期间独占核心、存储及点表,不提交持久记录。 读取、事件字段、时标或输出失败时返回false;核心读取错误可能锁存faulted,候选须整体丢弃。 */ static bool Flow_File(EnergyXmlWriter *writer, IEC60870_EnergyFreeze_t *freeze) { size_t count = IEC60870_EnergyFreeze_FlowReverse_Count(freeze), i, j; uint32_t total = 0U; IEC60870_EnergyFreezeFlowReverse_t event; /* 第一遍计算展开后的有效DI数量,第二遍输出,故两遍之间也必须独占输入。 * 事件按持久序号遍历,不按发生时刻重排;同一事件的多个点保留同一时标。 */ for (i = 0U; i < count; ++i) { if (IEC60870_EnergyFreeze_Get_FlowReverse(freeze, i, &event) != IEC60870_ENERGY_FREEZE_OK || event.count > IEC60870_ENERGY_FREEZE_EVENT_POINTS) { return false; } for (j = 0U; j < event.count; ++j) { if (event.indices[j] >= freeze->config.flowrev_count) { return false; } if (Flow_Valid(&event, j)) { ++total; } } } if (!Emit(writer, "\n")) { return false; } for (i = 0U; i < count; ++i) { size_t index; if (IEC60870_EnergyFreeze_Get_FlowReverse(freeze, i, &event) != IEC60870_ENERGY_FREEZE_OK) { return false; } /* 外层用配置索引保证点表顺序,与IOA数值大小无关。 */ for (index = 0U; index < freeze->config.flowrev_count; ++index) { for (j = 0U; j < event.count; ++j) { if (event.indices[j] != index || !Flow_Valid(&event, j)) { continue; } if (!Emit(writer, "config.flowrev_ioas[index]) || !Emit(writer, "\" tm=\"") || !Timestamp(writer, event.occur_utc_ms, true) || !Emit(writer, "\" val=\"") || !Number(writer, event.values[j]) || !Emit(writer, "\"/>\n")) { return false; } } } } return Emit(writer, "\n"); } /** * 功能:同步生成FRZ/FLOWREV候选XML,调用期间独占已就绪的核心、存储、点表及文件配置。 * 输入参数:freeze——电能冻结核心实例;kind——记录或文件类别;day——相对1970-01-01的本地日序;config——配置及调用期间借用的元数据;write——同步接收输出片段的回调; * context——传给输出回调的调用方上下文。 * 输出参数:freeze——复用读取工作区及完整性校验可能锁存的故障状态;size——仅完整成功时写入文件字节数,不含NUL;允许NULL的入口不强制输出。 * 返回值:true表示完整文件已输出;false表示参数、读取校验或输出回调失败,候选内容不可发布。 * 说明:FRZ按day导出最近30个封存窗口中的非空文件,核验全部97个位置;空FRZ仍验证后返回false。 FLOWREV忽略day,启用事件表后允许num=0;FRZ单位按点数提供, * 属性传UTF-8原文。 sink完整接收片段才返回true,不得重入或修改输入;借用片段不含NUL且可能拆开UTF-8字符。 整体成功才返回true并写回可选size(不含NUL); * 失败保持size原值,调用方丢弃全部候选内容。 存储/封存完整性错误锁存faulted,参数或sink失败本身不锁存故障;最终校验前不得发布。 */ bool IEC60870_EnergyFreezeFile_Write(IEC60870_EnergyFreeze_t *freeze, IEC60870_EnergyFreezeFileKind_t kind, uint32_t day, const IEC60870_EnergyFreezeFileConfig_t *config, IEC60870_EnergyFreezeFileWriteFn write, void *context, uint32_t *size) { EnergyXmlWriter writer; IEC60870_EnergyFreezeStatus_t status; IEC60870_EnergyFreezeSeal_t seal; uint64_t start = 0U; uint32_t digest = UINT32_MAX; unsigned slot, count = 0U; size_t i; if (freeze == NULL || config == NULL || write == NULL || !Attribute_Valid(config->device_name) || !IEC60870_EnergyFreeze_Get_Status(freeze, &status) || status.faulted) { return false; } /* 先校验导出范围及属性,避免已知不合法的请求先向sink写入文件头。 */ if (kind == IEC60870_ENERGY_FREEZE_FILE_FRZ) { if (!status.sealed_valid || !status.retained_valid || day < status.retained_from || day > status.sealed_day || status.sealed_day - day >= 30U || config->units == NULL || !IEC60870_EnergyFreeze_Window_Start(day, freeze->config.day_start_minutes, &start) || IEC60870_EnergyFreeze_Get_Seal(freeze, day, &seal) != IEC60870_ENERGY_FREEZE_OK) { return false; } if (seal.count == 0U) { /* 空窗不生成FRZ,但仍检查其声称的空位图,防止掩盖多出的记录或摘要损坏。 */ (void)IEC60870_EnergyFreeze_Validate_Seal(freeze, day); return false; } for (i = 0U; i < freeze->config.point_count; ++i) { if (!Attribute_Valid(config->units[i])) { return false; } } for (slot = 0U; slot < 96U; ++slot) { if (Bit(&seal, slot)) { ++count; } } { /* 摘要前缀必须与核心Digest_Start一致:小端窗口日序,再接完整13字节位图。 */ uint8_t bytes[4]; for (slot = 0U; slot < 4U; ++slot) { bytes[slot] = (uint8_t)(day >> (slot * 8U)); } digest = Digest_Update(digest, bytes, sizeof(bytes)); digest = Digest_Update(digest, seal.bitmap, sizeof(seal.bitmap)); } } else if (kind != IEC60870_ENERGY_FREEZE_FILE_FLOWREV || freeze->config.flowrev_count == 0U) { return false; } writer.write = write; writer.context = context; writer.size = 0U; if (!Emit(&writer, "\n\n
device_name) || !Emit(&writer, "\"/>\n")) { return false; } if (kind == IEC60870_ENERGY_FREEZE_FILE_FRZ) { if (!Data_Attributes(&writer, freeze, config, false, count) || !Data_Attributes(&writer, freeze, config, true, count)) { return false; } /* 每个物理位置恰好读取一次,缺bit也读取,以检测额外记录。 * 成功Read留下刚验证过自身CRC的wire;在下一次核心调用前累计正文, * 输出同一份解码快照。必须排除尾CRC,完整码字有固定CRC余数。 */ for (slot = 0U; slot < 97U; ++slot) { IEC60870_EnergyFreezeRecord_t record; IEC60870_EnergyFreezeResult_t result = slot == 96U ? IEC60870_EnergyFreeze_Read_Day(freeze, day, &record) : IEC60870_EnergyFreeze_Read_Interval(freeze, day, (uint16_t)(slot + 1U), &record); bool present = result == IEC60870_ENERGY_FREEZE_OK; if ((result != IEC60870_ENERGY_FREEZE_OK && result != IEC60870_ENERGY_FREEZE_EMPTY) || present != Bit(&seal, slot)) { freeze->faulted = true; return false; } if (!present) { continue; } if (record.count != freeze->config.point_count) { freeze->faulted = true; return false; } for (i = 0U; i < record.count; ++i) { if (record.quality[i] != 0U || !isfinite(record.values[i])) { freeze->faulted = true; return false; } } digest = Digest_Update(digest, freeze->wire, 44U + 5U * record.count); if (!Window_Record(&writer, &record, slot == 96U ? 0U : slot + 1U, start)) { return false; } } /* 到此sink可能已有完整数据正文;摘要不符仍须拒绝整份候选并锁存故障。 */ if ((digest ^ UINT32_MAX) != seal.content_crc) { freeze->faulted = true; return false; } } else if (!Flow_File(&writer, freeze)) { return false; } if (!Emit(&writer, "\n")) { return false; } if (size != NULL) { *size = writer.size; } return true; }