571 lines
36 KiB
C
571 lines
36 KiB
C
/**
|
||
* 公共链路类型与接口：初始化、I/S序号、k/w窗口、S确认及TESTFR，两种角色共用。
|
||
* 业务调用方按本端角色包含Master_StartStop.h或Slave_StartStop.h即可同时获得本头文件的声明。
|
||
* 启停接口分别由角色头文件公开；Internal.h只声明实现之间的协作函数。
|
||
*
|
||
* 每条连接持有一份State，所有事件串行处理。Prepare/应答Handle成功只代表
|
||
* 报文已生成，须由调用方发送并按具体接口提交Complete；构帧不能当作发送完成。
|
||
* 完整状态校验集中在IEC104_Link.c；使用启停接口时再链接对应角色实现。
|
||
*/
|
||
#ifndef IEC104_LINK_COMMON_H
|
||
#define IEC104_LINK_COMMON_H
|
||
|
||
#include "IEC104_Codec.h"
|
||
|
||
#ifdef __cplusplus
|
||
extern "C" {
|
||
#endif
|
||
|
||
/** 每条TCP连接的本端角色；初始化后在该连接存续期间不得切换。 */
|
||
typedef enum {
|
||
IEC104_ROLE_INVALID = 0, /* 未初始化或损坏标记；正常链路接口拒绝此值 */
|
||
IEC104_ROLE_CONTROLLING, /* 控制站：主动发起STARTDT/STOPDT并等待CON */
|
||
IEC104_ROLE_CONTROLLED /* 被控站：接收STARTDT/STOPDT_ACT并发送CON */
|
||
} IEC104_LinkRole_t;
|
||
|
||
/**
|
||
* 数据传输是否启用。被控站按START/STOP受理结果立即更新，与CON写入完成解耦。
|
||
* 控制站仍按原ACT/CON流程提交状态，并允许在启动过程中提前发送命令。
|
||
* 本字段不表达停止等待ACK；被控站STOPPED/STOP_DRAINING仍接受S确认。
|
||
*/
|
||
typedef enum {
|
||
IEC104_DT_STOPPED = 0, /* 数据传输未启用；具体接收/确认权限由角色及过程决定 */
|
||
IEC104_DT_STARTED /* 已提交启动；I帧收发还须满足当前dt_procedure的门控条件 */
|
||
} IEC104_DataTransferState_t;
|
||
|
||
/**
|
||
* STARTDT/STOPDT过程，控制站与被控站使用各自的合法值；TESTFR独立。
|
||
* 控制站：STOPPED/IDLE -> START_ACT_SEND_PENDING -> START_CON_WAITING -> STARTED/IDLE；
|
||
* STARTED/IDLE -> STOP_REQUESTED -> STOP_ACT_SEND_PENDING -> STOP_CON_WAITING -> STOPPED/IDLE。
|
||
* 被控站使用以下三个逻辑状态：
|
||
* - STOPPED/IDLE：停用；
|
||
* - STARTED/IDLE：启用，受理START立即进入；
|
||
* - STOPPED/STOP_DRAINING：停用并等待确认，受理STOP立即进入。
|
||
* 停止确认满足后生成CON并回STOPPED/IDLE；任何阶段受理START都进入STARTED/IDLE。
|
||
* 被控站不保存CON发送半态或相反ACT暂存标志，已有CON只由发送FIFO维护。
|
||
*/
|
||
typedef enum {
|
||
IEC104_DT_PROC_IDLE = 0, /* 当前没有STARTDT或STOPDT过程 */
|
||
|
||
/* 控制站专用过程。 */
|
||
IEC104_DT_PROC_START_ACT_SEND_PENDING, /* STARTDT_ACT已生成，等待发送完成 */
|
||
IEC104_DT_PROC_START_CON_WAITING, /* STARTDT_ACT已发送，等待STARTDT_CON */
|
||
IEC104_DT_PROC_STOP_REQUESTED, /* 已受理主动停止，正在准备S确认/ACT */
|
||
IEC104_DT_PROC_STOP_ACT_SEND_PENDING, /* STOPDT_ACT已生成，等待发送完成 */
|
||
IEC104_DT_PROC_STOP_CON_WAITING, /* STOPDT_ACT已发送，等待STOPDT_CON */
|
||
|
||
/* 被控站专用过程。 */
|
||
IEC104_DT_PROC_STOP_DRAINING = 7 /* 被控站已停用，等待确认后生成STOPDT_CON */
|
||
} IEC104_DtProcedure_t;
|
||
|
||
/**
|
||
* 普通S确认帧的发送进度。
|
||
*
|
||
* 普通w/t2确认与两端STOPDT流程共用此状态；同一时刻只允许一个S确认在途。
|
||
* 成功路径为IDLE -> 生成S帧 -> SEND_PENDING -> Complete_S_Ack_Send -> IDLE。
|
||
* 普通确认和STOPDT准备接口都使用同一构帧步骤，冻结报文携带的N(R)；
|
||
* Complete成功后才推进acked_nr。发送失败同样清除在途状态，但保持
|
||
* acked_nr不变并返回FATAL。
|
||
*/
|
||
typedef enum {
|
||
IEC104_S_ACK_IDLE = 0, /* 无S帧等待完成；此时s_ack_nr必须为0 */
|
||
IEC104_S_ACK_SEND_PENDING /* S帧已生成；s_ack_nr冻结其实际N(R) */
|
||
} IEC104_SAckState_t;
|
||
|
||
/**
|
||
* 主动TESTFR探测状态；与dt_state和dt_procedure相互独立。
|
||
* 顺序为IDLE -> ACT_SEND_PENDING -> CON_PENDING -> IDLE。
|
||
* 调用方须先提交ACT完整发送结果，再处理TESTFR_CON；未等待时忽略CON，不缓存。
|
||
* Prepare_T3_Testfr按t3触发共用的内部准备路径，不创建另一套探测状态。
|
||
* TESTFR_ACT发送失败时Complete接口回到IDLE并返回FATAL。
|
||
*/
|
||
typedef enum {
|
||
IEC104_TESTFR_IDLE = 0, /* 没有正在进行的主动探测 */
|
||
IEC104_TESTFR_ACT_SEND_PENDING, /* TESTFR_ACT已生成，等待发送完成 */
|
||
IEC104_TESTFR_CON_PENDING /* TESTFR_ACT已完整发送，等待TESTFR_CON */
|
||
} IEC104_TestfrState_t;
|
||
|
||
/**
|
||
* 链路事件结果，必须与枚举值比较。
|
||
* 被控站START受理立即启用并生成CON，STOP受理立即停用并登记停止义务。
|
||
* 排空中的重复STOP返回IGNORED；停用IDLE下的STOP重新应答。
|
||
* CON完成仅检查发送结果；完成旧CON不改变当前启停状态。
|
||
* 控制站的多余CON仍按相应接口返回IGNORED；非法序号、角色、状态或发送失败为FATAL。
|
||
* FATAL由上层断链；失败前已受理的状态或发送事实不能回滚重放。
|
||
*/
|
||
typedef enum {
|
||
IEC104_LINK_RESULT_FATAL = -1, /* 当前连接必须由上层立即关闭 */
|
||
IEC104_LINK_RESULT_IGNORED = 0, /* 合法重复或没有匹配的在途过程 */
|
||
IEC104_LINK_RESULT_OK = 1, /* 本次处理成功，具体输出与状态变化见接口约定 */
|
||
} IEC104_LinkResult_t;
|
||
|
||
/** 主动停止请求的受理结果；除ACCEPTED外均不修改状态，必须按枚举值分支。 */
|
||
typedef enum {
|
||
IEC104_STOPDT_REQUEST_ERROR = -1, /* 参数、角色或状态非法 */
|
||
IEC104_STOPDT_REQUEST_ACCEPTED = 0, /* 已进入STOP_REQUESTED */
|
||
IEC104_STOPDT_REQUEST_ALREADY_STOPPED, /* 已STOPPED且没有启停过程 */
|
||
IEC104_STOPDT_REQUEST_IN_PROGRESS, /* 此前的主动停止仍在进行 */
|
||
IEC104_STOPDT_REQUEST_BUSY /* 另一个启停过程占用过程槽 */
|
||
} IEC104_StopdtRequestResult_t;
|
||
|
||
/** STOPDT报文准备结果；不是字节数，必须按枚举值分支。 */
|
||
typedef enum {
|
||
IEC104_STOPDT_PREPARE_ERROR = -1, /* 参数、角色、状态或编码结果非法 */
|
||
IEC104_STOPDT_NOT_ACTIVE = 0, /* 当前没有对应的停止流程 */
|
||
IEC104_STOPDT_FRAME_READY, /* 新报文及发送描述已生成 */
|
||
IEC104_STOPDT_WAIT_SEND, /* 等待已有S/ACT/CON的发送完成 */
|
||
IEC104_STOPDT_WAIT_PEER_ACK, /* 被控站等待对端确认本端I帧 */
|
||
IEC104_STOPDT_WAIT_PEER_CON /* 控制站等待STOPDT_CON */
|
||
} IEC104_StopdtPrepareResult_t;
|
||
|
||
/** STOPDT准备接口实际生成的报文类型，用于选择对应的发送完成接口。 */
|
||
typedef enum {
|
||
IEC104_STOPDT_FRAME_S_ACK, /* S确认：提交给Complete_S_Ack_Send */
|
||
IEC104_STOPDT_FRAME_ACT, /* 主动停止：提交给Complete_Stopdt_Act_Send */
|
||
IEC104_STOPDT_FRAME_CON /* 被动停止应答：提交给Complete_Stopdt_Con_Send */
|
||
} IEC104_StopdtFrameType_t;
|
||
|
||
/**
|
||
* STOPDT报文的发送描述，仅在Prepare返回FRAME_READY时写入。
|
||
* 调用方须与报文一起保存在同一FIFO节点中，最终发送结束后按frame_type分派
|
||
* 完成事件；frame_length为预期长度，Complete仍须传入实际最终发送字节数。
|
||
*/
|
||
typedef struct {
|
||
IEC104_StopdtFrameType_t frame_type; /* 本次生成的S确认、ACT或CON */
|
||
uint16_t frame_length; /* 完整APDU长度；当前三种报文均为6字节 */
|
||
} IEC104_StopdtTx_t;
|
||
|
||
/**
|
||
* I帧在Prepare成功时固定的发送快照。
|
||
*
|
||
* 调用方必须把该对象与当前发送报文关联保存，并在最终发送结束时原样
|
||
* 传给Complete_I_Send；不能用完成时刻的V(S)或V(R)重新构造快照。
|
||
*/
|
||
typedef struct {
|
||
uint16_t send_number; /* 本帧已预留且写入控制域的N(S)，范围0..32767 */
|
||
uint16_t receive_number; /* 构帧时写入控制域的N(R)，范围0..32767 */
|
||
uint16_t frame_length; /* 本帧完整APDU长度，用于判断是否最终完整发送 */
|
||
} IEC104_IFrameTx_t;
|
||
|
||
/**
|
||
* Link独占的I帧发送进度快照，SendBuffer不再复制这三个协议位置。
|
||
* 序号范围均为0..32767；ACK不能越过已提交本地完成的next_completion_ns。
|
||
* 顺序按循环距离检查，不能用普通整数大小比较回绕前后的序号。
|
||
* next_frame_ns在Prepare成功后推进；Manager完成整个跨模块事务后再核对
|
||
* 当前I帧、已提交ASDU数量和业务记录，不能在中间状态检查一致性。
|
||
*/
|
||
typedef struct {
|
||
uint16_t next_frame_ns; /* Link下一帧可分配的N(S) */
|
||
uint16_t next_completion_ns; /* 下一个尚未提交本地发送完成的I帧N(S) */
|
||
uint16_t peer_ack_nr; /* 已接受的对端累计确认位置，不代表本地完成 */
|
||
} IEC104_IFrameSendProgress_t;
|
||
|
||
/**
|
||
* 单条IEC-104连接的全部链路运行状态。
|
||
*
|
||
* 主要不变量：
|
||
* - vs、sent_vs、va、vr、acked_nr和s_ack_nr均为15位序号，按模32768运算；
|
||
* - distance(va, vs)是本端已经预留但尚未被对端确认的I帧数；
|
||
* - distance(sent_vs, vs)是尚未提交发送完成事件的I帧数，包含排队帧；
|
||
* - 上述两个区间均必须小于32768；Prepare同时保护两条边界，避免回绕歧义；
|
||
* - 先提交本地Complete，再处理覆盖该帧的ACK；distance(sent_vs,vs)<=distance(va,vs)；
|
||
* - ACK仅允许推进到sent_vs，已完成未确认帧数为distance(va,sent_vs)；
|
||
* - distance(acked_nr, vr)是已经接收但尚未由成功上线I/S帧确认的I帧数；
|
||
* - s_ack_state为IDLE时s_ack_nr必须为0；
|
||
* - role决定允许出现的dt_procedure，稳定状态由dt_state单独保存；
|
||
* - testfr_state独立于启停过程，可以与STARTDT/STOPDT过程并存。
|
||
* - 被控站仅使用IDLE或STOP_DRAINING；STOP_DRAINING必须同时为STOPPED。
|
||
*
|
||
* 本结构不包含锁、发送队列和时钟。一个连接上的所有Prepare、Handle、Complete
|
||
* 和Expired调用必须由上层串行化；TCP重连必须重新初始化状态并丢弃旧完成事件。
|
||
* 本结构不保存故障标志；Handle/Complete通过FATAL返回值报告致命故障，由连接层断连。
|
||
* 本结构保存单条连接的状态，连接组的选择/切换由上层负责。本实现允许控制站
|
||
* 在ACT之后、CON之前发送命令，适用条件见IEC104_Link_设计架构.md第3.2节；
|
||
* dt_state不能作为双向I帧的统一开关。
|
||
* 这些不变量依赖合法的事件序列维持；内部状态校验不保存发送队列历史，不能
|
||
* 证明完成事件身份或重建序号绕环次数。调用方不应直接改字段来跳过启停流程。
|
||
*/
|
||
typedef struct {
|
||
IEC104_LinkRole_t role; /* 本端固定角色；正常运行只能是两个有效角色之一 */
|
||
|
||
uint16_t vs; /* V(S)：下一个尚未分配给发送队列I帧的N(S) */
|
||
uint16_t sent_vs; /* 下一个尚未提交发送完成事件的I帧N(S)，按FIFO推进 */
|
||
uint16_t va; /* V(A)：最早尚未被对端确认的本端发送序号 */
|
||
uint16_t vr; /* V(R)：期望从对端收到的下一个I帧N(S) */
|
||
uint16_t acked_nr; /* 最近一次成功上线I/S帧实际携带的N(R) */
|
||
|
||
IEC104_SAckState_t s_ack_state; /* 普通确认及两端STOPDT共用的S帧发送进度 */
|
||
uint16_t s_ack_nr; /* 在途S帧携带的N(R)快照；IDLE时必须为0 */
|
||
|
||
IEC104_DataTransferState_t dt_state; /* 已提交的数据传输稳定状态 */
|
||
IEC104_DtProcedure_t dt_procedure; /* 当前唯一的STARTDT/STOPDT过程半态 */
|
||
IEC104_TestfrState_t testfr_state; /* 独立的主动TESTFR探测进度 */
|
||
} IEC104_LinkState_t;
|
||
|
||
/* 只读观察快照；连接层据unconfirmed_rx_count管理接收计时，不自行计算序号环距离。
|
||
* 启停/探测字段供诊断展示，是否应构帧须使用Can_Prepare查询，不能在外层组合状态条件。 */
|
||
typedef struct {
|
||
IEC104_LinkRole_t role; /* 本端固定角色 */
|
||
IEC104_DataTransferState_t dt_state; /* 已提交的启停稳定状态 */
|
||
IEC104_DtProcedure_t dt_procedure; /* 当前启停过程 */
|
||
IEC104_TestfrState_t testfr_state; /* 独立的主动探测进度 */
|
||
uint16_t unconfirmed_rx_count; /* 已接收且尚未由完整发送的I/S确认的I帧数 */
|
||
} IEC104_LinkStatus_t;
|
||
|
||
/* 完整校验后返回数值快照；1成功，0参数/状态非法，失败不改输出，不推进任何过程。 */
|
||
extern int IEC104_Link_Get_Status(const IEC104_LinkState_t *state, IEC104_LinkStatus_t *status);
|
||
|
||
/*
|
||
* 只读检查普通S是否应准备，与Prepare_S_Ack共用同一规划规则；w范围1..32767。
|
||
* immediate非0跳过w门限（例如t2已到期），仍检查启停门控、在途S及待确认数量。
|
||
* 1应准备，0当前无需/不能准备，-1参数或状态非法；不预留缓冲、不生成报文、不提交确认。
|
||
* 同一连接的查询和准备须串行执行；返回1后仍须处理实际Prepare/Manager排队结果。
|
||
*/
|
||
extern int IEC104_Link_Can_Prepare_S_Ack(const IEC104_LinkState_t *state, uint16_t w, int immediate);
|
||
|
||
/* 只读检查是否可开始一轮TESTFR；不检查t3时间。1可准备，0已有探测，-1状态非法。
|
||
* 与主动/t3构帧入口共用准入规则；查询不改变探测状态，调用方仍须处理实际准备结果。 */
|
||
extern int IEC104_Link_Can_Prepare_Testfr_Act(const IEC104_LinkState_t *state);
|
||
|
||
/**
|
||
* 适用端：控制站与被控站。
|
||
* 功能：把IEC 60870-5-104推荐默认参数写入一条连接的链路配置。
|
||
* 输入参数：config——待初始化的配置对象；允许为NULL。
|
||
* 输出参数：k=12、w=8、t1=15000ms、t2=10000ms、t3=20000ms。
|
||
* 返回值：无。
|
||
* 说明：本函数只复制默认值，不创建定时器；连接调度层可在初始化后按需改写。
|
||
*/
|
||
extern void IEC104_Link_Config_Default(IEC104_LinkConfig_t *config);
|
||
|
||
/**
|
||
* 适用端：控制站与被控站，由role参数固定当前连接的本端角色。
|
||
* 功能：为新连接初始化链路状态。
|
||
* 输入参数：state——待初始化的状态对象；role——CONTROLLING或CONTROLLED。
|
||
* 输出参数：成功时写入role，清零序号和确认快照，数据传输置STOPPED，
|
||
* 启停过程、S确认和TESTFR置IDLE。
|
||
* 返回值：1表示初始化成功；0表示state为NULL或role非法，此时不修改状态。
|
||
* 说明：仅初始化链路算法状态，连接配置由Config_Default单独初始化。
|
||
* 新连接处理任何链路事件前须初始化成功，不要求在TCP建连成功后才调用。
|
||
* 本模块未实现连接生命周期管理；旧事件隔离和状态内存安全复用由接入方负责。
|
||
*/
|
||
extern int IEC104_Link_State_Init(IEC104_LinkState_t *state,
|
||
IEC104_LinkRole_t role);
|
||
|
||
/**
|
||
* 功能：校验完整链路状态并读取I帧发送进度，不修改链路。
|
||
* 输入参数：state——本连接的链路状态。
|
||
* 输出参数：progress——成功时写入数值快照；失败时保持原值，不得与state重叠。
|
||
* 返回值：1表示读取成功；0表示指针或链路状态非法，不是链路事件结果。
|
||
* 说明：快照只表示调用时的进度，不预留序号，不证明TCP可用或事件属于本连接。
|
||
* 同一连接须串行调用；跨模块核对前须完成对应的Prepare/Commit、
|
||
* Complete/Commit_Send_Completion或Handle/原ASDU确认释放整个步骤。
|
||
*/
|
||
extern int IEC104_Link_Get_Send_Progress(
|
||
const IEC104_LinkState_t *state, IEC104_IFrameSendProgress_t *progress);
|
||
|
||
/**
|
||
* 功能：判断链路是否满足新连接绑定所需的初始状态条件，不修改状态。
|
||
* 输入参数：state——待检查链路，允许NULL。
|
||
* 输出参数：无。
|
||
* 返回值：1表示状态合法、序号与确认位置为0、STOPPED且各过程空闲；否则0。
|
||
* 说明：由Link维护初始状态规则；返回1不证明TCP为新连接，也不能用于故障恢复。
|
||
*/
|
||
extern int IEC104_Link_Is_Initial_State(const IEC104_LinkState_t *state);
|
||
|
||
/**
|
||
* 适用端：控制站与被控站。
|
||
* 功能：复位链路序号、S确认、启停和探测状态，清除待完成过程的算法记录。
|
||
* 输入参数：state——链路状态对象；允许为NULL。
|
||
* 输出参数：state——保留有效角色，序号及S快照清零，回到STOPPED/IDLE；
|
||
* S确认和TESTFR置IDLE。
|
||
* 返回值：无。
|
||
* 说明：本接口只复位链路算法字段，不能用于致命故障后在原连接上继续通信。
|
||
* 外部接入要求：调用方负责关闭故障连接，并防止旧事件提交到重新初始化后的状态；
|
||
* 对应连接管理、任务调度和定时器管理当前未实现，不属于本接口行为。
|
||
* 新连接处理链路事件前须用State_Init成功初始化完整状态并指定角色。
|
||
* 原角色非法时规范化为INVALID，不会自动选择角色；须用State_Init重新初始化。
|
||
* Reset会读取原role，不能对未初始化的自动变量调用本接口。
|
||
*/
|
||
extern void IEC104_Link_State_Reset(IEC104_LinkState_t *state);
|
||
|
||
/**
|
||
* 适用端：控制站与被控站。
|
||
* 功能：检查接收到的I帧序号，并在合法时更新接收和发送确认状态。
|
||
* 输入参数：state——链路状态；apci——已经通过基础格式检查的I帧APCI。
|
||
* 输出参数：成功时更新state->vr和state->va；未确认数量由acked_nr到vr的距离推导。
|
||
* 返回值：OK表示接收方向已经开放且序号合法并完成更新；FATAL表示接收方向未开放，
|
||
* 或参数、帧类型、状态、序号非法。
|
||
* 说明：控制站收到STARTDT_CON前禁止接收I帧；被控站受理START后立即允许接收。
|
||
* 被控站STOP受理后拒绝新I帧并返回FATAL；后到START成功受理后重新开放。
|
||
* 本端新I帧和S可在START_CON之后排队，实际发送不得越过已有控制帧。
|
||
* 控制站停止期间接收合法I帧后，上层须立即安排S帧。
|
||
* 本函数成功时只推进V(A)/V(R)。
|
||
* 捎带N(R)不得越过sent_vs；对应I帧的Complete须先于本次Handle提交。
|
||
*/
|
||
extern IEC104_LinkResult_t IEC104_Link_Handle_I_Frame(
|
||
IEC104_LinkState_t *state, const IEC104_ApciInfo_t *apci);
|
||
|
||
/**
|
||
* 适用端：控制站与被控站。
|
||
* 功能：检查接收到的S帧确认号，并在合法时更新V(A)。
|
||
* 输入参数：state——链路状态；apci——已经通过基础格式检查的S帧APCI。
|
||
* 输出参数：成功时将state->va更新为apci->receive_number。
|
||
* 返回值：OK表示接收阶段和确认号合法并完成更新；其他情况为FATAL且状态不变。
|
||
* 说明：STARTED时允许S；被控站STOPPED/STOP_DRAINING时仍接收ACK。
|
||
* 被控站STOPPED/IDLE及控制站等待STARTDT_CON时拒绝S帧。
|
||
* S帧接收只更新va，不提交发送完成边界sent_vs，也不推进接收确认位置acked_nr。
|
||
* N(R)不得越过sent_vs；异步接入须先提交对应发送结果，再分派相关ACK。
|
||
*/
|
||
extern IEC104_LinkResult_t IEC104_Link_Handle_S_Frame(
|
||
IEC104_LinkState_t *state, const IEC104_ApciInfo_t *apci);
|
||
|
||
/* 只读检查新I帧的启停、k窗口及序号边界，与Prepare_I_Frame共用规划逻辑。
|
||
* 返回1可准备，0当前门控/窗口阻塞，-1参数或状态非法；不编码、不预留N(S)。 */
|
||
extern int IEC104_Link_Can_Prepare_I_Frame(const IEC104_LinkState_t *state, uint16_t k);
|
||
|
||
/**
|
||
* 适用端：控制站与被控站；仅在本端数据传输方向允许时生成。
|
||
* 功能：检查数据传输状态和k窗口，构造I帧并在编码成功后预留其N(S)；同连接调用须串行。
|
||
* 输入参数：state——链路状态；k——最大发送未确认I帧数，范围1..32767；
|
||
* asdu/asdu_len——完整ASDU及长度；frame/capacity——输出缓冲及容量；
|
||
* tx——由调用方随发送队列节点保存的序号和长度快照。
|
||
* 输出参数：成功时写入完整I帧和tx，并将V(S)循环加1。
|
||
* 返回值：成功返回完整APDU长度；0表示当前方向/阶段不允许、k窗口已满，
|
||
* 或新增预留将使未完成区间占满序号环；
|
||
* -1表示参数或链路状态非法。返回0/-1时不修改state、frame和tx。
|
||
* 说明：成功返回表示N(S)已经不可撤销地提交，报文必须进入该连接的严格FIFO队列；
|
||
* 两端STARTED/IDLE可预留；控制站还可在START_ACT_SEND_PENDING
|
||
* 和START_CON_WAITING预留，新I帧必须排在本次STARTDT_ACT之后。
|
||
* 调用方须先取得队列容量，将成功生成的ACT入队后再Prepare I帧；所有
|
||
* I/S/U帧在同一FIFO发送，先提交ACT完成再提交其后I帧完成。ACT失败须
|
||
* 丢弃整条连接及其队列，不能继续发送排在它后面的I帧。
|
||
* 后续发送失败必须断连，不得回滚V(S)。最终发送结果必须连同原tx传给
|
||
* IEC104_Link_Complete_I_Send()，完成阶段不能再次推进V(S)。
|
||
* 预留/排队时不启动等待确认的t1；发送层须自行限制排队和发送等待时间，
|
||
* 每次成功Prepare后恰好报告一次Complete，发送失败/超时也须报告失败长度。
|
||
*/
|
||
extern int IEC104_Link_Prepare_I_Frame(IEC104_LinkState_t *state,
|
||
uint16_t k,
|
||
const uint8_t *asdu,
|
||
uint16_t asdu_len,
|
||
uint8_t *frame,
|
||
uint16_t capacity,
|
||
IEC104_IFrameTx_t *tx);
|
||
|
||
/**
|
||
* 适用端：控制站与被控站。
|
||
* 功能：提交一帧由Prepare_I_Frame()生成的I帧最终本地发送结果。
|
||
* 输入参数：state——链路状态；tx——构帧成功时由调用方随队列节点保存的快照；
|
||
* sent_len——最终累计成功发送的字节数，等于tx->frame_length才算成功；发送失败也可传-1。
|
||
* 输出参数：完整发送、FIFO顺序及N(R)快照合法时更新acked_nr和sent_vs；
|
||
* 失败时均不推进，不回滚Prepare阶段的V(S)。
|
||
* 返回值：OK表示完整发送并成功提交；FATAL表示参数/状态非法、长度不符或
|
||
* 无待完成帧、完成顺序错误、N(R)快照失效。本接口没有IGNORED结果。
|
||
* 说明：Send限定为本地发送提交；返回OK不表示对端已经确认本帧。
|
||
* 部分写入尚在继续时不要调用；发送失败后上层连接管理器须断连。
|
||
* 本连接I/S完成事件须按发送FIFO恰好提交一次；本接口验证I帧N(S)==sent_vs。
|
||
* 发送层在整帧成功交给传输层时记录单调时间sent_at_ms并随完成事件传递；
|
||
* 不得用延迟执行回调时的当前时间代替实际完成时间。本接口不读取时钟。
|
||
* 成功后该帧进入等待ACK的区间；接收处理不得先于本次完成提交确认该帧。
|
||
* 完整APDU在传输层不再借用且本地完成已提交后可释放；等待ACK期间仍须保留
|
||
* 帧身份、序号快照、原始发送时间和业务关联，供确认、t1和故障回收使用。
|
||
* 业务原文的保留和重连恢复策略由发送管理层决定，链路完成不处理原文队列。
|
||
* 新连接不复用旧APDU、协议序号或完成事件。
|
||
*/
|
||
extern IEC104_LinkResult_t IEC104_Link_Complete_I_Send(
|
||
IEC104_LinkState_t *state, const IEC104_IFrameTx_t *tx, int sent_len);
|
||
|
||
/**
|
||
* 适用端：控制站与被控站。
|
||
* 功能：判断最早已完成发送但尚未被对端确认的I帧是否达到t1超时。
|
||
* 输入参数：state——链路状态；elapsed_ms——当前最早已完成未确认帧自整帧成功
|
||
* 交给传输层后经过的毫秒数，由调用方以该帧原始sent_at_ms计算；
|
||
* t1_ms——t1配置值，必须大于0。
|
||
* 输出参数：无，不修改链路状态。
|
||
* 返回值：1表示存在已完成未确认I帧且已经超时；0表示无此类帧或尚未超时；
|
||
* -1表示参数或链路序号状态非法。
|
||
* 说明：Complete_I_Send成功后，以及Handle_I/S_Frame成功推进V(A)后，调用方须
|
||
* 在同一串行调度区间重新选取最早已完成未确认帧；不存在则取消t1。
|
||
* 存在时以该帧原始发送完成时间作为起点；部分ACK后不可从当前时刻重计，
|
||
* 后续I帧Complete也不能延长前面未确认帧的截止时间。重复ACK不重置起点；
|
||
* 仅排队的帧不受此t1保护，超前于本地完成位置的ACK应被拒绝。
|
||
* 定时器只负责唤醒；回调必须校验连接/计时对象、重算当前帧elapsed_ms，
|
||
* 再调用本函数；只有返回1才按I帧确认超时断连。返回-1按非法状态处理。
|
||
* 本函数不保存时钟；使用宽位单调时间作差，超过uint32_t时饱和而非截断。
|
||
*/
|
||
extern int IEC104_Link_T1_I_Ack_Expired(
|
||
const IEC104_LinkState_t *state,
|
||
uint32_t elapsed_ms, uint32_t t1_ms);
|
||
|
||
/**
|
||
* 适用端：控制站与被控站。
|
||
* 功能：按w门限、显式立即确认或STOPDT排空要求生成一份普通S帧，并保存其N(R)快照。
|
||
* 输入参数：state——链路状态；w——接收确认门限，范围1..32767；
|
||
* immediate——非0跳过w门限，仍受启停状态和已有S在途限制；response——输出缓冲；
|
||
* capacity——缓冲实际容量，至少6字节。
|
||
* 输出参数：成功时response写入S帧，state转SEND_PENDING并保存构帧时V(R)。
|
||
* 返回值：6表示生成新S帧；0表示当前启停阶段不允许、未达到门限、
|
||
* 没有待确认数据或已有S帧在途；
|
||
* -1表示参数或状态非法。
|
||
* 说明：处于STOP_REQUESTED、STOP_ACT_SEND_PENDING、STOP_CON_WAITING或STOP_DRAINING时，
|
||
* 有待确认数据且无S在途时，即使immediate为0且未达到w，也会生成确认。生成不等于发送成功；
|
||
* 同一连接的I/S报文须按上线顺序串行发送，不能让较旧N(R)晚于较新N(R)上线。
|
||
* 被控站START受理后可准备S并排在CON之后；停用IDLE下不再准备普通S。
|
||
* 原接收时间和在途S快照不因启停改变。
|
||
*/
|
||
extern int IEC104_Link_Prepare_S_Ack(IEC104_LinkState_t *state,
|
||
uint16_t w, int immediate,
|
||
uint8_t *response, uint16_t capacity);
|
||
|
||
/**
|
||
* 适用端：控制站与被控站。
|
||
* 功能：提交公共S确认帧的最终发送结果，普通确认与两端STOPDT流程共用。
|
||
* 输入参数：state——链路状态；sent_len——最终累计发送字节数，恰好6表示成功。
|
||
* 输出参数：成功时用保存的N(R)推进acked_nr并回IDLE；发送失败或快照失效时
|
||
* 清除在途S帧且不推进确认位置，由上层断开连接。
|
||
* 返回值：OK表示完整发送并成功提交；IGNORED表示没有S帧等待完成；
|
||
* FATAL表示参数/状态非法、发送失败或快照失效。
|
||
* 说明：发送期间新收到的I帧仍保留在新acked_nr到V(R)之间；新连接初始化后必须
|
||
* 丢弃旧连接的完成事件。调用方必须与具体枚举值比较。
|
||
* 状态合法且无S在途时先返回IGNORED，不检查sent_len；状态非法则直接FATAL。
|
||
* S完成保留当前启停状态。这里的回IDLE仅指s_ack_state，不是dt_procedure。
|
||
* 普通确认及两端STOPDT中的S帧均由本接口完成。本接口不接收报文身份，
|
||
* 须按FIFO节点恰好分派一次。
|
||
*/
|
||
extern IEC104_LinkResult_t IEC104_Link_Complete_S_Ack_Send(
|
||
IEC104_LinkState_t *state, int sent_len);
|
||
|
||
/**
|
||
* 适用端：控制站与被控站。
|
||
* 功能：在最早已接收但本端尚未确认的I帧达到t2等待时间后生成S确认帧。
|
||
* 输入参数：state——链路状态；elapsed_ms——该接收帧等待本端确认的毫秒数；
|
||
* t2_ms——t2配置值，必须大于0；response——输出缓冲；
|
||
* capacity——缓冲实际容量，至少6字节。
|
||
* 输出参数：到期且可生成时写入S帧，并由普通S确认流程保存N(R)快照。
|
||
* 返回值：6表示生成S帧；0表示尚未到期、当前启停阶段不允许、
|
||
* 没有待确认I帧或已有S帧在途；
|
||
* -1表示参数或状态非法。
|
||
* 说明：本函数不读取系统时钟，也不维护计时起点；调用方必须使用单调时钟计算
|
||
* elapsed_ms。生成后仍由IEC104_Link_Complete_S_Ack_Send()提交最终发送结果。
|
||
* 即使尚未到期，也会完整校验参数和状态，非法输入返回-1。
|
||
* 启停及其他控制帧不重置t2，S由FIFO保证发送顺序。
|
||
*/
|
||
extern int IEC104_Link_Prepare_T2_Ack(IEC104_LinkState_t *state,
|
||
uint32_t elapsed_ms, uint32_t t2_ms,
|
||
uint8_t *response, uint16_t capacity);
|
||
|
||
/**
|
||
* 适用端：控制站与被控站；收到对端TESTFR_ACT时使用。
|
||
* 功能：独立处理已通过APCI解析的TESTFR_ACT，生成TESTFR_CON应答。
|
||
* 输入参数：apci——U帧且功能码为TESTFR_ACT；response——应答输出缓冲；
|
||
* capacity——缓冲实际容量，至少6字节。
|
||
* 输出参数：response——应答为68 04 83 00 00 00。
|
||
* 返回值：OK表示生成固定6字节应答；FATAL表示参数或报文非法。
|
||
* 说明：无状态接口，不修改启停状态、链路序号或I帧确认计数；
|
||
* 只生成应答，不执行发送，也不处理主动心跳及超时。
|
||
* TESTFR_CON发送没有对应链路Complete接口，发送失败由上层断连；不能
|
||
* 调用Complete_Testfr_Act_Send提交该应答，也不能据此结束本端主动探测。
|
||
*/
|
||
extern IEC104_LinkResult_t IEC104_Link_Handle_Testfr_Act(
|
||
const IEC104_ApciInfo_t *apci, uint8_t *response, uint16_t capacity);
|
||
|
||
/**
|
||
* 适用端：控制站与被控站。
|
||
* 功能：独立生成主动探测请求TESTFR_ACT，并标记等待最终发送结果。
|
||
* 输入参数：state——链路状态；request——请求输出缓冲；capacity——实际容量，至少6字节。
|
||
* 输出参数：request——写入68 04 43 00 00 00；state——探测转为ACT_SEND_PENDING。
|
||
* 返回值：6表示生成新请求；0表示已有探测进行中；-1表示参数或链路状态非法。
|
||
* 返回0或-1时不修改状态和输出缓冲。
|
||
* 说明：不执行网络发送；待发送完成和等待CON期间均不重复生成请求。
|
||
* 不受启停状态限制，不修改启停状态、序号及接收确认位置。
|
||
* 每次成功返回6都会建立一次完成义务：发送层必须保证恰好调用一次
|
||
* Complete_Testfr_Act_Send()；发送超时或失败也必须用非6的最终长度报告。
|
||
* ACT完整发送后先提交Complete，再分派收到的TESTFR_CON，与主动启停顺序一致。
|
||
*/
|
||
extern int IEC104_Link_Prepare_Testfr_Act(IEC104_LinkState_t *state,
|
||
uint8_t *request,
|
||
uint16_t capacity);
|
||
|
||
/**
|
||
* 适用端：控制站与被控站。
|
||
* 功能：在链路空闲达到t3后生成主动探测请求TESTFR_ACT。
|
||
* 输入参数：state——链路状态；idle_elapsed_ms——距最近链路活动的毫秒数；
|
||
* t3_ms——t3配置值，必须大于0；request——请求输出缓冲；
|
||
* capacity——实际容量，至少6字节。
|
||
* 输出参数：到期且当前没有主动探测时生成TESTFR_ACT，并进入ACT_SEND_PENDING。
|
||
* 返回值：6表示生成新请求；0表示尚未到期或已有主动探测；
|
||
* -1表示参数或链路状态非法。返回0或-1时不修改状态和输出缓冲。
|
||
* 说明：本函数不读取时钟，也不维护最近活动时间；连接层统一定义有效链路活动，
|
||
* 据此更新t3的单调计时起点并计算idle_elapsed_ms，不得重置正在等待CON的t1起点。
|
||
* 返回6只表示生成报文，尚未发送；发送结果仍由Complete_Testfr_Act_Send()提交。
|
||
* 成功生成后同样要求发送层恰好报告一次最终完成结果。
|
||
* 即使尚未到期，也会完整校验参数和状态，非法输入返回-1。
|
||
*/
|
||
extern int IEC104_Link_Prepare_T3_Testfr(IEC104_LinkState_t *state,
|
||
uint32_t idle_elapsed_ms,
|
||
uint32_t t3_ms,
|
||
uint8_t *request,
|
||
uint16_t capacity);
|
||
|
||
/**
|
||
* 适用端：控制站与被控站。
|
||
* 功能：记录主动TESTFR_ACT的最终发送结果，成功后开始等待TESTFR_CON。
|
||
* 输入参数：state——链路状态；sent_len——最终成功发送的累计字节数；负值也表示失败。
|
||
* 输出参数：有匹配ACT时，恰好6字节转CON_PENDING；其他长度结束本次探测并回IDLE。
|
||
* 返回值：OK表示ACT完整发送并开始等待CON；
|
||
* IGNORED表示没有待完成的ACT；
|
||
* FATAL表示状态非法或发送失败。
|
||
* 说明：部分写入仍在继续时不要调用；发送失败后上层须断连，不得在原连接重试。
|
||
* 同一连接串行调用；须先提交ACT完整发送结果，再分派收到的TESTFR_CON。
|
||
* 状态合法但无匹配ACT时先返回IGNORED，不检查sent_len，也不修改状态。
|
||
* 新连接初始化后丢弃旧连接的发送完成和接收事件；调用方必须与具体枚举值比较；
|
||
* 本接口不修改启停及序号状态，也不操作外部定时器。返回OK后，由连接层以
|
||
* 本次ACT实际完整发送时刻为等待CON的t1起点，不能用延迟回调处理时刻代替。
|
||
*/
|
||
extern IEC104_LinkResult_t IEC104_Link_Complete_Testfr_Act_Send(
|
||
IEC104_LinkState_t *state, int sent_len);
|
||
|
||
/**
|
||
* 适用端：控制站与被控站；收到对端TESTFR_CON时使用。
|
||
* 功能：处理已通过APCI解析且当前正在等待的TESTFR_CON。
|
||
* 输入参数：state——链路状态；apci——U帧且功能码为TESTFR_CON。
|
||
* 输出参数：仅CON_PENDING时回IDLE；非OK时不修改状态。
|
||
* 返回值：OK表示接受当前探测的确认；IGNORED表示当前未等待CON；
|
||
* FATAL表示参数、报文或链路状态非法。
|
||
* 说明：不生成应答，不修改启停状态、序号和确认位置；输入校验先于等待状态检查。
|
||
* ACT_SEND_PENDING时返回IGNORED且不缓存CON；调用方须先完成本ACT的Complete。
|
||
* 收到对端TESTFR_ACT时须另行调用Handle_Testfr_Act生成应答，不结束本端的确认等待。
|
||
* 返回OK后由连接层取消本轮等待计时；本接口不操作外部定时器。
|
||
*/
|
||
extern IEC104_LinkResult_t IEC104_Link_Handle_Testfr_Con(
|
||
IEC104_LinkState_t *state, const IEC104_ApciInfo_t *apci);
|
||
|
||
/**
|
||
* 适用端：控制站与被控站。
|
||
* 功能：判断主动TESTFR_ACT发送成功后等待TESTFR_CON是否达到t1超时。
|
||
* 输入参数：state——链路状态；elapsed_ms——距当前探测ACT实际完整发送的毫秒数；
|
||
* t1_ms——t1配置值，必须大于0。
|
||
* 输出参数：无，不修改链路状态。
|
||
* 返回值：1表示正在等待TESTFR_CON且已经超时；0表示未等待或尚未超时；
|
||
* -1表示参数或链路状态非法。
|
||
* 说明：Complete_Testfr_Act_Send()返回OK后，由连接层以本次ACT实际完整发送时刻
|
||
* 为单调计时起点，Handle_Testfr_Con()返回OK后由连接层取消本轮等待计时；
|
||
* 重复请求、无匹配事件或t3活动更新均不得重置t1起点。
|
||
* 连接层定时器只用作唤醒；回调须校验连接代次，并在连接串行调度中按当前
|
||
* 有效探测的起点重新计算elapsed_ms，再调用本函数，只有返回1才按t1超时断连。
|
||
* 同一连接的旧探测回调也可能晚到，不能沿用它携带的旧起点或时间差判断新探测。
|
||
* 本函数不识别探测轮次，不读时钟，也不操作外部定时器或关闭连接。
|
||
* 状态或t1_ms非法时先返回-1；合法时ACT_SEND_PENDING返回0，该状态表示本地
|
||
* 发送结果尚未提交，须先Complete再处理CON。发送层须限定排队和发送期限，
|
||
* 成功Prepare后恰好一次Complete，发送超时也以失败长度报告，不能静默丢弃完成事件。
|
||
*/
|
||
extern int IEC104_Link_T1_Testfr_Con_Expired(
|
||
const IEC104_LinkState_t *state,
|
||
uint32_t elapsed_ms, uint32_t t1_ms);
|
||
|
||
#ifdef __cplusplus
|
||
}
|
||
#endif
|
||
|
||
#endif /* IEC104_LINK_COMMON_H */
|