feat(iec104): 在模拟器跑通共享协议核心与标准DTU点表

引入成熟 IEC 60870-5-104 子站的只读子集(App/protocol/iec60870,28 个源文件
按原字节复制,UPSTREAM.sha256 记录来源,兼容补丁保留全部断言与容量),在其上
装配单属主共享核心(Start/Poll/Stop/Get_Status),并把标准 DTU 演示点表全量
接入为唯一真源。

- iec104_core:threadless 推进,poll 零等待,通知/交互/COV 扫描全部有界;
  生命周期区分失败启动待重试、重复启动拒绝、断线保固化 RAM。
- iec104_dtu_table / iec104_source:标准 DTU 全点表注册,无数据源的点读 0,
  遥控只做模拟状态可读回,不触碰实际出口。
- iec104_sim:仅窗口与独立服务模式起真实 TCP,无头黄金模式保持确定性假统计。
- test/host/iec104_dtu:独立真实 TCP 11 项、传输层 10 项、生命周期与借用负例。

验证:lvgl_sim 真实 TCP 11/11、传输 10/10,UI 像素回归未回退;AC5 单 TU
编译 0 错误 0 诊断。板端尚未切换:完整库闭包 RAM 超 92% 门禁净增预算 25730B,
结论为停止转实施,记录在 IEC104_MCU最小可行性验证.md。旧实现与 board 服务
保持原样,未提交 MDK 工程改动,未烧板。
This commit is contained in:
2026-11-17 20:48:00 +08:00
parent f84855a559
commit 2e9272cc8a
117 changed files with 54273 additions and 10 deletions
@@ -0,0 +1,461 @@
/*
* ASDU层仅处理公共头、对象布局、容量和分派。
* 对象编码调用基类函数表;对象解码按Type ID调用独立类型解析器。
* 所有外部可见写入都在字段、布局和容量验证完成后提交,失败不留下半条报文。
*/
#include "IEC60870_Asdu.h"
#include "IEC60870_InformationObjects_Internal.h"
#include <string.h>
/**
* 功能:计算当前配置的ASDU公共头字节数。
* 输入参数:parameters——已通过IEC60870_AppLayerParameters_Valid检查的非空参数。
* 输出参数:无。
* 返回值:2+sizeOfCOT+sizeOfCA,即4、5或6字节。
* 说明:固定的2字节是Type ID和VSQ;OA已包含在2字节COT中,不能再次累加。
*/
static uint16_t Header_Size(const IEC60870_AppLayerParameters_t *parameters)
{
return (uint16_t)(2 + parameters->sizeOfCOT + parameters->sizeOfCA);
}
/**
* 功能:检查信息对象区的精确长度、数量、SQ约束及连续地址上限。
* 输入参数:info——非空公共头视图,参数和对象原文在使用期间必须有效且不变。
* type——与info->type_id匹配的非空只读类型描述。
* 输出参数:无。
* 返回值:1表示对象区布局合法;0表示参数、数量、长度或隐含地址范围非法。
* 说明:先检查长度,再读取首IOA;这里只验证布局,不检查值、品质或时标。
*/
static int Layout_Valid(const IEC60870_AsduInfo_t *info,
const IEC60870_InformationObjectVTable *type)
{
uint16_t expected;
if (!IEC60870_AppLayerParameters_Valid(info->parameters) ||
info->information_objects == NULL || info->object_count == 0U ||
info->object_count > IEC60870_ASDU_MAX_OBJECTS || info->is_sequence > 1U ||
(info->is_sequence && !type->supports_sequence) ||
(type->single_object && info->object_count != 1U)) {
return 0;
}
/* 设N为数量、D为值载荷长度、L为IOA宽度:SQ=0占N*(L+D),SQ=1占L+N*D。
* 精确相等同时拒绝截短对象和额外尾字节;这里不计ASDU公共头。 */
expected = (uint16_t)(info->object_count * type->payload_size +
(info->is_sequence ? info->parameters->sizeOfIOA :
info->object_count * info->parameters->sizeOfIOA));
if (type->get_payload_size_from_buffer != NULL) {
uint16_t payload_size;
uint16_t address_size = (uint16_t)info->parameters->sizeOfIOA;
/* 当前变长类型是单对象文件段;先保护段头读取,再依据LOS计算实际长度。 */
if (info->object_count != 1U || info->is_sequence ||
info->information_objects_len < address_size) { return 0; }
payload_size = type->get_payload_size_from_buffer(info->information_objects + address_size,
(uint16_t)(info->information_objects_len - address_size));
if (payload_size == 0U) { return 0; }
expected = (uint16_t)(address_size + payload_size);
}
if (expected != info->information_objects_len ||
expected > info->parameters->maxSizeOfASDU - Header_Size(info->parameters)) {
return 0;
}
/* SQ首地址本身可表示,但末地址首IOA+N-1也必须能由同样的IOA宽度表示。 */
return !info->is_sequence ||
IEC60870_Object_Read_LE(info->information_objects, (unsigned int)info->parameters->sizeOfIOA) <=
IEC60870_Object_Max_IOA(info->parameters) - (info->object_count - 1U);
}
/**
* 功能:定位指定对象的值载荷,同时恢复其信息对象地址。
* 输入参数:info——已通过Layout_Valid校验的非空ASDU视图。
* type——与info->type_id匹配的非空只读类型描述。
* index——从0开始的索引,调用方必须保证小于object_count。
* 输出参数:ioa——非空地址输出;SQ=1时使用首地址加索引还原。
* payload_length——非空输出,返回固定或变长载荷的实际长度。
* 返回值:输入原文中的载荷借用指针,不含IOA,不复制字节。
* 说明:本内部函数不再验证长度/索引;返回指针的有效期与原ASDU一致。
*/
static const uint8_t *Element_Position(const IEC60870_AsduInfo_t *info,
const IEC60870_InformationObjectVTable *type, uint8_t index, uint32_t *ioa,
uint16_t *payload_length)
{
unsigned int address_size = (unsigned int)info->parameters->sizeOfIOA;
const uint8_t *data = info->information_objects;
*payload_length = type->payload_size;
if (type->get_payload_size_from_buffer != NULL) {
/* Layout_Valid已确认变长对象为SQ=0、数量1且载荷完整。 */
*payload_length = type->get_payload_size_from_buffer(data + address_size,
(uint16_t)(info->information_objects_len - address_size));
}
/* SQ=1的对象区为:首IOA、载荷0、载荷1……;后续地址不占报文字节。 */
if (info->is_sequence) {
*ioa = IEC60870_Object_Read_LE(data, address_size) + index;
return data + address_size + index * type->payload_size;
}
/* SQ=0每个对象都有独立IOA,故步长包含地址;取值前先跳过该地址。 */
data += index * (address_size + type->payload_size);
*ioa = IEC60870_Object_Read_LE(data, address_size);
return data + address_size;
}
/**
* 功能:核对容器控制字段与已构造ASDU布局是否一致。
* 输入参数:self——待检查容器或借用原文对象,可为NULL。
* 输出参数:无。
* 返回值:1表示结构状态一致;0表示参数、容量、类型、数量、长度或首地址非法。
* 说明:构造容器按类型重算精确长度;借用原文对象只检查公共头及最低长度。
* 不重新解码值,参数、控制字段及对象区须由调用方保持有效且不变。
*/
static int Container_Valid(const IEC60870_Asdu_t *self)
{
uint16_t expected;
const IEC60870_InformationObjectVTable *type;
if (self == NULL || self->buffer == NULL ||
!IEC60870_AppLayerParameters_Valid(self->parameters) ||
self->capacity < Header_Size(self->parameters) ||
self->capacity > self->parameters->maxSizeOfASDU ||
self->length < Header_Size(self->parameters) ||
self->length > self->capacity || self->is_sequence > 1U ||
self->object_count > IEC60870_ASDU_MAX_OBJECTS || self->is_from_buffer > 1U) {
return 0;
}
if (self->is_from_buffer) {
IEC60870_AsduInfo_t info;
/* 已有原文的容量固定为其长度,不将未知对象当作可追加的构造容器。
* 不读取未知类型的IOA;first_ioa仅供构造时的连续地址检查使用。 */
return self->capacity == self->length && self->first_ioa == 0U &&
IEC60870_Parse_ASDU_Header(self->parameters, self->buffer, self->length, &info) &&
self->type_id == info.type_id && self->object_count == info.object_count &&
self->is_sequence == info.is_sequence;
}
expected = Header_Size(self->parameters);
if (self->object_count == 0U) {
if (self->type_id != 0U) { return 0; }
} else {
type = IEC60870_InformationObject_Get_Descriptor(self->type_id);
if (type == NULL || (self->is_sequence && !type->supports_sequence) ||
(type->single_object && self->object_count != 1U)) {
return 0;
}
expected = (uint16_t)(expected + self->object_count * type->payload_size +
(self->is_sequence ? self->parameters->sizeOfIOA :
self->object_count * self->parameters->sizeOfIOA));
if (type->get_payload_size_from_buffer != NULL) {
IEC60870_AsduInfo_t info;
if (!IEC60870_Parse_ASDU_Header(self->parameters, self->buffer, self->length, &info) ||
!Layout_Valid(&info, type)) { return 0; }
expected = self->length;
}
}
if (self->length != expected || self->buffer[0] != self->type_id ||
self->buffer[1] != (uint8_t)(self->object_count | (self->is_sequence << 7))) {
return 0;
}
if (self->object_count != 0U &&
(self->first_ioa != IEC60870_Object_Read_LE(self->buffer + Header_Size(self->parameters),
(unsigned int)self->parameters->sizeOfIOA) ||
(self->is_sequence && self->first_ioa >
IEC60870_Object_Max_IOA(self->parameters) - (self->object_count - 1U)))) {
return 0;
}
return 1;
}
/**
* 功能:在调用方缓冲区中创建一个尚未加入对象的ASDU。
* 输入参数:parameters——非空合法参数;容器借用指针,使用期间必须有效且不变。
* capacity——buffer实际可用字节数;有效容量取此值与maxSizeOfASDU的较小值。
* header——非空公共头配置;COT为0..63,P/N和TEST为0/1,CA须适合所选宽度。
* is_sequence——0为逐对象IOA,1为连续地址;一条ASDU内不自动切换。
* 输出参数:self——非空容器存储,成功后记录缓冲区、参数及初始状态。
* buffer——非空可写ASDU缓冲区,初始只写公共头,不含APCI。
* 返回值:OK为成功,FULL为实际缓冲区不足头长,ERROR为参数或字段非法。
* 说明:全部检查通过后才写回;首对象尚未确定,Type ID和对象数均为0。
* 本函数不分配内存,也不发送;SQ适用性按具体类型检查,空容器不能Get_Data。
*/
IEC60870_AsduResult_t IEC60870_Asdu_Create(IEC60870_Asdu_t *self,
const IEC60870_AppLayerParameters_t *parameters,
uint8_t *buffer, uint16_t capacity, const IEC60870_AsduHeader_t *header, int is_sequence)
{
IEC60870_Asdu_t result;
uint16_t header_length;
if (self == NULL || buffer == NULL || header == NULL ||
!IEC60870_AppLayerParameters_Valid(parameters) ||
(is_sequence != 0 && is_sequence != 1) ||
header->cause_of_transmission > 63U || header->is_negative_confirm > 1U ||
header->is_test > 1U || (parameters->sizeOfCA == 1 && header->common_address > 255U)) {
return IEC60870_ASDU_ERROR;
}
header_length = Header_Size(parameters);
if (capacity < header_length) { return IEC60870_ASDU_FULL; }
memset(&result, 0, sizeof(result));
result.buffer = buffer;
/* 缓冲区较大也不能突破协议配置上限;仅保存参数指针,不复制配置。 */
result.capacity = capacity > parameters->maxSizeOfASDU ?
(uint16_t)parameters->maxSizeOfASDU : capacity;
result.length = header_length;
result.is_sequence = (uint8_t)is_sequence;
result.parameters = parameters;
/* 此后没有可能失败的校验;按所选宽度恰好写入header_length字节。 */
/* Type ID暂置0;VSQ bit7为SQ、低7位为数量,初始数量为0。 */
buffer[0] = 0;
buffer[1] = (uint8_t)(is_sequence << 7);
/* COT首字节:bit0..5为原因、bit6为P/N、bit7为TEST;2字节COT才写OA。 */
buffer[2] = (uint8_t)(header->cause_of_transmission |
(header->is_negative_confirm << 6) | (header->is_test << 7));
if (parameters->sizeOfCOT == 2) { buffer[3] = header->originator_address; }
IEC60870_Object_Write_LE(buffer + 2 + parameters->sizeOfCOT,
header->common_address, (unsigned int)parameters->sizeOfCA);
*self = result;
return IEC60870_ASDU_OK;
}
/**
* 功能:将已有可写ASDU原文包装成调用方持有的对象。
* 输入参数:parameters——非空应用层参数;buffer——可写原文;length——原文长度。
* 输出参数:self——全部检查成功后写入;buffer不变。
* 返回值:OK为成功,ERROR为参数或最低长度非法。
* 说明:借用参数和原文,不分配、不复制;本入口不替代业务使用的完整Parse。
* 容量固定为原文长度,后续只允许修改公共头,不能追加信息对象。
*/
IEC60870_AsduResult_t IEC60870_Asdu_Create_From_Buffer(IEC60870_Asdu_t *self,
const IEC60870_AppLayerParameters_t *parameters, uint8_t *buffer, uint16_t length)
{
IEC60870_AsduInfo_t info;
IEC60870_Asdu_t result;
if (self == NULL || !IEC60870_Parse_ASDU_Header(parameters, buffer, length, &info)) {
return IEC60870_ASDU_ERROR;
}
memset(&result, 0, sizeof(result));
result.buffer = buffer;
result.capacity = length;
result.length = length;
result.type_id = info.type_id;
result.object_count = info.object_count;
result.is_sequence = info.is_sequence;
result.is_from_buffer = 1U;
result.parameters = parameters;
*self = result;
return IEC60870_ASDU_OK;
}
/**
* 功能:修改ASDU传送原因,保留COT字节中的两个独立标志。
* 输入参数:self——合法ASDU对象;cause——0..63。
* 输出参数:self->buffer[2]——校验成功后更新低6位。
* 返回值:OK为成功,ERROR为参数或对象状态非法。
* 说明:所有字段宽度配置中COT首字节均位于偏移2;不改变OA或载荷。
*/
IEC60870_AsduResult_t IEC60870_Asdu_Set_COT(IEC60870_Asdu_t *self, int cause)
{
if (cause < 0 || cause > 63 || !Container_Valid(self)) { return IEC60870_ASDU_ERROR; }
self->buffer[2] = (uint8_t)((self->buffer[2] & 0xC0U) | (uint8_t)cause);
return IEC60870_ASDU_OK;
}
/**
* 功能:修改ASDU的P/N标志,保留传送原因及TEST。
* 输入参数:self——合法ASDU对象;is_negative——0或1。
* 输出参数:self->buffer[2]——校验成功后仅更新bit6。
* 返回值:OK为成功,ERROR为参数或对象状态非法。
* 说明:不执行命令,不提交发送;失败保持字节原值。
*/
IEC60870_AsduResult_t IEC60870_Asdu_Set_Negative(IEC60870_Asdu_t *self, int is_negative)
{
if ((is_negative != 0 && is_negative != 1) || !Container_Valid(self)) {
return IEC60870_ASDU_ERROR;
}
self->buffer[2] = (uint8_t)((self->buffer[2] & 0xBFU) | (uint8_t)(is_negative << 6));
return IEC60870_ASDU_OK;
}
/**
* 功能:修改ASDU公共地址,保留其他公共头字段与对象区。
* 输入参数:self——合法ASDU对象;common_address——须适合sizeOfCA的无符号地址。
* 输出参数:self->buffer——在2+sizeOfCOT偏移按小端写入sizeOfCA字节。
* 返回值:OK为成功,ERROR为非法容器或1字节CA无法表示的地址;失败不写入。
* 说明:沿用Container_Valid检查构造及借用对象,不截断地址,不决定是否允许广播。
*/
IEC60870_AsduResult_t IEC60870_Asdu_Set_CA(IEC60870_Asdu_t *self, uint16_t common_address)
{
if (!Container_Valid(self) || (self->parameters->sizeOfCA == 1 && common_address > 255U)) {
return IEC60870_ASDU_ERROR;
}
IEC60870_Object_Write_LE(self->buffer + 2 + self->parameters->sizeOfCOT,
common_address, (unsigned int)self->parameters->sizeOfCA);
return IEC60870_ASDU_OK;
}
/**
* 功能:编码并追加一个同类型对象,成功后更新ASDU长度及VSQ。
* 输入参数:self——已成功Create且控制字段/参数/原文未被修改的容器。
* object——已由具体类型Create或解析器初始化的公共基类首成员。
* 输出参数:self——成功后更新容器及其字节缓冲区,失败保持原值。
* 返回值:OK为追加成功;FULL为字节空间或对象数已满;UNSUPPORTED为未知类型;
* ERROR为容器、身份、字段、地址或SQ约束非法。
* 说明:在有界临时区完成IOA和值编码(含变长文件段),确认容量后才写入。
* 首个成功对象固定Type ID;SQ=1首对象仍带IOA,其后只写载荷且地址必须递增1。
* FULL时由调用方提交已有非空ASDU,另起一条重试同一对象;不会自动拆包。
* 成功后仅保存对象的报文字节,不借用object,调用方可以立即复用其存储。
*/
IEC60870_AsduResult_t IEC60870_Asdu_Add_InformationObject(IEC60870_Asdu_t *self,
const IEC60870_InformationObject_t *object)
{
const IEC60870_InformationObjectVTable *type;
uint8_t encoded[IEC60870_OBJECT_MAX_ENCODED];
uint16_t added;
IEC60870_AsduResult_t status;
if (!Container_Valid(self) || self->is_from_buffer || object == NULL) { return IEC60870_ASDU_ERROR; }
type = IEC60870_InformationObject_Get_Descriptor(object->type_id);
if (type == NULL) { return IEC60870_ASDU_UNSUPPORTED; }
if (object->virtual_function_table != type ||
(self->object_count != 0U && self->type_id != type->type_id) ||
(self->is_sequence && !type->supports_sequence) ||
object->ioa > IEC60870_Object_Max_IOA(self->parameters)) {
return IEC60870_ASDU_ERROR;
}
/* 用减法先判断地址范围,再比较首IOA+已有数量,避免允许隐含地址越界。 */
if (self->is_sequence && self->object_count != 0U &&
(self->first_ioa > IEC60870_Object_Max_IOA(self->parameters) - self->object_count ||
object->ioa != self->first_ioa + self->object_count)) {
return IEC60870_ASDU_ERROR;
}
/* 字段错误优先于容量已满,以免把非法对象误当作下一条ASDU的可重试输入。 */
status = IEC60870_InformationObject_Encode(object, self->parameters,
self->is_sequence && self->object_count != 0U, encoded, sizeof(encoded), &added);
if (status != IEC60870_ASDU_OK) { return status; }
if (self->object_count == IEC60870_ASDU_MAX_OBJECTS ||
(type->single_object && self->object_count != 0U) ||
added > self->capacity - self->length) {
return IEC60870_ASDU_FULL;
}
/* 从此处开始统一提交,没有后续失败分支,容量不足不会留下半个对象。 */
memcpy(self->buffer + self->length, encoded, added);
if (self->object_count == 0U) {
self->first_ioa = object->ioa;
self->type_id = type->type_id;
self->buffer[0] = type->type_id;
}
self->length = (uint16_t)(self->length + added);
++self->object_count;
self->buffer[1] = (uint8_t)(self->object_count | (self->is_sequence << 7));
return IEC60870_ASDU_OK;
}
/**
* 功能:导出构造完成或直接借用的ASDU原文。
* 输入参数:self——非空合法对象;Create创建的容器必须至少加入一个对象。
* 输出参数:asdu——非空输出指针,成功时指向调用方原有缓冲区。
* length——非空输出指针,成功时得到当前ASDU字节数,不含APCI。
* 返回值:OK为成功;ERROR为容器、输出参数非法或容器为空;失败不修改输出。
* 说明:返回借用视图,不复制或发送。借用原文对象不额外进行完整对象校验。
* 后续Add/Create/Set会影响原文,length只是本次快照。
*/
IEC60870_AsduResult_t IEC60870_Asdu_Get_Data(const IEC60870_Asdu_t *self,
const uint8_t **asdu, uint16_t *length)
{
if (!Container_Valid(self) || (!self->is_from_buffer && self->object_count == 0U) ||
asdu == NULL || length == NULL) {
return IEC60870_ASDU_ERROR;
}
*asdu = self->buffer;
*length = self->length;
return IEC60870_ASDU_OK;
}
/**
* 功能:校验完整ASDU(含参数和文件类型),生成可用于逐对象提取的只读视图。
* 输入参数:parameters——显式非空应用层参数,字段宽度必须对应收到的报文。
* asdu——非空ASDU原文,不含APCI。
* length——完整ASDU字节数,不能超过配置上限,不能包含多余尾字节。
* 输出参数:info——非空视图输出,借用parameters和asdu,二者须在取对象期间有效且不变。
* 返回值:OK为成功;UNSUPPORTED为未支持类型;ERROR为公共头、布局或任一对象非法。
* 说明:先检查公共头和布局,再验证所有对象,全部成功后才发布info,失败保留旧输出。
* 不执行命令,也不判断COT/CA/IOA的业务适用性;具体对象通过Get_Element获取。
*/
IEC60870_AsduResult_t IEC60870_Asdu_Parse(const IEC60870_AppLayerParameters_t *parameters,
const uint8_t *asdu, uint16_t length, IEC60870_AsduInfo_t *info)
{
IEC60870_AsduInfo_t result;
const IEC60870_InformationObjectVTable *type;
uint8_t i;
if (info == NULL || !IEC60870_Parse_ASDU_Header(parameters, asdu, length, &result)) {
return IEC60870_ASDU_ERROR;
}
type = IEC60870_InformationObject_Get_Descriptor(result.type_id);
if (type == NULL) { return IEC60870_ASDU_UNSUPPORTED; }
if (!Layout_Valid(&result, type)) { return IEC60870_ASDU_ERROR; }
/* 输出传NULL使类型解析器仅校验,不分配对象数组;任一对象失败就丢弃整个临时视图。 */
for (i = 0; i < result.object_count; ++i) {
uint32_t ioa;
uint16_t payload_length;
const uint8_t *payload = Element_Position(&result, type, i, &ioa, &payload_length);
IEC60870_AsduResult_t status = IEC60870_InformationObject_Decode(result.type_id, ioa,
payload, payload_length, NULL, 0);
if (status != IEC60870_ASDU_OK) { return status; }
}
*info = result;
return IEC60870_ASDU_OK;
}
/**
* 功能:从已解析视图中按索引取得一个独立类型的对象副本。
* 输入参数:info——由Asdu_Parse生成且未修改的视图,其原文和参数仍须有效。
* index——从0开始的对象索引,必须小于object_count。
* object_size——object实际可用字节数,至少为对应具体结构的sizeof。
* 输出参数:object——非空具体对象存储,结构类型必须由info->type_id正确选择。
* 返回值:OK为成功;UNSUPPORTED为未知类型;ERROR为布局、索引、载荷或输出尺寸非法。
* 说明:输出无需预先Create,成功时按值保存且不借用原文,失败保持原输出不变。
* 只重新检查布局和选中对象;尺寸校验不能替代C语言类型匹配,公共头仍从info读取。
*/
IEC60870_AsduResult_t IEC60870_Asdu_Get_Element(const IEC60870_AsduInfo_t *info,
uint8_t index, void *object, size_t object_size)
{
const IEC60870_InformationObjectVTable *type;
const uint8_t *payload;
uint32_t ioa;
uint16_t payload_length;
if (info == NULL || object == NULL) { return IEC60870_ASDU_ERROR; }
type = IEC60870_InformationObject_Get_Descriptor(info->type_id);
if (type == NULL) { return IEC60870_ASDU_UNSUPPORTED; }
if (!Layout_Valid(info, type) || index >= info->object_count) { return IEC60870_ASDU_ERROR; }
payload = Element_Position(info, type, index, &ioa, &payload_length);
return IEC60870_InformationObject_Decode(info->type_id, ioa, payload,
payload_length, object, object_size);
}
/**
* 功能:复制请求原文并改写COT/P/N,构造确认、终止或字段及遥控错误应答。
* 输入参数:parameters——与请求布局匹配的非空合法应用层参数。
* request——非空请求ASDU原文,不含APCI。
* length——请求ASDU的完整字节数。
* cause——接受7、9、10及44..49;用于确认、终止、未知字段及遥控软压板/时间戳错误。
* is_negative——P/N标志,0或1;否定激活确认使用cause=7、is_negative=1,遥控错误48/49同样传1。
* capacity——out实际可写字节数,至少为length。
* 输出参数:out——非空应答缓冲区,可与request原地或部分重叠。
* out_length——非空长度输出,成功时等于length。
* 返回值:OK为成功,FULL为输出容量不足,ERROR为参数或请求基础格式非法。
* 说明:只依赖公共头和最低长度检查,不要求具体对象解析成功,因此可回显未知类型。
* 保留TEST、OA、CA、VSQ及所有对象字节;失败不修改out/out_length,不自动发送。
*/
IEC60870_AsduResult_t IEC60870_Asdu_Build_Response(const IEC60870_AppLayerParameters_t *parameters,
const uint8_t *request, uint16_t length,
int cause, int is_negative, uint8_t *out, uint16_t capacity, uint16_t *out_length)
{
IEC60870_AsduInfo_t info;
uint8_t cot;
if (out == NULL || out_length == NULL || (is_negative != 0 && is_negative != 1) ||
(cause != IEC60870_ASDU_COT_ACTIVATION_CON && cause != IEC60870_ASDU_COT_DEACTIVATION_CON &&
cause != IEC60870_ASDU_COT_ACTIVATION_TERMINATION &&
(cause < IEC60870_ASDU_COT_UNKNOWN_TYPE || cause > IEC60870_ASDU_COT_COMMAND_TIME_ERROR)) ||
!IEC60870_Parse_ASDU_Header(parameters, request, length, &info)) {
return IEC60870_ASDU_ERROR;
}
if (capacity < length) { return IEC60870_ASDU_FULL; }
/* 先保存新COT,再memmove原文;即使输入输出重叠,也不会丢失请求的TEST。 */
cot = (uint8_t)(cause | (is_negative << 6) | (info.is_test << 7));
memmove(out, request, length);
out[2] = cot;
*out_length = length;
return IEC60870_ASDU_OK;
}
@@ -0,0 +1,199 @@
/*
* 101/104共用ASDU容器。公共头、VSQ/SQ、容量、IOA布局由本层维护,
* 数值、品质、命令限定词和时标的编解码由具体信息对象完成。
* 参数与字节缓冲区均由调用方提供;无动态内存或可变全局状态。
*
* 发送:具体类型Create -> Asdu_Create -> Add_InformationObject(逐个)-> Get_Data。
* 接收:Asdu_Parse -> 按info.type_id选择具体结构 -> Get_Element。
* Type ID决定载荷格式,COT表示传送原因,CA是站公共地址,IOA是点/对象地址;
* VSQ低7位是对象数,bit7是SQ。SQ=1只保存首IOA,随后各对象地址依次加1。
* Type42的两组记录使用独立数量,不符合本容器的普通对象布局;使用IEC60870_FaultEvent.h。
*/
#ifndef IEC60870_ASDU_H
#define IEC60870_ASDU_H
#include "IEC60870_Codec.h"
#include "IEC60870_InformationObjects.h"
#ifdef __cplusplus
extern "C" {
#endif
/* COT首字节的低6位,不含独立的P/N和TEST标志;不是完整的COT适用规则表。 */
typedef enum {
IEC60870_ASDU_COT_PERIODIC = 1, /* 周期/循环上报。 */
IEC60870_ASDU_COT_BACKGROUND = 2, /* 背景扫描。 */
IEC60870_ASDU_COT_SPONTANEOUS = 3, /* 突发上报。 */
IEC60870_ASDU_COT_INITIALIZED = 4, /* 初始化结束。 */
IEC60870_ASDU_COT_REQUEST = 5, /* 请求或被请求的数据。 */
IEC60870_ASDU_COT_ACTIVATION = 6, /* 激活请求。 */
IEC60870_ASDU_COT_ACTIVATION_CON = 7, /* 激活确认,P/N另行指定。 */
IEC60870_ASDU_COT_DEACTIVATION = 8, /* 停止激活请求。 */
IEC60870_ASDU_COT_DEACTIVATION_CON = 9, /* 停止激活确认。 */
IEC60870_ASDU_COT_ACTIVATION_TERMINATION = 10, /* 激活终止。 */
IEC60870_ASDU_COT_RETURN_INFO_REMOTE = 11, /* 远方命令引起的返回信息。 */
IEC60870_ASDU_COT_RETURN_INFO_LOCAL = 12, /* 当地命令引起的返回信息。 */
IEC60870_ASDU_COT_FILE_TRANSFER = 13, /* 文件传输。 */
IEC60870_ASDU_COT_INTERROGATED_BY_STATION = 20, /* 响应站总召唤的数据。 */
IEC60870_ASDU_COT_COUNTER_INTERROGATION = 37, /* 响应电能脉冲总召唤的数据。 */
IEC60870_ASDU_COT_COUNTER_GROUP_1 = 38,
IEC60870_ASDU_COT_COUNTER_GROUP_2 = 39,
IEC60870_ASDU_COT_COUNTER_GROUP_3 = 40,
IEC60870_ASDU_COT_COUNTER_GROUP_4 = 41,
IEC60870_ASDU_COT_UNKNOWN_TYPE = 44, /* 未知类型标识。 */
IEC60870_ASDU_COT_UNKNOWN_CAUSE = 45, /* 未知传送原因。 */
IEC60870_ASDU_COT_UNKNOWN_COMMON_ADDRESS = 46, /* 未知公共地址。 */
IEC60870_ASDU_COT_UNKNOWN_IOA = 47, /* 未知信息对象地址。 */
IEC60870_ASDU_COT_COMMAND_INTERLOCK_ERROR = 48, /* 遥控软压板状态错误,实施细则扩展。 */
IEC60870_ASDU_COT_COMMAND_TIME_ERROR = 49 /* 遥控时间戳错误,实施细则扩展。 */
} IEC60870_AsduCause_t;
/* 创建ASDU时仅提供公共头;Type ID由首个成功添加的对象决定,VSQ由容器维护。
* 字段赋值前不得截窄越界整数。COT/CA/IOA的业务适用性由应用层检查。 */
typedef struct {
uint8_t cause_of_transmission; /* COT低6位,0..63,不含P/N及TEST。 */
uint8_t is_negative_confirm; /* P/N:0肯定、1否定。 */
uint8_t is_test; /* TEST:0/1。 */
uint8_t originator_address; /* 显式OA;COT为1字节时忽略,解析输出0。 */
uint16_t common_address; /* 1字节CA拒绝超过255的值,不截断。 */
} IEC60870_AsduHeader_t;
/* 调用方保存的容器;控制字段由Create/Create_From_Buffer初始化,不得手工修改。
* 字节区通过Add或字段设置接口修改;parameters在使用期间必须有效且不变。
* Create_From_Buffer借用可写原文,只允许设置公共头,不允许继续追加对象。
* 同一实例由调用方串行使用;对象不分配或释放其借用的缓冲区。 */
typedef struct {
uint8_t *buffer; /* ASDU原文,不含APCI。 */
uint16_t capacity; /* min(调用方容量, maxSizeOfASDU)。 */
uint16_t length; /* 当前字节数,空容器仅有公共头。 */
uint8_t type_id; /* 空容器为0,首个对象成功加入后固定。 */
uint8_t object_count; /* 按类型限制为0..127或0..1;借用时记录原VSQ数量。 */
uint8_t is_sequence; /* SQ:0逐对象地址,1连续地址。 */
uint8_t is_from_buffer;/* 1为借用收到的原文;0为Create创建的构造容器。 */
uint32_t first_ioa; /* 构造时供SQ连续性校验;借用原文时为0且不使用。 */
const IEC60870_AppLayerParameters_t *parameters; /* 借用参数,不复制。 */
} IEC60870_Asdu_t;
/* 结果须显式比较IEC60870_ASDU_OK;FULL=0,ERROR/UNSUPPORTED为负值。
* 所有失败保留调用方输出。结构体、输出参数和字节区不得互相重叠;
* 唯一例外是Build_Response允许输入/输出字节区重叠。 */
/**
* 功能:创建空容器并固定参数、SQ和公共头;参数必须非空,头长=2+COT宽度+CA宽度。
* 输入参数:parameters——非空合法参数;容器借用指针,使用期间必须有效且不变。 capacity——buffer实际可用字节数;有效容量取此值与maxSizeOfASDU的较小值。
* header——非空公共头配置;COT为0..63,P/N和TEST为0/1,CA须适合所选宽度。 is_sequence——0为逐对象IOA,1为连续地址;一条ASDU内不自动切换。
* 输出参数:self——非空容器存储,成功后记录缓冲区、参数及初始状态。 buffer——非空可写ASDU缓冲区,初始只写公共头,不含APCI。
* 返回值:OK为成功,FULL为实际缓冲区不足头长,ERROR为参数或字段非法。
* 说明:有效容量不足头长返回FULL;SQ=1只适用于监视信息和文件目录。 初始Type ID为0,首个对象失败不会改变类型;空容器不能Get_Data。
*/
IEC60870_AsduResult_t IEC60870_Asdu_Create(IEC60870_Asdu_t *self,
const IEC60870_AppLayerParameters_t *parameters,
uint8_t *buffer, uint16_t capacity, const IEC60870_AsduHeader_t *header, int is_sequence);
/**
* 功能:在调用方存储中建立可修改的ASDU对象,直接借用已有报文字节。
* 输入参数:parameters——对应原文布局的非空合法参数,使用期间有效且不变。
* buffer——非空可写ASDU原文,不含APCI;length——原文完整长度。
* 输出参数:self——成功时写入容器,失败保持原值;buffer不变。
* 返回值:OK为成功,ERROR为参数或最低长度非法。
* 说明:只检查公共头和已知类型最低长度,允许未知类型回显错误应答。
* 业务执行前仍应调用Parse进行完整校验;不复制、不分配、不追加对象。
* 字段设置会修改buffer;必须保证buffer和parameters在使用期间有效。
*/
IEC60870_AsduResult_t IEC60870_Asdu_Create_From_Buffer(IEC60870_Asdu_t *self,
const IEC60870_AppLayerParameters_t *parameters, uint8_t *buffer, uint16_t length);
/**
* 功能:原地设置ASDU的传送原因。
* 输入参数:self——合法构造容器或借用原文的对象;cause——0..63。
* 输出参数:self->buffer——仅更新COT低6位,保留P/N、TEST及其余字节。
* 返回值:OK为成功,ERROR为参数非法;失败不修改原文。
* 说明:不判断传送原因的业务适用性,也不发送报文。
*/
IEC60870_AsduResult_t IEC60870_Asdu_Set_COT(IEC60870_Asdu_t *self, int cause);
/**
* 功能:原地设置ASDU的肯定或否定确认标志。
* 输入参数:self——合法ASDU对象;is_negative——0肯定、1否定。
* 输出参数:self->buffer——仅更新P/N位,保留COT、TEST及其余字节。
* 返回值:OK为成功,ERROR为参数非法;失败不修改原文。
* 说明:设置字段不代表业务已接受命令,也不提交发送。
*/
IEC60870_AsduResult_t IEC60870_Asdu_Set_Negative(IEC60870_Asdu_t *self, int is_negative);
/**
* 功能:原地设置ASDU公共地址,适用于合法构造容器或借用可写原文的对象。
* 输入参数:self——合法ASDU对象;common_address——0..65535,须适合配置的CA宽度。
* 输出参数:self->buffer——仅更新CA字段,按小端序写入1或2字节。
* 返回值:OK为成功,ERROR为对象状态或字段宽度非法;失败不修改任何原文字节。
* 说明:偏移由COT宽度确定,保留OA、TEST、P/N及对象原文;不限制业务上的站地址范围。
* 不分配、不改变容器长度、不发送;原文修改后,旧解析视图须重新解析。
*/
IEC60870_AsduResult_t IEC60870_Asdu_Set_CA(IEC60870_Asdu_t *self, uint16_t common_address);
/**
* 功能:通过对象函数表编码并复制到ASDU,成功后不再借用对象本身。
* 输入参数:self——已成功Create且控制字段/参数/原文未被修改的容器。 object——已由具体类型Create或解析器初始化的公共基类首成员。
* 输出参数:self——成功后更新容器及其字节缓冲区,失败保持原值。
* 返回值:OK为追加成功;FULL为字节空间或对象数已满;UNSUPPORTED为未知类型; ERROR为容器、身份、字段、地址或SQ约束非法。
* 说明:单类型约束、SQ连续地址和IOA宽度统一检查。字节容量不足、对象达到127个, 或单对象类型已加入对象时返回FULL;类型不匹配、SQ或字段非法返回ERROR。
* FULL时由调用方提交当前非空ASDU,另起一条重试同一对象,不自动发送或拆包。
*/
IEC60870_AsduResult_t IEC60870_Asdu_Add_InformationObject(IEC60870_Asdu_t *self,
const IEC60870_InformationObject_t *object);
/**
* 功能:获取构造容器或Create_From_Buffer对象的借用原文及当前长度。
* 输入参数:self——非空合法对象;Create创建的容器必须至少加入一个对象。
* 输出参数:asdu——非空输出指针,成功时指向调用方原有缓冲区。 length——非空输出指针,成功时得到当前ASDU字节数,不含APCI。
* 返回值:OK为成功;ERROR为容器、输出参数非法或容器为空;失败不修改输出。
* 说明:Create创建的空容器不可导出;借用原文对象沿用公共头最低长度检查。 不分配、不复制、不发送;需完整检查对象值时先调用Parse。 缓冲区修改后原视图失效;
* 提交104传输时应使用2/2/3配置及<=249的总长。
*/
IEC60870_AsduResult_t IEC60870_Asdu_Get_Data(const IEC60870_Asdu_t *self,
const uint8_t **asdu, uint16_t *length);
/**
* 功能:统一解析67种监视、命令、初始化结束、参数和文件类型。
* 输入参数:parameters——显式非空应用层参数,字段宽度必须对应收到的报文。 asdu——非空ASDU原文,不含APCI。 length——完整ASDU字节数,不能超过配置上限,
* 不能包含多余尾字节。
* 输出参数:info——非空视图输出,借用parameters和asdu,二者须在取对象期间有效且不变。
* 返回值:OK为成功;UNSUPPORTED为未支持类型;ERROR为公共头、布局或任一对象非法。
* 说明:验证精确长度和所有对象,文件段按LOS检查变长载荷。 监视与文件目录支持SQ=0/1;参数要求SQ=0、数量=1。 其余类型要求SQ=0、数量=1;
* 未知类型及专用Type42返回UNSUPPORTED。 info借用参数和输入原文,二者在取对象期间均须有效且不变。
*/
IEC60870_AsduResult_t IEC60870_Asdu_Parse(const IEC60870_AppLayerParameters_t *parameters,
const uint8_t *asdu, uint16_t length, IEC60870_AsduInfo_t *info);
/**
* 功能:按Type ID调用具体解析器,向对应类型的存储写入一个按值对象。
* 输入参数:info——由Asdu_Parse生成且未修改的视图,其原文和参数仍须有效。 index——从0开始的对象索引,必须小于object_count。
* object_size——object实际可用字节数,至少为对应具体结构的sizeof。
* 输出参数:object——非空具体对象存储,结构类型必须由info->type_id正确选择。
* 返回值:OK为成功;UNSUPPORTED为未知类型;ERROR为布局、索引、载荷或输出尺寸非法。
* 说明:例如Type 1传入&point、sizeof(point),其中point为IEC60870_SinglePointInformation_t。
* 调用方必须依据info->type_id选择正确的结构类型;object_size至少为该结构尺寸, 尺寸检查不能替代C语言中的类型匹配。index从0开始,输出无需预先Create。
* 对象不借用原文;公共头继续从info读取,选中对象之外不再次重复解码。
*/
IEC60870_AsduResult_t IEC60870_Asdu_Get_Element(const IEC60870_AsduInfo_t *info,
uint8_t index, void *object, size_t object_size);
/**
* 功能:复制请求,只更新COT及P/N,保留TEST、OA、CA、VSQ和对象原文。
* 输入参数:parameters——与请求布局匹配的非空合法应用层参数。 request——非空请求ASDU原文,不含APCI。 length——请求ASDU的完整字节数。
* cause——接受7、9、10及44..49;用于确认、终止、未知字段及遥控软压板/时间戳错误。 is_negative——P/N标志,0或1;
* 否定激活确认使用cause=7、is_negative=1。 capacity——out实际可写字节数,至少为length。
* 输出参数:out——非空应答缓冲区,可与request原地或部分重叠。 out_length——非空长度输出,成功时等于length。
* 返回值:OK为成功,FULL为输出容量不足,ERROR为参数或请求基础格式非法。
* 说明:cause接受7/9/10/44..49,is_negative为0/1;否定激活确认传7、1,遥控错误48/49由调用方传1置否定。仅检查公共头及最低长度,允许未知类型回显,不要求对象解析成功。参数须对应请求布局。
* 容量不足返回FULL,所有失败保留out及out_length。 输入/输出字节区支持原地与部分重叠;不执行命令或自动发送。
*/
IEC60870_AsduResult_t IEC60870_Asdu_Build_Response(const IEC60870_AppLayerParameters_t *parameters,
const uint8_t *request, uint16_t length,
int cause, int is_negative, uint8_t *out, uint16_t capacity, uint16_t *out_length);
#ifdef __cplusplus
}
#endif
#endif /* IEC60870_ASDU_H */
@@ -0,0 +1,103 @@
/*
* IEC 60870-5-101/104 共用时间源接口:读取当前日历、设置实际时钟。
* 读写日历统一采用固定UTC+8标准时间,年份1970..2099;CP56编码另限2000..2099。
* 此处的本地时间指固定UTC+8,不随Windows本地时区设置或夏令时变化。
* 时间源仅考虑Windows系统时钟和RTC,构建时二选一,业务直接调用Clock_Read/Clock_Set。
* Windows实现已提供;RTC目前只保留接入接口,具体芯片驱动暂不实现。
* 与IEC60870_Time的日期转换、CP56编解码分工;不自动接入ASDU或链路单调计时。
*/
#ifndef IEC60870_CLOCK_H
#define IEC60870_CLOCK_H
#include "IEC60870_Time.h"
/*
* 时间源编译选项:0=Windows系统时钟(默认,须在Windows构建),1=RTC预留接口。
* 这是编译时选择,不在运行期间切换;RTC模式不编译Windows读写代码。
* 选项须作用于IEC60870_Clock.c的编译,不能只在业务源文件中定义。
* RTC模式须由板级驱动实现下方的Clock_RTC_Read/Set;本模块不提供芯片驱动。
* 此选项与IEC60870_TIME_USE_PLATFORM的日期转换算法选择相互独立:
* 前者决定从哪里读取/设置当前时间,后者决定如何将UTC秒数转换为日历。
* RTC已提供约定的日历时,Clock读写入口不需要时间戳与日历之间的往返转换。
*/
#ifndef IEC60870_CLOCK_USE_RTC
#define IEC60870_CLOCK_USE_RTC 0
#endif
#if IEC60870_CLOCK_USE_RTC != 0 && IEC60870_CLOCK_USE_RTC != 1
#error "IEC60870_CLOCK_USE_RTC must be 0 (Windows) or 1 (RTC)"
#endif
#ifdef __cplusplus
extern "C" {
#endif
/*
* 时间源的读取结果。日历数值合法与时间质量分开表示。
* is_invalid=1仍须提供合法日历;没有可用日历时,平台读时函数应返回0。
* is_invalid=0仅表示未标记无效,不证明时钟已经校准或与外部时间源同步。
*/
typedef struct {
IEC60870_WallTime_t time; /* 固定UTC+8标准时间,ms为0..999,星期由公共入口重算 */
uint8_t is_invalid; /* 0=未标记无效,1=时间无效;可按业务约定传递给CP56的IV */
} IEC60870_ClockValue_t;
/*
* 构建:IEC60870_Clock.c + IEC60870_Time.c;Windows读写实现在Clock.c内部。
* 以后接RTC时,定义IEC60870_CLOCK_USE_RTC=1并加入实现下方RTC接口的板级驱动。
* 时间源由构建选择,公共接口不需要时钟对象、函数指针绑定或初始化。
* RTC等硬件仍须由应用按驱动要求初始化;同一时钟的读写由调用方串行执行。
* 本模块不提供设备锁,不进行动态内存分配。
*/
/**
* 功能:从构建时选定的时间源读取固定UTC+8标准时间,并校验日历和质量标志。
* 输入参数:value——接收结果的指针,不得为空。
* 输出参数:value——合法日历、星期(0=周日..6=周六)及源提供的is_invalid。
* 返回值:1 取得格式合法的结果,is_invalid可能为1;0 参数非法、底层失败或结果非法。
* 说明:先读取局部变量,检查完成后才提交输出,失败不修改value。 局部结果的is_invalid初始为1,驱动应按实际状态明确填写0或1。 调用方须同时检查返回值和is_invalid,
* 读取成功不等于时钟准确或已同步。
*/
int IEC60870_Clock_Read(IEC60870_ClockValue_t *value);
/**
* 功能:将固定UTC+8标准时间交给构建时选定的时间源设置实际时钟。
* 输入参数:local_time——非空,1970..2099的合法UTC+8标准时间;输入的weekday可忽略。
* 输出参数:无。
* 返回值:1 底层报告设置成功;0 参数非法、平台不支持设时或底层未报告成功。
* 说明:先检查日历并重算星期,再将副本交给时间源实现,原始输入保持不变。 Windows分支转换为UTC后调用系统设时接口;RTC分支直接将日历交给驱动。 本接口不接收IV/SU;
* 校时报文须先通过CP56转换及业务校时条件检查。 不提供硬件写入回滚;失败时设备是否已有部分修改由具体驱动决定。
*/
int IEC60870_Clock_Set(const IEC60870_WallTime_t *local_time);
/*
* RTC预留接入接口:仅RTC模式需要由板级驱动实现,Windows模式不引用这两个符号。
* 业务调用上方公共入口,下面的函数由公共层同步调用,无需注册回调或绑定时钟对象。
* 不得保留输入/输出指针供返回后使用,也不能反向调用公共读写入口。
* 本模块仅声明,不提供空实现或默认成功结果;RTC硬件由应用按驱动要求初始化。
*/
/**
* 功能:由板级驱动读取RTC日历,供IEC60870_Clock_Read调用。
* 输入参数:value——公共层提供的非空局部结果,其is_invalid初始为1。
* 输出参数:value——一组一致的固定UTC+8日历和is_invalid=0/1;weekday由公共层重算。
* 返回值:1 取得可供检查的日历;0 读取失败或没有可用日历。
* 说明:驱动负责寄存器格式转换及读取一致性,避免读到跨秒、跨日拼接的字段。 RTC日历的时间基准由设备约定,驱动须保证输出为UTC+8;无毫秒能力时可填写ms=0。 即使日历数值合法,
* 停振、掉电等状态仍可能使时间无效,须按实际状态填写质量。
*/
int IEC60870_Clock_RTC_Read(IEC60870_ClockValue_t *value);
/**
* 功能:由板级驱动设置RTC实际时钟,供IEC60870_Clock_Set调用。
* 输入参数:local_time——非空,公共层已校验并重算星期的UTC+8日历副本,只在调用期间有效。
* 输出参数:无。
* 返回值:1 驱动报告设置成功;0 设置失败或设备不支持设置。
* 说明:驱动负责将日历转换为芯片要求的寄存器格式,按芯片能力处理毫秒。 只读驱动直接返回0;写入失败时可能已有部分寄存器改变,公共层不提供回滚。
*/
int IEC60870_Clock_RTC_Set(const IEC60870_WallTime_t *local_time);
#ifdef __cplusplus
}
#endif
#endif /* IEC60870_CLOCK_H */
@@ -0,0 +1,193 @@
/*
* 101/104共用的无状态ASDU基础解析:参数校验、公共头及最低载荷长度检查。
* 只处理调用方提供的字节和参数,不依赖APCI、TCP、串口或连接状态。
* 具体信息对象的完整校验由IEC60870_Asdu和InformationObjects完成。
*/
#include "IEC60870_Codec.h"
#include <stddef.h>
#include <string.h>
/* ASDU公共头中各组合字段的位掩码。 */
#define IEC60870_ASDU_OBJECT_COUNT_MASK 0x7FU
#define IEC60870_ASDU_SEQUENCE_MASK 0x80U
#define IEC60870_ASDU_CAUSE_MASK 0x3FU
#define IEC60870_ASDU_NEGATIVE_MASK 0x40U
#define IEC60870_ASDU_TEST_MASK 0x80U
#define IEC60870_ASDU_IOA_LEN 3U
/* 已知固定长度类型的单个信息对象总长,包含3字节IOA;0表示未在本表检查。
* 保留IOA使读命令C_RD_NA_1的零数据长度与未知类型可区分。
* Type ID是线上的协议值;变长文件段F_SG_NA_1及其他未列类型由业务解析。 */
static const uint8_t asdu_object_lengths[] = {
[1] = IEC60870_ASDU_IOA_LEN + 1U, /* M_SP_NA_1 */
[2] = IEC60870_ASDU_IOA_LEN + 4U, /* M_SP_TA_1 */
[3] = IEC60870_ASDU_IOA_LEN + 1U, /* M_DP_NA_1 */
[4] = IEC60870_ASDU_IOA_LEN + 4U, /* M_DP_TA_1 */
[5] = IEC60870_ASDU_IOA_LEN + 2U, /* M_ST_NA_1 */
[6] = IEC60870_ASDU_IOA_LEN + 5U, /* M_ST_TA_1 */
[7] = IEC60870_ASDU_IOA_LEN + 5U, /* M_BO_NA_1 */
[8] = IEC60870_ASDU_IOA_LEN + 8U, /* M_BO_TA_1 */
[9] = IEC60870_ASDU_IOA_LEN + 3U, /* M_ME_NA_1 */
[10] = IEC60870_ASDU_IOA_LEN + 6U, /* M_ME_TA_1 */
[11] = IEC60870_ASDU_IOA_LEN + 3U, /* M_ME_NB_1 */
[12] = IEC60870_ASDU_IOA_LEN + 6U, /* M_ME_TB_1 */
[13] = IEC60870_ASDU_IOA_LEN + 5U, /* M_ME_NC_1 */
[14] = IEC60870_ASDU_IOA_LEN + 8U, /* M_ME_TC_1 */
[15] = IEC60870_ASDU_IOA_LEN + 5U, /* M_IT_NA_1 */
[16] = IEC60870_ASDU_IOA_LEN + 8U, /* M_IT_TA_1 */
[17] = IEC60870_ASDU_IOA_LEN + 6U, /* M_EP_TA_1 */
[18] = IEC60870_ASDU_IOA_LEN + 7U, /* M_EP_TB_1 */
[19] = IEC60870_ASDU_IOA_LEN + 7U, /* M_EP_TC_1 */
[20] = IEC60870_ASDU_IOA_LEN + 5U, /* M_PS_NA_1 */
[21] = IEC60870_ASDU_IOA_LEN + 2U, /* M_ME_ND_1 */
[30] = IEC60870_ASDU_IOA_LEN + 8U, /* M_SP_TB_1 */
[31] = IEC60870_ASDU_IOA_LEN + 8U, /* M_DP_TB_1 */
[32] = IEC60870_ASDU_IOA_LEN + 9U, /* M_ST_TB_1 */
[33] = IEC60870_ASDU_IOA_LEN + 12U, /* M_BO_TB_1 */
[34] = IEC60870_ASDU_IOA_LEN + 10U, /* M_ME_TD_1 */
[35] = IEC60870_ASDU_IOA_LEN + 10U, /* M_ME_TE_1 */
[36] = IEC60870_ASDU_IOA_LEN + 12U, /* M_ME_TF_1 */
[37] = IEC60870_ASDU_IOA_LEN + 12U, /* M_IT_TB_1 */
[38] = IEC60870_ASDU_IOA_LEN + 10U, /* M_EP_TD_1 */
[39] = IEC60870_ASDU_IOA_LEN + 11U, /* M_EP_TE_1 */
[40] = IEC60870_ASDU_IOA_LEN + 11U, /* M_EP_TF_1 */
[41] = IEC60870_ASDU_IOA_LEN + 14U, /* S_IT_TC_1 */
[45] = IEC60870_ASDU_IOA_LEN + 1U, /* C_SC_NA_1 */
[46] = IEC60870_ASDU_IOA_LEN + 1U, /* C_DC_NA_1 */
[47] = IEC60870_ASDU_IOA_LEN + 1U, /* C_RC_NA_1 */
[48] = IEC60870_ASDU_IOA_LEN + 3U, /* C_SE_NA_1 */
[49] = IEC60870_ASDU_IOA_LEN + 3U, /* C_SE_NB_1 */
[50] = IEC60870_ASDU_IOA_LEN + 5U, /* C_SE_NC_1 */
[51] = IEC60870_ASDU_IOA_LEN + 4U, /* C_BO_NA_1 */
[58] = IEC60870_ASDU_IOA_LEN + 8U, /* C_SC_TA_1 */
[59] = IEC60870_ASDU_IOA_LEN + 8U, /* C_DC_TA_1 */
[60] = IEC60870_ASDU_IOA_LEN + 8U, /* C_RC_TA_1 */
[61] = IEC60870_ASDU_IOA_LEN + 10U, /* C_SE_TA_1 */
[62] = IEC60870_ASDU_IOA_LEN + 10U, /* C_SE_TB_1 */
[63] = IEC60870_ASDU_IOA_LEN + 12U, /* C_SE_TC_1 */
[64] = IEC60870_ASDU_IOA_LEN + 11U, /* C_BO_TA_1 */
[70] = IEC60870_ASDU_IOA_LEN + 1U, /* M_EI_NA_1 */
[100] = IEC60870_ASDU_IOA_LEN + 1U, /* C_IC_NA_1 */
[101] = IEC60870_ASDU_IOA_LEN + 1U, /* C_CI_NA_1 */
[102] = IEC60870_ASDU_IOA_LEN, /* C_RD_NA_1 */
[103] = IEC60870_ASDU_IOA_LEN + 7U, /* C_CS_NA_1 */
[104] = IEC60870_ASDU_IOA_LEN + 2U, /* C_TS_NA_1 */
[105] = IEC60870_ASDU_IOA_LEN + 1U, /* C_RP_NA_1 */
[106] = IEC60870_ASDU_IOA_LEN + 2U, /* C_CD_NA_1 */
[107] = IEC60870_ASDU_IOA_LEN + 9U, /* C_TS_TA_1 */
[110] = IEC60870_ASDU_IOA_LEN + 3U, /* P_ME_NA_1 */
[111] = IEC60870_ASDU_IOA_LEN + 3U, /* P_ME_NB_1 */
[112] = IEC60870_ASDU_IOA_LEN + 5U, /* P_ME_NC_1 */
[113] = IEC60870_ASDU_IOA_LEN + 1U, /* P_AC_NA_1 */
[120] = IEC60870_ASDU_IOA_LEN + 6U, /* F_FR_NA_1 */
[121] = IEC60870_ASDU_IOA_LEN + 7U, /* F_SR_NA_1 */
[122] = IEC60870_ASDU_IOA_LEN + 4U, /* F_SC_NA_1 */
[123] = IEC60870_ASDU_IOA_LEN + 5U, /* F_LS_NA_1 */
[124] = IEC60870_ASDU_IOA_LEN + 4U, /* F_AF_NA_1 */
[126] = IEC60870_ASDU_IOA_LEN + 13U, /* F_DR_TA_1 */
[127] = IEC60870_ASDU_IOA_LEN + 16U /* F_SC_NB_1 */
};
/**
* 功能:调用前已检查参数、可变公共头及ASDU总长。
* 输入参数:parameters——应用层字段宽度配置;asdu——待校验的ASDU字节;asdu_len——ASDU实际字节数;header_length——已校验的公共头长度。
* 输出参数:无。
* 返回值:1表示已知固定长度载荷未被截短;0表示长度不足。未知类型不在此处拒绝。
* 说明:表中仍以3字节IOA为基准, 计算时先减去基准IOA再加上配置宽度。仅检查已知固定长度对象是否被截短; 不要求长度恰好相等,不解释对象内容,也不在这里判定零对象或SQ的业务合法性。
*/
static int ASDU_Payload_Length_Valid(const IEC60870_AppLayerParameters_t *parameters,
const uint8_t *asdu, uint16_t asdu_len, uint16_t header_length)
{
uint32_t object_count = asdu[1] & IEC60870_ASDU_OBJECT_COUNT_MASK;
uint32_t object_length;
uint32_t required_length;
if (object_count == 0U || asdu[0] >= sizeof(asdu_object_lengths)) {
return 1;
}
object_length = asdu_object_lengths[asdu[0]];
if (object_length == 0U) {
return 1;
}
if ((asdu[1] & IEC60870_ASDU_SEQUENCE_MASK) != 0U) {
/* 连续地址只传首个IOA;非连续地址则每个对象均携带IOA。 */
required_length = (uint32_t)parameters->sizeOfIOA +
object_count * (object_length - IEC60870_ASDU_IOA_LEN);
} else {
required_length = object_count *
(object_length - IEC60870_ASDU_IOA_LEN + (uint32_t)parameters->sizeOfIOA);
}
return (uint32_t)(asdu_len - header_length) >= required_length;
}
/**
* 功能:检查101/104共用应用层参数的字段宽度、源发地址和总长上限。
* 输入参数:parameters——待检查参数,允许NULL。
* 输出参数:无。
* 返回值:合法返回1,NULL或非法字段返回0。
* 说明:先校验小范围字段再计算头长,不选择默认配置或修改参数。
*/
int IEC60870_AppLayerParameters_Valid(const IEC60870_AppLayerParameters_t *parameters)
{
return parameters != NULL && parameters->sizeOfTypeId == 1 &&
parameters->sizeOfVSQ == 1 &&
(parameters->sizeOfCOT == 1 || parameters->sizeOfCOT == 2) &&
(parameters->sizeOfCA == 1 || parameters->sizeOfCA == 2) &&
parameters->sizeOfIOA >= 1 && parameters->sizeOfIOA <= 3 &&
parameters->originatorAddress >= 0 && parameters->originatorAddress <= 255 &&
parameters->maxSizeOfASDU >= 2 + parameters->sizeOfCOT + parameters->sizeOfCA &&
parameters->maxSizeOfASDU <= IEC60870_MAX_ASDU_LEN;
}
/**
* 功能:检查ASDU公共头及已知固定长度对象的最低载荷长度,解析公共头。
* 输入参数:parameters——双方约定的非空应用层参数;asdu/asdu_len——完整ASDU。
* 输出参数:asdu_info——解析成功时写入公共头字段和信息对象区位置。
* 返回值:解析成功返回1,参数或长度非法返回0且不修改asdu_info。
* 说明:按Type ID、VSQ数量及SQ位检查最低载荷长度;未知/变长类型及零对象不做此检查。
* 不检查多余尾字节、SQ/数量的类型约束、传送原因、地址或信息对象内容是否合法。
*/
int IEC60870_Parse_ASDU_Header(const IEC60870_AppLayerParameters_t *parameters,
const uint8_t *asdu,
uint16_t asdu_len,
IEC60870_AsduInfo_t *asdu_info)
{
IEC60870_AsduInfo_t result;
uint16_t header_length;
unsigned int ca_index;
if (asdu == NULL || asdu_info == NULL || !IEC60870_AppLayerParameters_Valid(parameters)) {
return 0;
}
header_length = (uint16_t)(2 + parameters->sizeOfCOT + parameters->sizeOfCA);
if (asdu_len < header_length || asdu_len > parameters->maxSizeOfASDU ||
!ASDU_Payload_Length_Valid(parameters, asdu, asdu_len, header_length)) {
return 0;
}
/* COT为1字节时CA紧跟COT,不存在OA;先组装局部结果,再一次性发布。 */
memset(&result, 0, sizeof(result));
ca_index = (unsigned int)(2 + parameters->sizeOfCOT);
result.common_address = asdu[ca_index];
if (parameters->sizeOfCA == 2) {
result.common_address |= (uint16_t)((uint16_t)asdu[ca_index + 1U] << 8);
}
result.type_id = asdu[0];
result.object_count =
(uint8_t)(asdu[1] & IEC60870_ASDU_OBJECT_COUNT_MASK);
result.is_sequence =
(uint8_t)((asdu[1] & IEC60870_ASDU_SEQUENCE_MASK) != 0U);
result.cause_of_transmission =
(uint8_t)(asdu[2] & IEC60870_ASDU_CAUSE_MASK);
result.is_negative_confirm =
(uint8_t)((asdu[2] & IEC60870_ASDU_NEGATIVE_MASK) != 0U);
result.is_test =
(uint8_t)((asdu[2] & IEC60870_ASDU_TEST_MASK) != 0U);
result.originator_address = parameters->sizeOfCOT == 2 ? asdu[3] : 0;
result.information_objects = &asdu[header_length];
result.information_objects_len = (uint16_t)(asdu_len - header_length);
result.parameters = parameters;
*asdu_info = result;
return 1;
}
@@ -0,0 +1,54 @@
/* 101/104共用的ASDU公共头解析与参数检查,不包含传输帧接口。 */
#ifndef IEC60870_CODEC_H
#define IEC60870_CODEC_H
#include "IEC60870_Types.h"
#ifdef __cplusplus
extern "C" {
#endif
/* ASDU公共头的解析结果;本模块不解析具体信息对象,调用方按type_id另行处理。 */
typedef struct {
uint8_t type_id; /* 类型标识 */
uint8_t object_count; /* VSQ中的信息对象数量 */
uint8_t is_sequence; /* VSQ中的SQ标志 */
uint8_t cause_of_transmission; /* 传送原因,不含标志位 */
uint8_t is_negative_confirm; /* 传送原因中的P/N标志 */
uint8_t is_test; /* 传送原因中的TEST标志 */
uint8_t originator_address; /* 源发地址 */
uint16_t common_address; /* ASDU公共地址 */
const uint8_t *information_objects; /* 信息对象区首地址 */
uint16_t information_objects_len; /* 信息对象区长度 */
const IEC60870_AppLayerParameters_t *parameters; /* 借用本次解析参数,不可修改。 */
} IEC60870_AsduInfo_t;
/**
* 功能:校验应用层字段宽度、默认源发地址及ASDU总长上限。
* 输入参数:parameters——待检查参数,允许NULL。
* 输出参数:无。
* 返回值:合法返回1,NULL或非法值返回0。
* 说明:不修改参数,不替调用方选择101/104的传输配置。
*/
extern int IEC60870_AppLayerParameters_Valid(const IEC60870_AppLayerParameters_t *parameters);
/**
* 功能:检查ASDU公共头及已知固定长度对象的最低载荷长度,解析公共头。
* 输入参数:parameters——非空应用层参数;asdu——ASDU首地址;asdu_len——总长度。
* 输出参数:asdu_info——解析成功时写入公共头字段和信息对象区位置。
* 返回值:解析成功返回1,参数或长度非法返回0且不修改asdu_info。
* 说明:头长为2+sizeOfCOT+sizeOfCA,IOA及最低载荷长度按sizeOfIOA计算。
* 未知/变长类型及零对象不做载荷检查;不检查多余尾字节、SQ/数量的类型约束、
* 传送原因、地址或信息对象内容是否合法。接收器在链路受理前调用本函数。
* information_objects及parameters均为借用,取对象期间报文和参数必须有效且不变。
*/
extern int IEC60870_Parse_ASDU_Header(const IEC60870_AppLayerParameters_t *parameters,
const uint8_t *asdu,
uint16_t asdu_len,
IEC60870_AsduInfo_t *asdu_info);
#ifdef __cplusplus
}
#endif
#endif /* IEC60870_CODEC_H */
@@ -0,0 +1,120 @@
/*
* COMTRADE 1999 编码:生成 ASCII 配置文件和 BINARY 波形数据。
* 调用方持有冻结的录波、元数据及全部输出缓冲;本模块不分配内存,
* 不操作文件系统、平台时钟或通信链路。文件保存与 TI=210 传输由上层负责。
*/
#ifndef IEC60870_COMTRADE_H
#define IEC60870_COMTRADE_H
#include "IEC60870_FaultRecorder.h"
#include "IEC60870_Time.h"
#ifdef __cplusplus
extern "C" {
#endif
/* BAY08_0010_20141114_192135_830.cfg 共 34 字符,另留结尾 NUL;不含目录前缀。 */
#define IEC60870_COMTRADE_FILENAME_CAPACITY 35U
#define IEC60870_COMTRADE_TEXT_MAX 64U
#define IEC60870_COMTRADE_NUMBER_MAX 13U
/* 工程量 = multiplier * DAT 整数值 + offset。
* 系数用十进制 ASCII 字符串传入,避免区域设置影响小数点和目标端浮点 printf。
* 允许正负号、小数点及 e/E 指数;尾数至少一位数字,总长不超过 13 字符,
* 指数绝对值不超过 99。multiplier 必须非零,primary/secondary 必须为正数。
* 通道顺序固定为 Ua/Ub/Uc/U0(V)、Ia/Ib/Ic/I0(A),对应录波帧 analog[]。
* 'P' 表示换算后为一次量,'S' 表示二次量;primary/secondary 描述变比。
* DAT 的 -32768 保留为缺测标记,有效数值范围为 -32767..32767。
* 本模块按原值编码,不限幅,也不把无符号 ADC 计数自动转换成电气量。 */
typedef struct {
const char *multiplier, *offset, *primary, *secondary;
char primary_or_secondary;
} IEC60870_ComtradeAnalog_t;
typedef struct {
const char *station, *device; /* 非空可打印 ASCII,最长 64 字符,禁止逗号。 */
IEC60870_ComtradeAnalog_t analog[IEC60870_FAULT_RECORDER_ANALOG_COUNT];
/* 两数组均按录波的 digital_count 提供元素,顺序对应遥信位顺序。
* 名称数组为 NULL 时生成 D1..D64;常态数组为 NULL 时各通道常态均为 0。
* 名称限制与 station 相同;常态只能为 0 或 1。这些指针均不转移所有权。 */
const char *const *digital_names;
const uint8_t *digital_normal;
/* 捕获触发时刻后保持不变,采用项目本地标准时间 UTC+8,IV=0、SU=0。
* COMTRADE 1999 的日期行不含时区,接收端须按相同时间口径解释。
* trigger_microseconds 仅补足 CP56 毫秒以下的余数,不是整秒内微秒数。 */
IEC60870_CP56Time2a_t trigger_time;
uint16_t trigger_microseconds; /* 毫秒以下的 0..999 微秒。 */
} IEC60870_ComtradeConfig_t;
/**
* 功能:设置默认标识、单位比例系数/变比和自动遥信名;config=NULL 时无操作。
* 输入参数:无。
* 输出参数:config——写入默认配置;NULL时不操作。
* 返回值:无。
* 说明:触发时间仍为无效状态,调用方必须填写实际捕获的时间后才能生成 CFG。
*/
void IEC60870_Comtrade_Config_Default(IEC60870_ComtradeConfig_t *config);
/**
* 功能:根据 READY 状态的冻结录波生成 CFG;成功返回 true,失败返回 false。
* 输入参数:recorder——冻结录波源;config——配置及调用期间借用的元数据;capacity——缓冲可用容量。
* 输出参数:buffer——可选CFG缓冲;容量足够且预检通过后写入文本和终止NUL;length——成功写入不含NUL的CFG长度。
* 返回值:true表示CFG长度查询或完整生成成功;false表示输入、格式边界或容量校验失败。
* 说明:输出为 ASCII、CRLF 换行、无 BOM,末尾附加 NUL;length 不含 NUL, 保存文件时只写 length 字节。buffer=NULL 且 capacity=0
* 可查询所需长度, 实际输出容量必须大于该长度。失败不改输出及 length。 调用期间借用全部元数据,元数据和录波必须保持不变;输入、输出不得重叠。 固定为单采样率、BINARY、时标倍率
* 1;首点时间 = 触发时间减去 trigger_index/rate。小数微秒四舍五入,CFG 起始/触发时刻和 DAT 时标 采用同一舍入规则,因此不能另用“当前时间”代替冻结的触发时间。
* 拒绝超过 1 MHz 的采样率、超出 uint32 的 DAT 长度、达到保留缺测时标 0xffffffff 的时间偏移、非法元数据/日期和落在 2000..2099 以外的首点。
* 不支持闰秒。
*/
bool IEC60870_Comtrade_Build_CFG(const IEC60870_FaultRecorder_t *recorder,
const IEC60870_ComtradeConfig_t *config, char *buffer, size_t capacity,
size_t *length);
/**
* 功能:返回 DAT 的精确字节数;只需不可变的 READY 录波,不依赖 CFG 元数据。
* 输入参数:recorder——冻结录波源。
* 输出参数:size——非NULL长度输出;成功写入DAT总字节数,失败保持原值。
* 返回值:true表示DAT长度已计算;false表示录波未就绪、格式边界或输出指针非法。
* 说明:成功返回 true 并写 size,失败返回 false 且不改 size。
*/
bool IEC60870_Comtrade_Data_Size(const IEC60870_FaultRecorder_t *recorder,
uint32_t *size);
/**
* 功能:从任意字节 offset 开始编码恰好 length 字节,允许在一条采样记录内部开始 或跨多条记录,便于 TI=210 分段读取及重复读取同一偏移。
* 输入参数:recorder——冻结录波源;offset——文件或映像内的字节偏移;length——字节数。
* 输出参数:buffer——编码或复制结果的目标字节区。
* 返回值:true表示请求字节范围已复制;false表示录波、范围或目标缓冲无效。
* 说明:成功返回 true。 每条记录依次为:4 字节点号(从 1 开始)、4 字节相对首点的微秒时标、 8 个 int16 模拟量、向上取整(digital_count/16) 个 uint16
* 遥信字。 多字节字段均为小端;遥信 1 对应首字最低位,末字未使用位清零。 offset==文件大小且 length==0 合法;其他请求必须整体处于文件范围内, 不自动补齐 EOF。
* length 非零时 buffer 不得为 NULL。 从 CFG/DAT 读取开始直到应用最后关闭文件,录波必须保持 READY 且不变, 不得提前 Release。
* 输出不得与录波对象/帧存储重叠;非法参数不改输出。
*/
bool IEC60870_Comtrade_Read_DAT(const IEC60870_FaultRecorder_t *recorder,
uint32_t offset, uint8_t *buffer, size_t length);
/**
* 功能:生成不含目录的 BAY 文件名,data_file=true 选 .dat,否则选 .cfg。
* 输入参数:bay——间隔编号;sequence——顺序号;trigger_time——触发日历;data_file——true生成DAT名称,false生成CFG名称;capacity——缓冲可用容量。
* 输出参数:buffer——编码或复制结果的目标字节区。
* 返回值:true表示文件名已完整生成;false表示参数非法或容量不足,输出不变。
* 说明:bay=1..99、sequence=1..9999,名称精确到触发时刻的毫秒;同一对文件须 使用相同参数。调用方负责按间隔持久化序号、检查重名和添加 COMTRADE 目录。 成功返回
* true;非法时间/参数或容量不足返回 false 且不改 buffer。
*/
bool IEC60870_Comtrade_File_Name(uint8_t bay, uint16_t sequence,
const IEC60870_CP56Time2a_t *trigger_time, bool data_file,
char *buffer, size_t capacity);
/**
* 功能:序号 9999 的下一值为 1;输入 0 或大于 9999 时返回 0 表示非法输入。
* 输入参数:sequence——顺序号。
* 输出参数:无。
* 返回值:1..9999循环序号的下一值;9999回到1,0或大于9999的非法输入返回0。
* 说明:此函数只计算下一值,不保存序号,也不保证对应文件名尚未使用。
*/
uint16_t IEC60870_Comtrade_Next_Sequence(uint16_t sequence);
#ifdef __cplusplus
}
#endif
#endif /* IEC60870_COMTRADE_H */
@@ -0,0 +1,334 @@
/* 电能量冻结持久核心:维护定时冻结、日冻结、潮流反转及封存事实。
* 不依赖堆、线程、文件系统或104协议;与计数量召唤的FRZ命令限定词无关。
* 调用方持有实例和存储,并串行执行全部操作(含查询、恢复和XML导出);
* 存储回调不得重入同一实例。公开时刻均为UTC纪元毫秒,窗口按固定UTC+8划分。
* INTERVAL与DAY保存采样示值;本模块不计算累计值的差分或日用电量。 */
#ifndef IEC60870_ENERGY_FREEZE_H
#define IEC60870_ENERGY_FREEZE_H
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#ifdef __cplusplus
extern "C" {
#endif
/* 三张点表各最多64点;单条反转事件最多携带其中8点。
* 32个存储窗口供循环复用;XML导出层另限制为最近30个已封存窗口。 */
#define IEC60870_ENERGY_FREEZE_MAX_POINTS 64U
#define IEC60870_ENERGY_FREEZE_EVENT_POINTS 8U
#define IEC60870_ENERGY_FREEZE_DAYS 32U
#define IEC60870_ENERGY_FREEZE_SLOTS 96U
#define IEC60870_ENERGY_FREEZE_FLOW_CAPACITY 256U
#define IEC60870_ENERGY_FREEZE_DEDUP 16U
/* 最大记录 = 44字节公共头 + 64组(4字节值+1字节品质) + 4字节CRC。 */
#define IEC60870_ENERGY_FREEZE_WIRE_MAX 368U
/* 固定UTC+8本地2000-01-01 00:00:00至2099-12-31 23:59:59.999。 */
#define IEC60870_ENERGY_FREEZE_UTC_MIN UINT64_C(946656000000)
#define IEC60870_ENERGY_FREEZE_UTC_MAX UINT64_C(4102415999999)
/* INTERVAL/DAY为示值,FLOWREV为事件;SEAL证明窗口封存,META保存恢复边界。 */
typedef enum {
IEC60870_ENERGY_FREEZE_INTERVAL = 1, IEC60870_ENERGY_FREEZE_DAY = 2,
IEC60870_ENERGY_FREEZE_FLOWREV = 3, IEC60870_ENERGY_FREEZE_SEAL = 4,
IEC60870_ENERGY_FREEZE_META = 5
} IEC60870_EnergyFreezeKind_t;
/* ERROR:实例不可用、介质失败或记录损坏;INVALID:调用参数/初始化配置非法;
* CONFIG:持久记录指纹不匹配;TIME_REVERSED:now低于已观测高水位;
* TIME_REJECTED:网格、延迟、保留范围、封存或写入顺序不允许此次冻结;
* CONFLICT:同一冻结位置已有不同值;EMPTY:无记录或无到期任务;
* OK:成功;DUPLICATE:内容相同、未重复写入;SKIPPED:整条冻结品质不合格。
* 不应把正返回值一概当成新提交,也不能由失败推断介质一定未改变。 */
typedef enum {
IEC60870_ENERGY_FREEZE_ERROR = -1, IEC60870_ENERGY_FREEZE_INVALID = -2,
IEC60870_ENERGY_FREEZE_CONFIG = -3, IEC60870_ENERGY_FREEZE_TIME_REVERSED = -4,
IEC60870_ENERGY_FREEZE_TIME_REJECTED = -5, IEC60870_ENERGY_FREEZE_CONFLICT = -6,
IEC60870_ENERGY_FREEZE_EMPTY = 0, IEC60870_ENERGY_FREEZE_OK = 1,
IEC60870_ENERGY_FREEZE_DUPLICATE = 2, IEC60870_ENERGY_FREEZE_SKIPPED = 3
} IEC60870_EnergyFreezeResult_t;
/* Init按值复制此结构,但借用三张点表;表须持续有效且不可重排或修改。
* 每张表内IOA为非零24位地址且不重复;不同表之间不要求地址互斥。 */
typedef struct {
const uint32_t *interval_ioas; /* INTERVAL值数组的点序。 */
const uint32_t *day_ioas; /* DAY值数组的点序,与INTERVAL共用点数。 */
size_t point_count; /* 0..64;0关闭定时冻结,仍可启用FLOWREV。 */
const uint32_t *flowrev_ioas; /* 事件indices引用的独立点表。 */
size_t flowrev_count; /* 0..64;0表示未配置反转事件点。 */
uint32_t value_semantics; /* 应用定义的值含义/单位/映射版本,参与指纹。 */
uint16_t day_start_minutes; /* UTC+8本地窗口起点,0..1425且为15的倍数。 */
uint32_t grid_tolerance_ms; /* 采样时刻距最近15分钟网格的容差,最大60000。 */
uint32_t max_delay_ms; /* now晚于采样时刻的最大延迟,最大900000。 */
} IEC60870_EnergyFreezeConfig_t;
/* 同步逻辑槽接口:kind区分区域,index范围为[0, Slot_Count(kind))。
* read仅在没有已提交记录时返回EMPTY;成功返回OK并写回实际size。
* 已提交数据损坏必须报错,不能退回旧版本或伪装成EMPTY。
* commit返回true承诺原子、持久地替换该槽;回调返回前须消费完bytes。
* 返回false仍可能已落盘,核心随即锁存faulted;须重新Init核验介质后再用。
* context由调用方持有,核心共用wire工作区,回调不得保留其缓冲指针。 */
typedef struct {
void *context;
IEC60870_EnergyFreezeResult_t (*read)(void *context,
IEC60870_EnergyFreezeKind_t kind, uint32_t index, uint8_t *bytes,
size_t capacity, size_t *size);
bool (*commit)(void *context, IEC60870_EnergyFreezeKind_t kind,
uint32_t index, const uint8_t *bytes, size_t size);
} IEC60870_EnergyFreezeStore_t;
typedef struct {
uint32_t day; /* 窗口起始本地日期距1970-01-01的日序,不是YYYYMMDD。 */
uint16_t slot; /* INTERVAL: 1..96;DAY: 0;第1节为窗口起点,第96节为起点+23:45。 */
uint64_t freeze_utc_ms; /* 实际采样时刻,保留与名义网格的偏差。 */
uint64_t observed_utc_ms; /* 提交该记录时传入的now;派生DAY时可晚于采样。 */
size_t count; /* values/quality的有效长度,等于配置point_count。 */
float values[IEC60870_ENERGY_FREEZE_MAX_POINTS];
uint8_t quality[IEC60870_ENERGY_FREEZE_MAX_POINTS];
} IEC60870_EnergyFreezeRecord_t;
typedef struct {
uint64_t sequence; /* 从1开始的持久到达序号,不按occur排序、不回绕。 */
uint64_t occur_utc_ms; /* 原始发生时刻,允许乱序/回拨,不推进冻结观测高水位。 */
size_t count; /* 1..8;事件可保留坏品质/非有限值,XML仅输出有效项。 */
uint8_t indices[IEC60870_ENERGY_FREEZE_EVENT_POINTS]; /* flowrev_ioas的0起始索引,严格递增。 */
float values[IEC60870_ENERGY_FREEZE_EVENT_POINTS];
uint8_t quality[IEC60870_ENERGY_FREEZE_EVENT_POINTS];
} IEC60870_EnergyFreezeFlowReverse_t;
typedef struct {
uint32_t day;
uint64_t observed_utc_ms; /* 封存时的观测时刻。 */
uint8_t bitmap[13]; /* 位0..95对应INTERVAL,位96对应DAY;剩余7位必须为0。 */
uint8_t count; /* 置位数(含DAY),允许0,表示合法封存的空窗口。 */
uint32_t content_crc; /* 日序、位图及按节序排列的记录正文摘要,不含各记录尾CRC。 */
} IEC60870_EnergyFreezeSeal_t;
typedef struct {
bool interval; /* 当前网格有一次可尝试的定时冻结。 */
uint64_t grid_utc_ms; /* interval为true时有效,只是名义时刻,不可冒充实际采样时刻。 */
bool derive_day; /* 有窗口已存第1节且尚缺DAY;可与interval同时为true。 */
uint32_t day; /* derive_day为true时有效,为最早待派生窗口的日序。 */
} IEC60870_EnergyFreezeDue_t;
typedef struct {
bool sealed_valid;
uint32_t sealed_day; /* sealed_valid时有效,为当前连续封存前沿。 */
bool retained_valid;
uint32_t retained_from; /* retained_valid时有效,为32窗口保留下界R。 */
uint32_t seal_backlog; /* 按当前观测高水位计算的待封存窗口数。 */
uint32_t evicted_unsealed; /* 有数据但未封存即被淘汰的窗口累计数,UINT32_MAX饱和。 */
uint64_t observed_utc_ms; /* 已观测now高水位W;0表示尚未观测。 */
uint64_t flow_sequence; /* 最大已提交FLOWREV序号;0表示尚无事件。 */
size_t flow_count; /* 当前保留事件数,最大256。 */
bool faulted; /* 故障锁存后只供诊断,重新Init成功前不再提供正常读写。 */
} IEC60870_EnergyFreezeStatus_t;
/* 公开布局仅用于调用方静态分配;字段由核心维护,不可直接修改。
* Config/Store结构按值复制,点表及store.context仍为借用对象。
* 只缓存存在位图与边界,不缓存全部示值;读操作也会复用wire并可能锁存故障。 */
typedef struct {
IEC60870_EnergyFreezeConfig_t config;
IEC60870_EnergyFreezeStore_t store;
uint32_t fingerprint;
uint32_t retained_from;
uint32_t sealed_day;
uint32_t evicted_unsealed;
uint64_t observed_utc_ms;
uint64_t latest_interval; /* have_interval时有效,该类已写最大名义网格。 */
uint64_t latest_day; /* have_day时有效;补派生较早DAY也不会降低此值。 */
uint64_t flow_sequence;
size_t flow_count;
bool retained_valid;
bool sealed_valid;
bool have_interval;
bool have_day;
bool have_meta;
bool initialized;
bool faulted;
uint8_t present[IEC60870_ENERGY_FREEZE_DAYS][13]; /* 按day % 32寻址的97位存在图。 */
bool seals[IEC60870_ENERGY_FREEZE_DAYS]; /* 同一物理窗口槽是否已封存。 */
uint8_t wire[IEC60870_ENERGY_FREEZE_WIRE_MAX]; /* 序列化/读取共用的临时字节区。 */
} IEC60870_EnergyFreeze_t;
/**
* 功能:清零配置并将网格容差、最大延迟设为1000ms;点表仍须应用填写。
* 输入参数:无。
* 输出参数:config——写入默认配置;NULL时不操作。
* 返回值:无。
* 说明:NULL无操作。
*/
void IEC60870_EnergyFreeze_Config_Default(IEC60870_EnergyFreezeConfig_t *config);
/**
* 功能:存储后端所需逻辑槽数;未知kind返回0,不含后端自己的双bank冗余。
* 输入参数:kind——记录或文件类别。
* 输出参数:无。
* 返回值:该类别的逻辑槽容量;未知类别返回0。
* 说明:不包含后端双bank等冗余,存储后端据此为各类别分配逻辑区域。
*/
uint32_t IEC60870_EnergyFreeze_Slot_Count(IEC60870_EnergyFreezeKind_t kind);
/**
* 功能:将名义网格时刻映射到业务窗口日序;参数或所得日期越界返回UINT32_MAX。
* 输入参数:nominal_utc_ms——名义UTC毫秒,本入口不进行15分钟取整;day_start_minutes——UTC+8午夜起算的业务日界分钟偏移。
* 输出参数:无。
* 返回值:业务窗口起始日序;时刻、日界偏移或归属日非法时返回UINT32_MAX。
* 说明:调用者提供名义时刻,本函数不负责按15分钟取整。
*/
uint32_t IEC60870_EnergyFreeze_Window_Day(uint64_t nominal_utc_ms,
uint16_t day_start_minutes);
/**
* 功能:日序转窗口起点UTC;失败返回false且不写utc_ms。
* 输入参数:day——相对1970-01-01的本地日序;day_start_minutes——UTC+8午夜起算的业务日界分钟偏移。
* 输出参数:utc_ms——成功写入窗口起点UTC毫秒;失败保持原值。
* 返回值:true表示起点已计算并写回;false表示参数无效且输出不变。
* 说明:日期、偏移或utc_ms无效时返回false且不改写输出,成功才填写*utc_ms。
*/
bool IEC60870_EnergyFreeze_Window_Start(uint32_t day, uint16_t day_start_minutes,
uint64_t *utc_ms);
/**
* 功能:初始化/故障后恢复:先读META,再扫描全部记录并核验封存摘要和事件连续性。
* 输入参数:self——调用方持有的模块实例及当前状态;config——配置及调用期间借用的元数据;store——同步存储回调表及其上下文。
* 输出参数:self——本次操作后的运行状态及复用工作区。
* 返回值:OK表示操作完成;INVALID表示参数或操作状态非法;CONFIG表示持久记录与当前配置指纹不符;ERROR表示实例不可用、I/O失败或内容损坏。
* 说明:全空存储可初始化成功;只读介质,不自动修复、清空或改写不兼容记录。 配置指纹不匹配返回CONFIG,介质/内容错误返回ERROR并锁存faulted。
*/
IEC60870_EnergyFreezeResult_t IEC60870_EnergyFreeze_Init(IEC60870_EnergyFreeze_t *self,
const IEC60870_EnergyFreezeConfig_t *config, const IEC60870_EnergyFreezeStore_t *store);
/**
* 功能:推进观测高水位,每次至多封存一个已到窗口结束+max_delay_ms的窗口。
* 输入参数:self——调用方持有的模块实例及当前状态;now_utc_ms——本次观测UTC毫秒。
* 输出参数:self——本次操作后的运行状态及复用工作区。
* 返回值:OK表示操作完成;INVALID表示参数或操作状态非法;ERROR表示实例不可用、I/O失败或内容损坏;CONFIG表示持久记录与当前配置指纹不符;
* TIME_REVERSED表示观测时间低于高水位;TIME_REJECTED表示网格、延迟或窗口顺序不允许。
* 说明:空窗口也可封存;OK可能只推进时间而未封存,积压量通过Get_Status查询。 先提交SEAL事实再提交META提示;后者失败也不能撤销已完成的封存。
*/
IEC60870_EnergyFreezeResult_t IEC60870_EnergyFreeze_Advance(IEC60870_EnergyFreeze_t *self,
uint64_t now_utc_ms);
/**
* 功能:纯查询:不推进观测高水位、不访问介质;只在OK时写out,EMPTY表示无任务。
* 输入参数:self——只读模块实例;now_utc_ms——本次观测UTC毫秒。
* 输出参数:out——仅OK时写入到期名义网格及窗口任务。
* 返回值:OK表示有任务并写出结果;EMPTY表示无任务;INVALID表示参数非法;ERROR表示实例不可用;TIME_REVERSED表示now_utc_ms低于观测高水位。
* 说明:仅提示当前网格之后容差范围内的INTERVAL及可由已存第1节派生的DAY, 不补造错过网格的值。记录时应传实际采样时间,不要把grid_utc_ms当成采样时刻。
*/
IEC60870_EnergyFreezeResult_t IEC60870_EnergyFreeze_Due(const IEC60870_EnergyFreeze_t *self,
uint64_t now_utc_ms, IEC60870_EnergyFreezeDue_t *out);
/**
* 功能:写一条INTERVAL:count必须等于point_count且非0,数组仅在调用期间借用。
* 输入参数:self——调用方持有的模块实例及当前状态;now_utc_ms——本次观测UTC毫秒;freeze_utc_ms——实际采样UTC毫秒;values——按配置点序排列的值;
* quality——与值数组同序的品质;count——数组项数。
* 输出参数:self——本次操作后的运行状态及复用工作区。
* 返回值:OK表示操作完成;DUPLICATE表示已有相同内容,未重复提交;SKIPPED表示整条冻结品质不合格;INVALID表示参数或操作状态非法;ERROR表示实例不可用、I/O失败或内容损坏;
* CONFIG表示持久记录与当前配置指纹不符;TIME_REVERSED表示观测时间低于高水位;TIME_REJECTED表示网格、延迟或窗口顺序不允许;CONFLICT表示已有记录内容不同。
* 说明:freeze按最近15分钟网格归槽,保留实际时刻;now用于延迟及回拨检查。 任一点品质非0或值非有限则整条SKIPPED;同类最新网格值/品质逐字节相同 返回DUPLICATE,
* 不同返回CONFLICT;更旧网格/封存窗等返回TIME_REJECTED。 参数及回拨检查通过即推进内存观测高水位,后续拒绝或跳过不回退该高水位。
*/
IEC60870_EnergyFreezeResult_t IEC60870_EnergyFreeze_Record_Interval(
IEC60870_EnergyFreeze_t *self, uint64_t now_utc_ms, uint64_t freeze_utc_ms,
const float *values, const uint8_t *quality, size_t count);
/**
* 功能:与Record_Interval同一准入规则,但名义网格必须恰为窗口起点,slot固定为0。
* 输入参数:self——调用方持有的模块实例及当前状态;now_utc_ms——本次观测UTC毫秒;freeze_utc_ms——实际采样UTC毫秒;values——按配置点序排列的值;
* quality——与值数组同序的品质;count——数组项数。
* 输出参数:self——本次操作后的运行状态及复用工作区。
* 返回值:OK表示操作完成;DUPLICATE表示已有相同内容,未重复提交;SKIPPED表示整条冻结品质不合格;INVALID表示参数或操作状态非法;ERROR表示实例不可用、I/O失败或内容损坏;
* CONFIG表示持久记录与当前配置指纹不符;TIME_REVERSED表示观测时间低于高水位;TIME_REJECTED表示网格、延迟或窗口顺序不允许;CONFLICT表示已有记录内容不同。
* 说明:freeze_utc_ms归槽后的名义网格须为窗口起点;count须非零且等于point_count。 其余时间、品质、重复/冲突及状态副作用与Record_Interval一致,
* 透传Record结果。
*/
IEC60870_EnergyFreezeResult_t IEC60870_EnergyFreeze_Record_Day(
IEC60870_EnergyFreeze_t *self, uint64_t now_utc_ms, uint64_t freeze_utc_ms,
const float *values, const uint8_t *quality, size_t count);
/**
* 功能:从指定未封存窗口的已存第1节复制DAY,保留原值、品质和freeze,observed取now。
* 输入参数:self——调用方持有的模块实例及当前状态;now_utc_ms——本次观测UTC毫秒;day——相对1970-01-01的本地日序。
* 输出参数:self——本次操作后的运行状态及复用工作区。
* 返回值:OK表示操作完成;DUPLICATE表示已有相同内容,未重复提交;EMPTY表示没有所需记录或到期任务;INVALID表示参数或操作状态非法;ERROR表示实例不可用、I/O失败或内容损坏;
* CONFIG表示持久记录与当前配置指纹不符;TIME_REVERSED表示观测时间低于高水位;TIME_REJECTED表示网格、延迟或窗口顺序不允许;CONFLICT表示已有记录内容不同。
* 说明:不重新采样或检查源记录的提交延迟;源缺失返回EMPTY,已有DAY则比较内容。 可补较早窗口,但不能降低DAY已写最大网格。
*/
IEC60870_EnergyFreezeResult_t IEC60870_EnergyFreeze_Derive_Day(
IEC60870_EnergyFreeze_t *self, uint64_t now_utc_ms, uint32_t day);
/**
* 功能:追加反转事件:1..8个严格递增索引,引用flowrev_ioas,值及品质原样保存。
* 输入参数:self——调用方持有的模块实例及当前状态;occur_utc_ms——事件发生UTC毫秒;indices——FLOWREV点表的索引数组;values——与indices同序排列的事件值;
* quality——与值数组同序的品质;count——数组项数。
* 输出参数:self——本次操作后的运行状态及复用工作区。
* 返回值:OK表示操作完成;DUPLICATE表示已有相同内容,未重复提交;INVALID表示参数或操作状态非法;ERROR表示实例不可用、I/O失败或内容损坏。
* 说明:最近16条按occur、索引、float原始字节和品质完全匹配去重;occur允许倒退。 先提交事件再更新META;任一提交失败后须恢复实例,不可盲目重试。 不推进冻结观测高水位;
* 环满覆盖最旧事件,序号耗尽返回ERROR且不回绕。
*/
IEC60870_EnergyFreezeResult_t IEC60870_EnergyFreeze_Append_FlowReverse(
IEC60870_EnergyFreeze_t *self, uint64_t occur_utc_ms, const uint8_t *indices,
const float *values, const uint8_t *quality, size_t count);
/**
* 功能:读取保留范围内记录,未封存数据也可读;INTERVAL的slot为1..96。
* 输入参数:self——调用方持有的模块实例及当前状态;day——相对1970-01-01的本地日序;slot——冻结节号;INTERVAL为1..96,DAY为0。
* 输出参数:self——复用工作区及读取校验可能锁存的故障状态;out——成功时写入的独立结果副本。
* 返回值:OK表示操作完成;EMPTY表示没有所需记录或到期任务;INVALID表示参数或操作状态非法;ERROR表示实例不可用、I/O失败或内容损坏;CONFIG表示持久记录与当前配置指纹不符。
* 说明:缺测或范围外返回EMPTY;已知存在的记录丢失/损坏则报错并锁存故障。 两个Read接口仅在OK时写out,结果为副本,不借用内部wire。
*/
IEC60870_EnergyFreezeResult_t IEC60870_EnergyFreeze_Read_Interval(
IEC60870_EnergyFreeze_t *self, uint32_t day, uint16_t slot,
IEC60870_EnergyFreezeRecord_t *out);
/**
* 功能:读取指定业务窗口起点的DAY示值,返回记录slot为0,不计算日用电量。
* 输入参数:self——调用方持有的模块实例及当前状态;day——相对1970-01-01的本地日序。
* 输出参数:self——复用工作区及读取校验可能锁存的故障状态;out——成功时写入的独立结果副本。
* 返回值:OK表示操作完成;EMPTY表示没有所需记录或到期任务;INVALID表示参数或操作状态非法;ERROR表示实例不可用、I/O失败或内容损坏;CONFIG表示持久记录与当前配置指纹不符。
* 说明:透传Read_Record结果,仅OK时填写out;普通缺测或保留范围外返回EMPTY。
*/
IEC60870_EnergyFreezeResult_t IEC60870_EnergyFreeze_Read_Day(
IEC60870_EnergyFreeze_t *self, uint32_t day, IEC60870_EnergyFreezeRecord_t *out);
/**
* 功能:当前保留事件条数;实例未就绪/故障时返回0,可用Get_Status区分故障与空库。
* 输入参数:self——只读模块实例。
* 输出参数:无。
* 返回值:当前保留的FLOWREV事件数;实例不可用时返回0。
* 说明:不能以0单独判断空库,应结合Get_Status检查健康状态。
*/
size_t IEC60870_EnergyFreeze_FlowReverse_Count(const IEC60870_EnergyFreeze_t *self);
/**
* 功能:oldest_index从0起按持久序号由旧到新读取;越界EMPTY,仅OK时写out。
* 输入参数:self——调用方持有的模块实例及当前状态;oldest_index——按提交顺序从最旧记录起的零基索引。
* 输出参数:self——复用工作区及读取校验可能锁存的故障状态;out——成功时写入的独立结果副本。
* 返回值:OK表示操作完成;EMPTY表示没有所需记录或到期任务;INVALID表示参数或操作状态非法;ERROR表示实例不可用、I/O失败或内容损坏。
* 说明:仅OK时填写out,越界返回EMPTY,参数或实例/读取错误返回相应结果。 应存在的事件读取失败或序号不符会锁存故障;不按occur墙钟排序。
*/
IEC60870_EnergyFreezeResult_t IEC60870_EnergyFreeze_Get_FlowReverse(
IEC60870_EnergyFreeze_t *self, size_t oldest_index, IEC60870_EnergyFreezeFlowReverse_t *out);
/**
* 功能:内存状态快照,不访问介质;faulted实例仍可诊断(Init失败时可能是部分恢复状态)。
* 输入参数:self——只读模块实例。
* 输出参数:out——诊断快照,允许Init失败后faulted的部分状态;失败不变。
* 返回值:true表示已复制诊断快照;false表示指针无效或实例既未初始化也未故障。
* 说明:参数无效或既未初始化又未故障时返回false,out保持不变。
*/
bool IEC60870_EnergyFreeze_Get_Status(const IEC60870_EnergyFreeze_t *self,
IEC60870_EnergyFreezeStatus_t *out);
/**
* 功能:Get_Seal读取封存记录自身,不扫描数据正文;无封存返回EMPTY,仅OK时写out。
* 输入参数:self——调用方持有的模块实例及当前状态;day——相对1970-01-01的本地日序。
* 输出参数:self——复用工作区及读取校验可能锁存的故障状态;out——成功时写入的独立结果副本。
* 返回值:OK表示操作完成;EMPTY表示没有所需记录或到期任务;INVALID表示参数或操作状态非法;ERROR表示实例不可用、I/O失败或内容损坏。
* 说明:SEAL一旦提交即是封存事实,后续数据缺失不能退化成缺测;空窗有count=0的合法SEAL。 Validate_Seal另扫描全部97个位置,核对存在位图及规范内容摘要。
* XML导出必须校验通过后才能发布,整个过程禁止并发修改核心或介质。
*/
IEC60870_EnergyFreezeResult_t IEC60870_EnergyFreeze_Get_Seal(
IEC60870_EnergyFreeze_t *self, uint32_t day, IEC60870_EnergyFreezeSeal_t *out);
/**
* 功能:验证SEAL的存在位图及正文摘要,空封存同样验证;整个过程须串行独占。
* 输入参数:self——调用方持有的模块实例及当前状态;day——相对1970-01-01的本地日序。
* 输出参数:self——复用工作区及读取校验可能锁存的故障状态。
* 返回值:OK表示操作完成;EMPTY表示没有所需记录或到期任务;INVALID表示参数或操作状态非法;ERROR表示实例不可用、I/O失败或内容损坏;CONFIG表示持久记录与当前配置指纹不符。
* 说明:全部一致返回OK,无封存返回EMPTY,参数/读取错误透传;摘要不符返回ERROR。 不修改介质,但正文缺失、意外增添或摘要不符会锁存faulted。
*/
IEC60870_EnergyFreezeResult_t IEC60870_EnergyFreeze_Validate_Seal(
IEC60870_EnergyFreeze_t *self, uint32_t day);
#ifdef __cplusplus
}
#endif
#endif
@@ -0,0 +1,67 @@
/*
* 附录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 */
@@ -0,0 +1,348 @@
/*
* Type42故障事件信息完整ASDU:两组异构记录共用链路IOA宽度,计数位于报文体。
* 此处采用故障事件扩展布局,不属于基础IEC标准定义的Type42对象。
* 两组记录分别携带数量和类型,不能在首记录前补普通外层IOA或在遥测值后补QDS。
* 编码先验证全部输入和容量,再写入;解析先验证整帧,再发布借用视图。
* 本模块只负责冻结简报的字节契约;故障判据、连续录波与上送先后分别由调用方组织,
* 不能用本模块的编码成功推断故障已经送达,或推断相应录波文件已经可靠保存。
*/
#include "IEC60870_FaultEvent.h"
#include "IEC60870_InformationObjects_Internal.h"
#include <float.h>
#include <math.h>
#include <string.h>
/* 后续memcpy只转换位模式,不转换数值格式;编译期先确认宿主float就是所需binary32。 */
_Static_assert(sizeof(float) == sizeof(uint32_t) && FLT_RADIX == 2 &&
FLT_MANT_DIG == 24 && FLT_MAX_EXP == 128, "Fault event requires binary32 float");
/**
* 功能:计算ASDU公共头长度,不含APCI或任何IOA。
* 输入参数:已验证的parameters
* 输出参数:无
* 返回值:2+COT宽度+CA宽度。
* 说明:前提:调用方已通过AppLayerParameters_Valid,固定2字节分别为TI和VSQ。
*/
static unsigned int Fault_Event_Header_Size(const IEC60870_AppLayerParameters_t *parameters)
{
return (unsigned int)(2 + parameters->sizeOfCOT + parameters->sizeOfCA);
}
/**
* 功能:按内部遥信类型选择完整SIQ/DIQ允许位。
* 输入参数:type为报文体的类型字段
* 输出参数:无
* 返回值:单点0xF1、双点0xF3,未定义类型为0。
* 说明:状态位和品质位均保留;0只表示类型非法,不是某个遥信状态。 只接收1/3/30/31,其他编号一律拒绝,不能默认作为双点处理。
*/
static uint8_t Fault_Event_Signal_Mask(uint8_t type)
{
if (type == IEC60870_ASDU_M_SP_NA_1 || type == IEC60870_ASDU_M_SP_TB_1) { return 0xF1U; }
if (type == IEC60870_ASDU_M_DP_NA_1 || type == IEC60870_ASDU_M_DP_TB_1) { return 0xF3U; }
return 0U;
}
/**
* 功能:取得单个遥测值的线上字节数,不含IOA。
* 输入参数:内部遥测类型
* 输出参数:无
* 返回值:13为4,9/11为2,其他为0表示不支持。
* 说明:两种分支都没有QDS;即使该组数量为0,也必须显式使用支持的类型。
*/
static unsigned int Fault_Event_Value_Size(uint8_t type)
{
if (type == IEC60870_ASDU_M_ME_NC_1) { return 4U; }
if (type == IEC60870_ASDU_M_ME_NA_1 || type == IEC60870_ASDU_M_ME_NB_1) { return 2U; }
return 0U;
}
/**
* 功能:验证本扩展允许的公共头语义及CA宽度。
* 输入参数:已验证的parameters,允许NULL的header
* 输出参数:无
* 返回值:1合法,0非法。
* 说明:前提:parameters有效;OA成员自身为uint8_t,COT为1字节时不编码OA。 CA为0或广播值的业务限制交由发布层处理,此处不查站注册。
*/
static int Fault_Event_Header_Valid(const IEC60870_AppLayerParameters_t *parameters,
const IEC60870_AsduHeader_t *header)
{
return header != NULL && header->cause_of_transmission == IEC60870_ASDU_COT_SPONTANEOUS &&
header->is_negative_confirm == 0U && header->is_test <= 1U &&
(parameters->sizeOfCA == 2 || header->common_address <= UINT8_MAX);
}
/**
* 功能:验证冻结记录的数量、类型、地址、状态、日历时标和有限浮点值。
* 输入参数:已验证的parameters,允许NULL的event
* 输出参数:无
* 返回值:1完整合法,0任一字段非法。
* 说明:前提:非空数组至少含其声明数量,调用期间输入有效且不变;先限制数量再访问数组。 N/M为0时不解引用对应数组,但不跳过类型校验;IOA仅查宽度,允许公共层的零地址。
* 仅用7字节时间暂存验证日期,不分配整帧临时数组,不把超过容量误归为内容错误。 编码写出阶段依赖这次全量校验,因此输入不可变要求必须贯穿整个Encode调用。
*/
static int Fault_Event_Input_Valid(const IEC60870_AppLayerParameters_t *parameters,
const IEC60870_FaultEvent_t *event)
{
uint32_t max_ioa = IEC60870_Object_Max_IOA(parameters);
uint8_t time_bytes[IEC60870_CP56_LEN];
uint8_t signal_mask;
size_t i;
if (event == NULL || event->signal_count > UINT8_MAX || event->measurement_count > UINT8_MAX ||
(event->signal_count != 0U && event->signals == NULL) ||
(event->measurement_count != 0U && event->measurements == NULL)) { return 0; }
signal_mask = Fault_Event_Signal_Mask(event->signal_type);
if (signal_mask == 0U || Fault_Event_Value_Size(event->measurement_type) == 0U) { return 0; }
for (i = 0U; i < event->signal_count; ++i) {
const IEC60870_FaultEventSignal_t *signal = &event->signals[i];
if (signal->ioa > max_ioa || (signal->value & (uint8_t)~signal_mask) != 0U ||
!IEC60870_Time_To_CP56(&signal->timestamp, time_bytes, sizeof(time_bytes))) { return 0; }
}
for (i = 0U; i < event->measurement_count; ++i) {
const IEC60870_FaultEventMeasurement_t *measurement = &event->measurements[i];
if (measurement->ioa > max_ioa ||
(event->measurement_type == IEC60870_ASDU_M_ME_NC_1 &&
!isfinite(measurement->value.short_float))) { return 0; }
}
return 1;
}
/**
* 功能:重置描述并选择默认内部类型30/13。 输入/
* 输入参数:无。
* 输出参数:调用方可写event,NULL无操作
* 返回值:无。
* 说明:只清描述,不操作原数组;默认13支持负电气量,避免负整数原码被按无符号数解释。
*/
void IEC60870_FaultEvent_Init(IEC60870_FaultEvent_t *event)
{
if (event == NULL) { return; }
memset(event, 0, sizeof(*event));
event->signal_type = IEC60870_ASDU_M_SP_TB_1;
event->measurement_type = IEC60870_ASDU_M_ME_NC_1;
}
/**
* 功能:把完整冻结快照编码为一条Type42 ASDU。
* 输入参数:parameters/header/event及out容量,具体字段范围见公开头文件。
* 输出参数:仅成功时写out原文和out_length总长
* 返回值:OK、字段ERROR或容量FULL。
* 说明:前提:输入在调用内有效且不变,输入/输出及两个输出之间不重叠;调用方串行使用这些存储。 字段校验先于容量校验,确保坏记录即使同时装不下也返回ERROR;不隐式拆分或部分成功。
*/
IEC60870_AsduResult_t IEC60870_FaultEvent_Encode(
const IEC60870_AppLayerParameters_t *parameters,
const IEC60870_AsduHeader_t *header, const IEC60870_FaultEvent_t *event,
uint8_t *out, uint16_t capacity, uint16_t *out_length)
{
size_t required, i;
unsigned int header_size, address_size, value_size;
uint8_t *cursor;
if (out == NULL || out_length == NULL || !IEC60870_AppLayerParameters_Valid(parameters) ||
!Fault_Event_Header_Valid(parameters, header) || !Fault_Event_Input_Valid(parameters, event)) {
return IEC60870_ASDU_ERROR;
}
header_size = Fault_Event_Header_Size(parameters);
address_size = (unsigned int)parameters->sizeOfIOA;
value_size = Fault_Event_Value_Size(event->measurement_type);
/* 设L为统一IOA宽度、V为遥测值宽度:每条遥信为L+1(SIQ/DIQ)+7(CP56)=L+8,
* 每条遥测为L+V;额外4字节是N、遥信类型、M、遥测类型,不是4个计数。
* 数量先限制到255后计算,最大和小于8192,避免按截窄后的数量接受过长快照。 */
required = header_size + 4U + event->signal_count * (address_size + 8U) +
event->measurement_count * (address_size + value_size);
if (required > capacity || required > (size_t)parameters->maxSizeOfASDU) { return IEC60870_ASDU_FULL; }
/* 此后所有内容已验证;只有成功路径写调用方缓冲,失败不会残留半条事件。
* VSQ只是固定占位,不能随内部记录数量累加;公共头后立即是N,没有外层IOA。 */
out[0] = IEC60870_ASDU_M_FT_NA_1;
out[1] = 1U;
out[2] = (uint8_t)(header->cause_of_transmission | (header->is_test ? 0x80U : 0U));
if (parameters->sizeOfCOT == 2) { out[3] = header->originator_address; }
IEC60870_Object_Write_LE(out + 2U + (unsigned int)parameters->sizeOfCOT,
header->common_address, (unsigned int)parameters->sizeOfCA);
cursor = out + header_size;
*cursor++ = (uint8_t)event->signal_count;
*cursor++ = event->signal_type;
for (i = 0U; i < event->signal_count; ++i) {
const IEC60870_FaultEventSignal_t *signal = &event->signals[i];
IEC60870_Object_Write_LE(cursor, signal->ioa, address_size);
cursor += address_size;
*cursor++ = signal->value;
/* 同一日历已经用等长暂存验证;输入不可变且与out不重叠时,此调用必然成功。
* 因而忽略返回值并非容忍坏时间,也不能据此允许编码中途修改采集数组。
* CP56输出保留日历及IV/SU,星期/GEN按时间库规则规范化,不承诺原七字节回显。 */
(void)IEC60870_Time_To_CP56(&signal->timestamp, cursor, IEC60870_CP56_LEN);
cursor += IEC60870_CP56_LEN;
}
*cursor++ = (uint8_t)event->measurement_count;
*cursor++ = event->measurement_type;
for (i = 0U; i < event->measurement_count; ++i) {
const IEC60870_FaultEventMeasurement_t *measurement = &event->measurements[i];
uint32_t raw;
IEC60870_Object_Write_LE(cursor, measurement->ioa, address_size);
cursor += address_size;
/* memcpy取得binary32位模式,避免float*到整数指针的别名/对齐问题;
* 再按整数逐字节写LE,不把宿主内存字节序直接复制到线上。2字节分支仅传无符号原码。 */
if (value_size == 4U) { memcpy(&raw, &measurement->value.short_float, sizeof(raw)); }
else { raw = measurement->value.unsigned_value; }
IEC60870_Object_Write_LE(cursor, raw, value_size);
cursor += value_size;
}
*out_length = (uint16_t)required;
return IEC60870_ASDU_OK;
}
/**
* 功能:验证并读取一条遥信记录,不处理外层公共头。
* 输入参数:record至少含L+8字节,address_size为1..3,signal_type已确认为支持类型。
* 输出参数:signal非NULL时仅在成功后赋值;NULL用于整帧预检
* 返回值:1合法,0状态/CP56非法。
* 说明:前提:调用方已经验证完整记录边界,输出不与输入重叠;本函数不再次检查长度或类型。 局部结果先初始化后发布,保留完整SIQ/DIQ,不按接收端界面文字重映射状态。
*/
static int Fault_Event_Read_Signal(const uint8_t *record, unsigned int address_size,
uint8_t signal_type, IEC60870_FaultEventSignal_t *signal)
{
IEC60870_FaultEventSignal_t result;
uint8_t mask = Fault_Event_Signal_Mask(signal_type);
memset(&result, 0, sizeof(result));
result.ioa = IEC60870_Object_Read_LE(record, address_size);
result.value = record[address_size];
if ((result.value & (uint8_t)~mask) != 0U ||
!IEC60870_Time_From_CP56(record + address_size + 1U, IEC60870_CP56_LEN,
&result.timestamp)) { return 0; }
if (signal != NULL) { *signal = result; }
return 1;
}
/**
* 功能:验证并读取一条遥测记录;不添加品质或时标。
* 输入参数:record至少含L+V字节,address_size为1..3,value_size已确认为2或4。
* 输出参数:measurement非NULL时仅在成功后赋值;NULL仅预检
* 返回值:1合法,0浮点非有限。
* 说明:前提:调用方已验证边界和类型,输出不与输入重叠。 先按LE读成整数位模式,再memcpy为float,避免指针别名及未对齐读;2字节保持uint16_t原码。
*/
static int Fault_Event_Read_Measurement(const uint8_t *record, unsigned int address_size,
unsigned int value_size, IEC60870_FaultEventMeasurement_t *measurement)
{
IEC60870_FaultEventMeasurement_t result;
uint32_t raw = IEC60870_Object_Read_LE(record + address_size, value_size);
memset(&result, 0, sizeof(result));
result.ioa = IEC60870_Object_Read_LE(record, address_size);
if (value_size == 4U) {
memcpy(&result.value.short_float, &raw, sizeof(raw));
if (!isfinite(result.value.short_float)) { return 0; }
} else { result.value.unsigned_value = (uint16_t)raw; }
if (measurement != NULL) { *measurement = result; }
return 1;
}
/**
* 功能:验证两组异构记录的完整ASDU并建立借用视图。
* 输入参数:parameters及asdu/length
* 输出参数:仅完整成功后写view
* 返回值:OK或ERROR。
* 说明:前提:输入存储在解析和取值期间有效且不变,view与输入不重叠。 公共头解析不负责Type42对象长度,必须继续验证内部两组计数、精确总长和每条载荷。 N/M为0不免除两组类型字段;
* VSQ完全不参与记录数和步长推导。
*/
IEC60870_AsduResult_t IEC60870_FaultEvent_Parse(
const IEC60870_AppLayerParameters_t *parameters,
const uint8_t *asdu, uint16_t length, IEC60870_FaultEventView_t *view)
{
IEC60870_AsduInfo_t header;
IEC60870_FaultEventView_t result;
size_t signal_size, measurement_offset, expected, i;
unsigned int address_size, value_size;
const uint8_t *body;
if (view == NULL || !IEC60870_Parse_ASDU_Header(parameters, asdu, length, &header) ||
header.type_id != IEC60870_ASDU_M_FT_NA_1 ||
header.cause_of_transmission != IEC60870_ASDU_COT_SPONTANEOUS || header.is_negative_confirm ||
header.information_objects_len < 4U) { return IEC60870_ASDU_ERROR; }
body = header.information_objects;
address_size = (unsigned int)parameters->sizeOfIOA;
signal_size = address_size + 8U;
/* body前2字节是N和遥信类型,随后N*(L+8)字节才到M;
* 先确认M及遥测类型这2字节都存在,再读取第二组,不能先读后补边界检查。
* VSQ的低7位和SQ均不参与此计算。 */
measurement_offset = 2U + (size_t)body[0] * signal_size;
if (Fault_Event_Signal_Mask(body[1]) == 0U || measurement_offset + 2U > header.information_objects_len) {
return IEC60870_ASDU_ERROR;
}
value_size = Fault_Event_Value_Size(body[measurement_offset + 1U]);
/* 精确相等同时拒绝截短和尾随数据,包括误加的遥测QDS;
* 不允许只解析可用前缀后把余下记录留给上层猜测。 */
expected = measurement_offset + 2U + (size_t)body[measurement_offset] * (address_size + value_size);
if (value_size == 0U || expected != header.information_objects_len) { return IEC60870_ASDU_ERROR; }
for (i = 0U; i < body[0]; ++i) {
if (!Fault_Event_Read_Signal(body + 2U + i * signal_size, address_size, body[1], NULL)) {
return IEC60870_ASDU_ERROR;
}
}
for (i = 0U; i < body[measurement_offset]; ++i) {
if (!Fault_Event_Read_Measurement(body + measurement_offset + 2U + i * (address_size + value_size),
address_size, value_size, NULL)) { return IEC60870_ASDU_ERROR; }
}
/* 两组所有记录均已通过检查,此时才形成可对外发布的视图;
* 只复制头字段和位置元数据,不复制参数或原文,不延长它们的存储寿命。 */
memset(&result, 0, sizeof(result));
result.header.cause_of_transmission = header.cause_of_transmission;
result.header.is_negative_confirm = header.is_negative_confirm;
result.header.is_test = header.is_test;
result.header.originator_address = header.originator_address;
result.header.common_address = header.common_address;
result.parameters = parameters;
result.asdu = asdu;
result.length = length;
result.signal_count = body[0];
result.signal_type = body[1];
result.measurement_count = body[measurement_offset];
result.measurement_type = body[measurement_offset + 1U];
*view = result;
return IEC60870_ASDU_OK;
}
/**
* 功能:从有效借用视图中按值读取第index条遥信。
* 输入参数:view及从0开始的index
* 输出参数:仅成功后写signal
* 返回值:OK或ERROR。
* 说明:前提:view由Parse建立,参数及原文有效且不变,输出与它们不重叠。 重新检查整帧后才按计数定位,避免别组损坏时仍返回一条看似有效的记录。 重检不是并发保护,也不能检查原文是否已释放;
* 调用方仍负责寿命和串行访问。
*/
IEC60870_AsduResult_t IEC60870_FaultEvent_Get_Signal(
const IEC60870_FaultEventView_t *view, size_t index,
IEC60870_FaultEventSignal_t *signal)
{
IEC60870_FaultEventView_t checked;
unsigned int address_size;
const uint8_t *record;
if (view == NULL || signal == NULL ||
IEC60870_FaultEvent_Parse(view->parameters, view->asdu, view->length, &checked) != IEC60870_ASDU_OK ||
index >= checked.signal_count) { return IEC60870_ASDU_ERROR; }
address_size = (unsigned int)checked.parameters->sizeOfIOA;
record = checked.asdu + Fault_Event_Header_Size(checked.parameters) + 2U + index * (address_size + 8U);
return Fault_Event_Read_Signal(record, address_size, checked.signal_type, signal) ?
IEC60870_ASDU_OK : IEC60870_ASDU_ERROR;
}
/**
* 功能:从有效借用视图中按值读取第index条遥测。
* 输入参数:view及从0开始的index
* 输出参数:仅成功后写measurement
* 返回值:OK或ERROR。
* 说明:前提:与Get_Signal相同,重检原文不撤销不可变/存储寿命要求。 从公共头后跳过4个数量/类型字节与整组遥信,再按L+V定位; 只产生值和地址,不把读取时刻当成故障时间。
*/
IEC60870_AsduResult_t IEC60870_FaultEvent_Get_Measurement(
const IEC60870_FaultEventView_t *view, size_t index,
IEC60870_FaultEventMeasurement_t *measurement)
{
IEC60870_FaultEventView_t checked;
unsigned int address_size, value_size;
const uint8_t *record;
if (view == NULL || measurement == NULL ||
IEC60870_FaultEvent_Parse(view->parameters, view->asdu, view->length, &checked) != IEC60870_ASDU_OK ||
index >= checked.measurement_count) { return IEC60870_ASDU_ERROR; }
address_size = (unsigned int)checked.parameters->sizeOfIOA;
value_size = Fault_Event_Value_Size(checked.measurement_type);
record = checked.asdu + Fault_Event_Header_Size(checked.parameters) + 4U +
(size_t)checked.signal_count * (address_size + 8U) + index * (address_size + value_size);
return Fault_Event_Read_Measurement(record, address_size, value_size, measurement) ?
IEC60870_ASDU_OK : IEC60870_ASDU_ERROR;
}
@@ -0,0 +1,146 @@
/*
* Type42故障事件信息:扩展格式的完整ASDU编解码,101/104共用。
* 此处内部字段采用已确认的接收端格式约定,不是基础IEC 101/104对保留编号42的定义。
* 公共头之后是两组数量/类型和记录,无普通信息对象的外层IOA。
* 遥信数量N、遥信类型、遥测数量M、遥测类型四个字段各占1字节,其中只有N/M是数量。
* 每组共用一个内部类型;两类IOA均使用同一链路宽度L,类型字段本身不是一条普通ASDU。
* 输入快照、输出缓冲和解析视图均由调用方持有;不分配内存、不读取系统时间。
*/
#ifndef IEC60870_FAULT_EVENT_H
#define IEC60870_FAULT_EVENT_H
#include "IEC60870_Asdu.h"
#ifdef __cplusplus
extern "C" {
#endif
/* 同一报文的遥信类型统一为1/3/30/31;四种类型均带CP56,不按类型省略时标。
* value是完整SIQ/DIQ:单点只允许0xF1中的位,双点只允许0xF3中的位。
* 位掩码校验允许状态和合法品质同时存在,调用方不能把value误当成单独的0/1或0..3。
* 接收端对完整状态字节的显示判断可能与状态位解释不同;本层不为界面显示抹去品质位。
* 双点状态按原始两位码保留,不根据接收端显示文字重映射状态。
* timestamp表示已冻结的日历时间及IV/SU;它不是可原样回显的七字节时标副本。 */
typedef struct {
uint32_t ioa;
uint8_t value;
IEC60870_CP56Time2a_t timestamp;
} IEC60870_FaultEventSignal_t;
/* 类型13读取short_float;9/11读取unsigned_value原始16位码。
* 此扩展格式将2字节测量值按无符号原码处理,本接口不做有符号转换、归一化或倍率换算。
* 因此需传负值时优先使用类型13;把负整数转成uint16_t只会保留补码,不能保留负值语义。
* 测量值后没有QDS,报文里也没有独立遥测时标;应用必须传入故障时刻的值。 */
typedef struct {
uint32_t ioa;
union {
uint16_t unsigned_value;
float short_float;
} value;
} IEC60870_FaultEventMeasurement_t;
/* 两组数量均为0..255;非零数量要求对应数组非NULL。
* 数量使用size_t保留调用方原值,编码前检查255上限,不通过截窄接受更大的数组。
* N=0或M=0不省略对应数量/类型字段,两组都空仍保留这4字节;内部类型仍须合法。
* 公共编码层允许任一组为空,不检查电气量种类、点表、重复地址或故障业务完整性。
* 业务上送入口另外要求故障遥信及八项必要电气量。
* 数组只在Encode调用期间借用;等待重试的调用方必须保留同一份冻结快照。 */
typedef struct {
uint8_t signal_type;
uint8_t measurement_type;
const IEC60870_FaultEventSignal_t *signals;
size_t signal_count;
const IEC60870_FaultEventMeasurement_t *measurements;
size_t measurement_count;
} IEC60870_FaultEvent_t;
/* Parse成功建立的只读借用视图;调用方不得修改其字段。
* parameters和asdu须在取记录期间保持有效且内容不变;Getter输出按值复制。
* 数量取自报文体,独立于VSQ;header不将VSQ解释为记录个数。
* Getter重新校验报文是失败原子性的保障,不授权调用方修改借用输入,也不能检测悬空指针。
* 报文缓冲需复用时,应先完成取值或自行保存原文,再为新原文重新Parse。 */
typedef struct {
IEC60870_AsduHeader_t header;
const IEC60870_AppLayerParameters_t *parameters;
const uint8_t *asdu;
uint16_t length;
uint8_t signal_type;
uint8_t signal_count;
uint8_t measurement_type;
uint8_t measurement_count;
} IEC60870_FaultEventView_t;
/**
* 功能:初始化调用方持有的故障快照描述,不申请或释放数组。
* 输入参数:event——可写描述,允许NULL;原有数组指针不会被释放。
* 输出参数:event——默认遥信30、遥测13,其余成员清零。
* 返回值:无;NULL时不操作。
* 说明:默认短浮点便于保存有符号电气量,避免2字节负值原码被按无符号数解释。
* 初始化不创建时标或点表,也不表示已具备业务上送要求的遥信和八项测量。
*/
void IEC60870_FaultEvent_Init(IEC60870_FaultEvent_t *event);
/**
* 功能:预检完整故障快照后编码一条ASDU,不含APCI,不自动拆分。
* 输入参数:parameters——合法链路参数,两类地址均按sizeOfIOA低字节在前编码。
* header——COT=3、P/N=0,TEST为0/1;CA仅检查宽度,不检查站注册或业务地址范围。
* event——两组冻结记录,类型和数量即使在数组为空时仍须合法。
* capacity——out实际可写字节数;总长还受maxSizeOfASDU限制。
* 输出参数:out/out_length——仅OK时写入完整原文及包含公共头的总长。
* 返回值:OK成功;非法字段/指针返回ERROR;内容合法但容量不足返回FULL。
* 前提:调用期间所有输入保持有效且不变;输入与输出、两个输出之间均不得重叠。
* 说明:先完整检查字段,再检查容量;同一输入兼有字段错误与容量不足时返回ERROR。
* VSQ固定0x01作为占位,不表示内部遥信或遥测数量;无独立遥信地址宽度。
* 短浮点仅接受有限binary32;CP56保留日历及IV/SU,不取当前时间、不换算时区。
* CP56在has_weekday=1时按日期生成星期,否则星期填0;GEN固定为0,其余保留位清零。
* 编解码保留时间语义,不能原样回显收到的七字节时标。
* 本专用入口不走Asdu_Add_InformationObject,也不创建普通对象函数表。
*/
IEC60870_AsduResult_t IEC60870_FaultEvent_Encode(
const IEC60870_AppLayerParameters_t *parameters,
const IEC60870_AsduHeader_t *header, const IEC60870_FaultEvent_t *event,
uint8_t *out, uint16_t capacity, uint16_t *out_length);
/**
* 功能:校验完整Type42原文及每条记录,建立供逐项读取的借用视图。
* 输入参数:parameters——对应原文的链路参数;asdu/length——不含APCI的完整ASDU及总长。
* 输出参数:view——全部校验成功后写入公共头、两组数量/类型及借用引用;失败不变。
* 返回值:OK成功;非法参数、类型、内容或长度一律返回ERROR,不返回半份解析结果。
* 前提:输出不与输入重叠;输入存储在Parse及后续Getter期间保持有效且不变。
* 说明:仅接受Type42、COT=3/P/N=0及明确支持的内部类型,TEST保留;VSQ的数值和SQ被忽略。
* 按两组计数核对精确总长,既拒绝截短,也拒绝额外尾字节,不用前缀成功掩盖后半帧错误。
* 普通Asdu_Parse仍只解析普通对象布局,Type42须调用本入口。
*/
IEC60870_AsduResult_t IEC60870_FaultEvent_Parse(
const IEC60870_AppLayerParameters_t *parameters,
const uint8_t *asdu, uint16_t length, IEC60870_FaultEventView_t *view);
/**
* 功能:按值取出指定遥信及其CP56日历,不再借用单条记录。
* 输入参数:view——Parse建立的有效视图;index——从0开始,须小于遥信数量N。
* 输出参数:signal——完整地址、SIQ/DIQ和时标;失败保持不变。
* 返回值:OK成功;NULL、越界或借用原文校验失败返回ERROR。
* 前提:输出不与view、parameters或原文重叠;原文/参数寿命和不可变要求仍适用。
* 说明:重验整帧后才输出该记录;不读取系统时间,也不改变视图。
* CP56解析输出为日历语义,星期重新推导且不保存GEN,不能代替原始七字节时标。
*/
IEC60870_AsduResult_t IEC60870_FaultEvent_Get_Signal(
const IEC60870_FaultEventView_t *view, size_t index,
IEC60870_FaultEventSignal_t *signal);
/**
* 功能:按值取出指定遥测;类型13输出float,9/11输出uint16_t原码。
* 输入参数:view——Parse建立的有效视图;index——从0开始,须小于遥测数量M。
* 输出参数:measurement——完整地址及所选类型的值成员;失败保持不变。
* 返回值:OK成功;NULL、越界或借用原文校验失败返回ERROR。
* 前提:输出不与view、parameters或原文重叠;输入存储仍须有效且不变。
* 说明:重验整帧不表示允许并发修改原文;本函数不缩放数值,也不补造QDS或接收时刻。
*/
IEC60870_AsduResult_t IEC60870_FaultEvent_Get_Measurement(
const IEC60870_FaultEventView_t *view, size_t index,
IEC60870_FaultEventMeasurement_t *measurement);
#ifdef __cplusplus
}
#endif
#endif /* IEC60870_FAULT_EVENT_H */
@@ -0,0 +1,176 @@
/*
* 模块:故障录波采样缓存。
* 职责:保存连续瞬时采样的故障前历史,按采样序号触发,收齐故障后窗口后冻结记录。
* 本模块不采集硬件、不生成波形、不写文件;不依赖 RTOS、时钟或传输层,也不分配内存。
* 调用者提供控制对象和采样数组,并负责实际采样率、同一时刻性及调用串行化。
*/
#ifndef IEC60870_FAULT_RECORDER_H
#define IEC60870_FAULT_RECORDER_H
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#ifdef __cplusplus
extern "C" {
#endif
#define IEC60870_FAULT_RECORDER_ANALOG_COUNT 8U
#define IEC60870_FAULT_RECORDER_MAX_DIGITAL 64U
#define IEC60870_FAULT_RECORDER_DIGITAL_WORDS 4U
/* 一帧必须来自同一采样时刻:模拟量依次为 Ua、Ub、Uc、U0、Ia、Ib、Ic、I0。
* 保存输入的瞬时整数值,不做有效值、相量或标度换算;物理单位和系数由导出层说明。
* 遥信第 1 路为 digital[0] 的 bit 0,后续通道依次排列;未配置的位在入队时清零。 */
typedef struct {
int16_t analog[IEC60870_FAULT_RECORDER_ANALOG_COUNT];
uint16_t digital[IEC60870_FAULT_RECORDER_DIGITAL_WORDS];
} IEC60870_FaultRecorderFrame_t;
typedef struct {
uint32_t sample_rate_hz; /* 实际输入帧率;须不少于额定频率的 80 倍。 */
uint32_t nominal_frequency_hz; /* 窗口计算使用的额定频率,不能为 0。 */
uint32_t pre_cycles; /* 不少于 4;前后时长均向上取整到完整采样间隔。 */
uint32_t post_cycles; /* 不少于 8;窗口两端点及触发点都保留。 */
uint16_t digital_count; /* 有效遥信通道数:1..64。 */
} IEC60870_FaultRecorderConfig_t;
/* 主流程:ARMED -> CAPTURING -> READY;迟触发也可从 ARMED 直接完成到 READY。
* CAPTURING 遇到不连续采样进入 FAILED;Release 后重新从空历史的 ARMED 开始。 */
typedef enum {
IEC60870_FAULT_RECORDER_ARMED = 0, /* 循环更新故障前历史,允许触发。 */
IEC60870_FAULT_RECORDER_CAPTURING, /* 已固定触发序号,等待故障后端点。 */
IEC60870_FAULT_RECORDER_READY, /* 完整记录冻结,允许读取,拒绝继续写入。 */
IEC60870_FAULT_RECORDER_FAILED /* 本次窗口不连续,须显式释放后重建历史。 */
} IEC60870_FaultRecorderState_t;
typedef enum {
IEC60870_FAULT_RECORDER_OK = 0, /* 已接收采样或触发,窗口尚未完成。 */
IEC60870_FAULT_RECORDER_COMPLETE, /* 本次调用使完整窗口进入 READY。 */
IEC60870_FAULT_RECORDER_BUSY, /* 当前状态不允许该操作。 */
IEC60870_FAULT_RECORDER_NO_HISTORY, /* 触发所需的故障前采样尚未收齐或已被覆盖。 */
IEC60870_FAULT_RECORDER_DISCONTINUITY, /* 输入序号重复、跳变或试图回绕。 */
IEC60870_FAULT_RECORDER_INVALID /* 参数、内存重叠或序号范围不合法。 */
} IEC60870_FaultRecorderResult_t;
typedef struct {
IEC60870_FaultRecorderState_t state;
uint32_t sample_rate_hz;
uint32_t nominal_frequency_hz;
uint16_t digital_count;
size_t pre_samples, post_samples; /* 触发点前后各有多少个采样间隔。 */
size_t frame_count; /* 仅 READY 返回完整记录帧数,其他状态为 0。 */
size_t trigger_index; /* 触发帧在完整记录中的下标,从 0 开始。 */
uint64_t first_sequence, trigger_sequence, last_sequence; /* 有效触发后才有意义的窗口绝对序号。 */
uint32_t triggers, completed, busy_triggers, history_misses, discontinuities; /* 饱和计数,Release 保留。 */
} IEC60870_FaultRecorderInfo_t;
/* 控制对象由调用者持有;成员仅供实现维护,应用不要直接改写。
* 使用对象前必须 Init;所有调用(含读取)须串行化,或在采集与导出上下文间转交所有权。
* 内部没有锁。self 和 storage 不得重叠,且必须存活到全部读取者结束。
* absolute sequence 表示采样时间顺序;oldest/record_start 等仅是环形数组的物理下标。 */
typedef struct {
IEC60870_FaultRecorderConfig_t config;
IEC60870_FaultRecorderFrame_t *storage;
size_t capacity, oldest, count, pre_samples, post_samples, record_count;
size_t record_start;
uint64_t first_sequence, last_sequence, trigger_sequence, record_first, record_last;
uint32_t triggers, completed, busy_triggers, history_misses, discontinuities;
IEC60870_FaultRecorderState_t state;
bool initialized;
} IEC60870_FaultRecorder_t;
/**
* 功能:向 config 写入默认配置;config 为 NULL 时不操作。 默认 50 Hz、4000 帧/秒、故障前 4 周波/后 8 周波、16 路遥信。 保留两端点后共 320 + 640
* + 1 = 961 帧,触发帧下标为 320。 周波覆盖按额定频率计算;实际验收频率范围所需的帧率与窗口由调用者配置。
* 输入参数:无。
* 输出参数:config——写入默认配置;NULL时不操作。
* 返回值:无。
* 说明:仅填写配置,不分配存储或初始化模块实例。
*/
void IEC60870_FaultRecorder_Config_Default(IEC60870_FaultRecorderConfig_t *config);
/**
* 功能:校验 config,并将所需最小帧数写入 capacity(不是字节数)。 校验每额定周波不少于 80 点、前后周波下限、遥信数量和帧数/字节数溢出。 返回 true 表示成功;无效参数返回
* false,并保持 capacity 的原值。 Init 可使用更大的采样数组,以保留更早的历史并容纳更迟到的故障触发。
* 输入参数:config——配置及调用期间借用的元数据。
* 输出参数:capacity——成功写入所需最小帧数。
* 返回值:true表示容量计算成功;false表示配置或输出指针无效,输出不变。
* 说明:调用方串行访问同一实例,采样数组的存储寿命由调用方负责。
*/
bool IEC60870_FaultRecorder_Required_Capacity(
const IEC60870_FaultRecorderConfig_t *config, size_t *capacity);
/**
* 功能:用 config 初始化 self,借用含 capacity 帧的 storage,进入空历史 ARMED。
* 输入参数:self——调用方持有的模块实例及当前状态;config——配置及调用期间借用的元数据;storage——由调用方持有的采样帧数组;capacity——采样数组可容纳的帧数。
* 输出参数:self——成功建立ARMED状态并重置统计;参数失败不变。
* 返回值:true表示初始化完成;false表示配置、容量或内存重叠校验失败。
* 说明:前提:storage 容量不少于 Required_Capacity 的结果,与 self 不重叠且生命周期足够。 返回 true 表示成功;失败返回 false 并保持 self 不变。
* 成功会重置计数器;不分配或清空采样数组,调用者后续须逐帧 Push 建立历史。
*/
bool IEC60870_FaultRecorder_Init(IEC60870_FaultRecorder_t *self,
const IEC60870_FaultRecorderConfig_t *config,
IEC60870_FaultRecorderFrame_t *storage, size_t capacity);
/**
* 功能:复制一帧瞬时采样;sequence 是采样源的绝对序号,首帧可从任意值开始。
* 输入参数:self——调用方持有的模块实例及当前状态;sequence——顺序号;frame——采样帧。
* 输出参数:self——更新后的录波状态、环形索引及统计。
* 返回值:INVALID表示参数或操作状态非法;BUSY表示当前状态不允许继续;DISCONTINUITY表示采样序号不连续;COMPLETE表示本次收齐完整录波窗口;OK表示操作完成。
* 说明:前提:后续每帧序号严格加 1,UINT64_MAX 不回绕;frame 不得与 self/storage 重叠。 ARMED 遇到不连续序号时丢弃旧历史,以本帧重新开始并返回
* DISCONTINUITY。 CAPTURING 遇到不连续序号时拒收本帧,进入 FAILED 并返回 DISCONTINUITY, 防止将缺点的窗口误当成固定采样率的有效录波。
* READY/FAILED 拒收并返回 BUSY。 正常接收返回 OK;收齐故障后端点返回 COMPLETE,记录被冻结以供导出。 未初始化、NULL 或重叠内存返回 INVALID,
* 不修改对象。
*/
IEC60870_FaultRecorderResult_t IEC60870_FaultRecorder_Push(
IEC60870_FaultRecorder_t *self, uint64_t sequence,
const IEC60870_FaultRecorderFrame_t *frame);
/**
* 功能:按已接收的 trigger_sequence 触发录波;该值是绝对序号,不是环形下标。
* 输入参数:self——调用方持有的模块实例及当前状态;trigger_sequence——触发采样的绝对序号。
* 输出参数:self——更新后的录波状态、环形索引及统计。
* 返回值:INVALID表示参数或操作状态非法;BUSY表示当前状态不允许继续;NO_HISTORY表示故障前历史不足;COMPLETE表示本次收齐完整录波窗口;OK表示操作完成。
* 说明:前提:状态为 ARMED,触发帧及其前 pre_samples 个间隔仍完整保留在历史中。 支持判据延迟上报:若故障后窗口也已在缓存内,立即冻结并返回 COMPLETE; 否则进入
* CAPTURING 并返回 OK,后续 Push 收齐剩余窗口。 非 ARMED 返回 BUSY;故障前历史不足返回 NO_HISTORY;未来触发序号或故障后 序号加法溢出返回
* INVALID。失败不会改动缓存采样,但可能更新对应统计计数。
*/
IEC60870_FaultRecorderResult_t IEC60870_FaultRecorder_Trigger(
IEC60870_FaultRecorder_t *self, uint64_t trigger_sequence);
/**
* 功能:将当前状态、配置与统计快照写入 info,任意已初始化状态均可读取。 frame_count 仅在 READY 非零;窗口绝对序号字段仅在有效触发后有意义。
* 输入参数:self——只读模块实例。
* 输出参数:info——成功时写入的独立结果副本。
* 返回值:true表示已取得状态快照;false表示实例或输出内存无效,输出不变。
* 说明:前提:info 不得与 self/storage 重叠,读取也须遵守对象的串行访问约定。 返回 true 表示成功;失败返回 false,保持 info 不变。
*/
bool IEC60870_FaultRecorder_Get_Info(const IEC60870_FaultRecorder_t *self,
IEC60870_FaultRecorderInfo_t *info);
/**
* 功能:按时间顺序复制冻结记录的第 index 帧,index 从 0 开始且须小于 frame_count。
* 输入参数:self——只读模块实例;index——零基索引。
* 输出参数:frame——成功时写入的独立结果副本。
* 返回值:true表示已复制指定冻结帧;false表示状态、索引或输出内存不合法,输出不变。
* 说明:前提:状态为 READY,frame 不得与 self/storage 重叠,读取期间不得 Release/Init。 返回 true 表示成功;失败返回 false,保持 frame 不变。
* READY 的采样保持不变直到显式 Release/Init,可供导出层按需反复读取。
*/
bool IEC60870_FaultRecorder_Get_Frame(const IEC60870_FaultRecorder_t *self,
size_t index, IEC60870_FaultRecorderFrame_t *frame);
/**
* 功能:放弃历史、正在录制或冻结的记录,保留配置与计数器,重新进入空历史 ARMED。
* 输入参数:self——调用方持有的模块实例及当前状态。
* 输出参数:self——更新后的录波状态、环形索引及统计。
* 返回值:true表示已重新进入空历史ARMED;false表示实例未初始化或为空。
* 说明:前提:所有导出者/读取句柄已结束对冻结记录的使用,且没有并发读写。 返回 true 表示成功;对象未初始化或为 NULL 时返回 false。 本模块只有一个采样数组:READY
* 期间不接收新样本,释放后须重新积累故障前历史; Release 不补采这段空档,也不清零数组的旧字节。
*/
bool IEC60870_FaultRecorder_Release(IEC60870_FaultRecorder_t *self);
#ifdef __cplusplus
}
#endif
#endif /* IEC60870_FAULT_RECORDER_H */
@@ -0,0 +1,203 @@
/* 三映像槽升级核心:角色与动作意图持久化,介质及安装动作由平台回调实现。
* 纯 C99,无堆/RTOS/文件系统;调用方持有实例和后端,所有操作必须串行。 */
#ifndef IEC60870_FIRMWARE_UPDATE_H
#define IEC60870_FIRMWARE_UPDATE_H
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#ifdef __cplusplus
extern "C" {
#endif
#define IEC60870_FIRMWARE_UPDATE_SLOT_COUNT 3U
#define IEC60870_FIRMWARE_UPDATE_NO_SLOT 255U
#define IEC60870_FIRMWARE_UPDATE_WIRE_SIZE 60U
#define IEC60870_FIRMWARE_UPDATE_SCRATCH_SIZE 256U
/* INVALID 表示参数或调用阶段不符,不产生介质副作用;REJECTED 表示基线/候选
* 完整性或产品许可拒绝。ERROR 表示不可继续当前操作;介质/安装不确定时会置
* faulted,事务号耗尽则仅拒绝 Begin,不置故障。EMPTY 仅用于无基线的启动准备。 */
typedef enum {
IEC60870_FIRMWARE_UPDATE_REJECTED = -3,
IEC60870_FIRMWARE_UPDATE_INVALID = -2,
IEC60870_FIRMWARE_UPDATE_ERROR = -1,
IEC60870_FIRMWARE_UPDATE_EMPTY = 0,
IEC60870_FIRMWARE_UPDATE_OK = 1
} IEC60870_FirmwareUpdateResult_t;
/* 这些值写入元数据,已有值的含义不能随枚举顺序调整。VERIFIED 仅表示内容
* 已核验;AUTHORIZED 才允许下一次启动安装。TRIAL 尚未轮转已确认的源槽。 */
typedef enum {
IEC60870_FIRMWARE_UPDATE_STATE_EMPTY = 0,
IEC60870_FIRMWARE_UPDATE_STABLE = 1,
IEC60870_FIRMWARE_UPDATE_RECEIVING = 2,
IEC60870_FIRMWARE_UPDATE_VERIFIED = 3,
IEC60870_FIRMWARE_UPDATE_AUTHORIZED = 4,
IEC60870_FIRMWARE_UPDATE_INSTALLING = 5,
IEC60870_FIRMWARE_UPDATE_TRIAL = 6,
IEC60870_FIRMWARE_UPDATE_ROLLING_BACK = 7
} IEC60870_FirmwareUpdateState_t;
/* 槽中仅保存 payload,不含传输包头。version/size 必须非零,crc 是 payload
* 的反射 CRC32;CRC 完整性检查不代替产品的签名、机型及版本许可策略。 */
typedef struct {
uint32_t version; /* 产品版本标识;核心只检查非零,不内置升降级准入规则。 */
uint32_t size; /* 纯负载字节数,受 Init 的 max_image_size 限制。 */
uint32_t crc; /* 完整负载的 CRC32 最终值;零本身也是合法校验值。 */
} IEC60870_FirmwareUpdateDescriptor_t;
/* 所有缓冲只在同步回调期间借用,不保存指针或重入会修改本实例的接口;
* 回调允许通过 Get_Status 只读查询角色,供平台决定当前/备份派生内容。
* metadata_read:仅从未提交返回 EMPTY;读取/损坏 ERROR,OK 才填写 size。
* metadata_commit:单条原子替换并完成持久同步才 true,false 可能已提交。
* image_begin:重置指定空闲槽为新候选;write/read 必须完成全部 length 字节。
* image_sync:候选完整内容已持久化才 true。install 不修改这三个源槽,按
* (transaction_id,slot,descriptor) 幂等地安装/选择运行映像,成功须持久完成;
* 它不得在返回前跳转或重启。相同回调用于安装、回退及确保稳定映像已安装。
* validate 可 NULL,在实际读回 CRC 正确后执行产品许可校验,false 为拒绝。
* 它也用于 current/backup 复验,不能无条件把旧版拒绝掉;实际槽长等介质
* 约束也由后端在这里检查,核心只读取描述符指定的字节数。
* context 由调用方保活;Init 不自动启动安装或取得后端资源所有权。 */
typedef struct {
void *context;
IEC60870_FirmwareUpdateResult_t (*metadata_read)(void *context,
uint8_t *bytes, size_t capacity, size_t *size);
bool (*metadata_commit)(void *context, const uint8_t *bytes, size_t size);
bool (*image_begin)(void *context, uint8_t slot, uint32_t size);
bool (*image_write)(void *context, uint8_t slot, uint32_t offset,
const uint8_t *bytes, size_t length);
bool (*image_read)(void *context, uint8_t slot, uint32_t offset,
uint8_t *bytes, size_t length);
bool (*image_sync)(void *context, uint8_t slot);
bool (*install)(void *context, uint8_t slot,
const IEC60870_FirmwareUpdateDescriptor_t *descriptor, uint64_t transaction_id);
bool (*validate)(void *context, uint8_t slot,
const IEC60870_FirmwareUpdateDescriptor_t *descriptor);
} IEC60870_FirmwareUpdateStore_t;
/* current 始终表示最后确认的映像;TRIAL 时实际试运行的是 candidate。
* Confirm 才轮转 current/backup,回退保留旧 current 及其原 backup。
* received_size 只在本次连续接收会话有效,不作为断电续传偏移。 */
typedef struct {
IEC60870_FirmwareUpdateState_t state; /* 最近一次已知成功提交的状态,故障时未必等于介质最新值。 */
uint8_t current_slot; /* 已确认角色;空库为 NO_SLOT。 */
uint8_t backup_slot; /* 上一个确认版本;首次 Provision 后为 NO_SLOT。 */
uint8_t candidate_slot; /* 有候选的持久阶段才有效,与两个保留角色互异。 */
uint64_t transaction_id; /* Provision 从1开始,每次 Begin 加1;安装及回退重试沿用它。 */
IEC60870_FirmwareUpdateDescriptor_t images[IEC60870_FIRMWARE_UPDATE_SLOT_COUNT]; /* 按物理槽索引,无角色项全零。 */
uint32_t received_size; /* 易失的已接收负载字节数,Init 后归零。 */
bool faulted; /* 易失闭锁位;仅重新 Init 可解除,查询仍可读取该位。 */
} IEC60870_FirmwareUpdateStatus_t;
/* 公开布局仅供静态分配,应用须通过API读取/修改状态。store 为浅拷贝;
* 接收会话和工作缓冲均不是可跨调用借用的文件快照。 */
typedef struct {
IEC60870_FirmwareUpdateStore_t store; /* 回调表按值保存,context 仍由调用方拥有。 */
IEC60870_FirmwareUpdateStatus_t status;
uint32_t max_image_size; /* 所有槽统一的负载上限,不包含任何传输封装。 */
bool initialized; /* 元数据结构及角色关系完整校验后才置位。 */
bool receiving_active; /* 仅本次 Begin 成功可写;恢复 RECEIVING 不会恢复写权限。 */
uint8_t wire[IEC60870_FIRMWARE_UPDATE_WIRE_SIZE]; /* 独立格式编码缓冲,不按结构体布局保存。 */
uint8_t scratch[IEC60870_FIRMWARE_UPDATE_SCRATCH_SIZE]; /* 同步读回工作区,不随映像增大。 */
} IEC60870_FirmwareUpdate_t;
/**
* 功能:校验参数和元数据,允许 store=&self->store。
* 输入参数:self——调用方持有的模块实例及当前状态;store——同步存储回调表及其上下文;max_image_size——允许的映像大小上限,单位字节。
* 输出参数:self——更新后的角色、接收进度及故障状态。
* 返回值:OK表示操作完成;INVALID表示参数或操作状态非法;ERROR表示实例不可用、I/O失败或内容损坏。
* 说明:参数 INVALID 保留原实例; 恢复失败实例不可用。空介质恢复为 STATE_EMPTY,不制造初始运行映像。 max_image_size 非零;Init 只恢复,不调用
* install 或自动授权候选。 恢复成功(包括空介质)返回 OK;此时尚未复验各映像的实际字节。
*/
IEC60870_FirmwareUpdateResult_t IEC60870_FirmwareUpdate_Init(
IEC60870_FirmwareUpdate_t *self, const IEC60870_FirmwareUpdateStore_t *store,
uint32_t max_image_size);
/**
* 功能:只允许空库;调用方先把真实基线 payload 写入 slot。
* 输入参数:self——调用方持有的模块实例及当前状态;slot——映像物理槽号;descriptor——映像版本、大小和CRC描述。
* 输出参数:self——更新后的角色、接收进度及故障状态。
* 返回值:OK表示操作完成;INVALID表示参数或操作状态非法;REJECTED表示映像内容或描述校验不通过;ERROR表示实例不可用、I/O失败或内容损坏。
* 说明:本接口同步并读回校验, 成功后持久登记为唯一 current,不创建假备份,也不调用 install。 descriptor 本次借用;内容/策略拒绝返回 REJECTED,仍保持空库角色。
*/
IEC60870_FirmwareUpdateResult_t IEC60870_FirmwareUpdate_Provision(
IEC60870_FirmwareUpdate_t *self, uint8_t slot,
const IEC60870_FirmwareUpdateDescriptor_t *descriptor);
/**
* 功能:只在 STABLE 接受候选,选择 current/backup 之外的槽,先持久记录接收意图。
* 输入参数:self——调用方持有的模块实例及当前状态;descriptor——映像版本、大小和CRC描述。
* 输出参数:self——更新后的角色、接收进度及故障状态。
* 返回值:OK表示操作完成;INVALID表示参数或操作状态非法;ERROR表示实例不可用、I/O失败或内容损坏。
* 说明:Write 要求连续 offset,Finish 同步并读回完整 payload;不能靠包头宣称验证。 重启不续传接收偏移,Prepare_Boot 将未授权
* RECEIVING/VERIFIED 候选取消。
*/
IEC60870_FirmwareUpdateResult_t IEC60870_FirmwareUpdate_Begin(
IEC60870_FirmwareUpdate_t *self, const IEC60870_FirmwareUpdateDescriptor_t *descriptor);
/**
* 功能:bytes 在同步调用期间借用,length 必须非零;OK 才推进易失接收偏移。
* 输入参数:self——调用方持有的模块实例及当前状态;offset——文件或映像内的字节偏移;bytes——字节数据;length——字节数。
* 输出参数:self——更新后的角色、接收进度及故障状态。
* 返回值:OK表示操作完成;INVALID表示参数或操作状态非法;ERROR表示实例不可用、I/O失败或内容损坏。
* 说明:后端写失败可能已有部分副作用,核心闭锁而不猜测可继续的偏移。
*/
IEC60870_FirmwareUpdateResult_t IEC60870_FirmwareUpdate_Write(
IEC60870_FirmwareUpdate_t *self, uint32_t offset, const uint8_t *bytes, size_t length);
/**
* 功能:仅完整接收会话可结束。
* 输入参数:self——调用方持有的模块实例及当前状态。
* 输出参数:self——更新后的角色、接收进度及故障状态。
* 返回值:OK表示操作完成;INVALID表示参数或操作状态非法;REJECTED表示映像内容或描述校验不通过;ERROR表示实例不可用、I/O失败或内容损坏。
* 说明:REJECTED 不闭锁,候选仍未验证,可由 Abort 撤销; 同步/读回 I/O 及元数据提交失败均闭锁,不能把完整接收当作持久成功。
*/
IEC60870_FirmwareUpdateResult_t IEC60870_FirmwareUpdate_Finish(IEC60870_FirmwareUpdate_t *self);
/**
* 功能:Abort 只取消未授权候选,EMPTY/STABLE 无候选时幂等返回 OK;Authorize 只 接受 VERIFIED,持久成功才返回 OK。
* 输入参数:self——调用方持有的模块实例及当前状态。
* 输出参数:self——更新后的角色、接收进度及故障状态。
* 返回值:OK表示操作完成;INVALID表示参数或操作状态非法;ERROR表示实例不可用、I/O失败或内容损坏。
* 说明:任意不确定元数据提交均故障闭锁直到 Init,不能原样重试同一动作。
*/
IEC60870_FirmwareUpdateResult_t IEC60870_FirmwareUpdate_Abort(IEC60870_FirmwareUpdate_t *self);
/**
* 功能:只保存授权事实,不执行安装。
* 输入参数:self——调用方持有的模块实例及当前状态。
* 输出参数:self——更新后的角色、接收进度及故障状态。
* 返回值:OK表示操作完成;INVALID表示参数或操作状态非法;ERROR表示实例不可用、I/O失败或内容损坏。
* 说明:外层负责证明授权来源及等待激活时点;核心 不接触协议 ACK,不能根据本接口参数自行判断业务授权是否成立。
*/
IEC60870_FirmwareUpdateResult_t IEC60870_FirmwareUpdate_Authorize(IEC60870_FirmwareUpdate_t *self);
/**
* 功能:每次真实启动/应用激活只调用一次,不是循环推进接口。
* 输入参数:self——调用方持有的模块实例及当前状态。
* 输出参数:self——更新后的角色、接收进度及故障状态;boot_image——仅OK时写入本次选择的启动映像描述。
* 返回值:OK表示操作完成;EMPTY表示没有所需记录或到期任务;INVALID表示参数或操作状态非法;ERROR表示实例不可用、I/O失败或内容损坏。
* 说明:先保存安装/回退意图, 再调用幂等 install;AUTHORIZED/恢复的 INSTALLING 成功进入 TRIAL。 后一次启动见 TRIAL 即回退到旧 current;恢复的
* ROLLING_BACK 继续回退。 STABLE 校验并确保 current 已安装;未授权候选被取消。仅 OK 填写 boot_image, EMPTY 或失败保持输出;
* 输出对象不得与实例重叠。实际引导/跳转由返回后的 平台代码执行。已复验旧 current/backup 后,候选内容或读取失败均转入回退;
* 旧映像验证、元数据提交或安装失败则闭锁等待重新初始化。安装失败保留 调用时的持久状态,稳定启动修复失败仍是 STABLE,不会凭失败制造回退意图。
*/
IEC60870_FirmwareUpdateResult_t IEC60870_FirmwareUpdate_Prepare_Boot(
IEC60870_FirmwareUpdate_t *self, IEC60870_FirmwareUpdateDescriptor_t *boot_image);
/**
* 功能:只在 TRIAL 的实际健康检查通过后调用,持久轮转角色;不能以收到协议ACK 代替运行确认。
* 输入参数:self——调用方持有的模块实例及当前状态。
* 输出参数:self——更新后的角色、接收进度及故障状态。
* 返回值:OK表示操作完成;INVALID表示参数或操作状态非法;ERROR表示实例不可用、I/O失败或内容损坏。
* 说明:本接口复验源槽,但不代替应用的运行/安装目标健康检查。 元数据提交失败可能已提交,须重新 Init 核对事实;调用阶段不符仍为 INVALID。
*/
IEC60870_FirmwareUpdateResult_t IEC60870_FirmwareUpdate_Confirm(IEC60870_FirmwareUpdate_t *self);
/**
* 功能:成功拷贝状态值,含故障位;NULL/未初始化返回 false 且输出不变。
* 输入参数:self——只读模块实例。
* 输出参数:status——仅成功时写入升级状态副本。
* 返回值:true表示已复制已初始化实例状态,false表示实例或输出无效。
* 说明:查询不验证映像字节、不推进状态,输出对象不得与实例重叠。
*/
bool IEC60870_FirmwareUpdate_Get_Status(const IEC60870_FirmwareUpdate_t *self,
IEC60870_FirmwareUpdateStatus_t *status);
#ifdef __cplusplus
}
#endif
#endif /* IEC60870_FIRMWARE_UPDATE_H */
@@ -0,0 +1,247 @@
/* 附录 B 历史记录核心:事件循环记录、定点冻结、日极值及启动恢复。
* 本模块不分配堆内存,不依赖操作系统或传输层;介质访问由存储回调完成。
* 提交成功必须表示一个槽已原子、持久替换;提交失败后实例进入故障态,
* 必须重新 Init 核对实际存储结果,不能直接重试同一条记录。
* 实例、点表和存储均由调用方持有;包括查询、导出在内的所有访问须串行。 */
#ifndef IEC60870_HISTORY_H
#define IEC60870_HISTORY_H
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#ifdef __cplusplus
extern "C" {
#endif
/* 事件容量按条数保留;日记录槽覆盖当前日和之前 31 个自然日。
* WIRE_MAX 是单条内部编码的工作区上限,不是历史总容量。 */
#define IEC60870_HISTORY_MAX_ANALOG 32U
#define IEC60870_HISTORY_SOE_CAPACITY 1024U
#define IEC60870_HISTORY_CO_CAPACITY 30U
#define IEC60870_HISTORY_DAYS 32U
#define IEC60870_HISTORY_SLOTS_PER_DAY 96U
#define IEC60870_HISTORY_WIRE_MAX 1024U
/* 类别值同时用于持久记录标识;存储后端按类别划分独立槽空间。 */
typedef enum {
IEC60870_HISTORY_SOE = 1, IEC60870_HISTORY_CO = 2,
IEC60870_HISTORY_FIXPT = 3, IEC60870_HISTORY_EXV = 4
} IEC60870_HistoryKind_t;
/* ERROR 为存储/状态错误,INVALID 为调用参数错误,CONFIG 为点表指纹不符;
* TIME_REVERSED 表示观测时刻回退。EMPTY 表示没有对应记录或没有配置遥测点,
* OK 表示操作成功;Observe 的 OK 不保证本次一定产生了新定点或新极值。 */
typedef enum {
IEC60870_HISTORY_ERROR = -1, IEC60870_HISTORY_INVALID = -2,
IEC60870_HISTORY_CONFIG = -3, IEC60870_HISTORY_TIME_REVERSED = -4,
IEC60870_HISTORY_EMPTY = 0, IEC60870_HISTORY_OK = 1
} IEC60870_HistoryResult_t;
/* 遥控操作阶段分别记条;它们不表示设备动作成功,也不等同网络应答状态。 */
typedef enum {
IEC60870_HISTORY_SELECT = 0, IEC60870_HISTORY_OPER = 1,
IEC60870_HISTORY_CANCEL = 2
} IEC60870_HistoryCommand_t;
/* 存储回调约定:
* read 按 kind/index 读取一个逻辑槽,最多写 capacity 字节,仅在 OK 时填写
* 实际 size;EMPTY 只用于没有已提交记录的槽,坏记录及读取失败必须报 ERROR。
* commit 完整接收 bytes/size,成功返回前须完成介质同步。提交前中断必须仍能
* 恢复旧记录;返回 false 也可能已经落盘,因此核心会锁住后续操作并要求恢复。
* context 只借用;字节缓冲只在回调期间有效,回调不得保存指针或重入本实例。 */
typedef struct {
void *context;
IEC60870_HistoryResult_t (*read)(void *context, IEC60870_HistoryKind_t kind,
uint32_t index, uint8_t *bytes, size_t capacity, size_t *size);
bool (*commit)(void *context, IEC60870_HistoryKind_t kind, uint32_t index,
const uint8_t *bytes, size_t size);
} IEC60870_HistoryStore_t;
/* 三组点表在实例整个使用期间借用,不得修改;组内地址须唯一且为非零 24 位值。
* 遥测数组顺序决定定点及极值数组的顺序,也参与持久记录指纹;改变点表后不能
* 用新配置解释旧存储,调用方须另行处理迁移或使用新的存储空间。
* freeze_grace_ms 为 0..1000 毫秒,允许在每刻钟边界后的窗口内取首个有效快照;
* 0 表示只接受精确边界。错过窗口保留缺测,不拿后来的值补写旧时段。 */
typedef struct {
const uint32_t *soe_ioas;
size_t soe_count;
const uint32_t *co_ioas;
size_t co_count;
const uint32_t *analog_ioas;
size_t analog_count;
uint32_t freeze_grace_ms;
} IEC60870_HistoryConfig_t;
/* 一条 SOE 或遥控记录的值副本。sequence 按类别递增,与墙钟是否回拨无关;
* quality 与 time_valid 保留采集事实,XML 未定义的字段不会被编码器擅自扩展。 */
typedef struct {
uint64_t sequence;
uint64_t utc_ms;
uint32_t ioa;
uint8_t value;
uint8_t quality;
IEC60870_HistoryCommand_t command;
bool time_valid;
} IEC60870_HistoryEvent_t;
/* day 是 UTC+8 本地日期对应的自 1970-01-01 起日序,slot 为当天第 1..96 节。
* 第 1 节对应 00:15,第 96 节对应归属日的 24:00;即使采样已到次日零点,
* 该定点仍保存在前一日。utc_ms 保留实际采样时刻,包含允许的调度迟到量。
* values/quality 的前 count 项与配置的 analog_ioas 一一对应。 */
typedef struct {
uint32_t day;
uint16_t slot;
uint64_t utc_ms;
size_t count;
float values[IEC60870_HISTORY_MAX_ANALOG];
uint8_t quality[IEC60870_HISTORY_MAX_ANALOG];
} IEC60870_HistoryFixed_t;
/* 单点当天的极值及其首次达到该值的时刻;相等值不更新时标。
* valid=false 表示当天尚无有效样本,此时不能解释其数值或发生时刻。 */
typedef struct {
float max;
float min;
uint64_t max_utc_ms;
uint64_t min_utc_ms;
bool valid;
} IEC60870_HistoryExtremePoint_t;
/* 一天全部遥测点的累计状态。utc_ms 是最近一次持久化变更的观测时刻,
* 不是文件生成时间;points 顺序沿用点表,当前日也保存以支持重启续算。 */
typedef struct {
uint32_t day;
uint64_t utc_ms;
size_t count;
IEC60870_HistoryExtremePoint_t points[IEC60870_HISTORY_MAX_ANALOG];
} IEC60870_HistoryExtrema_t;
/* 调用方持有的实例及固定工作区。公开布局用于静态分配,业务不得修改内部状态。
* config/store 是浅拷贝,数组和 context 的生命周期仍由调用方负责。
* wire/work_extrema 会在读写时复用,不是可跨调用借用的历史快照。 */
typedef struct {
IEC60870_HistoryConfig_t config;
IEC60870_HistoryStore_t store;
uint32_t fingerprint;
uint64_t event_sequence[2];
size_t event_count[2];
uint32_t latest_day;
uint64_t observed_utc_ms;
bool have_day;
bool initialized;
bool faulted;
uint8_t wire[IEC60870_HISTORY_WIRE_MAX];
IEC60870_HistoryExtrema_t work_extrema;
} IEC60870_History_t;
/**
* 功能:返回指定类别所需的逻辑槽数,供存储后端布局使用;未知类别返回 0。
* 输入参数:kind——记录或文件类别。
* 输出参数:无。
* 返回值:该类别的逻辑槽容量;未知类别返回0。
* 说明:冗余副本、提交元数据和介质对齐空间由后端在此槽数之外自行预留。
*/
uint32_t IEC60870_History_Slot_Count(IEC60870_HistoryKind_t kind);
/**
* 功能:UTC 毫秒转换成本地日序,不读取系统时间,不修改任何实例。
* 输入参数:utc_ms——UTC纪元毫秒。
* 输出参数:无。
* 返回值:固定UTC+8本地日序;超出支持历法范围返回UINT32_MAX。
* 说明:全模块接受的日历范围是 UTC+8 的 2000-01-01 00:00:00.000 至 2099-12-31 23:59:59.999,即 UTC 毫秒
* 946656000000..4102415999999。 超出范围返回 UINT32_MAX;事件 time_valid=false 也不能绕过此日历限制。
*/
uint32_t IEC60870_History_Local_Day(uint64_t utc_ms);
/**
* 功能:校验配置后扫描全部槽,恢复事件序号/条数、最新测量日及已保存的时间下界。
* 输入参数:self——调用方持有的模块实例及当前状态;config——配置及调用期间借用的元数据;store——同步存储回调表及其上下文。
* 输出参数:self——本次操作后的运行状态及复用工作区。
* 返回值:OK表示操作完成;INVALID表示参数或操作状态非法;CONFIG表示持久记录与当前配置指纹不符;ERROR表示实例不可用、I/O失败或内容损坏。
* 说明:self 由调用方提供;复制配置及回调表,但不接管其中指针。允许使用实例自身 config/store 字段作为重建输入。参数校验失败返回 INVALID 且不重置旧实例;
* 进入恢复后失败则实例不可用:CONFIG 为点表不匹配,ERROR 为损坏或读取失败。 本接口不清空存储、不修复坏记录,也不创建系统资源。
*/
IEC60870_HistoryResult_t IEC60870_History_Init(IEC60870_History_t *self,
const IEC60870_HistoryConfig_t *config, const IEC60870_HistoryStore_t *store);
/**
* 功能:追加一次已确认的遥信变位;ioa 必须属于 SOE 点表,value 为 0..3 的状态码。
* 输入参数:self——调用方持有的模块实例及当前状态;ioa——信息对象地址;value——待处理数值;quality——事件品质字节;utc_ms——UTC纪元毫秒;
* time_valid——事件原始时标是否有效。
* 输出参数:self——本次操作后的运行状态及复用工作区。
* 返回值:OK表示操作完成;INVALID表示参数或操作状态非法;ERROR表示实例不可用、I/O失败或内容损坏。
* 说明:quality 与 time_valid 原样保留;utc_ms 是事件发生时间,不能改用发送重试时间。 成功后递增序号并按容量覆盖最旧记录;非法输入返回 INVALID,存储或实例问题
* 返回 ERROR。函数不做变位检测或重复消除,调用方须保证每个实际事件只追加一次。
*/
IEC60870_HistoryResult_t IEC60870_History_Append_Soe(IEC60870_History_t *self,
uint32_t ioa, uint8_t value, uint8_t quality, uint64_t utc_ms, bool time_valid);
/**
* 功能:追加指定遥控阶段;ioa 必须属于遥控点表,command 为选择/执行/撤销,value 为 0..3。
* 输入参数:self——调用方持有的模块实例及当前状态;ioa——信息对象地址;command——遥控操作阶段;value——待处理数值;utc_ms——UTC纪元毫秒;
* time_valid——事件原始时标是否有效。
* 输出参数:self——本次操作后的运行状态及复用工作区。
* 返回值:OK表示操作完成;INVALID表示参数或操作状态非法;ERROR表示实例不可用、I/O失败或内容损坏。
* 说明:时标及循环提交规则同 SOE;本接口只保存操作事实,不判设备执行结果。 参数只按值使用,无借用输出;返回 OK、INVALID 或 ERROR。
*/
IEC60870_HistoryResult_t IEC60870_History_Append_Control(IEC60870_History_t *self,
uint32_t ioa, IEC60870_HistoryCommand_t command, uint8_t value,
uint64_t utc_ms, bool time_valid);
/**
* 功能:提供同一实际观测时刻的遥测数组,count 必须等于配置点数;输入数组仅本次借用。
* 输入参数:self——调用方持有的模块实例及当前状态;utc_ms——UTC纪元毫秒;values——按配置点序排列的值;quality——与值数组同序的品质;count——数组项数。
* 输出参数:self——本次操作后的运行状态及复用工作区。
* 返回值:OK表示操作完成;EMPTY表示没有所需记录或到期任务;INVALID表示参数或操作状态非法;CONFIG表示持久记录与当前配置指纹不符;ERROR表示实例不可用、I/O失败或内容损坏;
* TIME_REVERSED表示观测时间低于高水位。
* 说明:仅品质为 0 的有限浮点数参加极值统计;定点则要求本次全部点有效。应持续调用 以捕获日极值,并保证每个冻结宽限窗口至少有一次有效调用,才能得到每日 96 节。 只接受可信墙钟;
* 小于实例已观测时刻返回 TIME_REVERSED,不改历史;零遥测点返回 EMPTY。OK 也可能只是时间推进,没有新记录。非法输入返回 INVALID。 定点和极值各自提交,非跨类型事务;
* 若后一次提交失败,前一次已落盘记录仍保留, 返回 ERROR 并须 Init 恢复,不能因为整次 Observe 失败而回滚已提交数据。
*/
IEC60870_HistoryResult_t IEC60870_History_Observe(IEC60870_History_t *self,
uint64_t utc_ms, const float *values, const uint8_t *quality, size_t count);
/**
* 功能:返回恢复/提交后缓存的事件条数,不访问存储;仅接受 SOE/CO。
* 输入参数:self——只读模块实例;kind——记录或文件类别。
* 输出参数:无。
* 返回值:指定SOE/CO环的保留条数;类别或实例不可用时返回0。
* 说明:空记录、未知类别、未初始化或故障实例均返回 0,不能据此区分存储故障与空库。
*/
size_t IEC60870_History_Event_Count(const IEC60870_History_t *self,
IEC60870_HistoryKind_t kind);
/**
* 功能:按从旧到新的下标读取事件,oldest_index=0 是当前保留的最旧条目。
* 输入参数:self——调用方持有的模块实例及当前状态;kind——记录或文件类别;oldest_index——按提交顺序从最旧记录起的零基索引。
* 输出参数:self——复用工作区及读取校验可能锁存的故障状态;out——成功时写入的独立结果副本。
* 返回值:OK表示操作完成;EMPTY表示没有所需记录或到期任务;INVALID表示参数或操作状态非法;CONFIG表示持久记录与当前配置指纹不符;ERROR表示实例不可用、I/O失败或内容损坏。
* 说明:out 由调用方持有,只有 OK 才填写;越界/缺槽返回 EMPTY,参数错误为 INVALID, 存储异常为 ERROR/CONFIG。输出是独立值副本;查询期间必须禁止同实例追加/轮转。
*/
IEC60870_HistoryResult_t IEC60870_History_Get_Event(IEC60870_History_t *self,
IEC60870_HistoryKind_t kind, size_t oldest_index, IEC60870_HistoryEvent_t *out);
/**
* 功能:读取归属日 day 的第 slot 节;slot 只能为 1..96,不按已有条目重新编号。
* 输入参数:self——调用方持有的模块实例及当前状态;day——相对1970-01-01的本地日序;slot——定点节号1..96;事件及极值公共头使用0。
* 输出参数:self——复用工作区及读取校验可能锁存的故障状态;out——成功时写入的独立结果副本。
* 返回值:OK表示操作完成;EMPTY表示没有所需记录或到期任务;INVALID表示参数或操作状态非法;CONFIG表示持久记录与当前配置指纹不符;ERROR表示实例不可用、I/O失败或内容损坏。
* 说明:不在 32 日保留窗口、该节缺测或物理槽已归属其他日期时返回 EMPTY。 out 仅在 OK 时填写完整值副本;其他失败返回 INVALID、ERROR 或 CONFIG。
*/
IEC60870_HistoryResult_t IEC60870_History_Read_Fixed(IEC60870_History_t *self,
uint32_t day, uint16_t slot, IEC60870_HistoryFixed_t *out);
/**
* 功能:读取一天的累计极值,也可读取未结束的当前日;是否导出该日由文件层决定。
* 输入参数:self——调用方持有的模块实例及当前状态;day——相对1970-01-01的本地日序。
* 输出参数:self——复用工作区及读取校验可能锁存的故障状态;out——成功时写入的独立结果副本。
* 返回值:OK表示操作完成;EMPTY表示没有所需记录或到期任务;INVALID表示参数或操作状态非法;CONFIG表示持久记录与当前配置指纹不符;ERROR表示实例不可用、I/O失败或内容损坏。
* 说明:无记录/超保留窗口返回 EMPTY;参数或存储失败返回 INVALID、ERROR、CONFIG。 out 仅在 OK 时填写;逐点 valid 才能判定该点是否曾有有效样本。
*/
IEC60870_HistoryResult_t IEC60870_History_Read_Extrema(IEC60870_History_t *self,
uint32_t day, IEC60870_HistoryExtrema_t *out);
/**
* 功能:输出已恢复或观测到的最新测量日,不等于调用瞬间系统日期,也不由事件时间推进。
* 输入参数:self——只读模块实例。
* 输出参数:day——成功时写入的本地日序。
* 返回值:true表示已有最近测量日并填写day;false表示实例不可用或尚无测量日。
* 说明:未有测量日、实例不可用或 day=NULL 返回 false 并保留输出;true 时仅写 *day。
*/
bool IEC60870_History_Latest_Day(const IEC60870_History_t *self, uint32_t *day);
#ifdef __cplusplus
}
#endif
#endif
@@ -0,0 +1,64 @@
/*
* 附录 B 历史 XML 编码:将 SOE、遥控操作、日极值和定点记录转换为传输文件。
* 编码器分片输出、不分配堆内存,不访问文件系统或传输层。
* 记录持久化由历史核心/后端负责;对外可重复读取的冻结文件由调用方保存。
*/
#ifndef IEC60870_HISTORY_FILE_H
#define IEC60870_HISTORY_FILE_H
#include "IEC60870_History.h"
#ifdef __cplusplus
extern "C" {
#endif
/* 路径容量包含末尾 NUL;属性上限按原始 UTF-8 字节计,不含 NUL。
* XML 转义后可能变长,编码器逐片输出,不要求调用方准备等大的整行缓冲。 */
#define IEC60870_HISTORY_FILE_PATH_CAPACITY 48U
#define IEC60870_HISTORY_FILE_ATTRIBUTE_MAX 255U
typedef struct {
const char *device_name; /* 借用有效 UTF-8/XML 文本,最多 ATTRIBUTE_MAX 字节。 */
const char *const *analog_units; /* 可空;非空须按点表顺序提供 analog_count 个单位字符串。 */
} IEC60870_HistoryFileConfig_t;
/* 同步接收且保存全部 length 字节才返回 true;短写或其他失败必须返回 false。
* bytes 仅在回调期间借用,可能是临时栈缓冲或一个 UTF-8 字符的部分字节,不能
* 保留指针,也不能假设每片自带 NUL。合并全部分片后才构成完整 UTF-8 XML。
* 失败时可能已经输出文件前缀,调用方须丢弃整个候选文件,不能把前缀发布出去。
* 回调不得修改历史记录、点表或编码配置,也不得重入同一历史实例。 */
typedef bool (*IEC60870_HistoryFileWriteFn)(void *context, const uint8_t *bytes, size_t length);
/**
* 功能:生成大小写固定的完整虚拟路径,供目录项与读文件请求共同使用。
* 输入参数:kind——记录或文件类别;day——相对1970-01-01的本地日序;capacity——缓冲可用容量。
* 输出参数:name——成功生成的NUL结尾相对文件名;失败不变。
* 返回值:true表示文件名已完整生成;false表示参数非法或容量不足,输出不变。
* 说明:day 是 UTC+8 本地日序;SOE/CO 忽略 day,日文件只接受可表示的 2000..2099 日期。 name/capacity 由调用方提供,容量含 NUL;true
* 时填写结果,false 时不修改输出。 失败包括未知类别、日期无效或容量不足;这里只生成名称,不查询存在性/保留窗口。
*/
bool IEC60870_HistoryFile_Name(IEC60870_HistoryKind_t kind, uint32_t day,
char *name, size_t capacity);
/**
* 功能:通过 write/context 输出一份附录 B.3.2 XML,整个调用期间须独占历史实例。
* 输入参数:history——历史核心实例;kind——记录或文件类别;day——相对1970-01-01的本地日序;config——配置及调用期间借用的元数据;write——同步接收输出片段的回调;
* context——传给输出回调的调用方上下文。
* 输出参数:history——复用读取工作区及读取错误可能锁存的故障状态;size——仅完整成功时写入文件字节数,不含NUL;允许NULL的入口不强制输出。
* 返回值:true表示完整文件已输出;false表示参数、读取校验或输出回调失败,候选内容不可发布。
* 说明:history、config 及其字符串/数组都由调用方持有,编码器仅在本次调用中借用; 不消费记录、不改变保留策略。调用方须将成功输出冻结后再交给文件服务下载。 SOE/CO
* 从旧到新输出当前保留事件,允许 num=0;day 对这两类不起作用。 日文件仅开放最新测量日前的 30 个完整自然日。EXV 同时从属性表和数据表省略 没有有效样本的点;FIXPT
* 省略含失效值的快照,sectNum 写实际节数,sect 保留 原来的 1..96 节编号,不能因缺测重新编号;第 96 节写归属日 24:00。 规范 XML
* 没有定义独立品质/时间有效位属性,这些信息仍保留在内部持久记录中。 无日数据、输入无效、存储读取失败、输出失败或长度溢出均返回 false;已输出的 前缀须整体废弃。size 可为 NULL,
* 仅在完整成功后写入文件字节数,不包含 NUL。
*/
bool IEC60870_HistoryFile_Write(IEC60870_History_t *history,
IEC60870_HistoryKind_t kind, uint32_t day,
const IEC60870_HistoryFileConfig_t *config,
IEC60870_HistoryFileWriteFn write, void *context,
uint32_t *size);
#ifdef __cplusplus
}
#endif
#endif /* IEC60870_HISTORY_FILE_H */
File diff suppressed because it is too large Load Diff
File diff suppressed because it is too large Load Diff
@@ -0,0 +1,93 @@
/* 信息对象与ASDU的内部协作,不作为业务API。
* ASDU使用类型描述计算布局;具体对象通过只读函数表编码;解码按Type ID另行分派。
* 字节辅助函数不读写连接状态,也不依赖结构体对齐或主机字节序。 */
#ifndef IEC60870_INFORMATION_OBJECTS_INTERNAL_H
#define IEC60870_INFORMATION_OBJECTS_INTERNAL_H
#include "IEC60870_InformationObjects.h"
/* 单个文件段LOS最多255字节,另有4字节文件段头和最多3字节IOA。
* 即使对象可表示更长载荷,ASDU容器仍按配置的总长上限返回FULL。 */
#define IEC60870_OBJECT_MAX_PAYLOAD 259U
#define IEC60870_OBJECT_MAX_ENCODED (IEC60870_OBJECT_MAX_PAYLOAD + 3U)
/* 每个类型独立的只读编码函数表;解码仍由Type ID选择具体类型的解析函数。
* encode仅写临时载荷,公共入口验证后原子提交;变长类型提供两个长度回调。 */
typedef struct IEC60870_InformationObjectVTable {
uint8_t type_id; /* 线上类型标识;同时用于核对对象基类身份。 */
uint16_t payload_size; /* 固定类型的精确长度;变长类型的最低长度,不含IOA。 */
uint8_t single_object; /* 1表示仅允许一个对象;SQ约束由supports_sequence独立决定。 */
size_t object_size; /* 具体C结构的sizeof,用于输出存储检查,与线上长度无关。 */
int (*encode)(const IEC60870_InformationObject_t *object, uint8_t *payload); /* 写临时载荷,1成功/0字段非法。 */
uint8_t supports_sequence; /* 1允许SQ=1;参数类型仅支持SQ=0、一个对象。 */
uint16_t (*get_payload_size)(const IEC60870_InformationObject_t *object); /* NULL为固定长度。 */
uint16_t (*get_payload_size_from_buffer)(const uint8_t *payload, uint16_t length); /* 变长载荷精确长度;0非法。 */
} IEC60870_InformationObjectVTable;
/**
* 功能:未支持的Type ID返回NULL;地址和长度校验由使用方在读报文前完成。
* 输入参数:type_id——报文或已初始化对象中的类型标识。
* 输出参数:无。
* 返回值:支持时返回静态描述表指针,未知类型返回NULL。
* 说明:表中保存载荷长度、对象存储尺寸、单对象限制和编码函数;不解析值字段。
*/
const IEC60870_InformationObjectVTable *IEC60870_InformationObject_Get_Descriptor(uint8_t type_id);
/**
* 功能:按Type ID调用具体Get_From_Buffer;object==NULL时仅验证,不输出。
* 输入参数:type_id——需要解析的具体类型。 ioa——已还原的地址,0..0xFFFFFF。 payload——不含IOA的载荷;只有0字节载荷的读命令允许NULL。 length——载荷字节数,
* 须精确匹配该类型。 object_size——非空object的可用字节数,至少为该具体结构的sizeof。
* 输出参数:object——匹配具体类型的输出存储;NULL表示仅校验,不输出对象。
* 返回值:OK为成功,UNSUPPORTED为未知类型,ERROR为地址、长度、字段或存储尺寸非法。
* 说明:object_size是调用方实际提供的容量,必须至少为所选具体类型的sizeof; 非空object必须对应该具体结构,尺寸足够不能替代类型匹配。失败不修改输出。
*/
IEC60870_AsduResult_t IEC60870_InformationObject_Decode(uint8_t type_id, uint32_t ioa,
const uint8_t *payload, uint16_t length, void *object, size_t object_size);
/**
* 功能:从低字节在前的字节序列读取无符号值。
* 输入参数:data——至少length字节的有效输入,调用方先完成边界检查。
* length——1..4,用于1/2/3字节地址或2/4字节数值。
* 输出参数:无。
* 返回值:按位拼接的uint32_t,未使用高位为0。
* 说明:逐字节读,允许未对齐输入;不检查指针或范围。
*/
static inline uint32_t IEC60870_Object_Read_LE(const uint8_t *data, unsigned int length)
{
uint32_t value = 0;
unsigned int i;
for (i = 0; i < length; ++i) {
value |= (uint32_t)data[i] << (8U * i);
}
return value;
}
/**
* 功能:将数值低length字节按低字节在前写入报文。
* 输入参数:value——待写数值;需要保留的高位是否越界由调用方预先检查。
* length——1..4;只写指定字节数,不写尾部填充。
* 输出参数:data——至少length字节的可写区域。
* 返回值:无。
* 说明:逐字节写,不要求对齐;IOA必须先按所选宽度校验,防止被静默截断。
*/
static inline void IEC60870_Object_Write_LE(uint8_t *data, uint32_t value, unsigned int length)
{
unsigned int i;
for (i = 0; i < length; ++i) {
data[i] = (uint8_t)(value >> (8U * i));
}
}
/**
* 功能:计算所选IOA字段宽度能够表示的最大地址。
* 输入参数:parameters——非空且已通过AppLayerParameters_Valid校验,sizeOfIOA为1..3。
* 输出参数:无。
* 返回值:分别为0xFF、0xFFFF或0xFFFFFF。
* 说明:位移最多24位;本函数不检查参数,非法宽度不得传入。
*/
static inline uint32_t IEC60870_Object_Max_IOA(const IEC60870_AppLayerParameters_t *parameters)
{
return (UINT32_C(1) << (8U * (unsigned int)parameters->sizeOfIOA)) - 1U;
}
#endif /* IEC60870_INFORMATION_OBJECTS_INTERNAL_H */
@@ -0,0 +1,53 @@
/* 共用发送入口只做接口分派;101/104分别提供其实际处理函数。 */
#include "IEC60870_Slave.h"
/**
* 功能:将普通ASDU发送请求分派给对应协议。
* 输入参数:self——连接接口;asdu——待提交ASDU。
* 输出参数:由接入实现记录提交结果。
* 返回值:接入函数的布尔结果;连接或函数指针为空时返回false。
* 说明:ASDU合法性由接入实现检查,便于同一次调用记录准确的失败原因。
*/
bool IEC60870_MasterConnection_Send_ASDU(IEC60870_MasterConnection_t *self, IEC60870_Asdu_t *asdu)
{
return self != NULL && self->send_asdu != NULL && self->send_asdu(self, asdu);
}
/**
* 功能:将激活确认请求分派给对应协议。
* 输入参数:self——连接接口;asdu——可修改ASDU;negative——否定标志。
* 输出参数:由接入实现修改ASDU并记录提交结果。
* 返回值:接入函数的布尔结果;连接或函数指针为空时返回false。
* 说明:共用入口不依赖TCP或串口,不保存请求或执行重试。
*/
bool IEC60870_MasterConnection_Send_ACT_CON(IEC60870_MasterConnection_t *self,
IEC60870_Asdu_t *asdu, bool negative)
{
return self != NULL && self->send_act_con != NULL && self->send_act_con(self, asdu, negative);
}
/**
* 功能:将激活终止请求分派给对应协议。
* 输入参数:self——连接接口;asdu——可修改ASDU。
* 输出参数:由接入实现修改ASDU并记录提交结果。
* 返回值:接入函数的布尔结果;连接或函数指针为空时返回false。
* 说明:本入口不判断业务是否完成,调用时机由业务决定。
*/
bool IEC60870_MasterConnection_Send_ACT_TERM(IEC60870_MasterConnection_t *self, IEC60870_Asdu_t *asdu)
{
return self != NULL && self->send_act_term != NULL && self->send_act_term(self, asdu);
}
/**
* 功能:通过协议接入获取应用层参数。
* 输入参数:self——连接接口。
* 输出参数:无。
* 返回值:接入提供的只读参数指针;连接或函数指针为空时返回NULL。
* 说明:不创建默认参数,不改变连接状态,也不延长参数的生命周期。
*/
const IEC60870_AppLayerParameters_t *IEC60870_MasterConnection_Get_Application_Layer_Parameters(
IEC60870_MasterConnection_t *self)
{
if (self == NULL || self->get_application_layer_parameters == NULL) { return NULL; }
return self->get_application_layer_parameters(self);
}
@@ -0,0 +1,73 @@
/*
* 101/104共用的子站发送接口,表示一条面向主站的连接。
* 共用入口通过函数指针分派;具体发送、确认和终止由对应协议接入实现。
* 本层不包含TCP、串口、队列或连接状态机,不分配内存。
*/
#ifndef IEC60870_SLAVE_H
#define IEC60870_SLAVE_H
#include "IEC60870_Asdu.h"
#include <stdbool.h>
#ifdef __cplusplus
extern "C" {
#endif
typedef struct IEC60870_MasterConnection IEC60870_MasterConnection_t;
/* 接入实现初始化此接口并保证object及函数指针有效;业务通过下面的函数调用。
* 参数及ASDU的实际布局必须与所接协议一致。所有调用由所属事件循环串行执行。
* send返回true前必须复制或消耗ASDU原文,不能在返回后继续借用调用方字节。
* false不统一表示可重试,具体接入实现负责提供失败原因和处理约定。 */
struct IEC60870_MasterConnection {
void *object; /* 协议接入上下文;共用入口不解释此指针。 */
bool (*send_asdu)(IEC60870_MasterConnection_t *self, IEC60870_Asdu_t *asdu);
bool (*send_act_con)(IEC60870_MasterConnection_t *self, IEC60870_Asdu_t *asdu, bool negative);
bool (*send_act_term)(IEC60870_MasterConnection_t *self, IEC60870_Asdu_t *asdu);
const IEC60870_AppLayerParameters_t *(*get_application_layer_parameters)(
IEC60870_MasterConnection_t *self);
};
/**
* 功能:通过当前连接提交一条已构造好的ASDU。
* 输入参数:self——已由协议接入初始化的连接;asdu——有效ASDU对象。
* 输出参数:具体接入实现记录本次提交结果;本入口不修改ASDU字段。
* 返回值:true表示已发送或已被发送模块接手;false表示失败。
* 说明:true不等于主站已确认;false后按具体协议的结果处理,不自动重试。
*/
bool IEC60870_MasterConnection_Send_ASDU(IEC60870_MasterConnection_t *self, IEC60870_Asdu_t *asdu);
/**
* 功能:通过当前连接发送激活确认。
* 输入参数:self——已初始化连接;asdu——可修改ASDU;negative——是否否定确认。
* 输出参数:asdu原地设置COT=7及指定P/N;具体接入实现记录提交结果。
* 返回值:true表示发送模块已接手;false表示失败。
* 说明:字段在提交前修改,提交失败也不会恢复;不执行请求中的业务命令。
*/
bool IEC60870_MasterConnection_Send_ACT_CON(IEC60870_MasterConnection_t *self,
IEC60870_Asdu_t *asdu, bool negative);
/**
* 功能:通过当前连接发送激活终止。
* 输入参数:self——已初始化连接;asdu——对应请求的可修改ASDU对象。
* 输出参数:asdu原地设置COT=10、P/N=0;具体接入实现记录提交结果。
* 返回值:true表示发送模块已接手;false表示失败。
* 说明:业务在相应处理完成后调用;提交失败也不恢复已修改的字段。
*/
bool IEC60870_MasterConnection_Send_ACT_TERM(IEC60870_MasterConnection_t *self,
IEC60870_Asdu_t *asdu);
/**
* 功能:获取当前连接使用的应用层参数。
* 输入参数:self——已初始化连接。
* 输出参数:无。
* 返回值:借用的只读参数指针;接口为空或未实现时返回NULL。
* 说明:返回指针的有效期由协议接入定义;调用方不能修改参数。
*/
const IEC60870_AppLayerParameters_t *IEC60870_MasterConnection_Get_Application_Layer_Parameters(
IEC60870_MasterConnection_t *self);
#ifdef __cplusplus
}
#endif
#endif /* IEC60870_SLAVE_H */
@@ -0,0 +1,13 @@
/* Compile-time assertions for C99 targets; no runtime storage or code. */
#ifndef IEC60870_STATIC_ASSERT_H
#define IEC60870_STATIC_ASSERT_H
#if !defined(__cplusplus) && (!defined(__STDC_VERSION__) || __STDC_VERSION__ < 201112L)
#define IEC60870_ASSERT_JOIN_INNER(a, b) a##b
#define IEC60870_ASSERT_JOIN(a, b) IEC60870_ASSERT_JOIN_INNER(a, b)
/* A false constant expression produces an invalid negative array bound. */
#define _Static_assert(condition, message) \
typedef char IEC60870_ASSERT_JOIN(iec60870_static_assert_, __LINE__)[(condition) ? 1 : -1]
#endif
#endif /* IEC60870_STATIC_ASSERT_H */
@@ -0,0 +1,510 @@
/*
* IEC 60870-5-101/104 公共时间工具:日历计算、CP56Time2a 编解码及本地标准时间转换。
* 供 101 和 104 的业务层按需调用,编解码不读取协议类型或链路状态。
* CP56 编解码保留 IV 和 SU;转本地标准时间时检查 IV,处理 SU 和源时区,返回完整日历。
* 公共编码允许 SU=0/1;后续业务发送入口负责提供本地标准时间日历并设置 SU=0。
* 本文件只提供公共工具,不自动接入 ASDU 业务处理或执行校时。
* 整数公历换算按 400 年周期展开,将三月作为年内起点以统一处理二月和闰日。
* 仅在校验后的 1970..2099 年范围内运算,天数及秒数均可用 uint32_t 表示。
* 时间戳转日历可选平台库或纯整数算法;接入层提供约定的标准时区偏移,负责系统时钟、RTC 和单调计时。
*/
#include "IEC60870_Time.h"
#include <string.h>
/**
* 功能:编码两字节经过时间。
* 输入参数:value——毫秒值;capacity——out的实际容量。
* 输出参数:out——成功写入2字节,失败不变。
* 返回值:1成功;0空指针或容量不足。
* 说明:先保存输入,允许输入输出重叠;不将经过时间解释为日历时间。
*/
int IEC60870_Time_To_CP16(const IEC60870_CP16Time2a_t *value, uint8_t *out, size_t capacity)
{
uint16_t milliseconds;
if (value == NULL || out == NULL || capacity < IEC60870_CP16_LEN) { return 0; }
milliseconds = value->milliseconds;
out[0] = (uint8_t)milliseconds;
out[1] = (uint8_t)(milliseconds >> 8);
return 1;
}
/**
* 功能:解码两字节经过时间。
* 输入参数:in——低字节在前的输入;length——至少2字节。
* 输出参数:value——经过时间,失败不变。
* 返回值:1成功;0空指针或长度不足。
* 说明:CP16使用完整16位数值范围,不含质量标志。
*/
int IEC60870_Time_From_CP16(const uint8_t *in, size_t length, IEC60870_CP16Time2a_t *value)
{
IEC60870_CP16Time2a_t result;
if (in == NULL || value == NULL || length < IEC60870_CP16_LEN) { return 0; }
result.milliseconds = (uint16_t)((uint16_t)in[0] | ((uint16_t)in[1] << 8));
*value = result;
return 1;
}
/**
* 功能:编码三字节短时标。
* 输入参数:value——分钟、分钟内毫秒和IV;capacity——out容量。
* 输出参数:out——成功写入3字节,失败不变。
* 返回值:1成功;0参数或字段非法。
* 说明:分钟0..59,毫秒0..59999,IV为0/1;第三字节bit6始终为0。
*/
int IEC60870_Time_To_CP24(const IEC60870_CP24Time2a_t *value, uint8_t *out, size_t capacity)
{
uint8_t encoded[IEC60870_CP24_LEN];
if (value == NULL || out == NULL || capacity < sizeof(encoded) ||
value->milliseconds > 59999U || value->minute > 59U || value->is_invalid > 1U) { return 0; }
encoded[0] = (uint8_t)value->milliseconds;
encoded[1] = (uint8_t)(value->milliseconds >> 8);
encoded[2] = (uint8_t)(value->minute | (value->is_invalid << 7));
memcpy(out, encoded, sizeof(encoded));
return 1;
}
/**
* 功能:校验并解码三字节短时标。
* 输入参数:in——至少3字节;length——实际可读长度。
* 输出参数:value——成功保存解析值;失败保持原值。
* 返回值:1成功;0长度、保留位、分钟或毫秒非法。
* 说明:IV保留;调用方结合已有时间基准恢复小时及日期。
*/
int IEC60870_Time_From_CP24(const uint8_t *in, size_t length, IEC60870_CP24Time2a_t *value)
{
IEC60870_CP24Time2a_t result = {0};
if (in == NULL || value == NULL || length < IEC60870_CP24_LEN || (in[2] & 0x40U)) { return 0; }
result.milliseconds = (uint16_t)((uint16_t)in[0] | ((uint16_t)in[1] << 8));
result.minute = in[2] & 0x3FU;
result.is_invalid = in[2] >> 7;
if (result.milliseconds > 59999U || result.minute > 59U) { return 0; }
*value = result;
return 1;
}
#if IEC60870_TIME_USE_PLATFORM != 0 && IEC60870_TIME_USE_PLATFORM != 1
#error "IEC60870_TIME_USE_PLATFORM must be 0 or 1"
#endif
#if IEC60870_TIME_USE_PLATFORM
#ifndef _WIN32
#error "Platform time conversion currently requires Windows; use IEC60870_TIME_USE_PLATFORM=0"
#endif
#include <time.h>
#endif
/**
* 功能:判断公历闰年。
* 输入参数:year——公历年份;本函数只执行闰年规则,不检查模块支持的年份范围。
* 输出参数:无。
* 返回值:1 为闰年,0 为平年。
* 说明:能被 4 整除且不能被 100 整除,或能被 400 整除的年份为闰年。
*/
static int Is_Leap(uint32_t year)
{
return ((year % 4U) == 0U && (year % 100U) != 0U) || (year % 400U) == 0U;
}
/**
* 功能:取得指定公历月份的实际天数。
* 输入参数:year——公历年份;month——月份,合法范围为 1..12。
* 输出参数:无。
* 返回值:合法月份返回 28..31,非法月份返回 0。
* 说明:先检查月份再访问表,闰年二月单独返回 29;年份范围由上层日期检查负责。
*/
static uint32_t Days_In_Month(uint32_t year, uint32_t month)
{
static const uint8_t days[12] = {31U, 28U, 31U, 30U, 31U, 30U,
31U, 31U, 30U, 31U, 30U, 31U};
if (month < 1U || month > 12U) {
return 0U;
}
if (month == 2U && Is_Leap(year)) {
return 29U;
}
return days[month - 1U];
}
/**
* 功能:统一检查年份范围和日期是否真实存在。
* 输入参数:year——1970..2099;month——1..12;day——待检查的日号。
* 输出参数:无。
* 返回值:1 为合法日期,0 为年份、月份或日号非法。
* 说明:按当月实际天数检查 day,不接受平年二月二十九;非法月份的天数为 0,也会被拒绝。
*/
static int Date_Is_Valid(uint32_t year, uint32_t month, uint32_t day)
{
uint32_t limit;
if (year < IEC60870_TIME_MIN_YEAR || year > IEC60870_TIME_MAX_YEAR) {
return 0;
}
limit = Days_In_Month(year, month);
return day >= 1U && day <= limit;
}
/**
* 功能:检查完整日历值的日期、时分秒和毫秒范围。
* 输入参数:time——待检查的日历指针,可为空。
* 输出参数:无。
* 返回值:1 为数值合法,0 为空指针、无效日期或时间字段越界。
* 说明:小时 0..23,分/秒 0..59,毫秒 0..999;weekday 为派生字段,不参与检查。 这里只检查数值,不能据此判断时间基准、时钟是否准确或该值是否允许用于校时。
*/
static int WallTime_Is_Valid(const IEC60870_WallTime_t *time)
{
return time != NULL && Date_Is_Valid(time->year, time->month, time->day) &&
time->hour <= 23U && time->minute <= 59U && time->second <= 59U && time->ms <= 999U;
}
/**
* 功能:将公历日期转换为自 1970-01-01 起的完整天数。
* 输入参数:year、month、day——已校验的合法日期,年份须在 1970..2099 内。
* 输出参数:无。
* 返回值:完整天数,0 对应 1970-01-01;本内部函数不重复校验参数。
* 说明:将三月作为年首,一、二月归入上一年,使闰日统一落在年末。 era 为 400 年周期编号,yoe 为周期内年份,mp 为从三月起算的月份编号 0..11。 doy 为从三月起算的年内天数,
* doe 为周期内天数;每 400 年有 146097 天。 最后减去 719468,将算法的天数原点平移到 1970-01-01。
*/
static uint32_t Days_From_Civil(uint32_t year, uint32_t month, uint32_t day)
{
uint32_t y = (month <= 2U) ? (year - 1U) : year;
uint32_t era = y / 400U;
uint32_t yoe = y - era * 400U;
uint32_t mp = (month > 2U) ? (month - 3U) : (month + 9U);
uint32_t doy = (153U * mp + 2U) / 5U + day - 1U;
uint32_t doe = yoe * 365U + yoe / 4U - yoe / 100U + doy;
return era * 146097U + doe - 719468U;
}
/**
* 功能:将已校验的日历字段展开为相对 1970-01-01 00:00:00 的线性秒数。
* 输入参数:time——非空且已通过 WallTime_Is_Valid 检查的日历值。
* 输出参数:无。
* 返回值:0..IEC60870_TIME_MAX_SECONDS 的完整秒数,不包含毫秒。
* 说明:此处只计算天数和日内秒数,忽略 ms、weekday,不处理时区或 SU。 只有输入日历本身采用 UTC 时,结果才可直接作为 UTC 纪元秒数使用。
*/
static uint32_t Seconds_From_Civil(const IEC60870_WallTime_t *time)
{
return Days_From_Civil(time->year, time->month, time->day) * 86400U +
(uint32_t)time->hour * 3600U + (uint32_t)time->minute * 60U + (uint32_t)time->second;
}
/**
* 功能:根据自 1970-01-01 起的完整天数计算星期。
* 输入参数:days——模块支持年份内的天数,0 对应 1970-01-01。
* 输出参数:无。
* 返回值:0=周日,1=周一,...,6=周六。
* 说明:纪元日是周四,因此先加 4 再对 7 取余;本内部函数不检查日期范围。
*/
static uint8_t Weekday_From_Days(uint32_t days)
{
return (uint8_t)((days + 4U) % 7U);
}
/**
* 功能:供时间源适配等调用方复用日历合法性检查,不把本地日历当作UTC转秒数。
* 输入参数:time——待检查的日历指针,可以为空;weekday不参与检查。
* 输出参数:无。
* 返回值:1 年月日、时分秒和毫秒在模块范围内;0 参数非法。
* 说明:只根据传入数据计算或判定,不改写输入对象。
*/
int IEC60870_Time_Is_Valid(const IEC60870_WallTime_t *time)
{
return WallTime_Is_Valid(time);
}
/**
* 功能:校验公历日期并计算星期。
* 输入参数:year——1970..2099;month——1..12;day——当月日号。
* 输出参数:weekday——接收 0..6 的星期值,0 表示周日。
* 返回值:1 成功;0 日期非法或输出指针为空,失败时输出不变。
* 说明:输出采用0=周日、1=周一至6=周六,不使用宿主区域设置。
*/
int IEC60870_Time_Get_Weekday(uint16_t year, uint8_t month, uint8_t day, uint8_t *weekday)
{
if (weekday == NULL || !Date_Is_Valid(year, month, day)) {
return 0;
}
*weekday = Weekday_From_Days(Days_From_Civil(year, month, day));
return 1;
}
/**
* 功能:将 UTC 日历转换为自 1970-01-01 00:00:00 UTC 起的完整秒数。
* 输入参数:time——1970..2099 年的合法 UTC 日历;ms 须在 0..999 内。
* 输出参数:seconds——接收 0..IEC60870_TIME_MAX_SECONDS;0 是有效时间值。
* 返回值:1 成功;0 参数非法,失败时输出不变。
* 说明:日历类型没有时区或 SU,调用方须保证输入采用 UTC;ms 只检查范围,不计入完整秒数。 含 IV/SU 的 CP56 解析值应使用 CP56_To_Seconds,
* 不能直接丢弃标志后调用本函数。
*/
int IEC60870_Time_To_Seconds(const IEC60870_WallTime_t *time, uint32_t *seconds)
{
uint32_t result;
if (seconds == NULL || !WallTime_Is_Valid(time)) {
return 0;
}
result = Seconds_From_Civil(time);
*seconds = result;
return 1;
}
/**
* 功能:将 UTC 纪元秒数和毫秒余数还原为完整公历时间。
* 输入参数:seconds——0..IEC60870_TIME_MAX_SECONDS;ms——0..999。
* 输出参数:time——接收 UTC 年月日、时分秒、毫秒及重新计算的 weekday。
* 返回值:1 成功;0 参数非法或平台转换失败,失败时输出不变,不对越界毫秒进行截断或进位。
* 说明:编译时选择平台库或整数算法;使用局部结果,全部完成后才写回调用方输出。
*/
int IEC60870_Time_From_Seconds(uint32_t seconds, uint16_t ms, IEC60870_WallTime_t *time)
{
IEC60870_WallTime_t result = {0};
#if IEC60870_TIME_USE_PLATFORM
__time64_t stamp;
struct tm utc;
#else
uint32_t days, rem, z, era, doe, yoe, doy, mp, month, year;
#endif
if (time == NULL || seconds > IEC60870_TIME_MAX_SECONDS || ms > 999U) {
return 0;
}
#if IEC60870_TIME_USE_PLATFORM
/* 显式使用 64 位接口,避免 32 位 time_t 的 2038 年上限;转换结果始终为 UTC。 */
stamp = (__time64_t)seconds;
if (_gmtime64_s(&utc, &stamp) != 0) {
return 0;
}
result.year = (uint16_t)(utc.tm_year + 1900);
result.month = (uint8_t)(utc.tm_mon + 1);
result.day = (uint8_t)utc.tm_mday;
result.hour = (uint8_t)utc.tm_hour;
result.minute = (uint8_t)utc.tm_min;
result.second = (uint8_t)utc.tm_sec;
result.weekday = (uint8_t)utc.tm_wday;
#else
/* 先分成完整天数和日内秒数,日期换算与时分秒拆分分别进行。 */
days = seconds / 86400U;
rem = seconds % 86400U;
/*
* 与 Days_From_Civil 反向对应:先恢复以三月为年首的天数,再求 400 年周期及周期内年份。
* yoe 中的修正项处理闰日、世纪和周期末日,避免将周期最后一天归入下一周期。
* mp 先得到从三月起算的月份编号,再还原为 1..12;一、二月归回下一公历年。
*/
z = days + 719468U;
era = z / 146097U;
doe = z - era * 146097U;
yoe = (doe - doe / 1460U + doe / 36524U - doe / 146096U) / 365U;
doy = doe - (365U * yoe + yoe / 4U - yoe / 100U);
mp = (5U * doy + 2U) / 153U;
month = (mp < 10U) ? (mp + 3U) : (mp - 9U);
year = yoe + era * 400U + ((month <= 2U) ? 1U : 0U);
result.year = (uint16_t)year;
result.month = (uint8_t)month;
result.day = (uint8_t)(doy - (153U * mp + 2U) / 5U + 1U);
result.hour = (uint8_t)(rem / 3600U);
result.minute = (uint8_t)((rem % 3600U) / 60U);
result.second = (uint8_t)(rem % 60U);
result.weekday = Weekday_From_Days(days);
#endif
result.ms = ms;
*time = result;
return 1;
}
/**
* 功能:将 UTC 纪元秒数和毫秒直接展开为固定 UTC+8 的本地标准时间。
* 输入参数:utc_seconds——未加时区偏移的 UTC 纪元秒数;ms——0..999。
* 输出参数:local_time——本地年月日、时分秒、毫秒及重新计算的星期。
* 返回值:1 成功;0 参数非法、本地日期超出 1970..2099 或平台转换失败,失败时输出不变。
* 说明:先检查再平移秒数,只展开一次日历;调用方无需手动调整小时、日期或星期。
*/
int IEC60870_Time_Seconds_To_Local(uint32_t utc_seconds, uint16_t ms,
IEC60870_WallTime_t *local_time)
{
const uint32_t local_offset_seconds = (uint32_t)IEC60870_LOCAL_UTC_OFFSET_MINUTES * 60U;
if (local_time == NULL || ms > 999U ||
utc_seconds > IEC60870_TIME_MAX_SECONDS - local_offset_seconds) {
return 0;
}
/* 平移值只用于展开本地日历,不作为新的 UTC 时间戳保存或返回。 */
return IEC60870_Time_From_Seconds(utc_seconds + local_offset_seconds, ms, local_time);
}
/**
* 功能:将源日历、SU 和源标准时区一起换算为有效的 UTC 纪元秒数。
* 输入参数:value——合法的 2000..2099 年 CP56 解析值,IV=0,SU/has_weekday 为 0/1;
* standard_utc_offset_minutes——源标准当地时间减 UTC 的分钟数,范围 -1439..1439, 不包含夏令时;源标准时区 UTC+8 填 480,即使 SU=1
* 也不改变该偏移。
* 输出参数:seconds——接收 UTC 完整秒数,毫秒仍由输入日历保存。
* 返回值:1 成功;0 参数非法、IV=1 或结果越界,失败时输出不变。
* 说明:原始解码尚未修正 SU;在本函数中扣除一小时后,不应再由业务重复扣减。
*/
int IEC60870_Time_CP56_To_Seconds(const IEC60870_CP56Time2a_t *value,
int16_t standard_utc_offset_minutes, uint32_t *seconds)
{
int64_t utc_seconds;
/*
* 标准时区偏移不包含夏令时,绝对值须小于一天;这是本接口的参数范围。
* IV=1 的时间可被原始编解码保留,但不能在这里作为有效时间转换;SU=1 则正常参与换算。
*/
if (value == NULL || seconds == NULL || !WallTime_Is_Valid(&value->time) ||
value->time.year < IEC60870_CP56_MIN_YEAR || value->time.year > IEC60870_CP56_MAX_YEAR ||
value->is_invalid != 0U || value->is_summer_time > 1U || value->has_weekday > 1U ||
standard_utc_offset_minutes < -1439 || standard_utc_offset_minutes > 1439) {
return 0;
}
/*
* 标准时间 = 报文日历 - SU * 3600;UTC = 标准时间 - 标准时区偏移。
* 在秒数上调整可跨日/月/年;有符号 64 位中间值避免 2038 年问题及加减回绕。
* 原日历和 SU 保持配套,不能先改小时再保留 SU,否则再次换算会重复扣减。
*/
utc_seconds = (int64_t)Seconds_From_Civil(&value->time) -
(int64_t)value->is_summer_time * INT64_C(3600) -
(int64_t)standard_utc_offset_minutes * INT64_C(60);
/* 在有符号域中检查最终值,再转 uint32_t,避免负数或超范围结果被当成有效纪元秒数。 */
if (utc_seconds < 0 || utc_seconds > (int64_t)IEC60870_TIME_MAX_SECONDS) {
return 0;
}
/* 读取输入和检查结果范围后才提交输出;毫秒余数仍取 value->time.ms。 */
*seconds = (uint32_t)utc_seconds;
return 1;
}
/**
* 功能:将 CP56 解析值转换为固定 UTC+8 的本地标准时间日历。
* 输入参数:value——合法 CP56 解析值,须保留配套的源日历及 IV/SU; source_standard_utc_offset_minutes——源标准时区偏移,单位为分钟,范围
* -1439..1439, 不包含夏令时;源标准时区与本地相同时传 IEC60870_LOCAL_UTC_OFFSET_MINUTES。
* 输出参数:local_time——接收本地标准时间年月日、时分秒、毫秒和重新计算的星期。
* 返回值:1 成功;0 参数非法、IV=1、转换结果越界或平台转换失败,失败时输出不变。
* 说明:通常在 From_CP56 成功后调用;输出已处理 SU 和时区,业务不再加八小时或减一小时。
*/
int IEC60870_Time_CP56_To_Local(const IEC60870_CP56Time2a_t *value,
int16_t source_standard_utc_offset_minutes,
IEC60870_WallTime_t *local_time)
{
uint32_t utc_seconds;
/* 下层已统一检查 IV、SU、源偏移和日期,并完成夏令时修正;本层不再重复扣除一小时。 */
if (local_time == NULL ||
!IEC60870_Time_CP56_To_Seconds(value, source_standard_utc_offset_minutes, &utc_seconds)) {
return 0;
}
/* 与直接从时间戳取本地时间共用入口,统一处理上限、跨日/月/年和星期。 */
return IEC60870_Time_Seconds_To_Local(utc_seconds, value->time.ms, local_time);
}
/**
* 功能:将日历及 IV/SU/星期标志编码为七字节 CP56Time2a。
* 输入参数:value——合法的 2000..2099 年日历,三个标志均为 0/1; capacity——out 的实际可写字节数,至少 IEC60870_CP56_LEN。
* 输出参数:out——只写前七字节,超出部分保持原样。
* 返回值:1 成功;0 参数非法,失败时整个输出缓冲区不变。
* 说明:公共编码生成规范日历,GEN 固定为 0;不用于恢复接收时的原始七字节。 业务发送统一设置 SU=0 的约束由后续业务入口落实;原文确认应直接保留请求时标。
*/
int IEC60870_Time_To_CP56(const IEC60870_CP56Time2a_t *value, uint8_t *out, size_t capacity)
{
uint8_t encoded[IEC60870_CP56_LEN];
uint8_t weekday = 0U;
uint16_t msec;
if (value == NULL || out == NULL || capacity < IEC60870_CP56_LEN ||
!WallTime_Is_Valid(&value->time) ||
value->time.year < IEC60870_CP56_MIN_YEAR || value->time.year > IEC60870_CP56_MAX_YEAR ||
value->is_invalid > 1U || value->is_summer_time > 1U || value->has_weekday > 1U) {
return 0;
}
/* 报文星期 0 表示未使用;携带星期时由日期重算,将内存中的周日 0 转成报文值 7。 */
if (value->has_weekday != 0U) {
weekday = Weekday_From_Days(Days_From_Civil(value->time.year, value->time.month, value->time.day));
weekday = (uint8_t)((weekday == 0U) ? 7U : weekday);
}
/* CP56 前两字节保存分钟内毫秒,范围 0..59999,由秒和毫秒余数组合而成。 */
msec = (uint16_t)((uint32_t)value->time.second * 1000U + value->time.ms);
/* 逐字节布局,不把结构体转成报文,也不要求输出缓冲区对齐。 */
encoded[0] = (uint8_t)(msec & 0xFFU);
encoded[1] = (uint8_t)(msec >> 8);
/* 解析结构没有 GEN 字段,故此处仅写分钟和 IV,bit6 保持 0;不能据此转发替代时标。 */
encoded[2] = (uint8_t)(value->time.minute | (uint8_t)(value->is_invalid << 7));
/*
* SU 按输入写入 bit7,不改变小时值;小时字段及 SU 已校验,保留位保持为 0。
* 这里不能直接清除 SU=1:若小时仍是夏令时值,单独清标志会改变报文所表达的时刻。
*/
encoded[3] = (uint8_t)(value->time.hour | (uint8_t)(value->is_summer_time << 7));
/* 日号占低五位、星期占高三位;月份和两位年份单独存储,未使用的高位保持为 0。 */
encoded[4] = (uint8_t)(value->time.day | (uint8_t)(weekday << 5));
encoded[5] = value->time.month;
encoded[6] = (uint8_t)(value->time.year - IEC60870_CP56_MIN_YEAR);
/* 校验和读取输入完成后才统一提交输出;也允许 out 与 value 的存储重叠。 */
memcpy(out, encoded, IEC60870_CP56_LEN);
return 1;
}
/**
* 功能:校验并解码前七字节 CP56Time2a,保留源日历及 IV/SU。
* 输入参数:in——报文起点;length——实际可读字节数,至少 IEC60870_CP56_LEN。
* 输出参数:value——接收日历、IV、SU 和是否携带星期;weekday 始终按日期重新计算。
* 返回值:1 成功;0 指针、长度、RES2/3/4 或日期时间不合法,失败时输出不变。
* 说明:后续字节不处理;SU=1 或 IV=1 本身不导致解码失败,仍要求日期及其余字段合法。 成功只表示满足格式约束,尚未进行时间转换,也不表示该时间可以用于校时。
*/
int IEC60870_Time_From_CP56(const uint8_t *in, size_t length, IEC60870_CP56Time2a_t *value)
{
IEC60870_CP56Time2a_t result = {0};
uint16_t msec;
if (in == NULL || value == NULL || length < IEC60870_CP56_LEN) {
return 0;
}
/*
* IEC 60870-5-101 7.2.6.18 允许 RES1(分钟 bit6)在监视方向表示 GEN。
* IEC TS 60870-5-604 表5/7 也列出 RES1=0/1,不能把它与 IV 或非法编码混同。
* 本日历解析值不导出 GEN;需要原文回显的业务必须保留收到的七字节。
* RES2/3/4(小时 bit5..6、月份 bit4..7、年份 bit7)仍要求为 0。
*/
if ((in[3] & 0x60U) != 0U ||
(in[5] & 0xF0U) != 0U || (in[6] & 0x80U) != 0U) {
return 0;
}
/* 按低字节在前还原分钟内毫秒;超过 59999 不能表示合法的秒与毫秒余数。 */
msec = (uint16_t)((uint16_t)in[0] | ((uint16_t)in[1] << 8));
if (msec > 59999U) {
return 0;
}
result.time.year = (uint16_t)(IEC60870_CP56_MIN_YEAR + in[6]);
result.time.month = (uint8_t)(in[5] & 0x0FU);
result.time.day = (uint8_t)(in[4] & 0x1FU);
result.time.hour = (uint8_t)(in[3] & 0x1FU);
/* 分钟仅取低六位:bit6 的 GEN 不影响数值,bit7 的 IV 必须另存,不能随掩码丢失。 */
result.time.minute = (uint8_t)(in[2] & 0x3FU);
result.time.second = (uint8_t)(msec / 1000U);
result.time.ms = (uint16_t)(msec % 1000U);
result.is_invalid = (uint8_t)((in[2] >> 7) & 1U);
/* 与原始小时配套保留 SU,交给后续转换接口处理,避免丢失信息或重复扣除一小时。 */
result.is_summer_time = (uint8_t)((in[3] >> 7) & 1U);
/* 报文星期 0 表示未提供星期;内存中的 weekday=0 表示周日,需由 has_weekday 区分。 */
result.has_weekday = (uint8_t)((in[4] >> 5) != 0U);
/*
* 年份 100..127 会展开为 2100..2127,在此随其他无效日期一起拒绝,不自动映射世纪。
* 必须先验证实际日期,再重算星期;容忍星期不符不允许把 2 月 30 日等值自动进位。
*/
if (!WallTime_Is_Valid(&result.time)) {
return 0;
}
/*
* 星期是 101 7.2.6.18 的可选信息。本库按年月日解释时刻,不因附带星期不符而拒绝。
* 这是接收兼容策略;实际日期仍须合法,输出星期始终重算,编码时也不传播错误星期。
*/
result.time.weekday = Weekday_From_Days(Days_From_Civil(result.time.year, result.time.month,
result.time.day));
/*
* IV=1 仍可供业务记录;取有效的本地标准时间时,应将完整结果交给 CP56_To_Local 检查和转换。
* 是否允许校时、远端时间是否合理仍由业务判断,此处不设置 RTC。
* 最后才写回整个解析值:此前任一失败都不修改调用方输出。
*/
*value = result;
return 1;
}
@@ -0,0 +1,244 @@
/*
* 模块名称:IEC 60870-5-101/104 公共时间工具
* 模块功能:CP16/CP24/CP56编解码、公历日期/星期、本地标准时间及纪元秒数工具。
* 适用协议:101 和 104 的时间格式共用同一实现,独立于各自的帧格式和链路层。
* 职责边界:公共编解码保留 IV/SU,允许合法的 SU=0/1,不调整输入日历。
* 业务接收时通过 CP56_To_Local 检查 IV、处理 SU 和源时区,取得本地标准时间日历。
* 后续业务发送入口须保证日历已是本地标准时间,并统一设置 SU=0。
* 接入状态:IEC60870_Asdu 已复用 CP56 编解码;事件采集、时间源读取和实际校时仍由业务接入。
* 适用平台:可选平台库或纯整数日期转换;不读取系统时钟、不设置 RTC、不推断时区规则或处理链路定时器。
*/
#ifndef IEC60870_TIME_H
#define IEC60870_TIME_H
#include <stddef.h>
#include <stdint.h>
#ifdef __cplusplus
extern "C" {
#endif
/* CP16为经过时间;CP24仅含分钟及分钟内毫秒,不能单独恢复完整日期。 */
#define IEC60870_CP16_LEN 2U
#define IEC60870_CP24_LEN 3U
#define IEC60870_CP56_LEN 7U
#define IEC60870_TIME_MIN_YEAR 1970U
#define IEC60870_TIME_MAX_YEAR 2099U
/* 两位年份按 2000 年起解释是本实现的世纪约定,须与通信对端一致。 */
#define IEC60870_CP56_MIN_YEAR 2000U
#define IEC60870_CP56_MAX_YEAR 2099U
/* 2099-12-31 23:59:59 UTC;本模块不接受 uint32_t 可表示但超出约定年份的秒数。 */
#define IEC60870_TIME_MAX_SECONDS UINT32_C(4102444799)
/*
* 本地标准时区固定为 UTC+8,不读取系统时区。
* 源标准时区也为 UTC+8 时,转换接口传入此值;即使报文 SU=1,源标准偏移仍为 480。
* 其他源时区由调用方按双方约定提供标准偏移,不能一律传入此值。
*/
#define IEC60870_LOCAL_UTC_OFFSET_MINUTES 480
/*
* 时间戳转日历的编译选项:1 使用平台库,0 使用本模块保留的纯整数算法。
* 当前平台库后端为 Windows CRT 的 _gmtime64_s;Windows 默认 1,其他平台默认 0。
* 无合适时间库时,在编译 IEC60870_Time.c 时定义 IEC60870_TIME_USE_PLATFORM=0。
* 两种实现均输出 UTC,支持相同的 1970..2099 年范围,不读取当前时间或本地时区。
*/
#ifndef IEC60870_TIME_USE_PLATFORM
#ifdef _WIN32
#define IEC60870_TIME_USE_PLATFORM 1
#else
#define IEC60870_TIME_USE_PLATFORM 0
#endif
#endif
typedef struct {
uint16_t milliseconds; /* CP16经过时间,0..65535毫秒,无IV或SU。 */
} IEC60870_CP16Time2a_t;
typedef struct {
uint16_t milliseconds; /* CP24分钟内毫秒,0..59999,包含秒。 */
uint8_t minute; /* 0..59;不含小时、日期或时区。 */
uint8_t is_invalid; /* IV,0/1;编码和解码保留。 */
} IEC60870_CP24Time2a_t;
/**
* 功能:编码CP16经过时间或CP24短时标。
* 输入参数:value——非空解析值;capacity——输出容量,分别至少2/3字节。
* 输出参数:out——低字节在前的协议字节,不改变输入时间基准。
* 返回值:1成功;0参数或字段非法,输出不变。
* 说明:CP24保留IV但检查分钟和毫秒范围,不推断小时或日期,不携带SU。
*/
int IEC60870_Time_To_CP16(const IEC60870_CP16Time2a_t *value, uint8_t *out, size_t capacity);
/**
* 功能:编码三字节短时标。
* 输入参数:value——分钟、分钟内毫秒和IV;capacity——out容量。
* 输出参数:out——成功写入3字节,失败不变。
* 返回值:1成功;0参数或字段非法。
* 说明:分钟0..59,毫秒0..59999,IV为0/1;第三字节bit6始终为0。
*/
int IEC60870_Time_To_CP24(const IEC60870_CP24Time2a_t *value, uint8_t *out, size_t capacity);
/**
* 功能:解码CP16经过时间或CP24短时标。
* 输入参数:in——非空字节串;length——可读长度,分别至少2/3字节。
* 输出参数:value——成功后保存独立解析值,失败不变。
* 返回值:1成功;0参数、长度、CP24保留位或字段非法。
* 说明:只读取前2/3字节;CP24的IV=1仍可解析,但不表示时间有效。
*/
int IEC60870_Time_From_CP16(const uint8_t *in, size_t length, IEC60870_CP16Time2a_t *value);
/**
* 功能:校验并解码三字节短时标。
* 输入参数:in——至少3字节;length——实际可读长度。
* 输出参数:value——成功保存解析值;失败保持原值。
* 返回值:1成功;0长度、保留位、分钟或毫秒非法。
* 说明:IV保留;调用方结合已有时间基准恢复小时及日期。
*/
int IEC60870_Time_From_CP24(const uint8_t *in, size_t length, IEC60870_CP24Time2a_t *value);
/*
* 公历时间值,不携带时区或 SU;Seconds_To_Local、CP56_To_Local 输出本地标准时间,
* From_Seconds 输出 UTC。
* 调用 To_Seconds 时须提供 UTC 日历,不能把本地标准时间日历直接当成 UTC 转秒数。
* weekday 为派生字段:0=周日,1=周一,...,6=周六。
* 编码及转秒数时忽略传入的 weekday;解码及从秒数转换时按日期重新计算。
* 此类型仅供内存中传值,不能直接作为 CP56Time2a 的报文字节布局。
*/
typedef struct {
uint16_t year; /* 普通日历为 1970..2099;CP56 编解码限于 2000..2099 */
uint8_t month; /* 1..12 */
uint8_t day; /* 1..当月实际天数 */
uint8_t hour; /* 0..23 */
uint8_t minute; /* 0..59 */
uint8_t second; /* 0..59,不表示闰秒 */
uint16_t ms; /* 0..999 */
uint8_t weekday; /* 0..6,输出时由日期推导 */
} IEC60870_WallTime_t;
/*
* CP56Time2a 的日历解析值;IV/SU 与普通日历分开保存,供业务判断有效性及时间基准。
* is_invalid、is_summer_time 和 has_weekday 只能为 0 或 1。
* 编码由 has_weekday 决定是否携带星期,IV 和 SU 按输入保留。
* 此日历值不保存接收的 GEN(分钟 bit6)和原始星期,不能用于七字节原文的无损回显。
* IV=1 仍可编解码,但日期字段仍须合法;成功不表示该时间可用于校时。
* 标准允许选用 SU 但不推荐使用;本项目后续业务发送入口负责统一设置 SU=0。
* 公共编解码支持 SU=0/1,不强制清零;发送前须确保日历与标志一致,不能只清 SU 而保留夏令时日历。
* SU 不携带时区信息;取本地标准时间时将完整解析值及源标准时区偏移交给 CP56_To_Local。
*/
typedef struct {
IEC60870_WallTime_t time; /* 2000..2099;按双方约定的时间基准及 SU 解释 */
uint8_t is_invalid; /* IV:1=时间无效,0=未置无效标志 */
uint8_t is_summer_time; /* SU:0=标准时间,1=夏令时;原始编解码保留,CP56 转换接口在为 1 时扣除一小时 */
uint8_t has_weekday; /* 1=报文带星期,0=报文星期域为 0(未使用) */
} IEC60870_CP56Time2a_t;
/*
* 所有接口:成功返回 1;参数/格式非法、结果越界、平台转换失败或将 IV=1 转为有效时间时返回 0。
* 返回 0 时不修改任何输出;调用方仍须保证指针有效且实际空间不少于所报长度。
* 模块不维护共享可变状态或动态内存。输入和输出允许重叠。
* 成功写回输出时,会覆盖与输出重叠的输入存储;需要保留原始输入时应使用独立输出存储。
*/
/**
* 功能:检查日历的年月日、时分秒及毫秒是否合法,不进行时间转换。
* 输入参数:time——待检查的日历值;年份1970..2099,毫秒0..999。
* 输出参数:无。
* 返回值:1 数值合法;0 空指针、无效日期或字段越界。
* 说明:忽略派生字段weekday;不判断时区、时钟是否准确或是否允许校时。
*/
int IEC60870_Time_Is_Valid(const IEC60870_WallTime_t *time);
/**
* 功能:检查公历日期并计算星期。
* 输入参数:year——1970..2099;month、day——合法月份和日期。
* 输出参数:weekday——0=周日,1=周一,...,6=周六。
* 返回值:1 成功;0 日期非法或输出为空,输出不变。
* 说明:输出采用0=周日、1=周一至6=周六,不使用宿主区域设置。
*/
int IEC60870_Time_Get_Weekday(uint16_t year, uint8_t month, uint8_t day, uint8_t *weekday);
/**
* 功能:将 UTC 日期和时间转换为自 1970-01-01 00:00:00 UTC 起的完整秒数。
* 输入参数:time——年份 1970..2099,毫秒 0..999,其余字段须组成合法时间。
* 输出参数:seconds——0..IEC60870_TIME_MAX_SECONDS;0 是有效纪元时间,不表示失败。
* 返回值:1 成功;0 参数非法,输出不变。
* 说明:ms 参与范围校验,但不计入完整秒数;需保留亚秒精度时另行保存 time->ms。 忽略 weekday,不进行本地时区换算,也不计闰秒。 time 没有时区或 SU,
* 函数无法检查其是否真的采用 UTC,须由调用方保证。 对 CP56 解析值,取本地标准时间调用 CP56_To_Local;取纪元秒数调用 CP56_To_Seconds。
*/
int IEC60870_Time_To_Seconds(const IEC60870_WallTime_t *time, uint32_t *seconds);
/**
* 功能:将纪元秒数和毫秒余数转换为 UTC 日期和时间。
* 输入参数:seconds——0..IEC60870_TIME_MAX_SECONDS;ms——0..999。
* 输出参数:time——完整公历时间及按日期计算的 weekday。
* 返回值:1 成功;0 参数非法或平台转换失败,输出不变;不会把越界毫秒截断成 999。
* 说明:由 IEC60870_TIME_USE_PLATFORM 选择平台库或纯整数算法;均不做本地时区换算。
*/
int IEC60870_Time_From_Seconds(uint32_t seconds, uint16_t ms, IEC60870_WallTime_t *time);
/**
* 功能:将 UTC 纪元秒数和毫秒余数直接转换为本地标准时间日历(固定 UTC+8)。
* 输入参数:utc_seconds——未加时区偏移的 UTC 纪元秒数;ms——0..999。 本地日期须在 1970..2099 年内,因此 utc_seconds 上限为
* IEC60870_TIME_MAX_SECONDS - IEC60870_LOCAL_UTC_OFFSET_MINUTES * 60。
* 输出参数:local_time——本地年月日、时分秒、毫秒及重新计算的星期。
* 返回值:1 成功;0 参数非法、本地日期越界或平台转换失败,输出不变。
* 说明:内部统一处理时区偏移及跨日/月/年,调用方不再加八小时。 不读取系统时区或开启夏令时;已是固定 UTC+8 标准时间的 RTC 日历可直接用于 CP56 编码。
*/
int IEC60870_Time_Seconds_To_Local(uint32_t utc_seconds, uint16_t ms,
IEC60870_WallTime_t *local_time);
/**
* 功能:将 CP56Time2a 解析值转换为 UTC 纪元完整秒数,SU=1 时扣除一小时。
* 输入参数:value——合法的 2000..2099 年日期时间,IV=0,SU/has_weekday 为 0/1; standard_utc_offset_minutes——源报文标准当地时间减
* UTC 的分钟数,范围 -1439..1439, 向东为正、向西为负;UTC 填 0,UTC+8 填 480,UTC-5 填 -300。 此偏移必须不含夏令时的一小时;SU 会单独扣除,
* 不能重复计算。
* 输出参数:seconds——0..IEC60870_TIME_MAX_SECONDS 的 UTC 秒数。
* 返回值:1 成功;0 参数非法、IV=1 或换算结果越界,输出不变。
* 说明:UTC = 报文日历对应秒数 - SU * 3600 - 标准时区偏移 * 60。 在秒数上运算,支持跨日/月/年;年份 2000 的输入可换算为 1999 年的 UTC。 ms
* 校验后不计入完整秒数;未与输出重叠时,输入日期、SU 和毫秒均保持不变。 忽略传入的 weekday;不根据日期猜测夏令时,不访问系统时区或设置 RTC。
*/
int IEC60870_Time_CP56_To_Seconds(const IEC60870_CP56Time2a_t *value,
int16_t standard_utc_offset_minutes, uint32_t *seconds);
/**
* 功能:将 CP56Time2a 解析值转换为本地标准时间日历(固定 UTC+8),并处理 SU。
* 输入参数:value——合法的 2000..2099 年日期时间,IV=0,SU/has_weekday 为 0/1;
* source_standard_utc_offset_minutes——源报文标准当地时间减 UTC 的分钟数, 范围 -1439..1439,不含夏令时;双方约定本地标准时间时传
* IEC60870_LOCAL_UTC_OFFSET_MINUTES(480),源报文为 UTC 时传 0。
* 输出参数:local_time——1970..2099 年的本地标准时间年月日、时分秒、毫秒及重新计算的星期。
* 返回值:1 成功;0 参数非法、IV=1、本地标准时间越界或平台转换失败,输出不变。
* 说明:本地标准时间 = 报文日历 - SU * 一小时 - 源标准时区偏移 + 八小时。 源标准时区为 UTC+8 时,SU=0 保持原时间,SU=1 减一小时,自动处理跨日/月/年。
* 毫秒原样保留;日历结果通过 local_time 输出,函数返回值仅表示成功或失败。 输入与输出未重叠时,不改写输入日历或 SU。 结果已是本地标准时间,
* 调用方无需再次加八小时或减夏令时的一小时。 业务再次发送此日历时应构造新的 CP56 值并置 SU=0,不能沿用原报文的 SU=1。
*/
int IEC60870_Time_CP56_To_Local(const IEC60870_CP56Time2a_t *value,
int16_t source_standard_utc_offset_minutes,
IEC60870_WallTime_t *local_time);
/**
* 功能:将 CP56Time2a 解析值编码为 7 字节报文,毫秒域按低字节在前写入。
* 输入参数:value——合法的 2000..2099 年日期时间,三个标志字段均为 0/1; capacity——out 可写字节数,至少 IEC60870_CP56_LEN。
* 输出参数:out——仅写前 7 字节,GEN 及保留位清零,IV 和 SU 按输入保留。
* 返回值:1 成功;0 参数非法,整个输出缓冲区不变。
* 说明:has_weekday=1 时由日期计算报文星期(1=周一..7=周日),否则填 0。 此接口生成日历时标;接收后再编码会纠正错误星期并清除 GEN,不能代替原文应答。 不校时、不转换时区,
* 也不因 SU=1 而调整小时值。 SU=0/1 均可编码,本接口不会自动清零或因 SU=1 而拒绝合法输入。 后续业务发送入口负责传入已是本地标准时间的日历并设置 SU=0;
* 此处只执行公共编码。 IV=1 不放宽日期、时间及标志取值的检查。
*/
int IEC60870_Time_To_CP56(const IEC60870_CP56Time2a_t *value, uint8_t *out, size_t capacity);
/**
* 功能:检查并解析前 7 字节 CP56Time2a,后续字节留给调用方处理。
* 输入参数:in——报文起点;length——可读字节数,至少 IEC60870_CP56_LEN。
* 输出参数:value——源报文的日历时间、IV、SU 及报文是否携带星期,尚未转换为本地标准时间; weekday 始终由日期计算。
* 返回值:1 成功;0 参数、RES2/3/4 或日期时间非法,输出不变。
* 说明:年份域只接受 0..99,解释为 2000..2099;星期域 0 表示未使用, 非零星期仅标记 has_weekday,不因与日期不符而拒绝,输出星期由日期重算。 接受分钟
* bit6(RES1/GEN)为 0/1,此日历值不导出它,编码时该位为 0。 小时 bit5..6、月份 bit4..7、年份 bit7(RES2/3/4)仍必须为 0。
* 星期容忍是本库针对标准可选字段的接收策略,不放宽实际日期或业务时效检查。 SU=1 本身不导致失败,IV/SU 均原样返回;不转换时区或夏令时。 IV=1 且其余字段合法时仍可成功解析,
* 供业务记录;两个 CP56 转换接口会拒绝该无效时间。 解码后取本地标准时间调用 CP56_To_Local;需要纪元秒数时调用 CP56_To_Seconds。 转换前须保留完整的日历及
* SU,不可先清 SU,也不可先减一小时再携带 SU=1 转换。 业务仍须检查时间约定及校时权限;不自动设置 RTC。
*/
int IEC60870_Time_From_CP56(const uint8_t *in, size_t length, IEC60870_CP56Time2a_t *value);
#ifdef __cplusplus
}
#endif
#endif /* IEC60870_TIME_H */
@@ -0,0 +1,30 @@
/*
* 101/104共用的应用层值类型:ASDU字段宽度和总长上限。
* 只依赖标准整数类型,不包含传输帧、连接、队列或平台接口。
* 调用方按接入协议显式选择参数;104的默认配置由104接入层提供。
*/
#ifndef IEC60870_TYPES_H
#define IEC60870_TYPES_H
#include <stdint.h>
#include "IEC60870_StaticAssert.h"
#define IEC60870_MAX_ASDU_LEN 254 /* 通用101/104 ASDU存储上限;104传输仍限249。 */
/* 应用层参数描述ASDU字段宽度及长度上限,字段使用int以便校验原始范围。
* Type ID/VSQ固定为1字节;COT/CA可为1或2字节,IOA可为1、2或3字节。
* 通用ASDU上限为254;接入本工程104 TCP时使用2/2/3及不超过249的上限。
* 参数由调用方持有,构造器及解析视图借用它;使用期间必须有效且不可修改。
* originatorAddress供业务作为发送OA的默认值,报文构造仍以header中显式OA为准;
* COT为1字节时不编码OA,解析得到的OA为0。配置需要双方一致,不自动协商。 */
typedef struct {
int sizeOfTypeId; /* 固定1,不支持修改。 */
int sizeOfVSQ; /* 固定1,不支持修改。 */
int sizeOfCOT; /* 1或2;2字节时包含OA。 */
int originatorAddress; /* 业务默认源发地址,0..255。 */
int sizeOfCA; /* 公共地址长度,1或2。 */
int sizeOfIOA; /* 信息对象地址长度,1、2或3。 */
int maxSizeOfASDU; /* 包含公共头;至少容纳头,最多254。 */
} IEC60870_AppLayerParameters_t;
#endif /* IEC60870_TYPES_H */
@@ -0,0 +1,119 @@
/* 附录 C 运行日志:固定容量循环保存,介质原子性由调用方后端保证。
* 无堆、无操作系统和文件系统依赖;全部访问须由调用方串行化。 */
#ifndef IEC60870_USER_LOG_H
#define IEC60870_USER_LOG_H
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#ifdef __cplusplus
extern "C" {
#endif
/* CAPACITY 是介质逻辑槽数,不要求 RAM 保存整环;WIRE_MAX 为单条最大编码:
* 32 字节固定头 + 128 字节文本 + 4 字节 CRC。UTC 两端均包含在合法范围内。 */
#define IEC60870_USER_LOG_CAPACITY 1024U
#define IEC60870_USER_LOG_TEXT_MAX 128U
#define IEC60870_USER_LOG_WIRE_MAX 164U
#define IEC60870_USER_LOG_UTC_MIN UINT64_C(946656000000)
#define IEC60870_USER_LOG_UTC_MAX UINT64_C(4102415999999)
/* INVALID 表示输入错误;ERROR 包括实例/介质错误及序号耗尽。并非所有 ERROR
* 都设置 faulted,例如耗尽时已有记录仍可查询;EMPTY 用于空槽或越界查询。 */
typedef enum {
IEC60870_USER_LOG_INVALID = -2,
IEC60870_USER_LOG_ERROR = -1,
IEC60870_USER_LOG_EMPTY = 0,
IEC60870_USER_LOG_OK = 1
} IEC60870_UserLogResult_t;
/* index 为 0..1023 的逻辑槽。read 仅在 OK 时填写实际 size;EMPTY 只表示
* 从未提交的空槽,损坏/短读/I/O 失败必须 ERROR。commit 成功表示原子替换并
* 完成持久同步;失败可能已经提交,核心将故障闭锁直到重新 Init。
* context 由调用方持有,缓冲仅在回调中借用,不得保存指针或重入实例。 */
typedef struct {
void *context;
IEC60870_UserLogResult_t (*read)(void *context, uint32_t index,
uint8_t *bytes, size_t capacity, size_t *size);
bool (*commit)(void *context, uint32_t index, const uint8_t *bytes, size_t size);
} IEC60870_UserLogStore_t;
/* sequence 按提交顺序递增,校时回拨不改变记录顺序;text 始终以 NUL 结尾。
* 这是独立的内存值副本,text 的终止符和结构体填充不属于持久化字节布局。 */
typedef struct {
uint64_t sequence;
uint64_t utc_ms;
uint8_t type;
uint8_t value;
char text[IEC60870_USER_LOG_TEXT_MAX + 1U];
} IEC60870_UserLogRecord_t;
/* 调用方静态分配;公开布局仅为分配方便,业务不得直接改内部状态。
* store 为浅拷贝;wire 是复用工作区,不能作为跨调用的记录借用。 */
typedef struct {
IEC60870_UserLogStore_t store;
uint64_t sequence;
uint64_t latest_utc_ms;
size_t count;
bool initialized;
bool faulted;
uint8_t wire[IEC60870_USER_LOG_WIRE_MAX];
} IEC60870_UserLog_t;
/**
* 功能:扫描全部槽并校验格式、CRC、槽号和序号连续性;不清空或修复介质。
* 输入参数:self——调用方持有的模块实例及当前状态;store——同步存储回调表及其上下文。
* 输出参数:self——本次操作后的运行状态及复用工作区。
* 返回值:OK表示操作完成;INVALID表示参数或操作状态非法;ERROR表示实例不可用、I/O失败或内容损坏。
* 说明:self/store 必须非空且回调齐全。允许 store=&self->store;参数错误返回 INVALID 并保留旧实例,扫描失败返回 ERROR 且实例不可用,成功返回 OK。
* 实例与回调 context 均由调用方持有,初始化不取得资源所有权。
*/
IEC60870_UserLogResult_t IEC60870_UserLog_Init(IEC60870_UserLog_t *self,
const IEC60870_UserLogStore_t *store);
/**
* 功能:追加一条事实:type 为 1..11;1/10/11 的 value 只能为 1,其余为 0/1。
* 输入参数:self——调用方持有的模块实例及当前状态;type——类别编号;utc_ms——UTC纪元毫秒;value——待处理数值;text——文本或文本输出器。
* 输出参数:self——本次操作后的运行状态及复用工作区。
* 返回值:OK表示操作完成;INVALID表示参数或操作状态非法;ERROR表示实例不可用、I/O失败或内容损坏。
* 说明:text 是非空、至多 128 字节的可打印 ASCII;utc_ms 是 UTC 毫秒,允许范围 对应 UTC+8 的 2000..2099。时标允许回拨,不按类别去重,来源状态转换由
* 应用控制。参数本次调用内借用。成功 OK,非法输入 INVALID,故障/序号耗尽 ERROR;仅持久提交成功后推进内存条数/序号,失败不会自动重试。 01/10/11
* 分别表达重启、参数修改、升级行为;02..09 为状态类。核心只检验 类型和值,不推断来源身份、连接极性或设备动作是否真的发生。
*/
IEC60870_UserLogResult_t IEC60870_UserLog_Append(IEC60870_UserLog_t *self,
uint8_t type, uint64_t utc_ms, uint8_t value, const char *text);
/**
* 功能:返回当前保留条数;空库、空指针、未初始化或故障实例都返回 0,不能据此 区分空库与错误。
* 输入参数:self——只读模块实例。
* 输出参数:无。
* 返回值:当前保留条数;NULL、未初始化或故障实例返回0。
* 说明:需要导出时应由 Write/Get 的结果确认实例可用性。
*/
size_t IEC60870_UserLog_Count(const IEC60870_UserLog_t *self);
/**
* 功能:oldest_index 从 0 起,按提交顺序从旧到新查询;超出条数返回 EMPTY。
* 输入参数:self——调用方持有的模块实例及当前状态;oldest_index——按提交顺序从最旧记录起的零基索引。
* 输出参数:self——本次操作后的运行状态及复用工作区;record——成功时写入的独立结果副本。
* 返回值:OK表示操作完成;EMPTY表示没有所需记录或到期任务;INVALID表示参数或操作状态非法;ERROR表示实例不可用、I/O失败或内容损坏。
* 说明:record 须指向调用方独立的输出对象,不得与 self 或存储重叠。成功 OK 时 拷贝完整记录;其他结果保持输出不变。读取/校验错误返回 ERROR 并故障闭锁, 参数错误返回
* INVALID;查询不消费记录。
*/
IEC60870_UserLogResult_t IEC60870_UserLog_Get(IEC60870_UserLog_t *self,
size_t oldest_index, IEC60870_UserLogRecord_t *record);
/**
* 功能:返回最新提交记录的时标,并非所有记录中的最大墙钟值;空库/实例无效/ 输出为空时返回 false,保持输出不变。
* 输入参数:self——只读模块实例。
* 输出参数:utc_ms——成功时写入最新提交记录的UTC毫秒。
* 返回值:true表示已取得最新提交记录的时标;false表示不可用或无记录,输出不变。
* 说明:调用方拥有输出值,无介质读取。
*/
bool IEC60870_UserLog_Latest_Time(const IEC60870_UserLog_t *self, uint64_t *utc_ms);
#ifdef __cplusplus
}
#endif
#endif /* IEC60870_USER_LOG_H */
@@ -0,0 +1,38 @@
/* 附录 C XML 编码:同步流式输出,不分配堆内存,不操作文件系统。 */
#ifndef IEC60870_USER_LOG_FILE_H
#define IEC60870_USER_LOG_FILE_H
#include "IEC60870_UserLog.h"
#ifdef __cplusplus
extern "C" {
#endif
/* 传输使用的完整虚拟路径,大小写固定;不代表编码器会创建文件系统目录。
* 设备 ID 上限不含 NUL,调用方存放最大长度字符串时需另留一个终止字节。 */
#define IEC60870_USER_LOG_FILE_NAME "HISTORY/ULOG/ulog.xml"
#define IEC60870_USER_LOG_DEVICE_ID_MAX 24U
/* 成功须同步保存全部 length 字节;短写或错误返回 false。bytes 只在回调
* 期间有效,不含隐式 NUL,调用方不得保留指针或修改/重入日志实例。
* 失败可能已写出文件前缀,调用方必须丢弃整个候选文件。 */
typedef bool (*IEC60870_UserLogFileWriteFn)(void *context,
const uint8_t *bytes, size_t length);
/**
* 功能:按递增序号输出保留的全部记录,允许 num=0。
* 输入参数:log——用户日志核心实例;device_id——设备标识;write——同步接收输出片段的回调;context——传给输出回调的调用方上下文。
* 输出参数:log——复用读取工作区及读取错误可能锁存的故障状态;size——仅完整成功时写入文件字节数,不含NUL;允许NULL的入口不强制输出。
* 返回值:true表示完整文件已输出;false表示参数、读取校验或输出回调失败,候选内容不可发布。
* 说明:device_id 为非空、最多 24 字节的可打印 ASCII,编码器转义 XML 属性中的特殊字符。记录时标以固定 UTC+8 输出两位年份。实例、字符串、sink context
* 全部由调用方持有,本次 同步调用期间须独占日志实例,成功产物应冻结后再交给文件服务。 非法输入、存储错误、sink 失败或长度溢出返回 false;size 可空,仅完整 成功后写入字节数,
* 不含 NUL,失败保持输出不变且丢弃已输出的任何前缀。 使用附录 C 正式模板的 Ulog/devID/txt 字段;不扩展内部序号等私有属性。 空库仍输出完整 Header 和空
* DataRec,不为凑满 1024 条创建虚构日志。
*/
bool IEC60870_UserLogFile_Write(IEC60870_UserLog_t *log, const char *device_id,
IEC60870_UserLogFileWriteFn write, void *context, uint32_t *size);
#ifdef __cplusplus
}
#endif
#endif /* IEC60870_USER_LOG_FILE_H */
+6
View File
@@ -0,0 +1,6 @@
# Shared codec import
Byte-preserved subset of `IEC60870-Slave/common` at baseline f84855a5.
Asdu, Codec, InformationObjects, Slave and Time implement shared protocol data.
FaultEvent is also required by the imported spontaneous Type42 encoder.
Local compatibility patches preserve every compile-time assertion condition.