68 lines
4.4 KiB
C
68 lines
4.4 KiB
C
/*
|
||
* 附录B电能量XML编码:FRZ读取已封存窗口,FLOWREV读取已提交的反转事件。
|
||
* 本模块只负责同步编码,不创建文件、不管理下载会话;存储和输出均由调用方提供。
|
||
* 输出在最终校验通过前都是候选内容,失败时调用方须丢弃整份候选文件。
|
||
*/
|
||
#ifndef IEC60870_ENERGY_FREEZE_FILE_H
|
||
#define IEC60870_ENERGY_FREEZE_FILE_H
|
||
|
||
#include "IEC60870_EnergyFreeze.h"
|
||
|
||
#ifdef __cplusplus
|
||
extern "C" {
|
||
#endif
|
||
|
||
/* 路径缓冲容量含结尾NUL;属性上限按UTF-8字节计数,不含NUL。 */
|
||
#define IEC60870_ENERGY_FREEZE_FILE_PATH_CAPACITY 48U
|
||
#define IEC60870_ENERGY_FREEZE_FILE_ATTRIBUTE_MAX 255U
|
||
|
||
typedef enum {
|
||
IEC60870_ENERGY_FREEZE_FILE_FRZ = 1,
|
||
IEC60870_ENERGY_FREEZE_FILE_FLOWREV = 2
|
||
} IEC60870_EnergyFreezeFileKind_t;
|
||
|
||
/* 字符串及数组只在Write期间借用,须保持有效且不变;内容须符合UTF-8/XML属性规则。 */
|
||
typedef struct {
|
||
const char *device_name; /* 两类文件都需要;由编码器转义,不应预先转义。 */
|
||
const char *const *units; /* FRZ按point_count逐点配置;DAY沿用同索引单位,FLOWREV不使用。 */
|
||
} IEC60870_EnergyFreezeFileConfig_t;
|
||
|
||
/* 同步接收片段:true表示本片段length字节全部接收,false立即中止编码。
|
||
* bytes仅在回调内有效,片段不含结尾NUL,也不保证按XML节点或UTF-8字符分界。
|
||
* 不得重入或修改核心、点表和配置;已接收片段在后续校验失败时不会自动撤回。 */
|
||
typedef bool (*IEC60870_EnergyFreezeFileWriteFn)(void *context,
|
||
const uint8_t *bytes, size_t length);
|
||
|
||
/**
|
||
* 功能:生成相对路径,成功才改写name;capacity含结尾NUL,容量不足或类别/日期无效则失败。
|
||
* 输入参数:kind——记录或文件类别;day——相对1970-01-01的本地日序;capacity——缓冲可用容量。
|
||
* 输出参数:name——成功生成的NUL结尾相对文件名;失败不变。
|
||
* 返回值:true表示文件名已完整生成;false表示参数非法或容量不足,输出不变。
|
||
* 说明:FRZ的day为Window_Day返回的窗口起始日序,路径为HISTORY/FRZ/frzYYYYMMDD.xml。 FLOWREV忽略day,
|
||
* 路径固定为HISTORY/FLOWREV/flowrev.xml。 此函数仅格式化名称,不检查核心中是否存在可导出的记录。
|
||
*/
|
||
bool IEC60870_EnergyFreezeFile_Name(IEC60870_EnergyFreezeFileKind_t kind,
|
||
uint32_t day, char *name, size_t capacity);
|
||
|
||
/**
|
||
* 功能:同步生成XML。
|
||
* 输入参数:freeze——电能冻结核心实例;kind——记录或文件类别;day——相对1970-01-01的本地日序;config——配置及调用期间借用的元数据;write——同步接收输出片段的回调;
|
||
* context——传给输出回调的调用方上下文。
|
||
* 输出参数:freeze——复用读取工作区及完整性校验可能锁存的故障状态;size——仅完整成功时写入文件字节数,不含NUL;允许NULL的入口不强制输出。
|
||
* 返回值:true表示完整文件已输出;false表示参数、读取校验或输出回调失败,候选内容不可发布。
|
||
* 说明:freeze须已初始化且未故障;整个调用须串行独占核心及其存储、点表和配置。 FRZ仅接受最近30个已封存窗口中实际有数据的day,缺窗不向更早日期补足30份。
|
||
* 读取SEAL后单遍读取96节及DAY共97个位置,同时核验位图、正文摘要并输出同一份快照; 缺节保持缺失,空封存仍需验证完整性,但不生成文件。各点单位应区分有功与无功电能。
|
||
* FLOWREV忽略day,要求启用事件点表;按持久序号排列,单条内按配置索引输出有效DI。 num为有效DI数量而非事件数,允许为零;品质非零或数值非有限的点不导出。 成功返回true,
|
||
* size非NULL时写入XML总字节数(不含NUL);失败保持size原值, 但回调可能已经收到部分XML,调用方必须丢弃候选内容,成功后再发布稳定下载快照。
|
||
* 存储/封存完整性错误会锁存核心faulted;参数错误或输出回调失败本身不锁存故障。
|
||
*/
|
||
bool IEC60870_EnergyFreezeFile_Write(IEC60870_EnergyFreeze_t *freeze,
|
||
IEC60870_EnergyFreezeFileKind_t kind, uint32_t day,
|
||
const IEC60870_EnergyFreezeFileConfig_t *config,
|
||
IEC60870_EnergyFreezeFileWriteFn write, void *context, uint32_t *size);
|
||
|
||
#ifdef __cplusplus
|
||
}
|
||
#endif
|
||
#endif /* IEC60870_ENERGY_FREEZE_FILE_H */
|