120 lines
6.6 KiB
C
120 lines
6.6 KiB
C
/* 附录 C 运行日志:固定容量循环保存,介质原子性由调用方后端保证。
|
||
* 无堆、无操作系统和文件系统依赖;全部访问须由调用方串行化。 */
|
||
#ifndef IEC60870_USER_LOG_H
|
||
#define IEC60870_USER_LOG_H
|
||
|
||
#include <stdbool.h>
|
||
#include <stddef.h>
|
||
#include <stdint.h>
|
||
|
||
#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 */
|