/* 附录 B XML 生成实现。每次只读取一条记录并输出有限片段,不持有整份文件。 * 本模块不做介质提交或网络发送;调用方须保持输入稳定,并拥有最终冻结文件。 */ #include "IEC60870_HistoryFile.h" #include "IEC60870_Time.h" #include #include #include #include #include /* 本次编码的输出回调与累计字节数。size 仅在回调完全接收一片后递增。 */ typedef struct { IEC60870_HistoryFileWriteFn write; void *context; uint32_t size; } HistoryXmlWriter; /** * 功能:输出以 NUL 结束的内部片段,但 NUL 本身不进入文件;先防止 32 位文件长度 溢出,再调用同步写入。 * 输入参数:writer——同步输出状态;调用方保证回调有效;text——文本或文本输出器。 * 输出参数:writer——输出器累计长度及其目标内容。 * 返回值:true表示本段内容已完整输出;false表示校验、格式化、读取或sink接收失败。 * 说明:回调失败可能已写出前缀,不能从此函数自动回滚。 */ static bool Emit(HistoryXmlWriter *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; } /** * 功能:XML 中的点号、数量和节号统一用十进制,不沿用另一文件格式的十六进制点号。 * 输入参数:writer——同步输出状态;调用方保证回调有效;value——待处理数值。 * 输出参数:writer——输出器累计长度及其目标内容。 * 返回值:true表示本段内容已完整输出;false表示校验、格式化、读取或sink接收失败。 * 说明:写出片段通过同步回调交付;失败不撤回已经接收的前缀。 */ static bool Unsigned(HistoryXmlWriter *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); } /** * 功能:binary32 用 9 位有效数字输出,足以保留其数值;拒绝非有限值。 * 输入参数:writer——同步输出状态;调用方保证回调有效;value——待处理数值。 * 输出参数:writer——输出器累计长度及其目标内容。 * 返回值:true表示本段内容已完整输出;false表示校验、格式化、读取或sink接收失败。 * 说明:小数点固定为点号,不受宿主数值区域设置影响。%g 不输出千位分组,因此仅替换 decimal_point 即可保留数字和指数部分;不修改进程全局的区域设置。 */ static bool Number(HistoryXmlWriter *writer, float value) { char text[64], canonical[64]; const char *separator; char *where; size_t prefix, separator_length; 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); separator_length = strlen(separator); memcpy(canonical, text, prefix); canonical[prefix] = '.'; strcpy(canonical + prefix + 1U, where + separator_length); return Emit(writer, canonical); } /** * 功能:转义前验证完整 UTF-8 和 XML 1.0 可用字符:按原始字节限制属性长度, 拒绝截断序列、非法续字节、过长编码、代理码点和禁用控制字符。 * 输入参数:value——待校验或输出的文本。 * 输出参数:无。 * 返回值:true表示文本满足长度、UTF-8及XML字符限制,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_HISTORY_FILE_ATTRIBUTE_MAX; ++length) { if (p[length] == 0U) { break; } } if (length > IEC60870_HISTORY_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; } /** * 功能:属性值先整段校验,再转义 XML 五个保留字符;制表/换行/回车使用数字实体, 避免 XML 属性空白归一化改变原值。 * 输入参数:writer——同步输出状态;调用方保证回调有效;value——待校验或输出的文本。 * 输出参数:writer——输出器累计长度及其目标内容。 * 返回值:true表示本段内容已完整输出;false表示校验、格式化、读取或sink接收失败。 * 说明:其余 UTF-8 字节原样顺序输出。 逐字节回调是流式输出,不表示单片一定构成完整 Unicode 字符。 */ static bool Attribute(HistoryXmlWriter *writer, const char *value) { char one[2]; if (!Attribute_Valid(value)) { return false; } one[1] = '\0'; 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 毫秒转固定 UTC+8 日历;规范两位年份仅接受 2000..2099。 * 输入参数:utc_ms——UTC纪元毫秒。 * 输出参数:time——转换后的日历;内部预检失败时不得使用。 * 返回值:true表示日期转换成功且年份受支持,false表示转换或范围检查失败。 * 说明:先检查秒数转换范围,避免 64 位时标截断为 32 位后落入错误日期。 */ static bool Local_Time(uint64_t utc_ms, IEC60870_WallTime_t *time) { uint64_t seconds = utc_ms / 1000U; return seconds <= UINT32_MAX && IEC60870_Time_Seconds_To_Local((uint32_t)seconds, (uint16_t)(utc_ms % 1000U), time) != 0 && time->year >= 2000U; } /** * 功能:day 已经是本地日期的日序,按纯日历转换即可,不能再次叠加八小时时区。 * 输入参数:day——相对1970-01-01的本地日序。 * 输出参数:time——转换后的日历;内部预检失败时不得使用。 * 返回值:true表示日期转换成功且年份受支持,false表示转换或范围检查失败。 * 说明:这里只取文件归属日;原始事件/极值时标走 Local_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) != 0 && time->year >= 2000U; } /** * 功能:SOE/遥控输出 YYMMDD_HHMMSS_MS,日极值按格式输出到秒。 * 输入参数:writer——同步输出状态;调用方保证回调有效;utc_ms——UTC纪元毫秒;milliseconds——是否输出毫秒文本。 * 输出参数:writer——输出器累计长度及其目标内容。 * 返回值:true表示本段内容已完整输出;false表示校验、格式化、读取或sink接收失败。 * 说明:毫秒开关只决定文本精度,不改动持久记录里保存的原始发生时刻。 */ static bool Timestamp(HistoryXmlWriter *writer, uint64_t utc_ms, bool milliseconds) { IEC60870_WallTime_t time; char text[24]; int n; if (!Local_Time(utc_ms, &time)) { 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); } /** * 功能:定点文本使用“归属日期 + 该节区间终点”,不能直接格式化实际采样时间。 * 输入参数:writer——同步输出状态;调用方保证回调有效;record——记录值副本。 * 输出参数:writer——输出器累计长度及其目标内容。 * 返回值:true表示本段内容已完整输出;false表示校验、格式化、读取或sink接收失败。 * 说明:这样第 96 节仍属于当天文件,且明确写成当天 24:00。 */ static bool Fixed_Timestamp(HistoryXmlWriter *writer, const IEC60870_HistoryFixed_t *record) { IEC60870_WallTime_t date; char text[24]; unsigned minutes; int n; if (!Date(record->day, &date) || record->slot == 0U || record->slot > 96U) { return false; } /* 调度迟到量保留在 record.utc_ms;XML 节标识采用规范要求的计划终点。 */ minutes = (unsigned)record->slot * 15U; n = snprintf(text, sizeof(text), "%02u%02u%02u_%02u%02u00", (unsigned)(date.year - 2000U), (unsigned)date.month, (unsigned)date.day, minutes / 60U, minutes % 60U); return n > 0 && (size_t)n < sizeof(text) && Emit(writer, text); } /** * 功能:先在局部缓冲形成完整名称,再检查调用方容量,保证失败不留下截断路径。 * 输入参数:kind——记录或文件类别;day——相对1970-01-01的本地日序;capacity——缓冲可用容量。 * 输出参数:name——成功生成的NUL结尾相对文件名;失败不变。 * 返回值:true表示文件名已完整生成;false表示参数非法或容量不足,输出不变。 * 说明:路径匹配区分大小写,名称只能来自四种固定类别,不接受任意路径拼接。 */ bool IEC60870_HistoryFile_Name(IEC60870_HistoryKind_t kind, uint32_t day, char *name, size_t capacity) { char text[IEC60870_HISTORY_FILE_PATH_CAPACITY]; IEC60870_WallTime_t date; int n; if (name == NULL || capacity == 0U) { return false; } if (kind == IEC60870_HISTORY_SOE) { strcpy(text, "HISTORY/SOE/soe.xml"); } else if (kind == IEC60870_HISTORY_CO) { strcpy(text, "HISTORY/CO/co.xml"); } else { const char *directory, *prefix; if (!Date(day, &date)) { return false; } if (kind == IEC60870_HISTORY_EXV) { directory = "EXV"; prefix = "exv"; } else if (kind == IEC60870_HISTORY_FIXPT) { directory = "FIXPT"; prefix = "fixpt"; } else { return false; } n = snprintf(text, sizeof(text), "HISTORY/%s/%s%04u%02u%02u.xml", directory, prefix, (unsigned)date.year, (unsigned)date.month, (unsigned)date.day); if (n < 0 || (size_t)n >= sizeof(text)) { return false; } } if (strlen(text) >= capacity) { return false; } strcpy(name, text); return true; } /** * 功能:以事件环当前条数声明 num,再按最旧到最新逐条读取;数量不足不补假记录。 * 输入参数:writer——同步输出状态;调用方保证回调有效;history——历史核心实例;kind——记录或文件类别。 * 输出参数:writer——输出器累计长度及其目标内容;history——复用读取工作区及读取错误可能锁存的故障状态。 * 返回值:true表示本段内容已完整输出;false表示校验、格式化、读取或sink接收失败。 * 说明:CO 追加操作阶段字符串,SOE 只输出规定的状态字段;读取失败终止整份候选。 */ static bool Event_File(HistoryXmlWriter *writer, IEC60870_History_t *history, IEC60870_HistoryKind_t kind) { IEC60870_HistoryEvent_t event; size_t i, count = IEC60870_History_Event_Count(history, kind); if (count > (kind == IEC60870_HISTORY_SOE ? IEC60870_HISTORY_SOE_CAPACITY : IEC60870_HISTORY_CO_CAPACITY)) { return false; } if (!Emit(writer, "\r\n")) { return false; } for (i = 0U; i < count; ++i) { const char *command; if (IEC60870_History_Get_Event(history, kind, i, &event) != IEC60870_HISTORY_OK || !Emit(writer, "\r\n")) { return false; } } return Emit(writer, "\r\n"); } /** * 功能:属性表使用当前配置点号和同下标单位;缺省单位输出空字符串。 * 输入参数:writer——同步输出状态;调用方保证回调有效;history——历史核心实例;config——配置及调用期间借用的元数据;index——零基索引。 * 输出参数:writer——输出器累计长度及其目标内容。 * 返回值:true表示本段内容已完整输出;false表示校验、格式化、读取或sink接收失败。 * 说明:数据部分按该表顺序对应,不自行排序或混入未配置点。 */ static bool Point_Attribute(HistoryXmlWriter *writer, const IEC60870_History_t *history, const IEC60870_HistoryFileConfig_t *config, size_t index) { const char *unit = config->analog_units == NULL ? "" : config->analog_units[index]; return Emit(writer, "config.analog_ioas[index]) && Emit(writer, "\" type=\"float\" unit=\"") && Attribute(writer, unit) && Emit(writer, "\"/>\r\n"); } /** * 功能:先读取一份日极值值副本并统计有效点,属性表和数据表使用相同筛选及顺序。 * 输入参数:writer——同步输出状态;调用方保证回调有效;history——历史核心实例;day——相对1970-01-01的本地日序;config——配置及调用期间借用的元数据。 * 输出参数:writer——输出器累计长度及其目标内容;history——复用读取工作区及读取错误可能锁存的故障状态。 * 返回值:true表示本段内容已完整输出;false表示校验、格式化、读取或sink接收失败。 * 说明:全部点无有效样本时拒绝生成日文件,不把零值写成实际最大/最小值。 */ static bool Extrema_File(HistoryXmlWriter *writer, IEC60870_History_t *history, uint32_t day, const IEC60870_HistoryFileConfig_t *config) { IEC60870_HistoryExtrema_t record; size_t i, count = 0U; if (IEC60870_History_Read_Extrema(history, day, &record) != IEC60870_HISTORY_OK || record.day != day || record.count != history->config.analog_count) { return false; } for (i = 0U; i < record.count; ++i) { if (record.points[i].valid) { ++count; } } if (count == 0U || !Emit(writer, "\r\n")) { return false; } for (i = 0U; i < record.count; ++i) { if (record.points[i].valid && !Point_Attribute(writer, history, config, i)) { return false; } } if (!Emit(writer, "\r\n\r\n")) { return false; } for (i = 0U; i < record.count; ++i) { const IEC60870_HistoryExtremePoint_t *point = &record.points[i]; if (!point->valid) { continue; } if (!Emit(writer, "max) || !Emit(writer, "\" max_tm=\"") || !Timestamp(writer, point->max_utc_ms, false) || !Emit(writer, "\" min=\"") || !Number(writer, point->min) || !Emit(writer, "\" min_tm=\"") || !Timestamp(writer, point->min_utc_ms, false) || !Emit(writer, "\"/>\r\n")) { return false; } } return Emit(writer, "\r\n"); } /** * 功能:XML 定点没有逐点品质字段,因此只接受至少一点且所有点品质为零、数值有限 的快照;避免把失效测量编码成看似有效的普通浮点数。 * 输入参数:record——记录值副本。 * 输出参数:无。 * 返回值:true表示快照至少有一点,且全部点品质为0、数值有限,false表示不能导出。 * 说明:只根据传入数据计算或判定,不改写输入对象。 */ static bool Fixed_Valid(const IEC60870_HistoryFixed_t *record) { size_t i; for (i = 0U; i < record->count; ++i) { if (record->quality[i] != 0U || !isfinite(record->values[i])) { return false; } } return record->count > 0U; } /** * 功能:两遍读取当天最多 96 槽:第一遍用 96 字节存在表统计实际节数,第二遍输出。 * 输入参数:writer——同步输出状态;调用方保证回调有效;history——历史核心实例;day——相对1970-01-01的本地日序;config——配置及调用期间借用的元数据。 * 输出参数:writer——输出器累计长度及其目标内容;history——复用读取工作区及读取错误可能锁存的故障状态。 * 返回值:true表示本段内容已完整输出;false表示校验、格式化、读取或sink接收失败。 * 说明:省略缺测节但保留原始节号,每节数据顺序沿用 DataAttr。两遍间输入不得变动; 第二遍仍复核日期/节号/点数,任何不一致都使整份候选失败。 */ static bool Fixed_File(HistoryXmlWriter *writer, IEC60870_History_t *history, uint32_t day, const IEC60870_HistoryFileConfig_t *config) { IEC60870_HistoryFixed_t record; uint8_t present[IEC60870_HISTORY_SLOTS_PER_DAY] = {0}; uint16_t slot; size_t i; uint32_t count = 0U; for (slot = 1U; slot <= IEC60870_HISTORY_SLOTS_PER_DAY; ++slot) { IEC60870_HistoryResult_t result = IEC60870_History_Read_Fixed(history, day, slot, &record); if (result == IEC60870_HISTORY_EMPTY) { continue; } if (result != IEC60870_HISTORY_OK || record.day != day || record.slot != slot || record.count != history->config.analog_count) { return false; } if (Fixed_Valid(&record)) { present[slot - 1U] = 1U; ++count; } } if (count == 0U || !Emit(writer, "config.analog_count) || !Emit(writer, "\" sectNum=\"") || !Unsigned(writer, count) || !Emit(writer, "\" interval=\"15min\">\r\n")) { return false; } for (i = 0U; i < history->config.analog_count; ++i) { if (!Point_Attribute(writer, history, config, i)) { return false; } } if (!Emit(writer, "\r\n")) { return false; } for (slot = 1U; slot <= IEC60870_HISTORY_SLOTS_PER_DAY; ++slot) { if (!present[slot - 1U]) { continue; } if (IEC60870_History_Read_Fixed(history, day, slot, &record) != IEC60870_HISTORY_OK || record.day != day || record.slot != slot || record.count != history->config.analog_count || !Fixed_Valid(&record) || !Emit(writer, "\r\n")) { return false; } for (i = 0U; i < record.count; ++i) { if (!Emit(writer, "\r\n")) { return false; } } if (!Emit(writer, "\r\n")) { return false; } } return true; } /** * 功能:编码总入口:先检查实例、属性及日文件时间窗口,再输出文件头和类别内容。 * 输入参数:history——历史核心实例;kind——记录或文件类别;day——相对1970-01-01的本地日序;config——配置及调用期间借用的元数据;write——同步接收输出片段的回调; * context——传给输出回调的调用方上下文。 * 输出参数:history——复用读取工作区及读取错误可能锁存的故障状态;size——仅完整成功时写入文件字节数,不含NUL;允许NULL的入口不强制输出。 * 返回值:true表示完整文件已输出;false表示参数、读取校验或输出回调失败,候选内容不可发布。 * 说明:存储保留 32 日不意味着对外可导出 32 日;这里只允许此前 30 个完整日。 全程无锁/无快照复制,串行稳定输入是调用方契约。只有尾标签也写成功之后 才发布 size; * 任意中途失败都要求调用方丢弃已经输出的所有字节。 */ 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) { HistoryXmlWriter writer; const char *type; uint32_t latest; size_t i; bool success; if (history == NULL || !history->initialized || history->faulted || config == NULL || write == NULL || history->config.analog_count > IEC60870_HISTORY_MAX_ANALOG || !Attribute_Valid(config->device_name)) { return false; } if (kind == IEC60870_HISTORY_SOE) { type = "SOE"; } else if (kind == IEC60870_HISTORY_CO) { type = "CO"; } else if (kind == IEC60870_HISTORY_FIXPT) { type = "FIXPT"; } else if (kind == IEC60870_HISTORY_EXV) { type = "EXV"; } else { return false; } if (kind == IEC60870_HISTORY_FIXPT || kind == IEC60870_HISTORY_EXV) { if (!IEC60870_History_Latest_Day(history, &latest) || day >= latest || latest - day > 30U) { return false; } for (i = 0U; config->analog_units != NULL && i < history->config.analog_count; ++i) { if (!Attribute_Valid(config->analog_units[i])) { return false; } } } writer.write = write; writer.context = context; writer.size = 0U; if (!Emit(&writer, "\r\n\r\n
device_name) || !Emit(&writer, "\"/>\r\n")) { return false; } if (kind == IEC60870_HISTORY_SOE || kind == IEC60870_HISTORY_CO) { success = Event_File(&writer, history, kind); } else if (kind == IEC60870_HISTORY_EXV) { success = Extrema_File(&writer, history, day, config); } else { success = Fixed_File(&writer, history, day, config); } if (!success || !Emit(&writer, "\r\n")) { return false; } if (size != NULL) { *size = writer.size; } return true; }