666 lines
34 KiB
C
666 lines
34 KiB
C
/*
|
||
* 模块名称: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;
|
||
}
|