115 lines
7.9 KiB
C
115 lines
7.9 KiB
C
/*
|
|
* 模块名称:Windows 宿主持久历史适配与 XML 下载快照
|
|
* 模块功能:为 History 核心提供双副本持久槽,为 Type210 提供稳定目录和文件内容。
|
|
* 职责边界:仅使用调用者指定的已有目录;不创建线程,不自行轮询协议或采集设备。
|
|
* 调用约定:整个对象须串行访问,存储文件从 Open 到 Close 独占;首次使用先清零对象。
|
|
*/
|
|
#ifndef IEC104_EXAMPLE_HISTORY_H
|
|
#define IEC104_EXAMPLE_HISTORY_H
|
|
|
|
#include "IEC60870_History.h"
|
|
#include "IEC60870_Time.h"
|
|
|
|
#define EXAMPLE_HISTORY_DIRECTORY_CAPACITY 30U /* 单次日目录最多列出三十个完成日。 */
|
|
#define EXAMPLE_HISTORY_NAME_CAPACITY 64U /* 完整虚拟路径及结尾 NUL 的存储容量。 */
|
|
|
|
typedef struct {
|
|
char name[EXAMPLE_HISTORY_NAME_CAPACITY]; /* 大小写敏感的完整虚拟名;读文件可原样回传。 */
|
|
uint32_t size; /* 该版 XML 的字节数,与实际冻结内容一致。 */
|
|
IEC60870_CP56Time2a_t time; /* 业务日期或最新记录时间,供协议执行目录时间筛选。 */
|
|
uint32_t offset; /* 文件在本轮目录拼接快照中的字节偏移,不作为线上文件偏移。 */
|
|
} ExampleHistoryEntry;
|
|
|
|
typedef struct {
|
|
IEC60870_History_t core; /* 核心借用点表;调用者可经 core 提交事件及观测。 */
|
|
void *storage; /* 独占持久文件句柄;头文件不向使用者暴露 Windows 类型。 */
|
|
void *directory_file; /* 目录 XML 拼接快照;目录关闭后保留到下次召目录或整体关闭。 */
|
|
void *read_file; /* 当前下载的独立副本;目录重新生成不会改变其内容。 */
|
|
char parent[200]; /* 持久文件及临时快照的同一已有父目录。 */
|
|
char device_name[128]; /* XML 设备名副本,不继续借用 Open 的字符串实参。 */
|
|
ExampleHistoryEntry entries[EXAMPLE_HISTORY_DIRECTORY_CAPACITY]; /* 与目录快照同代的元数据。 */
|
|
size_t entry_count; /* 当前保留清单的项目数,目录收尾时不销毁其缓存。 */
|
|
uint32_t read_size; /* 当前读快照大小,Read_Close 后归零。 */
|
|
bool directory_active; /* 协议仍在枚举;不等于目录缓存是否存在。 */
|
|
bool opened; /* 持久文件头及核心恢复均成功后才为真。 */
|
|
uint8_t banks[2][IEC60870_HISTORY_WIRE_MAX + 32U]; /* 两份槽读取工作区,避免占用深层调用栈。 */
|
|
} ExampleHistory;
|
|
|
|
/**
|
|
* 功能:打开或首次创建 history.store,核对布局并恢复核心;已打开对象拒绝重复打开。
|
|
* 输入参数:self 首次须清零;parent 已存在;config 点表须存活至关闭;设备名在成功时复制。
|
|
* 输出参数:self——本次操作更新的实例或工作区。
|
|
* 返回值:true 表示可使用;false 保留已有文件,不自动重建空文件、不格式化损坏存储。
|
|
* 说明:每次提交包含 FlushFileBuffers;物理失电保证仍依赖设备兑现系统同步契约。
|
|
*/
|
|
bool Example_History_Open(ExampleHistory *self, const char *parent,
|
|
const IEC60870_HistoryConfig_t *config, const char *device_name);
|
|
/**
|
|
* 功能:退出或初始化回退共用清理:先关下载,再关目录缓存和独占存储,最终禁用核心。
|
|
* 输入参数:self——调用方持有的模块实例。
|
|
* 输出参数:self——本次操作更新的实例或工作区。
|
|
* 返回值:无。
|
|
* 说明:关闭读快照、目录缓存及持久文件,停止核心访问;不删除 history.store,可重复调用。
|
|
*/
|
|
void Example_History_Close(ExampleHistory *self);
|
|
/**
|
|
* 功能:按虚拟目录冻结清单和全部文件内容,不在后续 list 重试时重新生成。
|
|
* 输入参数:self——调用方持有的模块实例;name——文件名或显式长度的协议名称;length——本次数据或名称的有效字节数。
|
|
* 输出参数:self——本次操作更新的实例或工作区。
|
|
* 返回值:true表示完整目录快照已发布;false表示名称、记录校验或快照生成失败。
|
|
* 说明:冻结指定目录及内容;空名称代表 SOE,名称按字节匹配。每日目录只取最新三十个完成日。
|
|
* 同时只允许一次活动枚举;失败不发布部分清单,成功后供 Count/Get 按固定下标读取。
|
|
*/
|
|
bool Example_History_Directory_Open(ExampleHistory *self, const uint8_t *name, size_t length);
|
|
/**
|
|
* 功能:只向活动枚举暴露数量;关闭后缓存仍可供 Read_Open 使用。
|
|
* 输入参数:self——调用方持有的模块实例。
|
|
* 输出参数:无独立输出参数。
|
|
* 返回值:当前目录可枚举的条目数;目录未打开时为0。
|
|
* 说明:返回活动枚举的项目数;非活动状态返回零,不因此删除保留的目录快照。
|
|
*/
|
|
size_t Example_History_Directory_Count(const ExampleHistory *self);
|
|
/**
|
|
* 功能:按固定下标复制目录元数据,不返回临时栈指针,也不因重试改变清单。
|
|
* 输入参数:self——调用方持有的模块实例;index——本次条目、点或逻辑槽的下标;entry——目录条目。
|
|
* 输出参数:entry——目录条目。
|
|
* 返回值:true表示目录条目已复制到entry;false表示实例、目录或索引无效。
|
|
* 说明:按值复制一个目录项;越界或目录未打开返回 false,不改变调用方输出。
|
|
*/
|
|
bool Example_History_Directory_Get(const ExampleHistory *self, size_t index, ExampleHistoryEntry *entry);
|
|
/**
|
|
* 功能:协议目录收尾只结束枚举,保留已向主站声明的版本至下次召目录或整体关闭。
|
|
* 输入参数:self——调用方持有的模块实例。
|
|
* 输出参数:self——本次操作更新的实例或工作区。
|
|
* 返回值:无。
|
|
* 说明:结束枚举但保留已列出的快照,保证主站随后读文件仍得到该版内容。
|
|
*/
|
|
void Example_History_Directory_Close(ExampleHistory *self);
|
|
/**
|
|
* 功能:为一次下载取得独立快照:先匹配保留清单,命中则复制其原版本;未命中才按当前保留范围导出。
|
|
* 输入参数:self——调用方持有的模块实例;name——文件名或显式长度的协议名称;length——本次数据或名称的有效字节数;size——实际字节数回写位置。
|
|
* 输出参数:self——本次操作更新的实例或工作区;size——实际字节数回写位置。
|
|
* 返回值:true表示独立下载快照已打开并写回长度;false表示名称或快照准备失败。
|
|
* 说明:打开一个完整虚拟名:优先复制已列出的版本;无目录缓存命中时按当前保留范围生成。
|
|
* 成功后才写回 size;活动读必须先关闭,失败候选会清理,不把部分 XML 交给协议。
|
|
*/
|
|
bool Example_History_Read_Open(ExampleHistory *self, const uint8_t *name, size_t length, uint32_t *size);
|
|
/**
|
|
* 功能:从不可变读快照按绝对偏移完整读取;先用减法检查范围,避免 offset+length 溢出。
|
|
* 输入参数:self——调用方持有的模块实例;offset——从起点计算的字节偏移;buffer——调用方提供的数据缓冲;length——本次数据或名称的有效字节数。
|
|
* 输出参数:buffer——调用方提供的数据缓冲。
|
|
* 返回值:true表示指定范围的数据已完整读出;false表示范围非法、读取失败或短读。
|
|
* 说明:按文件内绝对偏移读取完整 length 字节;检查越界和短读,同偏移重试内容不变。
|
|
*/
|
|
bool Example_History_Read(ExampleHistory *self, uint32_t offset, uint8_t *buffer, size_t length);
|
|
/**
|
|
* 功能:结束本次下载,关闭临时句柄即删除读快照;目录缓存和持久文件继续存活。
|
|
* 输入参数:self——调用方持有的模块实例。
|
|
* 输出参数:self——本次操作更新的实例或工作区。
|
|
* 返回值:无。
|
|
* 说明:释放本次下载快照并归零大小,不影响目录缓存、持久记录或另一轮目录生成。
|
|
*/
|
|
void Example_History_Read_Close(ExampleHistory *self);
|
|
|
|
#endif
|