/* * 模块功能:将附录 C 日志核心接到 Windows 独占文件与不可变 XML 快照。 * 持久布局:32 字节文件头,随后 1024 个逻辑槽,每槽两份 32 字节头加载荷。 * 失败语义:三次同步分别隔离旧标记失效、候选完整落盘及最终发布;返回失败 * 不证明介质没有改变,核心故障后须关闭重开恢复,不能盲目再次追加。 */ #include "iec104_example_user_log.h" #include #include #include /* 文件头: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)); }