/* 附录 C 运行日志:固定容量循环保存,介质原子性由调用方后端保证。 * 无堆、无操作系统和文件系统依赖;全部访问须由调用方串行化。 */ #ifndef IEC60870_USER_LOG_H #define IEC60870_USER_LOG_H #include #include #include #ifdef __cplusplus extern "C" { #endif /* CAPACITY 是介质逻辑槽数,不要求 RAM 保存整环;WIRE_MAX 为单条最大编码: * 32 字节固定头 + 128 字节文本 + 4 字节 CRC。UTC 两端均包含在合法范围内。 */ #define IEC60870_USER_LOG_CAPACITY 1024U #define IEC60870_USER_LOG_TEXT_MAX 128U #define IEC60870_USER_LOG_WIRE_MAX 164U #define IEC60870_USER_LOG_UTC_MIN UINT64_C(946656000000) #define IEC60870_USER_LOG_UTC_MAX UINT64_C(4102415999999) /* INVALID 表示输入错误;ERROR 包括实例/介质错误及序号耗尽。并非所有 ERROR * 都设置 faulted,例如耗尽时已有记录仍可查询;EMPTY 用于空槽或越界查询。 */ typedef enum { IEC60870_USER_LOG_INVALID = -2, IEC60870_USER_LOG_ERROR = -1, IEC60870_USER_LOG_EMPTY = 0, IEC60870_USER_LOG_OK = 1 } IEC60870_UserLogResult_t; /* index 为 0..1023 的逻辑槽。read 仅在 OK 时填写实际 size;EMPTY 只表示 * 从未提交的空槽,损坏/短读/I/O 失败必须 ERROR。commit 成功表示原子替换并 * 完成持久同步;失败可能已经提交,核心将故障闭锁直到重新 Init。 * context 由调用方持有,缓冲仅在回调中借用,不得保存指针或重入实例。 */ typedef struct { void *context; IEC60870_UserLogResult_t (*read)(void *context, uint32_t index, uint8_t *bytes, size_t capacity, size_t *size); bool (*commit)(void *context, uint32_t index, const uint8_t *bytes, size_t size); } IEC60870_UserLogStore_t; /* sequence 按提交顺序递增,校时回拨不改变记录顺序;text 始终以 NUL 结尾。 * 这是独立的内存值副本,text 的终止符和结构体填充不属于持久化字节布局。 */ typedef struct { uint64_t sequence; uint64_t utc_ms; uint8_t type; uint8_t value; char text[IEC60870_USER_LOG_TEXT_MAX + 1U]; } IEC60870_UserLogRecord_t; /* 调用方静态分配;公开布局仅为分配方便,业务不得直接改内部状态。 * store 为浅拷贝;wire 是复用工作区,不能作为跨调用的记录借用。 */ typedef struct { IEC60870_UserLogStore_t store; uint64_t sequence; uint64_t latest_utc_ms; size_t count; bool initialized; bool faulted; uint8_t wire[IEC60870_USER_LOG_WIRE_MAX]; } IEC60870_UserLog_t; /** * 功能:扫描全部槽并校验格式、CRC、槽号和序号连续性;不清空或修复介质。 * 输入参数:self——调用方持有的模块实例及当前状态;store——同步存储回调表及其上下文。 * 输出参数:self——本次操作后的运行状态及复用工作区。 * 返回值:OK表示操作完成;INVALID表示参数或操作状态非法;ERROR表示实例不可用、I/O失败或内容损坏。 * 说明:self/store 必须非空且回调齐全。允许 store=&self->store;参数错误返回 INVALID 并保留旧实例,扫描失败返回 ERROR 且实例不可用,成功返回 OK。 * 实例与回调 context 均由调用方持有,初始化不取得资源所有权。 */ IEC60870_UserLogResult_t IEC60870_UserLog_Init(IEC60870_UserLog_t *self, const IEC60870_UserLogStore_t *store); /** * 功能:追加一条事实:type 为 1..11;1/10/11 的 value 只能为 1,其余为 0/1。 * 输入参数:self——调用方持有的模块实例及当前状态;type——类别编号;utc_ms——UTC纪元毫秒;value——待处理数值;text——文本或文本输出器。 * 输出参数:self——本次操作后的运行状态及复用工作区。 * 返回值:OK表示操作完成;INVALID表示参数或操作状态非法;ERROR表示实例不可用、I/O失败或内容损坏。 * 说明:text 是非空、至多 128 字节的可打印 ASCII;utc_ms 是 UTC 毫秒,允许范围 对应 UTC+8 的 2000..2099。时标允许回拨,不按类别去重,来源状态转换由 * 应用控制。参数本次调用内借用。成功 OK,非法输入 INVALID,故障/序号耗尽 ERROR;仅持久提交成功后推进内存条数/序号,失败不会自动重试。 01/10/11 * 分别表达重启、参数修改、升级行为;02..09 为状态类。核心只检验 类型和值,不推断来源身份、连接极性或设备动作是否真的发生。 */ IEC60870_UserLogResult_t IEC60870_UserLog_Append(IEC60870_UserLog_t *self, uint8_t type, uint64_t utc_ms, uint8_t value, const char *text); /** * 功能:返回当前保留条数;空库、空指针、未初始化或故障实例都返回 0,不能据此 区分空库与错误。 * 输入参数:self——只读模块实例。 * 输出参数:无。 * 返回值:当前保留条数;NULL、未初始化或故障实例返回0。 * 说明:需要导出时应由 Write/Get 的结果确认实例可用性。 */ size_t IEC60870_UserLog_Count(const IEC60870_UserLog_t *self); /** * 功能:oldest_index 从 0 起,按提交顺序从旧到新查询;超出条数返回 EMPTY。 * 输入参数:self——调用方持有的模块实例及当前状态;oldest_index——按提交顺序从最旧记录起的零基索引。 * 输出参数:self——本次操作后的运行状态及复用工作区;record——成功时写入的独立结果副本。 * 返回值:OK表示操作完成;EMPTY表示没有所需记录或到期任务;INVALID表示参数或操作状态非法;ERROR表示实例不可用、I/O失败或内容损坏。 * 说明:record 须指向调用方独立的输出对象,不得与 self 或存储重叠。成功 OK 时 拷贝完整记录;其他结果保持输出不变。读取/校验错误返回 ERROR 并故障闭锁, 参数错误返回 * INVALID;查询不消费记录。 */ IEC60870_UserLogResult_t IEC60870_UserLog_Get(IEC60870_UserLog_t *self, size_t oldest_index, IEC60870_UserLogRecord_t *record); /** * 功能:返回最新提交记录的时标,并非所有记录中的最大墙钟值;空库/实例无效/ 输出为空时返回 false,保持输出不变。 * 输入参数:self——只读模块实例。 * 输出参数:utc_ms——成功时写入最新提交记录的UTC毫秒。 * 返回值:true表示已取得最新提交记录的时标;false表示不可用或无记录,输出不变。 * 说明:调用方拥有输出值,无介质读取。 */ bool IEC60870_UserLog_Latest_Time(const IEC60870_UserLog_t *self, uint64_t *utc_ms); #ifdef __cplusplus } #endif #endif /* IEC60870_USER_LOG_H */