添加遥控、参数装载、文件传输等业务
This commit is contained in:
@@ -0,0 +1,569 @@
|
||||
/*
|
||||
* 模块功能:将附录 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));
|
||||
}
|
||||
Reference in New Issue
Block a user