Files
STM32F4-Base/IEC60870-Slave/examples/iec104_example_history.c
T
STF bdcc8b6500
CI / L0 静态门禁 (pre-commit) (push) Failing after 7m46s
CI / L0.5 主机侧单测 (MSVC) (push) Successful in 21s
添加遥控、参数装载、文件传输等业务
2026-11-16 22:19:17 -08:00

666 lines
34 KiB
C
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
/*
* 模块名称:Windows 历史存储与不可变文件快照
* 实现策略:每个逻辑槽保留两个独立校验的 bank,按代次选取已提交记录;
* XML 候选和读快照写入同目录临时文件,由句柄关闭触发删除。
* 运行边界:所有操作在调用线程同步完成,文件全程独占;不承诺硬实时延迟。
*/
#include "iec104_example_history.h"
#include "IEC60870_HistoryFile.h"
#include <stdio.h>
#include <string.h>
#include <windows.h>
#define STORE_HEADER_SIZE 32U /* 文件布局版本及容量校验头。 */
#define BANK_HEADER_SIZE 32U /* 单副本头,提交标记位于偏移二十四。 */
#define BANK_COMMITTED 0x54494d43UL /* 小端存储为提交标记,最后单独写入。 */
/* 测试构建在每次真实同步完成后注入中断,覆盖提交结果尚未交回调用方的模糊窗口。 */
#ifdef IEC104_EXAMPLE_HISTORY_TEST
/**
* 功能:在真实持久操作完成后提供测试中断判定。
* 输入参数:无。
* 输出参数:无输出参数;测试实现更新故障注入计数。
* 返回值:true允许继续,false在指定阶段模拟中断。
* 说明:仅测试宏启用时链接;真实写入已发生,返回false不撤销已同步内容。
*/
extern bool Example_History_Test_Continue(void);
#else
#define Example_History_Test_Continue() true
#endif
/**
* 功能:从字节缓冲解码32位小端整数。
* 输入参数:p——小端字段所在字节缓冲。
* 输出参数:无独立输出参数。
* 返回值:解码后的32位无符号整数。
* 说明:从已验证长度的字节区读取小端整数,不依赖结构体对齐或主机字节序。
*/
static uint32_t Get32(const uint8_t *p)
{
return (uint32_t)p[0] | ((uint32_t)p[1] << 8) |
((uint32_t)p[2] << 16) | ((uint32_t)p[3] << 24);
}
/**
* 功能:将32位整数写成小端字节序。
* 输入参数:p——小端字段所在字节缓冲;v——待编码整数。
* 输出参数:p——小端字段所在字节缓冲。
* 返回值:无。
* 说明:按显式小端顺序写四字节;调用者保证目标容量,不将宿主结构布局落盘。
*/
static void Put32(uint8_t *p, uint32_t v)
{
unsigned i;
for (i = 0U; i < 4U; ++i) { p[i] = (uint8_t)(v >> (8U * i)); }
}
/**
* 功能:从字节缓冲解码64位小端整数。
* 输入参数:p——小端字段所在字节缓冲。
* 输出参数:无独立输出参数。
* 返回值:解码后的64位无符号整数。
* 说明:组合两个小端半字得到完整代次号,避免 Windows 长整数位宽影响存储格式。
*/
static uint64_t Get64(const uint8_t *p)
{
return Get32(p) | ((uint64_t)Get32(p + 4U) << 32);
}
/**
* 功能:将64位整数写成小端字节序。
* 输入参数:p——小端字段所在字节缓冲;v——待编码整数。
* 输出参数:p——小端字段所在字节缓冲。
* 返回值:无。
* 说明:写入八字节代次号;较低三十二位在前,与读取路径严格对称。
*/
static void Put64(uint8_t *p, uint64_t v)
{
Put32(p, (uint32_t)v); Put32(p + 4U, (uint32_t)(v >> 32));
}
/**
* 功能:计算当前字节段的完整CRC-32校验值。
* 输入参数:p——小端字段所在字节缓冲;n——参与校验的字节数。
* 输出参数:无独立输出参数。
* 返回值:完成初值处理和末尾取反后的CRC-32值。
* 说明:对指定范围计算 CRC32;分别用于文件头、bank 头和载荷,不承担业务字段校验。
*/
static uint32_t Crc(const uint8_t *p, size_t n)
{
uint32_t crc = 0xffffffffUL;
size_t i;
unsigned bit;
for (i = 0U; i < n; ++i) {
crc ^= p[i];
for (bit = 0U; bit < 8U; ++bit) {
crc = (crc >> 1) ^ ((crc & 1U) != 0U ? 0xedb88320UL : 0U);
}
}
return ~crc;
}
/**
* 功能:取得指定记录种类的固定载荷容量。
* 输入参数:kind——记录或导出文件种类。
* 输出参数:无独立输出参数。
* 返回值:对应记录种类的固定载荷容量,单位字节。
* 说明:计算该类型在宿主布局中的最大载荷;日数据按最大点数预留,不随本次点表长度移动槽。
*/
static uint32_t Payload_Capacity(IEC60870_HistoryKind_t kind)
{
switch (kind) {
case IEC60870_HISTORY_SOE: case IEC60870_HISTORY_CO: return 48U;
case IEC60870_HISTORY_FIXPT: return 40U + IEC60870_HISTORY_MAX_ANALOG * 5U;
case IEC60870_HISTORY_EXV: return 40U + IEC60870_HISTORY_MAX_ANALOG * 25U;
default: return 0U;
}
}
/**
* 功能:计算逻辑槽中指定副本的文件字节偏移。
* 输入参数:kind——记录或导出文件种类;index——本次条目、点或逻辑槽的下标;bank——双副本编号0或1。
* 输出参数:无独立输出参数。
* 返回值:指定副本相对文件起点的字节偏移。
* 说明:文件头之后按 SOE、CO、定点、极值分区,每个逻辑槽依次放两份 bank。
* 类型和索引由外层验证;返回固定布局偏移,实际载荷变短不会改变后续槽的位置。
*/
static uint32_t Bank_Offset(IEC60870_HistoryKind_t kind, uint32_t index, unsigned bank)
{
uint32_t offset = STORE_HEADER_SIZE;
unsigned k;
for (k = 1U; k < (unsigned)kind; ++k) {
offset += IEC60870_History_Slot_Count((IEC60870_HistoryKind_t)k) *
2U * (BANK_HEADER_SIZE + Payload_Capacity((IEC60870_HistoryKind_t)k));
}
return offset + (index * 2U + bank) * (BANK_HEADER_SIZE + Payload_Capacity(kind));
}
/**
* 功能:将文件读写位置移动到指定绝对偏移。
* 输入参数:file——已打开的同步文件句柄;offset——从起点计算的字节偏移。
* 输出参数:无独立输出参数。
* 返回值:true表示本次操作成功,false表示校验拒绝或处理失败。
* 说明:将独占句柄移动到绝对偏移;共享文件指针要求本对象所有操作保持串行。
*/
static bool Seek(HANDLE file, uint32_t offset)
{
LARGE_INTEGER at;
at.QuadPart = offset;
return SetFilePointerEx(file, at, NULL, FILE_BEGIN) != 0;
}
/**
* 功能:定位并完整写入指定字节段。
* 输入参数:file——已打开的同步文件句柄;offset——从起点计算的字节偏移;bytes——字节数据缓冲;size——本次数据的字节数。
* 输出参数:无独立输出参数。
* 返回值:true表示本次操作成功,false表示校验拒绝或处理失败。
* 说明:定位后完整写入指定范围,系统返回成功但短写仍为失败;本函数本身不执行持久同步。
*/
static bool Write_At(HANDLE file, uint32_t offset, const uint8_t *bytes, size_t size)
{
DWORD done = 0U;
return size <= MAXDWORD && Seek(file, offset) &&
WriteFile(file, bytes, (DWORD)size, &done, NULL) != 0 && done == size;
}
/**
* 功能:读取并核验指定持久副本的提交标记、载荷及代次。
* 输入参数:self——调用方持有的模块实例;kind——记录或导出文件种类;index——本次条目、点或逻辑槽的下标;bank——双副本编号0或1;generation——持久提交代次回写位置;size——实际字节数回写位置。
* 输出参数:generation——持久提交代次回写位置;size——实际字节数回写位置。
* 返回值:1表示有效提交,0表示未提交,-1表示损坏,-2表示系统读取错误。
* 说明:读取并校验一个 bank:1=有效提交,0=未写或已清除提交标记,-1=损坏,-2=系统读取失败。
* 未提交候选与已提交损坏必须区分;任一副本损坏均由调用方拒绝,不能退回另一副本或清空记录。
* 读取内容留在 self->banks[bank],generation/size 只在已通过对应头部检查后使用。
*/
static int Read_Bank(ExampleHistory *self, IEC60870_HistoryKind_t kind,
uint32_t index, unsigned bank, uint64_t *generation, size_t *size)
{
DWORD done = 0U;
size_t bank_size = BANK_HEADER_SIZE + Payload_Capacity(kind);
uint8_t *p = self->banks[bank];
memset(p, 0, bank_size);
if (!Seek((HANDLE)self->storage, Bank_Offset(kind, index, bank)) ||
!ReadFile((HANDLE)self->storage, p, (DWORD)bank_size, &done, NULL)) { return -2; }
if (done == 0U) { return 0; }
/* 先识别已可靠失效的候选:写入新载荷中断时,其头部可以尚未完整。 */
if (done >= 28U && Get32(p + 24U) == 0U) { return 0; }
if (done < BANK_HEADER_SIZE) { return -1; }
if (Get32(p + 24U) != BANK_COMMITTED || memcmp(p, "HSL1", 4U) != 0 ||
Get32(p + 20U) != Crc(p, 20U)) { return -1; }
*size = Get32(p + 4U);
*generation = Get64(p + 8U);
if (*generation == 0U || *size > Payload_Capacity(kind) ||
done < BANK_HEADER_SIZE + *size ||
Get32(p + 16U) != Crc(p + BANK_HEADER_SIZE, *size)) { return -1; }
return 1;
}
/**
* 功能:读取持久逻辑槽并选择可恢复的副本。
* 输入参数:context——调用方注册的回调上下文;kind——记录或导出文件种类;index——本次条目、点或逻辑槽的下标;bytes——字节数据缓冲;capacity——目标缓冲容量;size——实际字节数回写位置。
* 输出参数:bytes——字节数据缓冲;size——实际字节数回写位置。
* 返回值:OK表示已读出可靠记录,EMPTY表示两副本均无提交,ERROR表示读取、校验或输出容量不满足要求。
* 说明:核心 read 适配:读取两份副本,优先选取校验通过且代次更新的一份。
* 只有两份均未提交才返回 EMPTY;任一副本损坏、系统读失败或同代次内容冲突均返回 ERROR。
*/
static IEC60870_HistoryResult_t Store_Read(void *context, IEC60870_HistoryKind_t kind,
uint32_t index, uint8_t *bytes, size_t capacity, size_t *size)
{
ExampleHistory *self = context;
uint64_t generation[2] = {0U, 0U};
size_t sizes[2] = {0U, 0U};
int a, b;
unsigned winner;
if (Payload_Capacity(kind) == 0U || index >= IEC60870_History_Slot_Count(kind)) {
return IEC60870_HISTORY_ERROR;
}
a = Read_Bank(self, kind, index, 0U, &generation[0], &sizes[0]);
b = Read_Bank(self, kind, index, 1U, &generation[1], &sizes[1]);
if (a < 0 || b < 0) { return IEC60870_HISTORY_ERROR; }
if (a != 1 && b != 1) {
return a == 0 && b == 0 ? IEC60870_HISTORY_EMPTY : IEC60870_HISTORY_ERROR;
}
if (a == 1 && b == 1 && generation[0] == generation[1] &&
(sizes[0] != sizes[1] || memcmp(self->banks[0] + BANK_HEADER_SIZE,
self->banks[1] + BANK_HEADER_SIZE, sizes[0]) != 0)) { return IEC60870_HISTORY_ERROR; }
winner = b == 1 && (a != 1 || generation[1] > generation[0]) ? 1U : 0U;
if (sizes[winner] > capacity) { return IEC60870_HISTORY_ERROR; }
memcpy(bytes, self->banks[winner] + BANK_HEADER_SIZE, sizes[winner]);
*size = sizes[winner];
return IEC60870_HISTORY_OK;
}
/**
* 功能:通过双副本和持久同步提交一个逻辑槽。
* 输入参数:context——调用方注册的回调上下文;kind——记录或导出文件种类;index——本次条目、点或逻辑槽的下标;bytes——字节数据缓冲;size——本次数据的字节数。
* 输出参数:无独立输出参数。
* 返回值:true表示本次操作成功,false表示校验拒绝或处理失败。
* 说明:核心 commit 适配:复用较旧副本,依次同步失效标记、完整内容、有效标记。
* 旧的有效副本在第三步完成前保留。false 可能发生在新数据已经持久化之后,
* 调用方必须重新恢复核心事实,不能把 false 理解成必定未写入并盲目重复追加。
* 写入前发现任一副本损坏或同代次内容冲突即失败,保留介质供诊断,不覆盖损坏事实。
*/
static bool Store_Commit(void *context, IEC60870_HistoryKind_t kind,
uint32_t index, const uint8_t *bytes, size_t size)
{
ExampleHistory *self = context;
uint64_t generation[2] = {0U, 0U}, next;
size_t sizes[2];
int a, b;
unsigned target;
uint32_t offset;
uint8_t marker[4] = {0U, 0U, 0U, 0U};
uint8_t *p;
HANDLE file = (HANDLE)self->storage;
if (Payload_Capacity(kind) == 0U || index >= IEC60870_History_Slot_Count(kind) ||
size > Payload_Capacity(kind)) { return false; }
a = Read_Bank(self, kind, index, 0U, &generation[0], &sizes[0]);
b = Read_Bank(self, kind, index, 1U, &generation[1], &sizes[1]);
if (a < 0 || b < 0) { return false; }
if (a == 1 && b == 1 && generation[0] == generation[1] &&
(sizes[0] != sizes[1] || memcmp(self->banks[0] + BANK_HEADER_SIZE,
self->banks[1] + BANK_HEADER_SIZE, sizes[0]) != 0)) { return false; }
target = a == 1 && (b != 1 || generation[0] >= generation[1]) ? 1U : 0U;
next = (a == 1 ? generation[0] : 0U);
if (b == 1 && generation[1] > next) { next = generation[1]; }
if (next == UINT64_MAX) { return false; }
++next;
offset = Bank_Offset(kind, index, target);
/* 第一步先可靠清除目标旧标记,防止中断后把部分新载荷解释成原来的已提交副本。 */
if (!Write_At(file, offset + 24U, marker, sizeof(marker)) || !FlushFileBuffers(file)) { return false; }
if (!Example_History_Test_Continue()) { return false; }
/* 第二步写入带新代次及校验的完整候选,此时标记仍为零,对恢复读取不可见。 */
p = self->banks[target];
memset(p, 0, BANK_HEADER_SIZE);
memcpy(p, "HSL1", 4U);
Put32(p + 4U, (uint32_t)size); Put64(p + 8U, next);
Put32(p + 16U, Crc(bytes, size)); Put32(p + 20U, Crc(p, 20U));
memcpy(p + BANK_HEADER_SIZE, bytes, size);
if (!Write_At(file, offset, p, BANK_HEADER_SIZE + size) || !FlushFileBuffers(file)) { return false; }
if (!Example_History_Test_Continue()) { return false; }
/* 第三步才发布提交标记并同步;最后的测试中断验证成功落盘但上层获失败的窗口。 */
Put32(marker, BANK_COMMITTED);
return Write_At(file, offset + 24U, marker, sizeof(marker)) && FlushFileBuffers(file) &&
Example_History_Test_Continue();
}
/**
* 功能:创建关闭时自动删除的独占临时快照文件。
* 输入参数:parent——已存在的宿主父目录。
* 输出参数:无独立输出参数。
* 返回值:成功返回临时文件句柄,失败返回INVALID_HANDLE_VALUE。
* 说明:在存储父目录创建独占临时快照;打开成功后由 DELETE_ON_CLOSE 负责清理。
* 已创建名字却无法取得句柄时主动删除候选,避免失败路径遗留空文件。
*/
static HANDLE Temporary(const char *parent)
{
char path[MAX_PATH];
HANDLE file;
if (!GetTempFileNameA(parent, "ich", 0U, path)) { return INVALID_HANDLE_VALUE; }
file = CreateFileA(path, GENERIC_READ | GENERIC_WRITE, 0U, NULL, OPEN_EXISTING,
FILE_ATTRIBUTE_TEMPORARY | FILE_FLAG_DELETE_ON_CLOSE, NULL);
if (file == INVALID_HANDLE_VALUE) { (void)DeleteFileA(path); }
return file;
}
/**
* 功能:将XML编码器给出的片段完整写入临时文件。
* 输入参数:context——调用方注册的回调上下文;bytes——字节数据缓冲;size——本次数据的字节数。
* 输出参数:无独立输出参数。
* 返回值:true表示本次操作成功,false表示校验拒绝或处理失败。
* 说明:XML 流式输出适配:每片必须完整写入临时文件,否则整份导出失败,不能发布前缀。
*/
static bool Sink(void *context, const uint8_t *bytes, size_t size)
{
DWORD done = 0U;
return size <= MAXDWORD && WriteFile((HANDLE)context, bytes, (DWORD)size, &done, NULL) && done == size;
}
/**
* 功能:比较协议名称与预期本地字符串是否完全一致。
* 输入参数:name——文件名或显式长度的协议名称;length——本次数据或名称的有效字节数;expected——预期匹配的本地字符串。
* 输出参数:无独立输出参数。
* 返回值:名称长度与全部字节均相同时返回true,否则返回false。
* 说明:协议名称可能不带 NUL,按显式长度和大小写精确匹配;不接受路径别名或模糊前缀。
*/
static bool Equal_Name(const uint8_t *name, size_t length, const char *expected)
{
return name != NULL && length == strlen(expected) && memcmp(name, expected, length) == 0;
}
/**
* 功能:将UTC毫秒转换为UTC+8的CP56日历时标。
* 输入参数:utc_ms——UTC毫秒时刻;time——CP56日历时标回写位置。
* 输出参数:time——CP56日历时标回写位置。
* 返回值:true表示本次操作成功,false表示校验拒绝或处理失败。
* 说明:将原始 UTC 毫秒转换为目录使用的本地 CP56 日历;只接受两位年份可表达的范围。
*/
static bool Make_Time(uint64_t utc_ms, IEC60870_CP56Time2a_t *time)
{
memset(time, 0, sizeof(*time));
return utc_ms / 1000U <= UINT32_MAX &&
IEC60870_Time_Seconds_To_Local((uint32_t)(utc_ms / 1000U), (uint16_t)(utc_ms % 1000U), &time->time) &&
time->time.year >= 2000U;
}
/**
* 功能:取得导出文件对应的目录时标。
* 输入参数:self——调用方持有的模块实例;kind——记录或导出文件种类;day——历史或冻结窗口日序;time——CP56日历时标回写位置。
* 输出参数:time——CP56日历时标回写位置。
* 返回值:true表示本次操作成功,false表示校验拒绝或处理失败。
* 说明:目录时间来自业务数据:事件文件取最新事件,日文件取所属日期零点。
* 不采用本次生成时刻,否则重复召目录会改变时间筛选结果。
*/
static bool File_Time(ExampleHistory *self, IEC60870_HistoryKind_t kind,
uint32_t day, IEC60870_CP56Time2a_t *time)
{
if (kind == IEC60870_HISTORY_SOE || kind == IEC60870_HISTORY_CO) {
IEC60870_HistoryEvent_t event;
size_t count = IEC60870_History_Event_Count(&self->core, kind);
/* 空事件文件只有固定目录时间标记,记录数仍为零,不由此制造一条事件。 */
if (count == 0U) { return Make_Time(946656000000ULL, time); }
if (IEC60870_History_Get_Event(&self->core, kind, count - 1U, &event) != IEC60870_HISTORY_OK) { return false; }
if (!Make_Time(event.utc_ms, time)) { return false; }
time->is_invalid = event.time_valid ? 0U : 1U;
return true;
}
return day != 0U && Make_Time((uint64_t)day * 86400000ULL - 28800000ULL, time);
}
/**
* 功能:将指定历史窗口编码为候选XML文件。
* 输入参数:self——调用方持有的模块实例;file——已打开的同步文件句柄;kind——记录或导出文件种类;day——历史或冻结窗口日序;size——实际字节数回写位置。
* 输出参数:size——实际字节数回写位置。
* 返回值:true表示本次操作成功,false表示校验拒绝或处理失败。
* 说明:把一个核心记录集合编码至已打开的候选文件;示例不配置工程单位,编码器输出空单位。
* 调用方负责候选偏移和生命周期,成功大小由编码器回写,失败内容不得进入目录清单。
*/
static bool Export(ExampleHistory *self, HANDLE file, IEC60870_HistoryKind_t kind,
uint32_t day, uint32_t *size)
{
IEC60870_HistoryFileConfig_t config;
config.device_name = self->device_name;
config.analog_units = NULL;
return IEC60870_HistoryFile_Write(&self->core, kind, day, &config, Sink, file, size);
}
/**
* 功能:预检日文件是否有可导出的数据:1=存在,0=真实缺测,-1=读取错误。
* 输入参数:self——调用方持有的模块实例;kind——记录或导出文件种类;day——历史或冻结窗口日序。
* 输出参数:无独立输出参数。
* 返回值:1表示该日存在记录,0表示无记录,-1表示读取或记录验证失败。
* 说明:极值至少有一个有效点,定点至少有一个已存完整节;缺测不补零,也不生成空日文件。
*/
static int Daily_Present(ExampleHistory *self, IEC60870_HistoryKind_t kind, uint32_t day)
{
if (kind == IEC60870_HISTORY_EXV) {
IEC60870_HistoryExtrema_t value;
IEC60870_HistoryResult_t result = IEC60870_History_Read_Extrema(&self->core, day, &value);
size_t i;
if (result == IEC60870_HISTORY_EMPTY) { return 0; }
if (result != IEC60870_HISTORY_OK) { return -1; }
for (i = 0U; i < value.count; ++i) { if (value.points[i].valid) { return 1; } }
return 0;
} else {
IEC60870_HistoryFixed_t value;
unsigned slot;
for (slot = 1U; slot <= 96U; ++slot) {
IEC60870_HistoryResult_t result = IEC60870_History_Read_Fixed(&self->core, day, (uint16_t)slot, &value);
if (result == IEC60870_HISTORY_OK) { return 1; }
if (result != IEC60870_HISTORY_EMPTY) { return -1; }
}
return 0;
}
}
/**
* 功能:建立独占文件并完成核心恢复,成功后才发布 opened。
* 输入参数:self——调用方持有的模块实例;parent——已存在的宿主父目录;config——初始化配置;device_name——导出文件使用的设备名称。
* 输出参数:self——本次操作更新的实例或工作区。
* 返回值:true表示请求的资源或存储实例已准备就绪;false表示输入校验、资源获取或恢复失败。
* 说明:允许关闭后用对象内保存的路径/配置再次打开,因此先复制实参,再清零对象。
*/
bool Example_History_Open(ExampleHistory *self, const char *parent,
const IEC60870_HistoryConfig_t *config, const char *device_name)
{
char path[256];
uint8_t header[STORE_HEADER_SIZE], expected[STORE_HEADER_SIZE] = {0};
LARGE_INTEGER size;
DWORD done = 0U;
HANDLE file;
IEC60870_HistoryStore_t store;
IEC60870_HistoryConfig_t saved_config;
char saved_parent[sizeof(self->parent)], saved_name[sizeof(self->device_name)];
bool created;
int n;
if (self == NULL || self->opened || parent == NULL || config == NULL || device_name == NULL ||
strlen(parent) >= sizeof(self->parent) || strlen(device_name) >= sizeof(self->device_name)) { return false; }
saved_config = *config;
strcpy(saved_parent, parent); strcpy(saved_name, device_name);
memset(self, 0, sizeof(*self));
n = snprintf(path, sizeof(path), "%s/history.store", saved_parent);
if (n < 0 || (size_t)n >= sizeof(path)) { return false; }
/* 共享模式为零:其他实例不能同时读写同一存储;锁的生命周期与 storage 句柄一致。 */
file = CreateFileA(path, GENERIC_READ | GENERIC_WRITE, 0U, NULL, OPEN_ALWAYS, FILE_ATTRIBUTE_NORMAL, NULL);
if (file == INVALID_HANDLE_VALUE) { return false; }
created = GetLastError() != ERROR_ALREADY_EXISTS;
self->storage = file;
memcpy(expected, "IEC104-HISTORY1", 14U);
Put32(expected + 16U, IEC60870_HISTORY_MAX_ANALOG);
Put32(expected + 20U, IEC60870_HISTORY_DAYS);
Put32(expected + 28U, Crc(expected, 28U));
if (!GetFileSizeEx(file, &size)) { goto failed; }
/* 只初始化本次新建文件;已有空文件可能是截断事故,必须拒绝而不是静默重置。 */
if (size.QuadPart == 0) {
if (!created) { goto failed; }
if (!Write_At(file, 0U, expected, sizeof(expected)) || !FlushFileBuffers(file)) { goto failed; }
} else if (!Seek(file, 0U) || !ReadFile(file, header, sizeof(header), &done, NULL) ||
done != sizeof(header) || memcmp(header, expected, sizeof(header)) != 0) { goto failed; }
store.context = self; store.read = Store_Read; store.commit = Store_Commit;
if (IEC60870_History_Init(&self->core, &saved_config, &store) != IEC60870_HISTORY_OK) { goto failed; }
strcpy(self->parent, saved_parent); strcpy(self->device_name, saved_name);
self->opened = true;
return true;
failed:
CloseHandle(file); self->storage = NULL;
return false;
}
/**
* 功能:结束本次下载,关闭临时句柄即删除读快照;目录缓存和持久文件继续存活。
* 输入参数:self——调用方持有的模块实例。
* 输出参数:self——本次操作更新的实例或工作区。
* 返回值:无。
* 说明:无。
*/
void Example_History_Read_Close(ExampleHistory *self)
{
if (self == NULL) { return; }
if (self->read_file != NULL) { CloseHandle((HANDLE)self->read_file); }
self->read_file = NULL; self->read_size = 0U;
}
/**
* 功能:退出或初始化回退共用清理:先关下载,再关目录缓存和独占存储,最终禁用核心。
* 输入参数:self——调用方持有的模块实例。
* 输出参数:self——本次操作更新的实例或工作区。
* 返回值:无。
* 说明:不删除已提交的持久文件;NULL 与已关闭对象均可重复清理。
*/
void Example_History_Close(ExampleHistory *self)
{
if (self == NULL) { return; }
Example_History_Read_Close(self);
if (self->directory_file != NULL) { CloseHandle((HANDLE)self->directory_file); }
if (self->storage != NULL) { CloseHandle((HANDLE)self->storage); }
self->storage = NULL; self->directory_file = NULL;
self->entry_count = 0U; self->directory_active = false; self->opened = false;
self->core.initialized = false;
}
/**
* 功能:按虚拟目录冻结清单和全部文件内容,不在后续 list 重试时重新生成。
* 输入参数:self——调用方持有的模块实例;name——文件名或显式长度的协议名称;length——本次数据或名称的有效字节数。
* 输出参数:self——本次操作更新的实例或工作区。
* 返回值:true表示完整目录快照已发布;false表示名称、记录校验或快照生成失败。
* 说明:日目录按时间窗口筛选实际存在日期;只有全部候选成功,才发布新的活动目录。
*/
bool Example_History_Directory_Open(ExampleHistory *self, const uint8_t *name, size_t length)
{
IEC60870_HistoryKind_t kind;
uint32_t latest = 0U, day = 0U, last = 0U, offset = 0U;
HANDLE file;
if (self == NULL || !self->opened || self->core.faulted || self->directory_active) { return false; }
if (length == 0U || Equal_Name(name, length, "HISTORY/SOE")) { kind = IEC60870_HISTORY_SOE; }
else if (Equal_Name(name, length, "HISTORY/CO")) { kind = IEC60870_HISTORY_CO; }
else if (Equal_Name(name, length, "HISTORY/EXV")) { kind = IEC60870_HISTORY_EXV; }
else if (Equal_Name(name, length, "HISTORY/FIXPT")) { kind = IEC60870_HISTORY_FIXPT; }
else { return false; }
/* 新一轮目录替换上次缓存;已打开下载拥有独立副本,不借用此句柄。 */
if (self->directory_file != NULL) { CloseHandle((HANDLE)self->directory_file); }
self->directory_file = NULL; self->entry_count = 0U;
file = Temporary(self->parent);
if (file == INVALID_HANDLE_VALUE) { return false; }
if (kind == IEC60870_HISTORY_EXV || kind == IEC60870_HISTORY_FIXPT) {
if (!IEC60870_History_Latest_Day(&self->core, &latest) || latest == 0U) { goto complete; }
/* latest 是正在累计的日期,只枚举前面三十个完成日;缺日不向更早日期补齐。 */
day = latest > 30U ? latest - 30U : 1U;
last = latest - 1U;
}
do {
ExampleHistoryEntry *entry;
if (kind == IEC60870_HISTORY_EXV || kind == IEC60870_HISTORY_FIXPT) {
int present = Daily_Present(self, kind, day);
if (present < 0) { goto failed; }
if (present == 0) { continue; }
}
if (self->entry_count >= EXAMPLE_HISTORY_DIRECTORY_CAPACITY) { goto failed; }
entry = &self->entries[self->entry_count];
entry->offset = offset;
if (!IEC60870_HistoryFile_Name(kind, day, entry->name, sizeof(entry->name)) ||
!File_Time(self, kind, day, &entry->time) || !Export(self, file, kind, day, &entry->size) ||
entry->size > UINT32_MAX - offset) { goto failed; }
/* 名称、时间、大小和拼接偏移属于同一份 XML;未成功的项目不增加计数。 */
offset += entry->size; ++self->entry_count;
} while (day++ < last);
complete:
self->directory_file = file; self->directory_active = true;
return true;
failed:
CloseHandle(file); self->entry_count = 0U;
return false;
}
/**
* 功能:只向活动枚举暴露数量;关闭后缓存仍可供 Read_Open 使用。
* 输入参数:self——调用方持有的模块实例。
* 输出参数:无独立输出参数。
* 返回值:当前目录可枚举的条目数;目录未打开时为0。
* 说明:无。
*/
size_t Example_History_Directory_Count(const ExampleHistory *self)
{
return self != NULL && self->directory_active ? self->entry_count : 0U;
}
/**
* 功能:按固定下标复制目录元数据,不返回临时栈指针,也不因重试改变清单。
* 输入参数:self——调用方持有的模块实例;index——本次条目、点或逻辑槽的下标;entry——目录条目。
* 输出参数:entry——目录条目。
* 返回值:true表示目录条目已复制到entry;false表示实例、目录或索引无效。
* 说明:无。
*/
bool Example_History_Directory_Get(const ExampleHistory *self, size_t index, ExampleHistoryEntry *entry)
{
if (self == NULL || !self->directory_active || entry == NULL || index >= self->entry_count) { return false; }
*entry = self->entries[index];
return true;
}
/**
* 功能:协议目录收尾只结束枚举,保留已向主站声明的版本至下次召目录或整体关闭。
* 输入参数:self——调用方持有的模块实例。
* 输出参数:self——本次操作更新的实例或工作区。
* 返回值:无。
* 说明:无。
*/
void Example_History_Directory_Close(ExampleHistory *self)
{
if (self != NULL) { self->directory_active = false; }
}
/**
* 功能:为一次下载取得独立快照:先匹配保留清单,命中则复制其原版本;未命中才按当前保留范围导出。
* 输入参数:self——调用方持有的模块实例;name——文件名或显式长度的协议名称;length——本次数据或名称的有效字节数;size——实际字节数回写位置。
* 输出参数:self——本次操作更新的实例或工作区;size——实际字节数回写位置。
* 返回值:true表示独立下载快照已打开并写回长度;false表示名称或快照准备失败。
* 说明:名称只与生成器给出的合法路径比较,不把主站输入拼到宿主路径上。
* 任一复制/导出失败均销毁候选,只有内容完整后才发布 read_file 及大小。
*/
bool Example_History_Read_Open(ExampleHistory *self, const uint8_t *name, size_t length, uint32_t *size)
{
HANDLE file;
size_t i;
IEC60870_HistoryKind_t kind = IEC60870_HISTORY_SOE;
uint32_t day = 0U, latest = 0U;
bool found = false;
if (self == NULL || !self->opened || self->core.faulted || self->read_file != NULL || size == NULL) { return false; }
file = Temporary(self->parent);
if (file == INVALID_HANDLE_VALUE) { return false; }
/* 目录与下载之间可以新增事件或跨日;命中缓存必须沿用原大小和原字节,不能重新导出。 */
for (i = 0U; i < self->entry_count; ++i) {
const ExampleHistoryEntry *entry = &self->entries[i];
if (Equal_Name(name, length, entry->name) && self->directory_file != NULL) {
uint8_t bytes[256];
uint32_t position = 0U;
if (!Seek((HANDLE)self->directory_file, entry->offset)) { goto failed; }
while (position < entry->size) {
DWORD done = 0U;
DWORD amount = entry->size - position < sizeof(bytes) ? entry->size - position : sizeof(bytes);
if (!ReadFile((HANDLE)self->directory_file, bytes, amount, &done, NULL) ||
done != amount || !Sink(file, bytes, amount)) { goto failed; }
position += amount;
}
self->read_size = entry->size; found = true; break;
}
}
/* 支持直接按完整名读取,但日文件仍须位于当前三十个完成日,不绕过导出窗口。 */
if (!found) {
if (Equal_Name(name, length, "HISTORY/SOE/soe.xml")) { kind = IEC60870_HISTORY_SOE; found = true; }
else if (Equal_Name(name, length, "HISTORY/CO/co.xml")) { kind = IEC60870_HISTORY_CO; found = true; }
else if (IEC60870_History_Latest_Day(&self->core, &latest)) {
unsigned k;
char expected[IEC60870_HISTORY_FILE_PATH_CAPACITY];
for (k = IEC60870_HISTORY_FIXPT; k <= IEC60870_HISTORY_EXV && !found; ++k) {
uint32_t first = latest > 30U ? latest - 30U : 1U;
for (day = first; day < latest; ++day) {
if (IEC60870_HistoryFile_Name((IEC60870_HistoryKind_t)k, day, expected, sizeof(expected)) &&
Equal_Name(name, length, expected)) { kind = (IEC60870_HistoryKind_t)k; found = true; break; }
}
}
}
if (!found || !Export(self, file, kind, day, &self->read_size)) { goto failed; }
}
self->read_file = file; *size = self->read_size;
return true;
failed:
CloseHandle(file); self->read_size = 0U;
return false;
}
/**
* 功能:从不可变读快照按绝对偏移完整读取;先用减法检查范围,避免 offset+length 溢出。
* 输入参数:self——调用方持有的模块实例;offset——从起点计算的字节偏移;buffer——调用方提供的数据缓冲;length——本次数据或名称的有效字节数。
* 输出参数:buffer——调用方提供的数据缓冲。
* 返回值:true表示指定范围的数据已完整读出;false表示范围非法、读取失败或短读。
* 说明:读顺序不必连续,相同偏移可因协议重试再次读取;短读即失败。
*/
bool Example_History_Read(ExampleHistory *self, uint32_t offset, uint8_t *buffer, size_t length)
{
DWORD done = 0U;
if (self == NULL || self->read_file == NULL || offset > self->read_size ||
length > self->read_size - offset || (length != 0U && buffer == NULL)) { return false; }
return Seek((HANDLE)self->read_file, offset) &&
ReadFile((HANDLE)self->read_file, buffer, (DWORD)length, &done, NULL) && done == length;
}