/* 附录 C XML 导出。片段同步送入调用方 sink,失败立即停止,不发布半个文件。 */ #include "IEC60870_UserLogFile.h" #include "IEC60870_Time.h" #include /* 一次导出的局部写入状态;size 是转义后实际字节数,不是原始文本长度。 * 不保存所有日志或整份 XML,记录副本和短格式片段在同步调用中反复复用。 */ typedef struct { IEC60870_UserLogFileWriteFn write; void *context; uint32_t size; } UserLogWriter; /** * 功能:在调用 sink 前检查长度,计数只包含已确认接收的字节。 * 输入参数:writer——同步输出状态;调用方保证回调有效;bytes——字节数据;length——字节数。 * 输出参数:writer——输出器累计长度及其目标内容。 * 返回值:true表示本段内容已完整输出;false表示校验、格式化、读取或sink接收失败。 * 说明:写出片段通过同步回调交付;失败不撤回已经接收的前缀。 */ static bool Emit_Bytes(UserLogWriter *writer, const char *bytes, size_t length) { if (length > UINT32_MAX - writer->size || !writer->write(writer->context, (const uint8_t *)bytes, length)) { return false; } writer->size += (uint32_t)length; return true; } /** * 功能:内部常量和转义串带 NUL,写出时只取内容;文件并不附加字符串终止符。 * 输入参数:writer——同步输出状态;调用方保证回调有效;text——文本或文本输出器。 * 输出参数:writer——输出器累计长度及其目标内容。 * 返回值:true表示本段内容已完整输出;false表示校验、格式化、读取或sink接收失败。 * 说明:写出片段通过同步回调交付;失败不撤回已经接收的前缀。 */ static bool Emit(UserLogWriter *writer, const char *text) { return Emit_Bytes(writer, text, strlen(text)); } /** * 功能:仅内部使用的小整数,width 为最少位数;不依赖 printf 或区域设置。 * 输入参数:writer——同步输出状态;调用方保证回调有效;value——待处理数值;width——十进制文本最少位数。 * 输出参数:writer——输出器累计长度及其目标内容。 * 返回值:true表示本段内容已完整输出;false表示校验、格式化、读取或sink接收失败。 * 说明:调用点只给固定的小宽度,10 字节足以容纳 uint32_t 的全部十进制数字。 */ static bool Number(UserLogWriter *writer, uint32_t value, size_t width) { char bytes[10]; size_t start = sizeof(bytes); do { bytes[--start] = (char)('0' + value % 10U); value /= 10U; } while (value != 0U || sizeof(bytes) - start < width); return Emit_Bytes(writer, bytes + start, sizeof(bytes) - start); } /** * 功能:所有属性使用双引号,五种特殊字符仍全部转义,以便内容可安全复用。 * 输入参数:writer——同步输出状态;调用方保证回调有效;text——文本或文本输出器。 * 输出参数:writer——输出器累计长度及其目标内容。 * 返回值:true表示本段内容已完整输出;false表示校验、格式化、读取或sink接收失败。 * 说明:写出片段通过同步回调交付;失败不撤回已经接收的前缀。 */ static bool Attribute(UserLogWriter *writer, const char *text) { const char *p; for (p = text; *p != '\0'; ++p) { const char *escaped = NULL; switch (*p) { case '&': escaped = "&"; break; case '<': escaped = "<"; break; case '>': escaped = ">"; break; case '"': escaped = """; break; case '\'': escaped = "'"; break; default: break; } if (escaped != NULL) { if (!Emit(writer, escaped)) { return false; } } else if (!Emit_Bytes(writer, p, 1U)) { return false; } } return true; } /** * 功能:在首次输出前检验设备 ID;24 字符是当前实现上限,不做 MSG 式空格填充。 * 输入参数:device_id——设备标识。 * 输出参数:无。 * 返回值:true表示设备标识非空且满足24字节ASCII字符限制,false表示不满足。 * 说明:只根据传入数据计算或判定,不改写输入对象。 */ static bool Device_Valid(const char *device_id) { size_t i; if (device_id == NULL) { return false; } for (i = 0U; i <= IEC60870_USER_LOG_DEVICE_ID_MAX; ++i) { unsigned char value = (unsigned char)device_id[i]; if (value == 0U) { return i != 0U; } if (value < 0x20U || value > 0x7eU) { return false; } } return false; } /** * 功能:复用公共日历转换,固定 UTC+8,不读取机器时区或当前墙钟。 * 输入参数:writer——同步输出状态;调用方保证回调有效;utc_ms——UTC纪元毫秒。 * 输出参数:writer——输出器累计长度及其目标内容。 * 返回值:true表示本段内容已完整输出;false表示校验、格式化、读取或sink接收失败。 * 说明:年份两位、毫秒三位;调用核心的相同闭区间,避免可存却无法导出的时标。 */ static bool Timestamp(UserLogWriter *writer, uint64_t utc_ms) { IEC60870_WallTime_t time; if (utc_ms < IEC60870_USER_LOG_UTC_MIN || utc_ms > IEC60870_USER_LOG_UTC_MAX || !IEC60870_Time_Seconds_To_Local((uint32_t)(utc_ms / 1000U), (uint16_t)(utc_ms % 1000U), &time)) { return false; } return Number(writer, time.year - 2000U, 2U) && Number(writer, time.month, 2U) && Number(writer, time.day, 2U) && Emit(writer, "_") && Number(writer, time.hour, 2U) && Number(writer, time.minute, 2U) && Number(writer, time.second, 2U) && Emit(writer, "_") && Number(writer, time.ms, 3U); } /** * 功能:串行遍历保留日志并同步生成附录C XML,空库可输出num=0;设备ID先行校验。 * 输入参数:log——用户日志核心实例;device_id——设备标识;write——同步接收输出片段的回调;context——传给输出回调的调用方上下文。 * 输出参数:log——复用读取工作区及读取错误可能锁存的故障状态;size——仅完整成功时写入文件字节数,不含NUL;允许NULL的入口不强制输出。 * 返回值:true表示完整文件已输出;false表示参数、读取校验或输出回调失败,候选内容不可发布。 * 说明:调用方须独占实例及后端,write消费当前片段且不可保留指针或重入。 全部输出成功才填写可选size;失败可能已有输出前缀,须丢弃整份候选文件。 */ bool IEC60870_UserLogFile_Write(IEC60870_UserLog_t *log, const char *device_id, IEC60870_UserLogFileWriteFn write, void *context, uint32_t *size) { UserLogWriter writer; IEC60870_UserLogRecord_t record; size_t count, i; if (log == NULL || !log->initialized || log->faulted || write == NULL || !Device_Valid(device_id)) { return false; } writer.write = write; writer.context = context; writer.size = 0U; /* 先拒绝无效实例,再解释 Count 的 0;调用方独占日志使 num 与随后 Get * 看到同一保留集合。任何读取/输出失败都放弃候选,不重写或修补 num。 */ count = IEC60870_UserLog_Count(log); /* C.2.2 正式模板与随后示例的 txt/text 不一致,这里选择模板的 txt; * Ulog 和 devID 同样遵从附录 C 大小写,不套用附录 B 的 devName。 */ if (!Emit(&writer, "\r\n\r\n") || !Emit(&writer, "
\r\n\r\n")) { return false; } for (i = 0U; i < count; ++i) { if (IEC60870_UserLog_Get(log, i, &record) != IEC60870_USER_LOG_OK || !Emit(&writer, "\r\n")) { return false; } } if (!Emit(&writer, "\r\n\r\n")) { return false; } /* 只有闭合标签也被 sink 完整接收后才发布总长度;失败前缀不能当文件使用。 */ if (size != NULL) { *size = writer.size; } return true; }