555 lines
39 KiB
C
555 lines
39 KiB
C
/*
|
||
* TCP内部的子站连接协调:串行衔接Receiver、Link和SendManager,不执行socket I/O。
|
||
* 本头文件供TcpServer实现使用;业务通过IEC104_TcpServer.h接入。
|
||
* 下文的调用方指TcpServer;对象及借用存储由其管理,内部帧和记录由其转为业务事件。
|
||
*/
|
||
#ifndef IEC104_CONNECTION_H
|
||
#define IEC104_CONNECTION_H
|
||
|
||
#include "IEC104_Receiver.h"
|
||
#include "IEC104_SendManager.h"
|
||
|
||
#ifdef __cplusplus
|
||
extern "C" {
|
||
#endif
|
||
|
||
/* 按具体值分支;只有SEND_READY提供发送字节,FRAME_WRITTEN提供完成结果。 */
|
||
typedef enum {
|
||
IEC104_CONNECTION_FATAL = -2, /* 已冻结连接;停止I/O,读取记录后Close */
|
||
IEC104_CONNECTION_ERROR = -1, /* 参数、身份、调用阶段或时钟非法 */
|
||
IEC104_CONNECTION_EMPTY = 0, /* 无可查询项或无待发送业务 */
|
||
IEC104_CONNECTION_OK = 1, /* 本次操作成功;发送进度接口中表示尚未整帧写完 */
|
||
IEC104_CONNECTION_WAIT = 2, /* 接收请求未受理,或发送门控/容量阻塞 */
|
||
IEC104_CONNECTION_FRAME_READY = 3, /* I帧已完成链路处理,等待TcpServer复制为事件并释放 */
|
||
IEC104_CONNECTION_SEND_READY = 4, /* 当前帧的剩余字节可交给实际传输 */
|
||
IEC104_CONNECTION_FRAME_WRITTEN = 5 /* 整帧写完及对应完成处理均已提交 */
|
||
} IEC104_ConnectionResult_t;
|
||
|
||
typedef enum {
|
||
IEC104_CONNECTION_UNINITIALIZED = 0, /* 零值标记;仍须成功Init后才能调用运行接口 */
|
||
IEC104_CONNECTION_ACTIVE, /* TCP由TcpServer管理;不表示已经STARTED */
|
||
IEC104_CONNECTION_FAILED, /* 保留接收原文、发送记录及ASDU队列供回收 */
|
||
IEC104_CONNECTION_CLOSED /* 借用已解除;ASDU队列仍由TcpServer持有 */
|
||
} IEC104_ConnectionPhase_t;
|
||
|
||
typedef enum {
|
||
IEC104_CONNECTION_FAULT_NONE = 0, /* 尚未登记故障 */
|
||
IEC104_CONNECTION_FAULT_FRAME, /* 起始字节、APCI或ASDU最低长度非法 */
|
||
IEC104_CONNECTION_FAULT_PROTOCOL, /* 序号、ACK或接收阶段不符合协议 */
|
||
IEC104_CONNECTION_FAULT_INTERNAL, /* 模块状态或交接失败 */
|
||
IEC104_CONNECTION_FAULT_TRANSPORT, /* 发送失败或外部传输故障;正常有序EOF由TcpServer收尾 */
|
||
IEC104_CONNECTION_FAULT_LOCAL_SEND_TIMEOUT, /* 当前APDU排队及写入总期限到达 */
|
||
IEC104_CONNECTION_FAULT_I_ACK_TIMEOUT, /* 已完整发出的I帧等待对端ACK达到t1 */
|
||
IEC104_CONNECTION_FAULT_TESTFR_TIMEOUT, /* 本端TESTFR_ACT已发完,等待CON达到t1 */
|
||
IEC104_CONNECTION_FAULT_STOP_TIMEOUT /* STOP已受理,确认及对应CON发送未在总期限内完成 */
|
||
} IEC104_ConnectionFault_t;
|
||
|
||
/* 内部连接配置的类型别名;配置值由公共Types定义,与TcpServer使用同一布局。 */
|
||
typedef IEC104_ProtocolConfig_t IEC104_ConnectionConfig_t;
|
||
|
||
/* TcpServer借用原文至匹配的Release或Close;代次与receive_serial共同标识这次内部读取。 */
|
||
typedef struct {
|
||
IEC104_ReceivedFrame_t frame; /* 完整APDU/APCI;仅交付已受理的I帧 */
|
||
uint64_t receive_serial; /* 本连接内不复用,拒绝迟到的重复Release */
|
||
} IEC104_ConnectionReceivedFrame_t;
|
||
|
||
/* 无指针的观察快照;CLOSED后的链路字段是收尾时的历史值,不用这些字段自行组合收发门控。 */
|
||
typedef struct {
|
||
uint64_t connection_generation; /* 本快照所属连接代次 */
|
||
IEC104_ConnectionPhase_t phase; /* Connection运行、故障冻结或已关闭阶段 */
|
||
IEC104_ConnectionFault_t fault; /* 首次故障原因;正常关闭仍可为NONE */
|
||
IEC104_DataTransferState_t dt_state; /* 受理START/STOP后立即更新的数据传输状态 */
|
||
IEC104_DtProcedure_t dt_procedure; /* 子站仅IDLE或STOP_DRAINING,CON进度由发送缓冲维护 */
|
||
IEC104_TestfrState_t testfr_state; /* 本端主动探测的发送/等待CON进度 */
|
||
uint16_t send_record_count; /* 全部未消费I帧记录数,包括已经ACK的回执 */
|
||
uint8_t has_received_i_frame; /* TcpServer可Peek,复制为事件后显式Release */
|
||
uint8_t has_unhandled_frame; /* WAIT或故障时保留的尚未完成处理帧 */
|
||
} IEC104_ConnectionStatus_t;
|
||
|
||
/*
|
||
* 仅供TcpServer内部的启停通知适配;不是业务回调,不得重入修改接口,可只读查询状态。
|
||
* can_accept只读查询启停通知容量;notify在实际状态改变后、请求处理返回前复制通知。
|
||
* 两个函数必须同时设置或同时为空;为空时独立Connection不产生通知背压。
|
||
*/
|
||
typedef struct {
|
||
void *context;
|
||
int (*can_accept)(void *context);
|
||
int (*notify)(void *context, IEC104_DataTransferState_t state);
|
||
} IEC104_ConnectionTransferObserver_t;
|
||
|
||
/*
|
||
* TcpServer内部持有,完整布局用于静态存储;全部字段由接口维护,无malloc、无锁、无业务回调。
|
||
* Init后地址固定,不能复制/移动:Manager引用本结构内唯一的Link和SendBuffer。
|
||
* 同一连接的所有调用必须串行;不要再直接调用内含对象的修改接口。
|
||
* Link和SendBuffer的运行期修改统一经Manager;Connection只读Link,发送期限也通过Manager查询。
|
||
* ASDU队列独立持有以支持重连恢复;对象、数组及输入/输出参数存储不得重叠。
|
||
*/
|
||
typedef struct {
|
||
IEC104_Receiver_t receiver; /* 组装半帧并保留完整APDU;I帧由TcpServer复制为事件后释放 */
|
||
IEC104_LinkState_t link_state; /* 本连接唯一协议状态,收发共用序号和启停进度 */
|
||
IEC104_SendBuffer_t send_buffer; /* 当前I帧及控制FIFO,保存实际写入进度 */
|
||
IEC104_SendManager_t send_manager; /* 关联ASDU、发送帧和ACK记录,引用本对象内的Link/Buffer */
|
||
IEC104_ConnectionConfig_t config; /* Init时复制的配置,运行期间保持不变 */
|
||
IEC104_ConnectionTransferObserver_t transfer_observer; /* 内部通知容量及变化交接 */
|
||
IEC104_SendFrameId_t stop_con_frame_id; /* 当前STOP对应的最后一帧CON,拒绝旧完成结束新期限 */
|
||
uint64_t connection_generation; /* 非零且跨连接不复用,所有外部事件均须匹配 */
|
||
uint64_t last_now_ms; /* 串行事件的单调时刻,不接受倒退 */
|
||
uint64_t last_activity_ms; /* 完整合法APDU到达或本地整帧完成;反向启停CON除外 */
|
||
uint64_t received_at_ms; /* 当前完整接收帧到达时刻,WAIT不续期 */
|
||
uint64_t receive_serial; /* 每次成帧递增;耗尽时结束连接 */
|
||
uint64_t rx_ack_started_ms; /* 当前连续未确认接收区间的最早起点 */
|
||
uint64_t testfr_started_ms; /* 本次TESTFR_ACT完整写出的时刻 */
|
||
uint64_t stop_started_ms; /* 本轮STOP原成帧时刻;受理时启用计时,受理前WAIT也计入总期限 */
|
||
IEC104_ConnectionPhase_t phase; /* Connection生命周期,独立于Link的STARTED/STOPPED */
|
||
IEC104_ConnectionFault_t fault; /* 只登记首次故障;Close保留该值供查询 */
|
||
uint8_t rx_link_applied; /* I帧已交给Manager,不得因重复Peek/驱动再交一次 */
|
||
uint8_t rx_ack_timer_active; /* 0/1:存在尚未全部确认的接收区间,rx_ack_started_ms有效 */
|
||
uint8_t testfr_timer_active; /* 0/1:本次ACT已完整发送,testfr_started_ms有效 */
|
||
uint8_t stop_timer_active; /* 0/1:STOP已受理、未取消且CON尚未完成,stop_started_ms有效 */
|
||
uint8_t receive_batch_active; /* 有界接收批次内暂缓对端确认超时,下一次Tick结束批次 */
|
||
uint8_t receive_batch_pending; /* 固定输入快照尚未处理完,下一轮必须立即续收 */
|
||
} IEC104_Connection_t;
|
||
|
||
/**
|
||
* 功能:写入Link默认值;本地发送和停止期限默认等于默认t1,HIGH严格优先。NULL无操作。
|
||
* 输入参数:config——调用方提供的配置存储,允许NULL。
|
||
* 输出参数:写入Link默认k/w/t1/t2/t3,本地发送和STOP总期限取默认t1,HIGH连续帧配额为4。
|
||
* 返回值:无。
|
||
* 说明:只填写配置,不初始化连接、不启动计时;调用方可在Init前修改配置字段。
|
||
* 返回补充:无;NULL时不操作。
|
||
*/
|
||
extern void IEC104_Connection_Config_Default(IEC104_ConnectionConfig_t *config);
|
||
|
||
/**
|
||
* 功能:初始化新子站连接,初始STOPPED;generation非零且跨连接不复用,now_ms允许0。
|
||
* 输入参数:connection——首次使用或已Close的对象;queue——已Init/Rebind到本代次的ASDU队列。
|
||
* control_frames/control_capacity——控制槽数组及槽数;records/record_capacity——I帧记录数组及条数。
|
||
* config——有效配置;connection_generation——非零且跨连接不复用;now_ms——初始单调时刻。
|
||
* 输出参数:成功写入完整Connection;Manager成功绑定时清空HIGH待发原文,保留待发NORMAL。
|
||
* 返回值:OK初始化成功;ERROR参数、配置、队列或绑定条件非法,connection和队列保持原值。
|
||
* 说明:queue已Init/Rebind到该代次且无待ACK条目;可有待发NORMAL,成功时清空HIGH。
|
||
* control_capacity>=1,record_capacity为1..32767;config不可为NULL。
|
||
* 配置须满足0<t2_ms<t1_ms;不满足时返回ERROR,不改connection或队列。
|
||
* OK后对象地址及借用存储保持有效;失败不改connection或队列。
|
||
* Manager负责校验并在最终地址初始化Link/Buffer;成功后仅提交其余连接字段,不修补Manager内部指针。
|
||
* 仅用于首次使用或Close后的对象;重新Init前必须结束旧I/O和所有借用。
|
||
*/
|
||
extern IEC104_ConnectionResult_t IEC104_Connection_Init(
|
||
IEC104_Connection_t *connection, IEC104_AsduQueue_t *queue,
|
||
IEC104_SendBufferControlFrame_t *control_frames, uint16_t control_capacity,
|
||
IEC104_IFrameSendRecordStorage_t *records, uint16_t record_capacity,
|
||
const IEC104_ConnectionConfig_t *config, uint64_t connection_generation, uint64_t now_ms);
|
||
|
||
/**
|
||
* 功能:Init后、首次Feed前安装内部启停通知适配;observer复制入连接,context须持续有效。
|
||
* 输入参数:connection——连接对象。
|
||
* connection_generation——连接代次。
|
||
* observer——ACK观察回调。
|
||
* 输出参数:connection——连接对象的更新结果。
|
||
* 返回值:按处理分支返回IEC104_CONNECTION_ERROR、IEC104_CONNECTION_OK。
|
||
* 说明:参数非法或已经接收过APDU返回ERROR,不改变适配器;不执行通知或推进协议。
|
||
*/
|
||
extern IEC104_ConnectionResult_t IEC104_Connection_Set_Transfer_Observer(
|
||
IEC104_Connection_t *connection, uint64_t connection_generation,
|
||
const IEC104_ConnectionTransferObserver_t *observer);
|
||
|
||
/**
|
||
* 功能:可选:开始一轮有界的非阻塞接收,暂缓I帧ACK和TESTFR_CON的t1判定。
|
||
* 输入参数:connection——连接对象。
|
||
* connection_generation——连接代次。
|
||
* 输出参数:connection——连接对象的更新结果。
|
||
* 返回值:按处理分支返回checked、IEC104_CONNECTION_ERROR、IEC104_CONNECTION_OK。
|
||
* 说明:用于先处理socket中已经到达的多帧输入,再检查对端是否仍欠确认;不重置期限。
|
||
* 同一轮必须调用Tick或Yield_Receive_Batch结束批次;重复Begin返回ERROR。
|
||
* 期间仍检查本地发送和STOP总期限,格式/协议错误仍立即失败;Close也会结束批次。
|
||
* 未调用本接口时,Feed仍即时检查全部期限;发送准备/回报仅检查本地发送和STOP期限。
|
||
*/
|
||
extern IEC104_ConnectionResult_t IEC104_Connection_Begin_Receive_Batch(
|
||
IEC104_Connection_t *connection, uint64_t connection_generation);
|
||
|
||
/**
|
||
* 功能:仅供调度预算让出:结束当前轮次,但已到达的有限输入快照尚未全部处理。
|
||
* 输入参数:connection——连接对象。
|
||
* connection_generation——连接代次。
|
||
* now_ms——当前单调毫秒时刻。
|
||
* 输出参数:connection——连接对象的更新结果。
|
||
* 返回值:按处理分支返回checked、IEC104_CONNECTION_ERROR、Drive(connection, now_ms, CHECK_ALL_TIMEOUTS)。
|
||
* 说明:不改任何期限起点,暂缓I_ACK/TESTFR判定;本地发送、STOP及控制推进仍有效。
|
||
* Get_Wait_Time返回0,调用方必须立即续收,且不得把后来到达的输入加入旧快照。
|
||
* 快照耗尽、实际容量背压或接收无进展时必须调用Tick恢复完整期限检查。
|
||
* 不能用于等待业务消费或socket可读;仅ACTIVE且已Begin时可调用。
|
||
*/
|
||
extern IEC104_ConnectionResult_t IEC104_Connection_Yield_Receive_Batch(
|
||
IEC104_Connection_t *connection, uint64_t connection_generation, uint64_t now_ms);
|
||
|
||
/**
|
||
* 功能:最多消费至一帧末尾,consumed_length必填;非NULL时始终写入实际消费量。
|
||
* 输入参数:connection/connection_generation——本连接及输入所属代次;data/length——本次可用字节。
|
||
* now_ms——本次单调时刻;length为0时data可为NULL,用于重试保留帧。
|
||
* 输出参数:consumed_length必填,写实际消费量;未消费尾部由调用方保留,不能按length直接丢弃。
|
||
* 返回值:OK半帧或控制帧已处理;FRAME_READY业务I帧就绪;WAIT请求待继续处理;ERROR接入非法;FATAL冻结。
|
||
* TESTFR_ACT在WAIT时已禁止本连接的新主动探测,但CON应答尚未入队,仍须保留请求重试。
|
||
* 说明:半帧或已受理S/U返回OK;I帧返回FRAME_READY;控制槽或启停通知容量不足返回WAIT并保留当前帧。
|
||
* 后两者重入时消费0字节。保留未消费尾部;Release/驱动解除阻塞后再Feed尾部。
|
||
* 长度为0时data可为NULL,用于重试当前帧。格式/协议错误冻结连接并返回FATAL。
|
||
* 格式合法的STARTDT_CON/STOPDT_CON消费后忽略,不应答、不改变启停或确认期限、不刷新t3;
|
||
* 不占业务通知或控制发送槽,处理后仍照常检查期限并推进已有控制义务。
|
||
* 链路受理不代表ASDU业务执行成功;ASDU内容由业务解析。无效参数不消费输入。
|
||
*/
|
||
extern IEC104_ConnectionResult_t IEC104_Connection_Feed(
|
||
IEC104_Connection_t *connection, uint64_t connection_generation,
|
||
const uint8_t *data, uint32_t length, uint64_t now_ms, uint32_t *consumed_length);
|
||
|
||
/**
|
||
* 功能:FRAME_READY时写只读视图;无业务帧EMPTY,保留帧待继续处理时WAIT。FAILED仍可读已受理I帧。
|
||
* 输入参数:connection/connection_generation——本连接及代次,允许ACTIVE或FAILED。
|
||
* 输出参数:仅FRAME_READY时写frame,包含完整APDU/APCI借用及本次receive_serial。
|
||
* 返回值:FRAME_READY可读取;EMPTY无完整业务帧;WAIT保留帧待继续处理;ERROR身份、输出或存储非法。
|
||
* 说明:不消费原文、不提交链路事件;借用在匹配Release或Close后失效。
|
||
* FAILED下WAIT仅描述遗留未处理完的帧,不表示可以继续驱动故障连接。
|
||
*/
|
||
extern IEC104_ConnectionResult_t IEC104_Connection_Peek_Received_Frame(
|
||
const IEC104_Connection_t *connection, uint64_t connection_generation,
|
||
IEC104_ConnectionReceivedFrame_t *frame);
|
||
|
||
/**
|
||
* 功能:TcpServer成功复制I_FRAME事件后释放匹配I帧,OK/ERROR;允许FAILED回收,不再次提交链路事件。
|
||
* 输入参数:connection_generation/receive_serial——本次Peek返回的连接代次及接收身份。
|
||
* 输出参数:成功清除接收进度和rx_link_applied;所有指向该APDU/ASDU的旧借用立即失效。
|
||
* 返回值:OK释放成功;ERROR身份不符、没有已受理I帧、已Close或底层释放失败。
|
||
* 说明:ACTIVE和FAILED均可回收;不再次处理N(S)/N(R),不撤回已经安排的链路确认。
|
||
*/
|
||
extern IEC104_ConnectionResult_t IEC104_Connection_Release_Received_Frame(
|
||
IEC104_Connection_t *connection, uint64_t connection_generation, uint64_t receive_serial);
|
||
|
||
/**
|
||
* 功能:提交当前连接的应答;仅接收批次之外、同代次ACTIVE连接可用,不执行socket I/O。
|
||
* 输入参数:connection/connection_generation——连接及代次;asdu/asdu_length——原文及长度。
|
||
* now_ms——本次单调时刻。
|
||
* 输出参数:head_info——SEND_READY时取得待发送帧信息。
|
||
* 返回值:SEND_READY或OK表示已接手;WAIT未接手;ERROR非法;FATAL为连接故障。
|
||
* 说明:两条路径均由Manager按实际状态准入:仅STARTED+IDLE时接手。
|
||
* 其他阶段在容量检查前返回ERROR且不入HIGH;普通路径先Drive,再检查准入。
|
||
* SEND_READY已生成I帧并写head_info;OK已复制到HIGH;两者都不再借用输入原文。
|
||
* WAIT尚未接手,ERROR参数/阶段/容量非法,FATAL连接失败;准备后的故障不能直接重放原文。
|
||
* 到期且准入允许时仅入HIGH,由Process先读取待处理ACK再检查期限;未到期时统一推进控制流程。
|
||
* 受理新STOPDT_ACT时,HIGH待发应答作废且无逐条回执;重复STARTDT_ACT不清理HIGH。
|
||
* 服务级NORMAL直接进入TcpServer持有的ASDU队列;应答的HIGH顺序、窗口及公平配额由Manager保持。
|
||
*/
|
||
extern IEC104_ConnectionResult_t IEC104_Connection_Submit_Response(
|
||
IEC104_Connection_t *connection, uint64_t connection_generation,
|
||
const uint8_t *asdu, uint16_t asdu_length, uint64_t now_ms,
|
||
IEC104_SendBufferHeadInfo_t *head_info);
|
||
|
||
/**
|
||
* 功能:空闲直发:Can只读、不Drive、不预留资源;Submit在实际编号前重新检查并推进Drive。
|
||
* 输入参数:connection/connection_generation——连接及代次;now_ms——本次单调时刻。
|
||
* reserve——提交后须保留的发送窗口和记录槽数量。
|
||
* 输出参数:无。
|
||
* 返回值:OK当前可提交;WAIT暂受协议或资源限制;ERROR为参数、会话或状态非法。
|
||
* 说明:到期期限或接收批次待续时WAIT,不缓存到HIGH;正在接收批次内重入属于ERROR。
|
||
* 保留或本次Drive新推进的待交付请求均阻止IDLE编号;WAIT仍须由TcpServer执行事件交付尾部。
|
||
* Can返回OK/WAIT/ERROR;Submit的SEND_READY才写head_info,此外可返回WAIT/ERROR/FATAL。
|
||
* 本层不执行网络收发;Drive受理的STOP会由后续Manager准入检查拦住新的IDLE。
|
||
*/
|
||
extern IEC104_ConnectionResult_t IEC104_Connection_Can_Submit_Idle(
|
||
const IEC104_Connection_t *connection, uint64_t connection_generation, uint64_t now_ms, uint16_t reserve);
|
||
/**
|
||
* 功能:使用默认业务等级尝试直接准备一帧IDLE业务ASDU。
|
||
* 输入参数:connection/connection_generation——连接及代次;asdu/asdu_length——原文及长度。
|
||
* reserve——须保留的资源数量;now_ms——本次单调时刻。
|
||
* 输出参数:head_info——SEND_READY时取得待发送帧信息。
|
||
* 返回值:SEND_READY已准备;WAIT尚未接手;ERROR非法;FATAL为连接故障。
|
||
* 说明:沿用带等级入口的协议驱动和准入检查;WAIT不把该ASDU转入业务队列。
|
||
*/
|
||
extern IEC104_ConnectionResult_t IEC104_Connection_Submit_Idle(
|
||
IEC104_Connection_t *connection, uint64_t connection_generation,
|
||
const uint8_t *asdu, uint16_t asdu_length, uint16_t reserve, uint64_t now_ms,
|
||
IEC104_SendBufferHeadInfo_t *head_info);
|
||
|
||
/**
|
||
* 功能:带凭证变体:SEND_READY直接交接,OK已进入HIGH,两者才写ticket(可NULL)。
|
||
* 输入参数:connection/connection_generation——连接及代次;asdu/asdu_length——原文及长度。
|
||
* now_ms——本次单调时刻。
|
||
* 输出参数:head_info——SEND_READY时的帧信息;ticket——成功接手时的票据,可为NULL。
|
||
* 返回值:SEND_READY或OK表示已接手;WAIT未接手;ERROR非法;FATAL为连接故障。
|
||
* 说明:协议工作到期时只入HIGH,由正常接收/Process处理期限,不提前Drive或判远端超时。
|
||
* WAIT未接手;兼容模式直交凭证为0,严格模式排队或直交均为非零可查询票据。
|
||
* 其余会话及输出约定同Submit_Response。
|
||
*/
|
||
extern IEC104_ConnectionResult_t IEC104_Connection_Submit_Response_Tracked(
|
||
IEC104_Connection_t *connection, uint64_t connection_generation,
|
||
const uint8_t *asdu, uint16_t asdu_length, uint64_t now_ms,
|
||
IEC104_SendBufferHeadInfo_t *head_info, uint64_t *ticket);
|
||
|
||
/**
|
||
* 功能:纯排队入口强制复制进HIGH以取得非零票据;准入及期限检查与Tracked相同。
|
||
* 输入参数:connection/connection_generation——连接及代次;asdu/asdu_length——原文及长度。
|
||
* now_ms——本次单调时刻。
|
||
* 输出参数:ticket——必填,仅成功接手后写入。
|
||
* 返回值:OK已排队;WAIT未接手;ERROR非法;FATAL为连接故障。
|
||
* 说明:ticket必须非NULL,仅OK写入;本次新应答不直接构帧,WAIT/ERROR/FATAL不改输出。
|
||
* 兼容模式TcpServer用此入口先安装ACK观察槽,之后交接才把票据关联到frame_serial。
|
||
* 严格模式ACK观察改走Tracked以支持有序队满直交;本Enqueue入口仍只排队,不绕过当前调度。
|
||
*/
|
||
extern IEC104_ConnectionResult_t IEC104_Connection_Enqueue_Response_Tracked(
|
||
IEC104_Connection_t *connection, uint64_t connection_generation,
|
||
const uint8_t *asdu, uint16_t asdu_length, uint64_t now_ms, uint64_t *ticket);
|
||
|
||
/**
|
||
* 功能:Init后、开始收发前安装传输内部ACK观察器,不向应用调用回调。
|
||
* 输入参数:connection/connection_generation——连接及代次;observer——回调集合,NULL表示清除。
|
||
* 输出参数:connection——连接对象的更新结果。
|
||
* 返回值:OK设置成功;ERROR为连接代次或发送管理器状态非法。
|
||
* 说明:观察器按值复制,context须由调用方保活;生命周期及禁止重入规则见SendManager接口。
|
||
*/
|
||
extern IEC104_ConnectionResult_t IEC104_Connection_Set_Ack_Observer(
|
||
IEC104_Connection_t *connection, uint64_t connection_generation,
|
||
const IEC104_SendManagerAckObserver_t *observer);
|
||
|
||
/**
|
||
* 功能:推进接收重试、控制应答及本地发送/STOP期限,再取得剩余发送字节;仅SEND_READY写head_info。
|
||
* 输入参数:connection/connection_generation——当前连接及代次;now_ms——本次单调时刻。
|
||
* 输出参数:仅SEND_READY时写head_info,其中pending_data是SendBuffer字节的只读借用。
|
||
* 返回值:SEND_READY有可写字节;EMPTY无待发项;WAIT受门控/窗口/容量或确认到期限制;ERROR非法;FATAL冻结。
|
||
* 说明:不在此处报告I帧ACK或TESTFR_CON超时故障;调用方须按Get_Wait_Time及时接收并Tick。
|
||
* 任一确认t1已到时只取得已有帧;无已有帧返回WAIT,不选择HIGH/NORMAL、不分配N(S)。
|
||
* 有效确认解除所有已到期等待后重新准入,不重置原期限;接收批次内外均适用。
|
||
* 无当前帧时才选ASDU并编号。RX的WAIT不阻止已有帧发送,避免控制槽满时互等。
|
||
* pending_data借用至该帧完成或Close;一次只能有一个未回报的写操作,禁止APDU交错。
|
||
*/
|
||
extern IEC104_ConnectionResult_t IEC104_Connection_Prepare_Next_Send(
|
||
IEC104_Connection_t *connection, uint64_t connection_generation, uint64_t now_ms,
|
||
IEC104_SendBufferHeadInfo_t *head_info);
|
||
|
||
/**
|
||
* 功能:内部EOF收尾查询:仅在Prepare_Next_Send返回WAIT、转移就绪事件后使用。
|
||
* 输入参数:connection——连接对象。
|
||
* connection_generation——连接代次。
|
||
* record_wait——uint8_t *所指数据。
|
||
* 输出参数:record_wait——uint8_t *所指数据的更新结果。
|
||
* 返回值:按处理分支返回IEC104_CONNECTION_ERROR、checked、IEC104_CONNECTION_OK。
|
||
* 说明:记录容量已满、队首可回收,且启停/k窗口和上次准备时刻的确认t1均允许新I帧时,record_wait=1。
|
||
* 表示当前等待可通过转移RECORD解除;其他限制为0,不把还需新ACK/STARTDT的等待误判为可恢复。
|
||
* 只读,不推进协议或预留序号;仅OK写输出,ERROR/FATAL沿用连接查询约定。
|
||
*/
|
||
extern IEC104_ConnectionResult_t IEC104_Connection_Get_Record_Wait(
|
||
const IEC104_Connection_t *connection, uint64_t connection_generation, uint8_t *record_wait);
|
||
|
||
/**
|
||
* 功能:回报实际写入增量,0表示暂不可写;OK尚未写完,FRAME_WRITTEN才写completion。
|
||
* 输入参数:frame_id——Prepare返回的当前帧身份;bytes_written_now——本次增量,非累计值,允许0。
|
||
* now_ms——本次单调时刻,最后一段的时刻作为整帧完成时刻;completion必填。
|
||
* 输出参数:Manager更新写入进度;仅FRAME_WRITTEN时写completion数值副本。
|
||
* 返回值:OK尚未整帧完成;FRAME_WRITTEN完成流程成功;ERROR身份/增量/时间非法;FATAL冻结。
|
||
* 说明:now_ms使用实际写入后的时刻;记录及计时照常更新,对端确认t1由后续接收/Tick判定。
|
||
* 本地发送和STOP期限仍检查;不得通过回报发送进度替代接收及Tick调度。
|
||
* 完成后自动重试保留接收帧/控制流程。FATAL可能发生在已登记写入之后,不能重放增量。
|
||
* 先回报本地已知完成,再Feed覆盖该帧的ACK;不允许用对端ACK推定写入结果。
|
||
*/
|
||
extern IEC104_ConnectionResult_t IEC104_Connection_Handle_Send_Progress(
|
||
IEC104_Connection_t *connection, IEC104_SendFrameId_t frame_id,
|
||
uint16_t bytes_written_now, uint64_t now_ms, IEC104_LocalSendCompletion_t *completion);
|
||
|
||
/**
|
||
* 功能:最终写失败:匹配当前帧时提交失败并冻结,返回FATAL;错身份ERROR,不影响当前帧。
|
||
* 输入参数:connection——当前连接;frame_id——尚未整帧完成的当前发送帧身份。
|
||
* 输出参数:connection——连接对象的更新结果。
|
||
* 返回值:匹配并处理失败后FATAL;错误代次、帧身份或调用阶段为ERROR;已冻结同代次仍为FATAL。
|
||
* 说明:部分字节可能已到达对端,不能撤回帧、重新分配N(S)或重发同一增量继续旧会话。
|
||
* 不自动关闭socket或清空业务记录;EAGAIN应走等待/0字节进度,不能当作最终失败。
|
||
*/
|
||
extern IEC104_ConnectionResult_t IEC104_Connection_Handle_Send_Failure(
|
||
IEC104_Connection_t *connection, IEC104_SendFrameId_t frame_id);
|
||
|
||
/**
|
||
* 功能:TcpServer在Poll中调用,结束可选接收批次并检查全部期限;会排队到期的S/TESTFR。
|
||
* 输入参数:connection/connection_generation——本次唤醒所属连接;now_ms——当前单调时刻。
|
||
* 输出参数:connection——连接对象的更新结果。
|
||
* 返回值:OK本轮正常;FRAME_READY仍有业务I帧;WAIT当前接收请求未受理;ERROR接入非法;FATAL冻结。
|
||
* 说明:不创建系统定时器、不准备新I帧。固定输入快照耗尽或实际背压时必须调用Tick。
|
||
* 返回OK、接收FRAME_READY/WAIT或FATAL;参数、阶段、旧代次或时钟非法返回ERROR。
|
||
* 所有now_ms须为同一单调时钟且按调用顺序不倒退,时间戳0有效,是否计时由active标志区分。
|
||
* t2保留连续未确认区间的最早起点;只确认区间前缀时不续期,剩余部分可能提前确认。
|
||
*/
|
||
extern IEC104_ConnectionResult_t IEC104_Connection_Tick(
|
||
IEC104_Connection_t *connection, uint64_t connection_generation, uint64_t now_ms);
|
||
|
||
/**
|
||
* 功能:供TcpServer在接收批次结束且已推进协议后,查询下一次驱动前可等待的毫秒数。
|
||
* 输入参数:connection——连接对象。
|
||
* connection_generation——连接代次。
|
||
* now_ms——当前单调毫秒时刻。
|
||
* max_wait_ms——最长等待毫秒数。
|
||
* wait_ms——等待毫秒数。
|
||
* 输出参数:仅OK写wait_ms;查询不改变last_now_ms、期限起点、发送队列或故障状态。
|
||
* 返回值:按处理分支返回IEC104_CONNECTION_ERROR、checked、IEC104_CONNECTION_OK。
|
||
* 说明:max_wait_ms是调用方本轮允许的上限,0表示不等待,UINT32_MAX仍是有限毫秒数。
|
||
* OK才写wait_ms,范围0..max_wait_ms;到期返回0,没有更早期限则返回max_wait_ms。
|
||
* 覆盖本地发送、I帧/TESTFR的t1、STOP总期限及当前可准备控制帧的t2/t3。
|
||
* 与超时检查、发送准入和控制推进共用即时期限视图,不另存或改写各帧的原始起点。
|
||
* S/TESTFR已在途或控制槽满时不反复被旧t2/t3唤醒,仍受发送及其他活动期限约束。
|
||
* 只读查询,不更新时刻、不续期、不排队或冻结连接;实际处理仍由Tick/收发驱动。
|
||
* 参数、代次、时钟、内部状态非法或接收批次未结束返回ERROR;FAILED返回FATAL。
|
||
*/
|
||
extern IEC104_ConnectionResult_t IEC104_Connection_Get_Wait_Time(
|
||
const IEC104_Connection_t *connection, uint64_t connection_generation, uint64_t now_ms,
|
||
uint32_t max_wait_ms, uint32_t *wait_ms);
|
||
|
||
/**
|
||
* 功能:供TcpServer查询内部回执并转换为RECORD事件;允许ACTIVE或FAILED,OK才写record。
|
||
* 输入参数:connection/connection_generation——匹配代次且尚未Close的连接,允许FAILED。
|
||
* 输出参数:仅OK时写record独立数值副本;不会自动消费记录或重新释放ASDU原文。
|
||
* 返回值:OK队首回执就绪;EMPTY无记录;WAIT最早记录尚未同时满足两个完成条件;ERROR接入非法。
|
||
* 说明:调用方:TcpServer查询并成功复制RECORD事件后,再按返回的frame_id调用Remove_Confirmed_Record。
|
||
*/
|
||
extern IEC104_ConnectionResult_t IEC104_Connection_Peek_Confirmed_Record(
|
||
const IEC104_Connection_t *connection, uint64_t connection_generation,
|
||
IEC104_IFrameSendRecord_t *record);
|
||
/**
|
||
* 功能:TcpServer成功复制RECORD事件后移除匹配队首回执;允许FAILED回收,不再次释放ASDU原文。
|
||
* 输入参数:connection——ACTIVE或FAILED连接;frame_id——Peek取得并已复制到事件中的回执身份。
|
||
* 输出参数:connection——连接对象的更新结果。
|
||
* 返回值:OK移除成功;ERROR身份不符、队首未就绪或记录不可用。
|
||
* 说明:这里释放的是发送记录,不是ASDU原文;NORMAL原文已在ACK处理时确认释放或核减覆盖计数。
|
||
*/
|
||
extern IEC104_ConnectionResult_t IEC104_Connection_Remove_Confirmed_Record(
|
||
IEC104_Connection_t *connection, IEC104_SendFrameId_t frame_id);
|
||
|
||
/**
|
||
* 功能:按交接顺序读取记录,供故障回收;OK写副本,越界EMPTY。Close后不能再读取。
|
||
* 输入参数:connection/connection_generation——匹配且尚未Close;offset——从当前最早记录起的条目偏移。
|
||
* 输出参数:仅OK时写record数值副本,保留原优先级、帧身份、本地完成及peer_acknowledged事实。
|
||
* 返回值:OK读到记录;EMPTY偏移超出当前条数;ERROR参数、身份或记录状态非法。
|
||
* 说明:ACTIVE/FAILED均可读取,不要求该记录已确认,也不消费;未ACK不能证明对端未收到。
|
||
*/
|
||
extern IEC104_ConnectionResult_t IEC104_Connection_Get_Record_By_Offset(
|
||
const IEC104_Connection_t *connection, uint64_t connection_generation,
|
||
uint16_t offset, IEC104_IFrameSendRecord_t *record);
|
||
|
||
/**
|
||
* 功能:返回数值状态,允许FAILED/CLOSED;OK写status,参数、旧代次或模块状态非法时ERROR不改输出。
|
||
* 输入参数:connection/connection_generation——匹配对象及代次,允许ACTIVE、FAILED和CLOSED。
|
||
* 输出参数:仅OK时写status数值快照,不暴露底层原文指针。
|
||
* 返回值:OK查询成功;ERROR身份、初始化阶段、输出指针或模块状态非法,不改输出。
|
||
* 说明:CLOSED后的链路字段是收尾时的历史值,不能据此判断当前存在可用TCP连接。
|
||
*/
|
||
extern IEC104_ConnectionResult_t IEC104_Connection_Get_Status(
|
||
const IEC104_Connection_t *connection, uint64_t connection_generation,
|
||
IEC104_ConnectionStatus_t *status);
|
||
|
||
/**
|
||
* 功能:EOF或外部传输失败时冻结;ACTIVE/FAILED下同代次返回FATAL并保留首次原因。
|
||
* 输入参数:connection/connection_generation——通知所属连接,允许ACTIVE或已FAILED。
|
||
* 输出参数:ACTIVE时登记TRANSPORT故障;已FAILED保留首次原因,不清空记录和接收原文。
|
||
* 返回值:匹配未Close的连接返回FATAL;旧代次、未初始化或已CLOSED返回ERROR。
|
||
* 说明:旧代次、未初始化或CLOSED返回ERROR;不关闭socket、提交当前帧Complete或清空记录。
|
||
*/
|
||
extern IEC104_ConnectionResult_t IEC104_Connection_Handle_Transport_Closed(
|
||
IEC104_Connection_t *connection, uint64_t connection_generation);
|
||
|
||
/**
|
||
* 功能:先结束旧I/O、结束字节借用、读取所需记录,再Close;同代次重复Close返回OK。
|
||
* 输入参数:connection/connection_generation——准备收尾的连接;必须已结束旧I/O及所有字节借用。
|
||
* 输出参数:Abort发送管理及缓冲,清除接收进度和计时有效标志,phase置CLOSED;保留首次故障。
|
||
* 返回值:OK收尾完成,包括同代次重复Close;ERROR对象、代次或初始化阶段非法。
|
||
* 说明:清理Receiver/Manager/SendBuffer,保留外部ASDU队列;不执行socket关闭或隐式Rebind。
|
||
* 重连顺序:Close -> Queue.Rebind(新代次) -> Connection.Init -> 新STARTDT。
|
||
*/
|
||
extern IEC104_ConnectionResult_t IEC104_Connection_Close(
|
||
IEC104_Connection_t *connection, uint64_t connection_generation);
|
||
|
||
/**
|
||
* 功能:显式业务类别贯通所有发送路径,不改变会话、期限或原文所有权契约。
|
||
* 输入参数:connection——连接对象。
|
||
* connection_generation——连接代次。
|
||
* now_ms——当前单调毫秒时刻。
|
||
* reserve——须保留的窗口及记录槽数量。
|
||
* priority——优先级。
|
||
* 输出参数:无。
|
||
* 返回值:按处理分支返回IEC104_CONNECTION_ERROR、IEC104_CONNECTION_WAIT、Record_Result(IEC104_SendManager_Can_Submit_Idle_Priority( &connection->send_manager, connection_generation, reserve, priority))。
|
||
* 说明:priority为0时,应答默认INTERROGATION、IDLE默认MEASUREMENT;有效显式值为1..12。
|
||
* 严格模式Submit先排队,队满时才按当前有序阶段检查直交;Enqueue始终不构帧。
|
||
* 尚未交付的接收请求可能产生更高级候选,会暂缓新编号;当前帧和协议维护仍可继续。
|
||
*/
|
||
IEC104_ConnectionResult_t IEC104_Connection_Can_Submit_Idle_Priority(
|
||
const IEC104_Connection_t *connection, uint64_t connection_generation, uint64_t now_ms, uint16_t reserve,
|
||
IEC104_BusinessPriority_t priority);
|
||
/**
|
||
* 功能:实际提交不沿用此前Can的结论:取值期间可能到期,Drive也可能受理STOP或推进出请求。
|
||
* 输入参数:connection——连接对象。
|
||
* connection_generation——连接代次。
|
||
* asdu——ASDU报文。
|
||
* asdu_length——ASDU字节长度。
|
||
* reserve——须保留的窗口及记录槽数量。
|
||
* now_ms——当前单调毫秒时刻。
|
||
* head_info——队首信息。
|
||
* priority——优先级。
|
||
* 输出参数:connection——连接对象的更新结果。
|
||
* head_info——队首信息的更新结果。
|
||
* 返回值:返回IEC104_ConnectionResult_t结果;本函数显式处理IEC104_CONNECTION_ERROR、IEC104_CONNECTION_WAIT、IEC104_CONNECTION_FAULT_INTERNAL、IEC104_CONNECTION_FATAL、IEC104_CONNECTION_SEND_READY,其余结果由下层调用传回。
|
||
* 说明:这些情况不把快照放进HIGH;只有本次重新准入成功,才允许Manager编号。
|
||
*/
|
||
IEC104_ConnectionResult_t IEC104_Connection_Submit_Idle_Priority(
|
||
IEC104_Connection_t *connection, uint64_t connection_generation,
|
||
const uint8_t *asdu, uint16_t asdu_length, uint16_t reserve, uint64_t now_ms,
|
||
IEC104_SendBufferHeadInfo_t *head_info,
|
||
IEC104_BusinessPriority_t priority);
|
||
/**
|
||
* 功能:按指定业务等级提交应答,允许直接准备I帧或复制到HIGH队列。
|
||
* 输入参数:connection/connection_generation——连接及代次;asdu/asdu_length——原文及长度。
|
||
* now_ms——本次单调时刻;priority——业务等级,0沿用默认等级。
|
||
* 输出参数:head_info——SEND_READY时取得待发送帧信息。
|
||
* 返回值:SEND_READY已准备;OK已排队;WAIT未接手;ERROR非法;FATAL为连接故障。
|
||
* 说明:本入口不返回交接票据;发送准备不代表TCP写完或对端确认。
|
||
*/
|
||
IEC104_ConnectionResult_t IEC104_Connection_Submit_Response_Priority(
|
||
IEC104_Connection_t *connection, uint64_t connection_generation,
|
||
const uint8_t *asdu, uint16_t asdu_length, uint64_t now_ms,
|
||
IEC104_SendBufferHeadInfo_t *head_info,
|
||
IEC104_BusinessPriority_t priority);
|
||
/**
|
||
* 功能:协议到期时只入HIGH,不Drive;
|
||
* 输入参数:connection——连接对象。
|
||
* connection_generation——连接代次。
|
||
* asdu——ASDU报文。
|
||
* asdu_length——ASDU字节长度。
|
||
* now_ms——当前单调毫秒时刻。
|
||
* head_info——队首信息。
|
||
* ticket——应答交接票据。
|
||
* priority——优先级。
|
||
* 输出参数:connection——连接对象的更新结果。
|
||
* head_info——队首信息的更新结果。
|
||
* ticket——应答交接票据的更新结果。
|
||
* 返回值:返回Submit_Response(connection, connection_generation, asdu, asdu_length, now_ms, head_info, ticket, 0, priority)的结果。
|
||
* 说明:正常路径复用控制推进及有界构帧检查。
|
||
*/
|
||
IEC104_ConnectionResult_t IEC104_Connection_Submit_Response_Tracked_Priority(
|
||
IEC104_Connection_t *connection, uint64_t connection_generation,
|
||
const uint8_t *asdu, uint16_t asdu_length, uint64_t now_ms,
|
||
IEC104_SendBufferHeadInfo_t *head_info, uint64_t *ticket,
|
||
IEC104_BusinessPriority_t priority);
|
||
/**
|
||
* 功能:强制把本条应答复制进HIGH并返回非零票据,容量WAIT时没有接手原文。
|
||
* 输入参数:connection——连接对象。
|
||
* connection_generation——连接代次。
|
||
* asdu——ASDU报文。
|
||
* asdu_length——ASDU字节长度。
|
||
* now_ms——当前单调毫秒时刻。
|
||
* ticket——应答交接票据。
|
||
* priority——优先级。
|
||
* 输出参数:connection——连接对象的更新结果。
|
||
* ticket——应答交接票据的更新结果。
|
||
* 返回值:强制把本条应答复制进HIGH并返回非零票据,容量WAIT时没有接手原文。
|
||
* 说明:不为本条应答准备I帧;共用入口仍可推进已有协议状态,调用方不能把纯排队理解成整个连接静止。
|
||
*/
|
||
IEC104_ConnectionResult_t IEC104_Connection_Enqueue_Response_Tracked_Priority(
|
||
IEC104_Connection_t *connection, uint64_t connection_generation,
|
||
const uint8_t *asdu, uint16_t asdu_length, uint64_t now_ms, uint64_t *ticket,
|
||
IEC104_BusinessPriority_t priority);
|
||
|
||
#ifdef __cplusplus
|
||
}
|
||
#endif
|
||
#endif /* IEC104_CONNECTION_H */
|