/* * 模块名称:附录 C 运行日志的 Windows 持久存储及 XML 下载适配。 * 模块功能:独占 ulog.store,以双 bank 保存循环槽,向 Type210 提供冻结文件。 * 使用边界:只访问调用方指定的已有目录,无线程与堆分配;全部调用必须串行。 * 首次使用先清零对象;存储、目录缓存和下载副本拥有独立的关闭时机。 * 核心回调 context 指回本对象,成功 Open 后不得按值复制或移动整个对象。 */ #ifndef IEC104_EXAMPLE_USER_LOG_H #define IEC104_EXAMPLE_USER_LOG_H #include "IEC60870_UserLogFile.h" #include "IEC60870_Time.h" #define EXAMPLE_USER_LOG_NAME_CAPACITY 64U typedef struct { char name[EXAMPLE_USER_LOG_NAME_CAPACITY]; /* 完整虚拟路径,大小写敏感。 */ uint32_t size; /* 当前冻结 XML 的准确字节数,不含 NUL。 */ IEC60870_CP56Time2a_t time; /* 最新提交日志的时标,供协议执行时间过滤。 */ } ExampleUserLogEntry; typedef struct { IEC60870_UserLog_t core; /* 业务通过核心追加日志,存储回调借用本对象。 */ void *storage; /* 从 Open 至 Close 独占的持久文件,不暴露 Windows 类型。 */ void *directory_file; /* 枚举结束后保留,直至下一次目录打开或整体关闭。 */ void *read_file; /* 当前下载的独立副本,不借用目录缓存的文件句柄。 */ char parent[200]; /* 已有父目录;持久文件及临时快照均创建于此。 */ char device_id[IEC60870_USER_LOG_DEVICE_ID_MAX + 1U]; /* 成功打开后拥有字符串副本。 */ ExampleUserLogEntry entry; /* 与目录缓存属于同一版本,空日志也有 num=0 文件。 */ uint32_t read_size; /* 只描述 read_file 的冻结长度,关闭后归零。 */ bool directory_active; /* 正在枚举,与 directory_file 缓存是否存在分别判断。 */ bool opened; /* 文件头和全环恢复成功后置位,不表示核心尚未发生后续故障。 */ uint8_t banks[2][IEC60870_USER_LOG_WIRE_MAX + 32U]; /* 两槽读取工作区,不将全库放进 RAM。 */ } ExampleUserLog; /** * 功能:文件头一致后才安装回调并扫描核心;全部恢复成功才对外设置 opened。 * 输入参数:self——调用方持有的模块实例;parent——已存在的宿主父目录;device_id——日志导出的设备标识。 * 输出参数:self——本次操作更新的实例或工作区。 * 返回值:true表示请求的资源或存储实例已准备就绪;false表示输入校验、资源获取或恢复失败。 * 说明:打开或首次创建独立 ulog.store,校验布局并恢复全部槽。 * self 首次清零;parent 已存在;device_id 为 1..24 字节可打印 ASCII。 * 活对象重复打开拒绝且保持原状态;已有空文件或损坏文件拒绝,不自动重建。 * true 才可调用核心;false 可 Close,已有介质不因此被删除或格式化。 * 后续提交失败时核心闭锁,须 Close/Open 恢复实际提交结果,不自动重试追加。 */ bool Example_User_Log_Open(ExampleUserLog *self, const char *parent, const char *device_id); /** * 功能:所有协议目录/读回调先结束;关闭临时句柄只删快照,不删 ulog.store。 * 输入参数:self——调用方持有的模块实例。 * 输出参数:self——本次操作更新的实例或工作区。 * 返回值:无。 * 说明:依次释放下载、目录缓存与存储锁,禁用核心;不删除持久日志,可重复关闭。 */ void Example_User_Log_Close(ExampleUserLog *self); /** * 功能:先在局部候选中同时准备字节、大小与时间,完整成功后才发布清单。 * 输入参数:self——调用方持有的模块实例;name——文件名或显式长度的协议名称;length——本次数据或名称的有效字节数。 * 输出参数:self——本次操作更新的实例或工作区。 * 返回值:true表示完整目录快照已发布;false表示名称、记录校验或快照生成失败。 * 说明:仅接受完整目录 HISTORY/ULOG;不接受空名、大小写变体或路径别名。 * 成功冻结单项清单及 XML;已有活动枚举拒绝。开始合法新枚举会替换旧缓存, * 候选生成失败不发布部分文件,已打开的独立下载仍保持原字节。 */ bool Example_User_Log_Directory_Open(ExampleUserLog *self, const uint8_t *name, size_t length); /** * 功能:返回协议枚举的可见项数;返回零不意味着保留的 XML 缓存已销毁。 * 输入参数:self——调用方持有的模块实例。 * 输出参数:无独立输出参数。 * 返回值:当前目录可枚举的条目数;目录未打开时为0。 * 说明:仅活动枚举返回一项;未打开/已关闭返回零,不由此判断日志是否为空。 */ size_t Example_User_Log_Directory_Count(const ExampleUserLog *self); /** * 功能:元数据按值交给调用者,名称不借用临时栈;失败不会留下半份目录项。 * 输入参数:self——调用方持有的模块实例;index——本次条目、点或逻辑槽的下标;entry——目录条目。 * 输出参数:entry——目录条目。 * 返回值:true表示目录条目已复制到entry;false表示实例、目录或索引无效。 * 说明:仅活动枚举的 index=0 可读;失败保持调用方 entry 不变。 */ bool Example_User_Log_Directory_Get(const ExampleUserLog *self, size_t index, ExampleUserLogEntry *entry); /** * 功能:协议 CLOSE_DIRECTORY 只结束枚举,缓存寿命延长到下一次合法枚举或整体 Close。 * 输入参数:self——调用方持有的模块实例。 * 输出参数:self——本次操作更新的实例或工作区。 * 返回值:无。 * 说明:只结束协议枚举,不释放已列出的版本,保证随后下载保持原大小与内容。 */ void Example_User_Log_Directory_Close(ExampleUserLog *self); /** * 功能:新下载始终取得自己的文件句柄;命中旧目录时复制已公布版本,不重新编码。 * 输入参数:self——调用方持有的模块实例;name——文件名或显式长度的协议名称;length——本次数据或名称的有效字节数;size——实际字节数回写位置。 * 输出参数:self——本次操作更新的实例或工作区;size——实际字节数回写位置。 * 返回值:true表示独立下载快照已打开并写回长度;false表示名称或快照准备失败。 * 说明:仅接受 HISTORY/ULOG/ulog.xml;有缓存时复制原版本,否则生成当前日志。 * size 只在成功后写回;最多一个活动下载,必须先 Read_Close 才能再次打开。 */ bool Example_User_Log_Read_Open(ExampleUserLog *self, const uint8_t *name, size_t length, uint32_t *size); /** * 功能:先用减法验证整个范围,避免 offset+length 溢出;同一偏移可重复读取。 * 输入参数:self——调用方持有的模块实例;offset——从起点计算的字节偏移;buffer——调用方提供的数据缓冲;length——本次数据或名称的有效字节数。 * 输出参数:buffer——调用方提供的数据缓冲。 * 返回值:true表示指定范围的数据已完整读出;false表示范围非法、读取失败或短读。 * 说明:任意偏移准确读取,拒绝范围溢出和短读;EOF 处允许 buffer=NULL、length=0。 */ bool Example_User_Log_Read(ExampleUserLog *self, uint32_t offset, uint8_t *buffer, size_t length); /** * 功能:关闭下载句柄即删除该临时副本;不释放目录缓存或持久文件锁,可重复调用。 * 输入参数:self——调用方持有的模块实例。 * 输出参数:self——本次操作更新的实例或工作区。 * 返回值:无。 * 说明:仅释放下载副本,不改目录缓存或持久日志。 */ void Example_User_Log_Read_Close(ExampleUserLog *self); #endif /* IEC104_EXAMPLE_USER_LOG_H */