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

570 lines
28 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.
/*
* 模块功能:将附录 C 日志核心接到 Windows 独占文件与不可变 XML 快照。
* 持久布局:32 字节文件头,随后 1024 个逻辑槽,每槽两份 32 字节头加载荷。
* 失败语义:三次同步分别隔离旧标记失效、候选完整落盘及最终发布;返回失败
* 不证明介质没有改变,核心故障后须关闭重开恢复,不能盲目再次追加。
*/
#include "iec104_example_user_log.h"
#include <stdio.h>
#include <string.h>
#include <windows.h>
/* 文件头:0..11 为布局标识,12..15 保留为零,16 为槽数,20 为最大载荷,
* 24 为单 bank 跨度,28 为前 28 字节的 CRC;除标识外各字段均为小端 uint32。
* bank 头:0 为四字节标识,4 为实际载荷长度,8 为 uint64 本槽提交代次,
* 16 为载荷 CRC,20 为前 20 字节 CRC,24 为提交标记,28 保留为零。
* 标记独立于头 CRC,允许先清零、最后写入;32 起才是核心序列化记录。
* bank 固定预留最大载荷,读取可包含旧尾部;载荷校验只使用实际长度,旧尾部不属于新记录。 */
#define STORE_HEADER_SIZE 32U
#define BANK_HEADER_SIZE 32U
#define BANK_SIZE (BANK_HEADER_SIZE + IEC60870_USER_LOG_WIRE_MAX)
#define STORE_MAX_SIZE (STORE_HEADER_SIZE + IEC60870_USER_LOG_CAPACITY * 2U * BANK_SIZE)
#define BANK_COMMITTED 0x54494d43UL
/* 仅测试构建在真实同步完成后返回失败,模拟持久化结果尚未交回的中断。
* 钩子不替换文件读写,也不代表供电切断或介质缓存失效;生产路径始终继续。 */
#ifdef IEC104_EXAMPLE_USER_LOG_TEST
/**
* 功能:在真实持久操作完成后提供测试中断判定。
* 输入参数:无。
* 输出参数:无输出参数;测试实现更新故障注入计数。
* 返回值:true允许继续,false在指定阶段模拟中断。
* 说明:仅测试宏启用时链接;真实写入已发生,返回false不撤销已同步内容。
*/
extern bool Example_User_Log_Test_Continue(void);
#else
#define Example_User_Log_Test_Continue() true
#endif
/**
* 功能:从字节缓冲解码32位小端整数。
* 输入参数:bytes——字节数据缓冲。
* 输出参数:无独立输出参数。
* 返回值:解码后的32位无符号整数。
* 说明:格式使用显式小端,不保存宿主结构体或依赖指针对齐。
*/
static uint32_t Get32(const uint8_t *bytes)
{
return (uint32_t)bytes[0] | ((uint32_t)bytes[1] << 8) |
((uint32_t)bytes[2] << 16) | ((uint32_t)bytes[3] << 24);
}
/**
* 功能:将32位整数写成小端字节序。
* 输入参数:bytes——字节数据缓冲;value——本次待处理的数值。
* 输出参数:bytes——字节数据缓冲。
* 返回值:无。
* 说明:调用方已保证四字节可写空间;截取各八位时不使用未对齐的整数指针。
*/
static void Put32(uint8_t *bytes, uint32_t value)
{
unsigned i;
for (i = 0U; i < 4U; ++i) { bytes[i] = (uint8_t)(value >> (8U * i)); }
}
/**
* 功能:从字节缓冲解码64位小端整数。
* 输入参数:bytes——字节数据缓冲。
* 输出参数:无独立输出参数。
* 返回值:解码后的64位无符号整数。
* 说明:先扩展高半字再移位,确保 32 位工具链也保留完整提交代次。
*/
static uint64_t Get64(const uint8_t *bytes)
{
return Get32(bytes) | ((uint64_t)Get32(bytes + 4U) << 32);
}
/**
* 功能:将64位整数写成小端字节序。
* 输入参数:bytes——字节数据缓冲;value——本次待处理的数值。
* 输出参数:bytes——字节数据缓冲。
* 返回值:无。
* 说明:与 Get64 对称,不借用 Windows 或编译器的结构体整数布局。
*/
static void Put64(uint8_t *bytes, uint64_t value)
{
Put32(bytes, (uint32_t)value); Put32(bytes + 4U, (uint32_t)(value >> 32));
}
/**
* 功能:计算当前字节段的完整CRC-32校验值。
* 输入参数:bytes——字节数据缓冲;length——本次数据或名称的有效字节数。
* 输出参数:无独立输出参数。
* 返回值:完成初值处理和末尾取反后的CRC-32值。
* 说明:文件头、bank 头及载荷分别校验,核心另行校验日志业务字段及序号连续性。
*/
static uint32_t Crc(const uint8_t *bytes, size_t length)
{
uint32_t crc = 0xffffffffUL;
size_t i;
unsigned bit;
for (i = 0U; i < length; ++i) {
crc ^= bytes[i];
for (bit = 0U; bit < 8U; ++bit) {
crc = (crc >> 1) ^ ((crc & 1U) != 0U ? 0xedb88320UL : 0U);
}
}
return ~crc;
}
/**
* 功能:计算逻辑槽中指定副本的文件字节偏移。
* 输入参数:index——本次条目、点或逻辑槽的下标;bank——双副本编号0或1。
* 输出参数:无独立输出参数。
* 返回值:指定副本相对文件起点的字节偏移。
* 说明:index 和 bank 已由存储回调检查;固定跨度不随记录文本长度改变。
*/
static uint32_t Bank_Offset(uint32_t index, unsigned bank)
{
return STORE_HEADER_SIZE + (index * 2U + bank) * BANK_SIZE;
}
/**
* 功能:将文件读写位置移动到指定绝对偏移。
* 输入参数:file——已打开的同步文件句柄;offset——从起点计算的字节偏移。
* 输出参数:无独立输出参数。
* 返回值:true表示本次操作成功,false表示校验拒绝或处理失败。
* 说明:每次访问显式定位,允许乱序读取;同一 HANDLE 的文件指针要求所有调用串行。
*/
static bool Seek(HANDLE file, uint32_t offset)
{
LARGE_INTEGER position;
position.QuadPart = offset;
return SetFilePointerEx(file, position, 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——调用方持有的模块实例;index——本次条目、点或逻辑槽的下标;bank——双副本编号0或1;generation——持久提交代次回写位置;size——实际字节数回写位置。
* 输出参数:generation——持久提交代次回写位置;size——实际字节数回写位置。
* 返回值:1表示有效提交,0表示未提交,-1表示损坏,-2表示系统读取错误。
* 说明:1=有效提交,0=未提交,-1=损坏,-2=系统读取错误。
* 标记可靠清零后的残缺候选允许忽略;带提交标记的截断或 CRC 错误不能当空槽。
* generation/size 只有返回 1 时可用于选副本;内容暂存在本对象对应 bank 工作区。
* 没有外部提交账本时,整个尾部消失或标记被清零可能与未提交不可区分。
*/
static int Read_Bank(ExampleUserLog *self, uint32_t index, unsigned bank,
uint64_t *generation, size_t *size)
{
uint8_t *bytes = self->banks[bank];
DWORD done = 0U;
memset(bytes, 0, BANK_SIZE);
if (!Seek((HANDLE)self->storage, Bank_Offset(index, bank)) ||
!ReadFile((HANDLE)self->storage, bytes, BANK_SIZE, &done, NULL)) { return -2; }
if (done == 0U) { return 0; }
if (done >= 28U && Get32(bytes + 24U) == 0U) { return 0; }
if (done < BANK_HEADER_SIZE || Get32(bytes + 24U) != BANK_COMMITTED ||
memcmp(bytes, "USL1", 4U) != 0 || Get32(bytes + 20U) != Crc(bytes, 20U) ||
Get32(bytes + 28U) != 0U) { return -1; }
*size = Get32(bytes + 4U);
*generation = Get64(bytes + 8U);
if (*generation == 0U || *size == 0U || *size > IEC60870_USER_LOG_WIRE_MAX ||
done < BANK_HEADER_SIZE + *size ||
Get32(bytes + 16U) != Crc(bytes + BANK_HEADER_SIZE, *size)) { return -1; }
return 1;
}
/**
* 功能:读取持久逻辑槽并选择可恢复的副本。
* 输入参数:context——调用方注册的回调上下文;index——本次条目、点或逻辑槽的下标;bytes——字节数据缓冲;capacity——目标缓冲容量;size——实际字节数回写位置。
* 输出参数:bytes——字节数据缓冲;size——实际字节数回写位置。
* 返回值:OK表示已读出可靠记录,EMPTY表示两副本均无提交,ERROR表示读取、校验或输出容量不满足要求。
* 说明:两份均未提交才是 EMPTY;任一副本损坏或读取失败时整槽报错。
* 同代次必须长度与内容一致,否则不能任意择一;可靠提交按最大代次选取。
* 本槽代次不代替核心记录的全局序号,核心仍检查全环连续性;零标记与 EOF
* 仍按未提交处理,无法据此证明历史从未存在。只在成功时复制载荷并写回 size。
*/
static IEC60870_UserLogResult_t Store_Read(void *context, uint32_t index,
uint8_t *bytes, size_t capacity, size_t *size)
{
ExampleUserLog *self = context;
uint64_t generation[2] = {0U, 0U};
size_t sizes[2] = {0U, 0U};
int first, second;
unsigned winner;
if (index >= IEC60870_USER_LOG_CAPACITY || bytes == NULL || size == NULL) {
return IEC60870_USER_LOG_ERROR;
}
first = Read_Bank(self, index, 0U, &generation[0], &sizes[0]);
second = Read_Bank(self, index, 1U, &generation[1], &sizes[1]);
if (first < 0 || second < 0) { return IEC60870_USER_LOG_ERROR; }
if (first == 0 && second == 0) { return IEC60870_USER_LOG_EMPTY; }
if (first == 1 && second == 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_USER_LOG_ERROR; }
winner = second == 1 && (first != 1 || generation[1] > generation[0]) ? 1U : 0U;
if (sizes[winner] > capacity) { return IEC60870_USER_LOG_ERROR; }
memcpy(bytes, self->banks[winner] + BANK_HEADER_SIZE, sizes[winner]);
*size = sizes[winner];
return IEC60870_USER_LOG_OK;
}
/**
* 功能:通过双副本和持久同步提交一个逻辑槽。
* 输入参数:context——调用方注册的回调上下文;index——本次条目、点或逻辑槽的下标;bytes——字节数据缓冲;size——本次数据的字节数。
* 输出参数:无独立输出参数。
* 返回值:true表示本次操作成功,false表示校验拒绝或处理失败。
* 说明:原子性只针对一个逻辑槽;不覆盖当前最新有效副本,代次号不允许回绕。
* bytes 只在调用期间借用;未提交或较旧的副本作为候选,成功代次递增。
* 任一副本损坏、读取失败或同代次内容冲突时拒绝写入,不覆盖损坏证据。
* 第一次 Flush 隔离旧标记,第二次 Flush 固定完整候选,第三次 Flush 发布;
* 任一步失败均交由核心故障闭锁。第三次同步已完成却返回失败时,新版本可能
* 已经可靠存在,必须重开确认。实际失电保证仍依赖系统与介质兑现同步契约。
*/
static bool Store_Commit(void *context, uint32_t index, const uint8_t *bytes, size_t size)
{
ExampleUserLog *self = context;
uint64_t generation[2] = {0U, 0U}, next;
size_t sizes[2] = {0U, 0U};
int first, second;
unsigned target;
uint32_t offset;
uint8_t marker[4] = {0U, 0U, 0U, 0U};
uint8_t *candidate;
HANDLE file = (HANDLE)self->storage;
if (index >= IEC60870_USER_LOG_CAPACITY || bytes == NULL || size == 0U ||
size > IEC60870_USER_LOG_WIRE_MAX) { return false; }
first = Read_Bank(self, index, 0U, &generation[0], &sizes[0]);
second = Read_Bank(self, index, 1U, &generation[1], &sizes[1]);
if (first < 0 || second < 0) { return false; }
if (first == 1 && second == 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 = first == 1 && (second != 1 || generation[0] >= generation[1]) ? 1U : 0U;
next = first == 1 ? generation[0] : 0U;
if (second == 1 && generation[1] > next) { next = generation[1]; }
if (next == UINT64_MAX) { return false; }
++next;
offset = Bank_Offset(index, target);
/* 先持久清除目标标记,后续候选即使只写了一部分也不会被恢复成已提交。 */
if (!Write_At(file, offset + 24U, marker, sizeof(marker)) ||
!FlushFileBuffers(file) || !Example_User_Log_Test_Continue()) { return false; }
candidate = self->banks[target];
memset(candidate, 0, BANK_HEADER_SIZE);
memcpy(candidate, "USL1", 4U);
Put32(candidate + 4U, (uint32_t)size); Put64(candidate + 8U, next);
Put32(candidate + 16U, Crc(bytes, size)); Put32(candidate + 20U, Crc(candidate, 20U));
memcpy(candidate + BANK_HEADER_SIZE, bytes, size);
/* 候选内容及校验先整体同步,提交标记仍为零,旧版本始终可选。 */
if (!Write_At(file, offset, candidate, BANK_HEADER_SIZE + size) ||
!FlushFileBuffers(file) || !Example_User_Log_Test_Continue()) { return false; }
/* 最后仅写四字节提交标记;此前任何未发布候选都不能替代可靠旧副本。 */
Put32(marker, BANK_COMMITTED);
return Write_At(file, offset + 24U, marker, sizeof(marker)) &&
FlushFileBuffers(file) && Example_User_Log_Test_Continue();
}
/**
* 功能:参数复制前验证设备标识,失败不创建持久文件;XML 转义由编码器负责。
* 输入参数:device_id——日志导出的设备标识。
* 输出参数:无独立输出参数。
* 返回值:设备标识满足导出约束时返回true,否则返回false。
* 说明:无。
*/
static bool Device_Id_Valid(const char *device_id)
{
size_t i;
if (device_id == NULL || device_id[0] == '\0') { return false; }
for (i = 0U; i <= IEC60870_USER_LOG_DEVICE_ID_MAX; ++i) {
unsigned char byte = (unsigned char)device_id[i];
if (byte == 0U) { return true; }
if (byte < 0x20U || byte > 0x7eU) { return false; }
}
return false;
}
/**
* 功能:文件头一致后才安装回调并扫描核心;全部恢复成功才对外设置 opened。
* 输入参数:self——调用方持有的模块实例;parent——已存在的宿主父目录;device_id——日志导出的设备标识。
* 输出参数:self——本次操作更新的实例或工作区。
* 返回值:true表示请求的资源或存储实例已准备就绪;false表示输入校验、资源获取或恢复失败。
* 说明:失败关闭本次取得的句柄,但不删除新建失败文件,也不修改既有损坏档案。
*/
bool Example_User_Log_Open(ExampleUserLog *self, const char *parent, const char *device_id)
{
char path[256], saved_parent[200], saved_id[IEC60870_USER_LOG_DEVICE_ID_MAX + 1U];
uint8_t header[STORE_HEADER_SIZE], expected[STORE_HEADER_SIZE] = {0};
IEC60870_UserLogStore_t store;
LARGE_INTEGER file_size;
HANDLE file;
DWORD done = 0U, attributes;
bool created;
int length;
if (self == NULL || self->opened || self->storage != NULL || self->directory_file != NULL ||
self->read_file != NULL || parent == NULL || parent[0] == '\0' ||
strlen(parent) >= sizeof(self->parent) || !Device_Id_Valid(device_id)) { return false; }
attributes = GetFileAttributesA(parent);
if (attributes == INVALID_FILE_ATTRIBUTES || (attributes & FILE_ATTRIBUTE_DIRECTORY) == 0U) { return false; }
/* 允许重新打开时参数借用 self 的字符串,先复制再清零控制对象。 */
strcpy(saved_parent, parent); strcpy(saved_id, device_id);
memset(self, 0, sizeof(*self));
length = snprintf(path, sizeof(path), "%s/ulog.store", saved_parent);
if (length < 0 || (size_t)length >= sizeof(path)) { return false; }
/* 共享模式零确保其他实例不能并发读写,不影响同目录独立的 history.store。 */
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-ULOG1", 12U);
Put32(expected + 16U, IEC60870_USER_LOG_CAPACITY);
Put32(expected + 20U, IEC60870_USER_LOG_WIRE_MAX);
Put32(expected + 24U, BANK_SIZE);
Put32(expected + 28U, Crc(expected, 28U));
if (!GetFileSizeEx(file, &file_size) || file_size.QuadPart > STORE_MAX_SIZE) { goto failed; }
if (file_size.QuadPart == 0) {
/* 只有本次新建的零长度文件可初始化;已有空文件属于异常,不自动格式化。 */
if (!created || !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_UserLog_Init(&self->core, &store) != IEC60870_USER_LOG_OK) { goto failed; }
strcpy(self->parent, saved_parent); strcpy(self->device_id, saved_id);
self->opened = true;
return true;
failed:
CloseHandle(file); self->storage = NULL; self->core.initialized = false;
return false;
}
/**
* 功能:创建关闭时自动删除的独占临时快照文件。
* 输入参数:parent——已存在的宿主父目录。
* 输出参数:无独立输出参数。
* 返回值:成功返回临时文件句柄,失败返回INVALID_HANDLE_VALUE。
* 说明:临时快照也使用独占句柄;最后关闭时删除,失败候选不成为可读文件。
*/
static HANDLE Temporary(const char *parent)
{
char path[MAX_PATH];
HANDLE file;
if (!GetTempFileNameA(parent, "iul", 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 每片须完整写入候选,短写立即使整次导出失败;这不是日志持久提交,
* 无需逐片 Flush。临时文件内容在成功交给目录或读快照前只属于生成者。
*/
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。
* 说明:线上名称按显式长度比较,不要求 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;
}
/**
* 功能:取得导出文件对应的目录时标。
* 输入参数:self——调用方持有的模块实例;time——CP56日历时标回写位置。
* 输出参数:time——CP56日历时标回写位置。
* 返回值:true表示本次操作成功,false表示校验拒绝或处理失败。
* 说明:空日志也可下载,目录使用固定空库时间而不伪造日志;非空取最新提交而非最大墙钟。
*/
static bool File_Time(ExampleUserLog *self, IEC60870_CP56Time2a_t *time)
{
uint64_t utc_ms = IEC60870_USER_LOG_UTC_MIN;
if (IEC60870_UserLog_Count(&self->core) != 0U &&
!IEC60870_UserLog_Latest_Time(&self->core, &utc_ms)) { return false; }
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 && time->time.year <= 2099U;
}
/**
* 功能:先在局部候选中同时准备字节、大小与时间,完整成功后才发布清单。
* 输入参数:self——调用方持有的模块实例;name——文件名或显式长度的协议名称;length——本次数据或名称的有效字节数。
* 输出参数:self——本次操作更新的实例或工作区。
* 返回值:true表示完整目录快照已发布;false表示名称、记录校验或快照生成失败。
* 说明:后续追加不会改写此文件;即使最新日志轮转覆盖,目录承诺的版本仍可下载。
*/
bool Example_User_Log_Directory_Open(ExampleUserLog *self, const uint8_t *name, size_t length)
{
HANDLE file;
ExampleUserLogEntry entry;
if (self == NULL || !self->opened || self->core.faulted || self->directory_active ||
!Equal_Name(name, length, "HISTORY/ULOG")) { return false; }
/* 新枚举使旧缓存失效,但已打开的下载有独立副本,仍然可以完成。 */
if (self->directory_file != NULL) { CloseHandle((HANDLE)self->directory_file); }
self->directory_file = NULL;
memset(&self->entry, 0, sizeof(self->entry));
file = Temporary(self->parent);
if (file == INVALID_HANDLE_VALUE) { return false; }
memset(&entry, 0, sizeof(entry));
if (!File_Time(self, &entry.time) ||
!IEC60870_UserLogFile_Write(&self->core, self->device_id, Sink, file, &entry.size)) {
CloseHandle(file); return false;
}
strcpy(entry.name, IEC60870_USER_LOG_FILE_NAME);
self->entry = entry; self->directory_file = file; self->directory_active = true;
return true;
}
/**
* 功能:返回协议枚举的可见项数;返回零不意味着保留的 XML 缓存已销毁。
* 输入参数:self——调用方持有的模块实例。
* 输出参数:无独立输出参数。
* 返回值:当前目录可枚举的条目数;目录未打开时为0。
* 说明:无。
*/
size_t Example_User_Log_Directory_Count(const ExampleUserLog *self)
{
return self != NULL && self->directory_active ? 1U : 0U;
}
/**
* 功能:元数据按值交给调用者,名称不借用临时栈;失败不会留下半份目录项。
* 输入参数:self——调用方持有的模块实例;index——本次条目、点或逻辑槽的下标;entry——目录条目。
* 输出参数:entry——目录条目。
* 返回值:true表示目录条目已复制到entry;false表示实例、目录或索引无效。
* 说明:无。
*/
bool Example_User_Log_Directory_Get(const ExampleUserLog *self, size_t index, ExampleUserLogEntry *entry)
{
if (self == NULL || !self->directory_active || index != 0U || entry == NULL) { return false; }
*entry = self->entry;
return true;
}
/**
* 功能:协议 CLOSE_DIRECTORY 只结束枚举,缓存寿命延长到下一次合法枚举或整体 Close。
* 输入参数:self——调用方持有的模块实例。
* 输出参数:self——本次操作更新的实例或工作区。
* 返回值:无。
* 说明:无。
*/
void Example_User_Log_Directory_Close(ExampleUserLog *self)
{
if (self != NULL) { self->directory_active = false; }
}
/**
* 功能:目录缓存与下载之间按块复制;不向全量日志或完整 XML 分配 RAM 缓冲。
* 输入参数:source——源快照文件句柄;destination——目标快照文件句柄;size——本次数据的字节数。
* 输出参数:无独立输出参数。
* 返回值:true表示本次操作成功,false表示校验拒绝或处理失败。
* 说明:无。
*/
static bool Copy_Snapshot(HANDLE source, HANDLE destination, uint32_t size)
{
uint8_t bytes[256];
uint32_t position = 0U;
if (!Seek(source, 0U)) { return false; }
while (position < size) {
DWORD done = 0U;
DWORD amount = size - position < sizeof(bytes) ? size - position : sizeof(bytes);
if (!ReadFile(source, bytes, amount, &done, NULL) || done != amount ||
!Sink(destination, bytes, amount)) { return false; }
position += amount;
}
return true;
}
/**
* 功能:新下载始终取得自己的文件句柄;命中旧目录时复制已公布版本,不重新编码。
* 输入参数:self——调用方持有的模块实例;name——文件名或显式长度的协议名称;length——本次数据或名称的有效字节数;size——实际字节数回写位置。
* 输出参数:self——本次操作更新的实例或工作区;size——实际字节数回写位置。
* 返回值:true表示独立下载快照已打开并写回长度;false表示名称或快照准备失败。
* 说明:复制或导出失败只删除本次候选,size 和现有目录缓存不变,不暴露部分 XML。
*/
bool Example_User_Log_Read_Open(ExampleUserLog *self, const uint8_t *name, size_t length, uint32_t *size)
{
HANDLE file;
uint32_t candidate_size;
if (self == NULL || !self->opened || self->core.faulted || self->read_file != NULL || size == NULL ||
!Equal_Name(name, length, IEC60870_USER_LOG_FILE_NAME)) { return false; }
file = Temporary(self->parent);
if (file == INVALID_HANDLE_VALUE) { return false; }
if (self->directory_file != NULL) {
candidate_size = self->entry.size;
if (!Copy_Snapshot((HANDLE)self->directory_file, file, candidate_size)) { goto failed; }
} else if (!IEC60870_UserLogFile_Write(&self->core, self->device_id, Sink, file, &candidate_size)) {
goto failed;
}
self->read_file = file; self->read_size = candidate_size; *size = candidate_size;
return true;
failed:
CloseHandle(file);
return false;
}
/**
* 功能:先用减法验证整个范围,避免 offset+length 溢出;同一偏移可重复读取。
* 输入参数:self——调用方持有的模块实例;offset——从起点计算的字节偏移;buffer——调用方提供的数据缓冲;length——本次数据或名称的有效字节数。
* 输出参数:buffer——调用方提供的数据缓冲。
* 返回值:true表示指定范围的数据已完整读出;false表示范围非法、读取失败或短读。
* 说明:下载仅依赖冻结文件,新增日志或重新召目录不影响它,不维护连续读取游标。
*/
bool Example_User_Log_Read(ExampleUserLog *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; }
if (length == 0U) { return true; }
return Seek((HANDLE)self->read_file, offset) &&
ReadFile((HANDLE)self->read_file, buffer, (DWORD)length, &done, NULL) && done == length;
}
/**
* 功能:关闭下载句柄即删除该临时副本;不释放目录缓存或持久文件锁,可重复调用。
* 输入参数:self——调用方持有的模块实例。
* 输出参数:self——本次操作更新的实例或工作区。
* 返回值:无。
* 说明:无。
*/
void Example_User_Log_Read_Close(ExampleUserLog *self)
{
if (self == NULL) { return; }
if (self->read_file != NULL) { CloseHandle((HANDLE)self->read_file); }
self->read_file = NULL; self->read_size = 0U;
}
/**
* 功能:所有协议目录/读回调先结束;关闭临时句柄只删快照,不删 ulog.store。
* 输入参数:self——调用方持有的模块实例。
* 输出参数:self——本次操作更新的实例或工作区。
* 返回值:无。
* 说明:无。
*/
void Example_User_Log_Close(ExampleUserLog *self)
{
if (self == NULL) { return; }
Example_User_Log_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->directory_active = false; self->opened = false; self->core.initialized = false;
memset(&self->entry, 0, sizeof(self->entry));
}