Files
STM32F4-Base/IEC60870-Slave/examples/iec104_example_energy_freeze.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

614 lines
31 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.
/* 冻结电能宿主后端。只负责持久字节和不可变下载,不替核心决定窗口封存或保留水位。 */
#include "iec104_example_energy_freeze.h"
#include <stdio.h>
#include <string.h>
#include <windows.h>
#define ENERGY_STORE_HEADER 32U
#define ENERGY_BANK_HEADER 32U
#define ENERGY_COMMITTED 0x54494d43UL
#ifdef IEC104_EXAMPLE_ENERGY_FREEZE_TEST
/**
* 功能:在真实持久操作完成后提供测试中断判定。
* 输入参数:无。
* 输出参数:无输出参数;测试实现更新故障注入计数。
* 返回值:true允许继续,false在指定阶段模拟中断。
* 说明:仅测试宏启用时链接;真实写入已发生,返回false不撤销已同步内容。
*/
extern bool Example_Energy_Freeze_Test_Continue(void);
#else
#define Example_Energy_Freeze_Test_Continue() true
#endif
/**
* 功能:从字节缓冲解码32位小端整数。
* 输入参数:p——小端字段所在字节缓冲。
* 输出参数:无独立输出参数。
* 返回值:解码后的32位无符号整数。
* 说明:从持久字节流读取小端32位值,不要求地址对齐;调用方保证至少有4字节。
*/
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);
}
/**
* 功能:从字节缓冲解码64位小端整数。
* 输入参数:p——小端字段所在字节缓冲。
* 输出参数:无独立输出参数。
* 返回值:解码后的64位无符号整数。
* 说明:按低32位在前的顺序读取小端64位值,避免直接解引用未对齐的文件字段。
*/
static uint64_t Get64(const uint8_t *p)
{
return Get32(p) | ((uint64_t)Get32(p + 4U) << 32);
}
/**
* 功能:将32位整数写成小端字节序。
* 输入参数:p——小端字段所在字节缓冲;value——本次待处理的数值。
* 输出参数:p——小端字段所在字节缓冲。
* 返回值:无。
* 说明:将32位值编码为4个小端字节,文件格式不依赖宿主字节序或结构体布局。
*/
static void Put32(uint8_t *p, uint32_t value)
{
unsigned i;
for (i = 0U; i < 4U; ++i) { p[i] = (uint8_t)(value >> (i * 8U)); }
}
/**
* 功能:将64位整数写成小端字节序。
* 输入参数:p——小端字段所在字节缓冲;value——本次待处理的数值。
* 输出参数:p——小端字段所在字节缓冲。
* 返回值:无。
* 说明:将64位代次编码为8个小端字节,低32位在前。
*/
static void Put64(uint8_t *p, uint64_t value)
{
Put32(p, (uint32_t)value); Put32(p + 4U, (uint32_t)(value >> 32));
}
/**
* 功能:计算当前字节段的完整CRC-32校验值。
* 输入参数:p——小端字段所在字节缓冲;length——本次数据或名称的有效字节数。
* 输出参数:无独立输出参数。
* 返回值:完成初值处理和末尾取反后的CRC-32值。
* 说明:计算带初值及末尾取反的CRC-32,用于文件头、bank头和载荷的独立校验。
*/
static uint32_t Crc(const uint8_t *p, size_t length)
{
uint32_t crc = UINT32_MAX;
size_t i;
for (i = 0U; i < length; ++i) {
unsigned bit;
crc ^= p[i];
for (bit = 0U; bit < 8U; ++bit) {
crc = (crc >> 1) ^ ((crc & 1U) != 0U ? 0xedb88320UL : 0U);
}
}
return crc ^ UINT32_MAX;
}
/**
* 功能:取得指定记录种类的固定载荷容量。
* 输入参数:kind——记录或导出文件种类。
* 输出参数:无独立输出参数。
* 返回值:对应记录种类的固定载荷容量,单位字节。
* 说明:固定布局是文件格式的一部分,不能随本次点数改变偏移。
*/
static uint32_t Payload_Capacity(IEC60870_EnergyFreezeKind_t kind)
{
switch (kind) {
case IEC60870_ENERGY_FREEZE_INTERVAL: case IEC60870_ENERGY_FREEZE_DAY: return 368U;
case IEC60870_ENERGY_FREEZE_FLOWREV: return 96U;
case IEC60870_ENERGY_FREEZE_SEAL: return 66U;
case IEC60870_ENERGY_FREEZE_META: return 72U;
default: return 0U;
}
}
/**
* 功能:计算逻辑槽中指定副本的文件字节偏移。
* 输入参数:kind——记录或导出文件种类;index——本次条目、点或逻辑槽的下标;bank——双副本编号0或1。
* 输出参数:无独立输出参数。
* 返回值:指定副本相对文件起点的字节偏移。
* 说明:按固定分区、逻辑槽和双bank编号计算文件偏移;调用方先验证kind/index,bank只取0或1。
*/
static uint32_t Bank_Offset(IEC60870_EnergyFreezeKind_t kind, uint32_t index, unsigned bank)
{
static const uint32_t base[] = {0U, 32U, 2457632U, 2483232U, 2548768U, 2555040U};
return base[(unsigned)kind] + (index * 2U + bank) * (ENERGY_BANK_HEADER + Payload_Capacity(kind));
}
/**
* 功能:将文件读写位置移动到指定绝对偏移。
* 输入参数:file——已打开的同步文件句柄;offset——从起点计算的字节偏移。
* 输出参数:无独立输出参数。
* 返回值:true表示本次操作成功,false表示校验拒绝或处理失败。
* 说明:将共享文件指针定位到绝对字节偏移,失败返回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——字节数据缓冲;length——本次数据或名称的有效字节数。
* 输出参数:无独立输出参数。
* 返回值:true表示本次操作成功,false表示校验拒绝或处理失败。
* 说明:定位并写足指定字节数,短写也视为失败;此处不执行持久同步,由提交阶段负责Flush。
*/
static bool Write_At(HANDLE file, uint32_t offset, const uint8_t *bytes, size_t length)
{
DWORD done = 0U;
return length <= MAXDWORD && Seek(file, offset) &&
WriteFile(file, bytes, (DWORD)length, &done, NULL) && done == length;
}
/**
* 功能:读取并核验指定持久副本的提交标记、载荷及代次。
* 输入参数:self——调用方持有的模块实例;kind——记录或导出文件种类;index——本次条目、点或逻辑槽的下标;bank——双副本编号0或1;generation——持久提交代次回写位置;size——实际字节数回写位置。
* 输出参数:generation——持久提交代次回写位置;size——实际字节数回写位置。
* 返回值:1表示可靠提交,0表示未提交,-1表示损坏或I/O错误。
* 说明:返回0为未提交,1为可靠提交,-1为不可恢复或I/O错误。
* 标记为零或非COMMITTED的候选不参与代次竞争;COMMITTED之后任何校验错误
* 都使整个逻辑槽失败,不能退选另一份旧副本来掩盖已提交损坏。
*/
static int Read_Bank(ExampleEnergyFreeze *self, IEC60870_EnergyFreezeKind_t kind,
uint32_t index, unsigned bank, uint64_t *generation, size_t *size)
{
uint8_t *p = self->banks[bank];
DWORD done = 0U;
size_t capacity = ENERGY_BANK_HEADER + Payload_Capacity(kind);
memset(p, 0, capacity);
if (!Seek((HANDLE)self->storage, Bank_Offset(kind, index, bank)) ||
!ReadFile((HANDLE)self->storage, p, (DWORD)capacity, &done, NULL)) { return -1; }
if (done == 0U) { return 0; }
if (done < 28U) { return -1; }
if (Get32(p + 24U) != ENERGY_COMMITTED) { return 0; }
if (done < ENERGY_BANK_HEADER || memcmp(p, "EZL1", 4U) != 0 ||
Get32(p + 20U) != Crc(p, 20U) || Get32(p + 28U) != 0U) { return -1; }
*size = Get32(p + 4U); *generation = Get64(p + 8U);
if (*generation == 0U || *size == 0U || *size > Payload_Capacity(kind) ||
done < ENERGY_BANK_HEADER + *size ||
Get32(p + 16U) != Crc(p + ENERGY_BANK_HEADER, *size)) { return -1; }
return 1;
}
/**
* 功能:读取持久逻辑槽并选择可恢复的副本。
* 输入参数:context——调用方注册的回调上下文;kind——记录或导出文件种类;index——本次条目、点或逻辑槽的下标;bytes——字节数据缓冲;capacity——目标缓冲容量;size——实际字节数回写位置。
* 输出参数:bytes——字节数据缓冲;size——实际字节数回写位置。
* 返回值:OK表示已读出可靠记录,EMPTY表示两副本均无提交,ERROR表示读取、校验或输出容量不满足要求。
* 说明:读取并校验两个bank,选择代次较新的可靠提交,只有成功才复制bytes并写回size。
* 两份都未提交返回EMPTY;任一已提交副本损坏、同代次内容冲突或容量不足均返回ERROR。
*/
static IEC60870_EnergyFreezeResult_t Store_Read(void *context, IEC60870_EnergyFreezeKind_t kind,
uint32_t index, uint8_t *bytes, size_t capacity, size_t *size)
{
ExampleEnergyFreeze *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_EnergyFreeze_Slot_Count(kind) ||
bytes == NULL || size == NULL) { return IEC60870_ENERGY_FREEZE_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_ENERGY_FREEZE_ERROR; }
if (a == 0 && b == 0) { return IEC60870_ENERGY_FREEZE_EMPTY; }
if (a == 1 && b == 1 && generation[0] == generation[1] &&
(sizes[0] != sizes[1] || memcmp(self->banks[0] + ENERGY_BANK_HEADER,
self->banks[1] + ENERGY_BANK_HEADER, sizes[0]) != 0)) { return IEC60870_ENERGY_FREEZE_ERROR; }
winner = b == 1 && (a != 1 || generation[1] > generation[0]) ? 1U : 0U;
if (sizes[winner] > capacity) { return IEC60870_ENERGY_FREEZE_ERROR; }
memcpy(bytes, self->banks[winner] + ENERGY_BANK_HEADER, sizes[winner]);
*size = sizes[winner];
return IEC60870_ENERGY_FREEZE_OK;
}
/**
* 功能:通过双副本和持久同步提交一个逻辑槽。
* 输入参数:context——调用方注册的回调上下文;kind——记录或导出文件种类;index——本次条目、点或逻辑槽的下标;bytes——字节数据缓冲;size——本次数据的字节数。
* 输出参数:无独立输出参数。
* 返回值:true表示本次操作成功,false表示校验拒绝或处理失败。
* 说明:向较旧或未提交的bank写入下一代:清标记、写候选、置提交标记,每阶段分别Flush。
* 保留另一份可靠提交供中断恢复,已提交损坏或代次耗尽则拒绝写入。
* 返回false时新值仍可能已经落盘,核心须闭锁并重新Init,不能直接重放本次提交。
*/
static bool Store_Commit(void *context, IEC60870_EnergyFreezeKind_t kind,
uint32_t index, const uint8_t *bytes, size_t size)
{
ExampleEnergyFreeze *self = context;
uint64_t generation[2] = {0U, 0U}, next;
size_t sizes[2] = {0U, 0U};
unsigned target;
int a, b;
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_EnergyFreeze_Slot_Count(kind) ||
bytes == NULL || size == 0U || 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] + ENERGY_BANK_HEADER,
self->banks[1] + ENERGY_BANK_HEADER, sizes[0]) != 0)) { return false; }
target = a == 1 && (b != 1 || generation[0] >= generation[1]) ? 1U : 0U;
next = generation[0] > generation[1] ? generation[0] : generation[1];
if (next == UINT64_MAX) { return false; }
offset = Bank_Offset(kind, index, target);
if (!Write_At(file, offset + 24U, marker, sizeof(marker)) || !FlushFileBuffers(file) ||
!Example_Energy_Freeze_Test_Continue()) { return false; }
p = self->banks[target];
memset(p, 0, ENERGY_BANK_HEADER);
memcpy(p, "EZL1", 4U); Put32(p + 4U, (uint32_t)size); Put64(p + 8U, next + 1U);
Put32(p + 16U, Crc(bytes, size)); Put32(p + 20U, Crc(p, 20U));
memcpy(p + ENERGY_BANK_HEADER, bytes, size);
if (!Write_At(file, offset, p, ENERGY_BANK_HEADER + size) || !FlushFileBuffers(file) ||
!Example_Energy_Freeze_Test_Continue()) { return false; }
Put32(marker, ENERGY_COMMITTED);
return Write_At(file, offset + 24U, marker, sizeof(marker)) && FlushFileBuffers(file) &&
Example_Energy_Freeze_Test_Continue();
}
/**
* 功能:创建关闭时自动删除的独占临时快照文件。
* 输入参数:parent——已存在的宿主父目录。
* 输出参数:无独立输出参数。
* 返回值:成功返回临时文件句柄,失败返回INVALID_HANDLE_VALUE。
* 说明:在指定父目录创建独占临时文件,句柄关闭时自动删除;打开失败则清理已生成的文件名。
*/
static HANDLE Temporary(const char *parent)
{
char path[MAX_PATH];
HANDLE file;
if (!GetTempFileNameA(parent, "ief", 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——字节数据缓冲;length——本次数据或名称的有效字节数。
* 输出参数:无独立输出参数。
* 返回值:true表示本次操作成功,false表示校验拒绝或处理失败。
* 说明:XML同步输出回调:从句柄当前位置写入完整片段,短写或I/O失败返回false,不保留bytes。
*/
static bool Sink(void *context, const uint8_t *bytes, size_t length)
{
DWORD done = 0U;
return length <= MAXDWORD && WriteFile((HANDLE)context, bytes, (DWORD)length, &done, NULL) && done == length;
}
/**
* 功能:比较协议名称与预期本地字符串是否完全一致。
* 输入参数:name——文件名或显式长度的协议名称;length——本次数据或名称的有效字节数;expected——预期匹配的本地字符串。
* 输出参数:无独立输出参数。
* 返回值:名称长度与全部字节均相同时返回true,否则返回false。
* 说明:按长度和字节精确匹配协议名称,区分大小写;name无需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毫秒展开为固定UTC+8的CP56日历,先清除品质及夏令时标志。
* 超出可表示日历范围时返回false,此时输出可能已部分改写,不得使用。
*/
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;
}
/**
* 功能:将指定历史窗口编码为候选XML文件。
* 输入参数:self——调用方持有的模块实例;file——已打开的同步文件句柄;kind——记录或导出文件种类;day——历史或冻结窗口日序;size——实际字节数回写位置。
* 输出参数:size——实际字节数回写位置。
* 返回值:true表示本次操作成功,false表示校验拒绝或处理失败。
* 说明:使用实例的设备名和单位,从临时文件当前位置写入候选XML;成功才写回size。
* 不负责发布或回滚文件,调用方在返回false时丢弃整份候选。
*/
static bool Export(ExampleEnergyFreeze *self, HANDLE file, IEC60870_EnergyFreezeFileKind_t kind,
uint32_t day, uint32_t *size)
{
IEC60870_EnergyFreezeFileConfig_t config;
config.device_name = self->device_name; config.units = self->units;
return IEC60870_EnergyFreezeFile_Write(&self->core, kind, day, &config, Sink, file, size);
}
/**
* 功能:独占打开已有父目录中的energy.store,新建文件写格式头,已有空档或损坏档拒绝重建。
* 输入参数:self——调用方持有的模块实例;parent——已存在的宿主父目录;config——初始化配置;device_name——导出文件使用的设备名称;units——各电能点的单位字符串表。
* 输出参数:self——本次操作更新的实例或工作区。
* 返回值:true表示请求的资源或存储实例已准备就绪;false表示输入校验、资源获取或恢复失败。
* 说明:初次使用须清零实例;复制目录和设备名,点表及units借用至Close,全部操作由调用方串行。
* 核心Init恢复成功后才置opened;失败关闭已打开的句柄,不把部分恢复实例交给业务使用。
*/
bool Example_Energy_Freeze_Open(ExampleEnergyFreeze *self, const char *parent,
const IEC60870_EnergyFreezeConfig_t *config, const char *device_name, const char *const *units)
{
char path[256], saved_parent[200], saved_name[128];
uint8_t header[ENERGY_STORE_HEADER], expected[ENERGY_STORE_HEADER] = {0};
IEC60870_EnergyFreezeConfig_t saved_config;
IEC60870_EnergyFreezeStore_t store;
HANDLE file;
LARGE_INTEGER size;
DWORD done = 0U;
bool created;
int n;
if (self == NULL || self->opened || parent == NULL || config == NULL || device_name == NULL ||
strlen(parent) >= sizeof(saved_parent) || strlen(device_name) >= sizeof(saved_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/energy.store", saved_parent);
if (n < 0 || (size_t)n >= sizeof(path)) { return false; }
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-ENERGY1", 14U);
Put32(expected + 16U, 64U); Put32(expected + 20U, 32U); Put32(expected + 24U, 256U);
Put32(expected + 28U, Crc(expected, 28U));
if (!GetFileSizeEx(file, &size)) { goto failed; }
if (size.QuadPart == 0) {
if (!created || !Write_At(file, 0U, expected, sizeof(expected)) || !FlushFileBuffers(file)) { goto failed; }
} else if (size.QuadPart > 2555248LL || !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_EnergyFreeze_Init(&self->core, &saved_config, &store) != IEC60870_ENERGY_FREEZE_OK) { goto failed; }
strcpy(self->parent, saved_parent); strcpy(self->device_name, saved_name);
self->units = units; self->opened = true;
return true;
failed:
CloseHandle(file); self->storage = NULL; self->core.initialized = false;
return false;
}
/**
* 功能:结束当前下载并删除其独立临时快照,清零长度;保留目录缓存及持久介质,允许重复关闭。
* 输入参数:self——调用方持有的模块实例。
* 输出参数:self——本次操作更新的实例或工作区。
* 返回值:无。
* 说明:无。
*/
void Example_Energy_Freeze_Read_Close(ExampleEnergyFreeze *self)
{
if (self == NULL) { return; }
if (self->read_file != NULL) { CloseHandle((HANDLE)self->read_file); }
self->read_file = NULL; self->read_size = 0U;
}
/**
* 功能:依次释放下载、目录缓存和持久文件句柄,令核心退出可用状态;energy.store内容保留。
* 输入参数:self——调用方持有的模块实例。
* 输出参数:self——本次操作更新的实例或工作区。
* 返回值:无。
* 说明:调用方先结束引用本实例的协议会话,避免关闭后仍访问快照。
*/
void Example_Energy_Freeze_Close(ExampleEnergyFreeze *self)
{
if (self == NULL) { return; }
Example_Energy_Freeze_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;
}
/**
* 功能:返回当前活动目录的缓存条目数;目录未打开或实例为空时返回0,不读取介质。
* 输入参数:self——调用方持有的模块实例。
* 输出参数:无独立输出参数。
* 返回值:当前目录可枚举的条目数;目录未打开时为0。
* 说明:无。
*/
size_t Example_Energy_Freeze_Directory_Count(const ExampleEnergyFreeze *self)
{
return self != NULL && self->directory_active ? self->entry_count : 0U;
}
/**
* 功能:按从0开始的索引复制活动目录条目;目录无效或索引越界返回false,保持entry原内容。
* 输入参数:self——调用方持有的模块实例;index——本次条目、点或逻辑槽的下标;entry——目录条目。
* 输出参数:entry——目录条目。
* 返回值:true表示目录条目已复制到entry;false表示实例、目录或索引无效。
* 说明:无。
*/
bool Example_Energy_Freeze_Directory_Get(const ExampleEnergyFreeze *self,
size_t index, ExampleEnergyFreezeEntry *entry)
{
if (self == NULL || !self->directory_active || entry == NULL || index >= self->entry_count) { return false; }
*entry = self->entries[index];
return true;
}
/**
* 功能:只结束目录枚举,保留条目及其XML缓存,使随后按名称下载仍取得已公布的版本。
* 输入参数:self——调用方持有的模块实例。
* 输出参数:self——本次操作更新的实例或工作区。
* 返回值:无。
* 说明:无。
*/
void Example_Energy_Freeze_Directory_Close(ExampleEnergyFreeze *self)
{
if (self != NULL) { self->directory_active = false; }
}
/**
* 功能:取得导出文件对应的目录时标。
* 输入参数:self——调用方持有的模块实例;kind——记录或导出文件种类;day——历史或冻结窗口日序;time——CP56日历时标回写位置。
* 输出参数:time——CP56日历时标回写位置。
* 返回值:true表示本次操作成功,false表示校验拒绝或处理失败。
* 说明:FRZ文件时间取窗口起点;FLOWREV取最新持久序号事件的occur,不取最大墙钟时刻。
* 无事件时使用可表示时间下界;读取或日历转换失败返回false。
*/
static bool File_Time(ExampleEnergyFreeze *self, IEC60870_EnergyFreezeFileKind_t kind,
uint32_t day, IEC60870_CP56Time2a_t *time)
{
uint64_t utc_ms;
if (kind == IEC60870_ENERGY_FREEZE_FILE_FRZ) {
return IEC60870_EnergyFreeze_Window_Start(day, self->core.config.day_start_minutes, &utc_ms) &&
Make_Time(utc_ms, time);
} else {
IEC60870_EnergyFreezeFlowReverse_t event;
size_t count = IEC60870_EnergyFreeze_FlowReverse_Count(&self->core);
if (count == 0U) { return Make_Time(IEC60870_ENERGY_FREEZE_UTC_MIN, time); }
return IEC60870_EnergyFreeze_Get_FlowReverse(&self->core, count - 1U, &event) == IEC60870_ENERGY_FREEZE_OK &&
Make_Time(event.occur_utc_ms, time);
}
}
/**
* 功能:日目录先验证SEAL,包括空窗;不能先凭数据不存在过滤,否则会掩盖已封存记录丢失。
* 输入参数:self——调用方持有的模块实例;name——文件名或显式长度的协议名称;length——本次数据或名称的有效字节数。
* 输出参数:self——本次操作更新的实例或工作区。
* 返回值:true表示完整目录快照已发布;false表示名称、记录校验或快照生成失败。
* 说明:无。
*/
bool Example_Energy_Freeze_Directory_Open(ExampleEnergyFreeze *self, const uint8_t *name, size_t length)
{
IEC60870_EnergyFreezeFileKind_t kind;
IEC60870_EnergyFreezeStatus_t status;
uint32_t day = 0U, last = 0U, offset = 0U;
HANDLE file;
if (self == NULL || !self->opened || self->directory_active ||
!IEC60870_EnergyFreeze_Get_Status(&self->core, &status) || status.faulted) { return false; }
if (Equal_Name(name, length, "HISTORY/FRZ")) { kind = IEC60870_ENERGY_FREEZE_FILE_FRZ; }
else if (Equal_Name(name, length, "HISTORY/FLOWREV") && self->core.config.flowrev_count != 0U) {
kind = IEC60870_ENERGY_FREEZE_FILE_FLOWREV;
} 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_ENERGY_FREEZE_FILE_FRZ) {
if (!status.sealed_valid || !status.retained_valid) { goto complete; }
last = status.sealed_day;
day = last >= 29U ? last - 29U : 0U;
if (day < status.retained_from) { day = status.retained_from; }
if (day > last) { goto complete; }
}
do {
ExampleEnergyFreezeEntry *entry;
if (kind == IEC60870_ENERGY_FREEZE_FILE_FRZ) {
IEC60870_EnergyFreezeSeal_t seal;
if (IEC60870_EnergyFreeze_Get_Seal(&self->core, day, &seal) != IEC60870_ENERGY_FREEZE_OK) { goto failed; }
if (seal.count == 0U) {
if (IEC60870_EnergyFreeze_Validate_Seal(&self->core, day) != IEC60870_ENERGY_FREEZE_OK) { goto failed; }
continue;
}
}
if (self->entry_count >= EXAMPLE_ENERGY_FREEZE_DIRECTORY_CAPACITY) { goto failed; }
entry = &self->entries[self->entry_count];
entry->offset = offset;
if (!IEC60870_EnergyFreezeFile_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; }
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;
}
/**
* 功能:缓存命中沿用已公布的XML;下载另建快照,不受后续召目录或底层轮转影响。
* 输入参数:self——调用方持有的模块实例;name——文件名或显式长度的协议名称;length——本次数据或名称的有效字节数;size——实际字节数回写位置。
* 输出参数:self——本次操作更新的实例或工作区;size——实际字节数回写位置。
* 返回值:true表示独立下载快照已打开并写回长度;false表示名称或快照准备失败。
* 说明:无。
*/
bool Example_Energy_Freeze_Read_Open(ExampleEnergyFreeze *self,
const uint8_t *name, size_t length, uint32_t *size)
{
IEC60870_EnergyFreezeStatus_t status;
IEC60870_EnergyFreezeFileKind_t kind = IEC60870_ENERGY_FREEZE_FILE_FLOWREV;
HANDLE file;
size_t i;
uint32_t day = 0U;
bool found = false;
if (self == NULL || !self->opened || self->read_file != NULL || size == NULL ||
!IEC60870_EnergyFreeze_Get_Status(&self->core, &status) || status.faulted) { return false; }
file = Temporary(self->parent);
if (file == INVALID_HANDLE_VALUE) { return false; }
for (i = 0U; i < self->entry_count; ++i) {
const ExampleEnergyFreezeEntry *entry = &self->entries[i];
if (self->directory_file != NULL && Equal_Name(name, length, entry->name)) {
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/FLOWREV/flowrev.xml") && self->core.config.flowrev_count != 0U) {
found = true;
} else if (status.sealed_valid && status.retained_valid) {
char expected[IEC60870_ENERGY_FREEZE_FILE_PATH_CAPACITY];
uint32_t first = status.sealed_day >= 29U ? status.sealed_day - 29U : 0U;
if (first < status.retained_from) { first = status.retained_from; }
for (day = first; day <= status.sealed_day; ++day) {
if (IEC60870_EnergyFreezeFile_Name(IEC60870_ENERGY_FREEZE_FILE_FRZ, day, expected, sizeof(expected)) &&
Equal_Name(name, length, expected)) {
kind = IEC60870_ENERGY_FREEZE_FILE_FRZ; 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;
}
/**
* 功能:从已打开的独立下载快照按偏移读取,范围必须完全位于read_size内,短读也返回false。
* 输入参数:self——调用方持有的模块实例;offset——从起点计算的字节偏移;buffer——调用方提供的数据缓冲;length——本次数据或名称的有效字节数。
* 输出参数:buffer——调用方提供的数据缓冲。
* 返回值:true表示指定范围的数据已完整读出;false表示范围非法、读取失败或短读。
* 说明:不依赖当前目录或核心记录;I/O失败可能已改写部分buffer,调用方不能使用失败片段。
*/
bool Example_Energy_Freeze_Read(ExampleEnergyFreeze *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;
}