Files
STM32F4-Base/IEC60870-Slave/104/IEC104_TcpServer.h
T
STF bdcc8b6500
CI / L0 静态门禁 (pre-commit) (push) Failing after 7m46s
CI / L0.5 主机侧单测 (MSVC) (push) Successful in 21s
添加遥控、参数装载、文件传输等业务
2026-11-16 22:19:17 -08:00

600 lines
45 KiB
C
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
/*
* IPv4子站TCP业务接口:隐藏Connection、队列及存储布局;socket只借给事件循环注册。
* 子站业务默认通过IEC104_Slave.h接入;本接口供Slave及独立TCP接入使用。
* Connection、SendManager等由TCP内部调度,服务对象仍保持不透明。
* 一个Slave拥有一个本模块句柄;本模块每个实例同时只服务一条主站TCP连接。
* 本层交付完整APDU及发送/连接事件,Slave再建立ASDU视图和原连接应答接口。
* 本层不解析具体业务命令、不自动应答ASDU;104序号、启停和超时由内部Connection处理。
*
* 生命周期:Create -> 统一启动配置/Init -> Prepare/Process/NextEvent -> Close/NextEvent -> Destroy。
* 应用配置由IEC104_Startup_Config_Default提供;本层不反向依赖业务层。
* 独立TCP循环也可使用Poll,由它组合准备、平台等待和推进;两种入口使用同一推进实现。
* Close释放网络并保留通知,Destroy在通知读空后归还静态槽,两者不能互相替代。
* 服务结果、提交结果和取事件结果是三种枚举;须分别比较OK、SUBMIT_OK、EVENT_READY。
* error可为NULL;非NULL时完整填写本次调用诊断,历史网络错误另见状态快照。
*
* 同一服务的全部接口在同一线程串行调用;Create/Destroy也须跨服务串行调用。
* 工程只链接一个Net后端;当前Windows实现需链接Ws2_32。
*/
#ifndef IEC104_TCPSERVER_H
#define IEC104_TCPSERVER_H
#include "IEC104_TcpTypes.h"
#include <stdbool.h>
#ifdef __cplusplus
extern "C" {
#endif
/* 不透明句柄:这里仅声明结构体名称,完整成员在IEC104_TcpServer.c中定义。
* 业务只持有Create返回的指针,不能定义对象、计算其sizeof、复制对象或访问内部成员。
* Slave可以保存并传递此指针,无需看见完整结构;这不表示把底层对象公开给业务。
* Connection、SendManager和缓冲区都由实现持有,业务无需为它们分配存储。 */
typedef struct IEC104_TcpServer IEC104_TcpServer_t;
/**
* 功能:从模块内部静态池取得对象,无malloc、无网络操作;无可用槽时返回NULL。
* 输入参数:无。
* 输出参数:无。
* 返回值:成功返回不透明句柄;无空闲槽或候选槽的代次/注册编号耗尽时返回NULL。
* 说明:默认容量1,可在IEC104_TcpServer_Config.h或编译参数中配置;成功后必须配对Destroy。
* 代次或注册编号耗尽的槽不再分配;句柄至Destroy成功前有效,不得free、清零或自行分配对象。
*/
extern IEC104_TcpServer_t *IEC104_TcpServer_Create(void);
/**
* 功能:只释放已Close(或尚未Init)且事件已读空的对象,成功返回OK。
* 输入参数:server——Create返回且尚未Destroy的句柄。
* 输出参数:error可为NULL;即使句柄无效或已成功归还,也交付本次诊断,不借用对象字段。
* 返回值:OK归还成功;INVALID_HANDLE/BUSY/INVALID_STATE/EVENTS_PENDING区分拒绝原因。
* 说明:无效句柄、重入、仍在运行、未读事件分别返回INVALID_HANDLE/BUSY/INVALID_STATE/EVENTS_PENDING。
* 不隐式丢弃事件或关闭运行中的服务;成功后所有旧句柄副本失效。
* 同一静态槽再分配仍保留代次及注册计数;调用方须结束旧业务任务,不能继续使用旧句柄。
* 成功后应将业务保存的指针置NULL;对象来自静态池,不得调用free。
*/
extern IEC104_TcpResult_t IEC104_TcpServer_Destroy(
IEC104_TcpServer_t *server, IEC104_TcpError_t *error);
/**
* 功能:成功返回OK;server来自Create,或已Close且事件已读空。
* 输入参数:server——Create取得或已Close且事件已读空的对象;config——公开配置。
* 输出参数:成功时复制配置并设置bound_port;error按本次操作填写,允许NULL。
* 返回值:OK成功;参数、配置、生命周期和网络错误分别返回对应的公开结果。
* 网络失败保留NET_INIT/LISTEN阶段及原生错误,参数错误不再伪装为平台socket错误。
* 说明:参数/基础配置失败为INVALID_ARGUMENT/INVALID_CONFIG,运行中为INVALID_STATE,旧事件未读为EVENTS_PENDING。
* 协议配置须满足0<t2_ms<t1_ms;不满足时在申请网络资源前返回INVALID_CONFIG,error阶段为VALIDATE。
* 注册编号耗尽为REGISTRATION_EXHAUSTED,error阶段为REGISTRATION;须Destroy归还句柄,不再重试Init。
* NETWORK_ERROR通过error区分NET_INIT/LISTEN阶段;地址内容解析失败也属于LISTEN阶段。
* 成功后服务队列已经可用,尚未接入客户端也可Enqueue_Event;内部队列初始化异常为INTERNAL_ERROR。
* 失败回收本次申请的网络资源,句柄仍归业务持有,可查询状态、重试或Destroy。
* 重复Init不关闭旧服务;成功后通过Prepare/Process或Poll持续驱动。
*/
extern IEC104_TcpResult_t IEC104_TcpServer_Init(
IEC104_TcpServer_t *server, const IEC104_TcpServerConfig_t *config, IEC104_TcpError_t *error);
/**
* 功能:查询下一轮事件循环需要的socket、协议/接入/发送等待上限和本地工作标志;仅OK修改info。
* 输入参数:server——已Init的句柄;info——非NULL快照存储;error——可选诊断。
* 输出参数:info——查询信息的更新结果。
* error——错误诊断的更新结果。
* 返回值:OK时完整写出info,参数、生命周期或内部查询失败时保持info原值。
* 说明:server须已Init;失败原因通过统一结果和error交付,不读取或修改Connection内部布局。
* service_token标识本次Init,socket token标识某次socket注册;二者与业务连接generation用途不同。
* Enqueue_Event、Send_Response、NextEvent、Process、Close_Connection、Init/Close改变调度条件,等待前须重新查询。
* 借出的socket只用于注册;Process/Send_Response/Close_Connection/Close可能关闭它们,之后须移除过期注册。
* 接入边沿触发时仍须遵守need_process;预算耗尽或背压恢复后不能只等下一个边沿。
* 接入资源暂缺或整轮4次均为RETRY时暂停100毫秒;期间撤销监听关注,由timer安排到期检查。
* 到期有接入容量即要求本地重试;无容量时等待NextEvent释放通知空间,不保留已到期定时器。
* 连续4次send返回OK+0或RETRY后暂停发送10毫秒;期间撤销客户端WRITE关注,由timer恢复。
* 暂停同时约束Process及快速应答;到期主动重试,接收和原协议期限继续推进。
* 单次通知模式须由应用按新快照重新布防;业务事件继续通过NextEvent取出。
*/
extern IEC104_TcpResult_t IEC104_TcpServer_Prepare(
const IEC104_TcpServer_t *server, IEC104_TcpWaitInfo_t *info, IEC104_TcpError_t *error);
/**
* 功能:根据一批就绪/定时/本地通知,有界执行接受、非阻塞收发和协议推进,绝不调用Net_Wait。
* 输入参数:server——已Init的句柄;ready——必填批次,本地唤醒也须携带有效service_token。
* 输出参数:error——可选的本次诊断;返回值为OK或参数、生命周期及服务级错误。
* 返回值:返回值为OK或参数、生命周期及服务级错误。
* 每轮返回后应用读取NextEvent,再更新监听与一次性定时器。
* 说明:ready必填;本地工作也使用最近Prepare的service_token构造空批次,不能用旧通知冒充新唤醒。
* 每轮最多32次Feed、32次send、4次accept和8条业务通知交付;断线收尾须一次完整交付。
* 交付预算或本类配额刚耗尽时先返回业务一次,下一轮重新获得预算;无处交付的I帧等待普通空间。
* 改变状态的ACT等待启停专用槽,NextEvent消费后安排重试;保留接收顺序,不影响已有CON续写。
* 可立即推进的工作由need_process提示,接入/发送暂停由timer提示,原有协议期限不重置。
* 就绪只是提示,实际I/O仍可能暂不可用;本地/定时唤醒也允许一次有界的非阻塞接收检查。
* 本批先接收并提交已到达事实,再检查确认期限;输入事件产生后交还应用处理,再续收。
* 仅因预算让出时,固定已到达输入的字节范围并要求立即续收,处理完后再检查ACK/TESTFR期限。
* 后来到达的输入不扩大旧批次;真正容量背压或接收无进展仍检查原期限。发送使用独立预算。
* OK包括无进度、过期通知被忽略及客户端已断线;服务级错误应保存error后Close。
* 所有调用必须在同一线程;不创建线程、系统定时器、跨线程唤醒或业务回调。
*/
extern IEC104_TcpResult_t IEC104_TcpServer_Process(
IEC104_TcpServer_t *server, const IEC104_TcpReady_t *ready, IEC104_TcpError_t *error);
/**
* 功能:独立循环的组合入口:Prepare -> 至多一次Net_Wait -> Process,使用同一套推进逻辑。
* 输入参数:server——已Init的句柄;max_wait_ms——网络等待上限,0不等待,UINT32_MAX仍为有限值。
* 输出参数:error——可选诊断;返回值沿用Prepare/等待/Process中首个失败结果,全部成功为OK。
* 返回值:返回值沿用Prepare/等待/Process中首个失败结果,全部成功为OK。
* 说明:每轮返回后NextEvent处理事件;使用应用自己的事件循环时直接调用Prepare/Process。
* max_wait_ms是本轮网络等待上限:0仅查询就绪,正数允许等待;UINT32_MAX仍为有限毫秒数。
* 实际等待还受最近协议/接入/发送重试期限约束;已有事件或可立即推进的工作时不等待。
* 无socket关注时也可有限等待;0毫秒立即返回,UINT32_MAX不会转成系统无限睡眠。
* 上限只约束网络等待,不保证整个函数的执行耗时;0模式下由业务主循环安排其他任务和休眠。
* OK表示服务可继续(包括客户端已断线);尚未Init为INVALID_STATE,重入为BUSY。
* NETWORK_ERROR/INTERNAL_ERROR及身份编号耗尽为服务级失败,保存error后应Close。
* 空闲、接入容量/资源暂缺、可恢复的网络中断及客户端故障均不作为服务级失败。
* 普通通知满仍可处理排在前面的S/U,不以普通通知容量阻挡CON;已确认回执暂留内部记录。
* 遇到无处交付的I帧时暂停续收并置receive_paused;启停专用槽满时暂缓受理后续改变状态的ACT。
* 消费对应通知后由Process恢复,不丢通知、不因通知积压直接断连;等待启停槽不设置receive_paused。
* 保留的I帧会挡住同一TCP流中后续S/U;应用须及时消费事件,原有协议期限不延长,超时仍可断连。
* EOF后停止为未编号NORMAL创建新I帧,原文留给下一连接;当前已编号帧、已受理HIGH及控制帧继续收尾。
* 部分写入跨Poll续发,不再等待新的ACK/STARTDT。
* 若仅因已确认记录尚未转为事件而缺少记录槽,则保留已受理应答,预算恢复或NextEvent腾出空间后续发;
* 已排空或仍需对端输入才能解除限制时关闭,原有协议及发送期限仍生效。
*/
extern IEC104_TcpResult_t IEC104_TcpServer_Poll(
IEC104_TcpServer_t *server, uint32_t max_wait_ms, IEC104_TcpError_t *error);
/**
* 功能:复制并取出最早事件,不执行I/O或业务函数;仅READY修改输出。
* 输入参数:server——尚未Destroy的句柄;event——业务提供的非NULL输出存储。
* 输出参数:server——TCP服务实例的更新结果。
* event——事件的更新结果。
* 返回值:READY写出独立副本,EMPTY/ERROR保持输出不变。
* 说明:EMPTY/ERROR保持输出不变,副本无需Release;Close后可读完全部收尾事件。
* 本层事件只含值和原文字节,可按值保存;Slave事件另外含自引用,须通过Slave_Copy_Event复制。
* 建立/激活/停用/断开均通过本入口逐条交付,不合并中间变化。
* 消费后安排保留I帧交付、启停CON续发、回执转移或接入重试;这里只取副本,不执行I/O或业务函数。
* 应用须及时消费通知并持续调用Process/Poll;等待通知空间不延长协议期限,长期不消费仍可能超时。
* READY后事件已从内部FIFO移除;需要稍后处理时由业务另存副本,不能依赖自动重投。
*/
extern IEC104_TcpEventResult_t IEC104_TcpServer_NextEvent(
IEC104_TcpServer_t *server, IEC104_TcpEvent_t *event);
/**
* 功能:复制主动上报到服务级低优先级事件队列(内部NORMAL);本入口只缓存,不立即写socket。
* 输入参数:server——服务实例;asdu/asdu_length——事件原文及字节数。
* 输出参数:server——TCP服务实例的更新结果。
* 返回值:OK已接手;WAIT暂时无法入队;ERROR为输入或状态非法;FATAL为队列失效。
* 说明:Init成功后即可调用,无需连接代次,首次连接前和断线期间也可缓存。
* EOF后全部尚未编号的数据及新增数据留给下一连接;STARTDT及可选启动门禁通过后发送。
* 重连后兼容模式保持NORMAL FIFO;严格模式保留原等级及同级受理顺序,再与本轮可发候选仲裁。
* 容量不足沿用覆盖最旧原文的策略,包括未ACK原文;不持久化,Close清空队列。
* 未ACK不代表对端未收到,恢复可能重复;同一服务应面向相同业务接收方或冗余域。
* 有连接且未EOF、未启动暂停时,成功入队使Prepare报告need_process;暂停或离线缓存不触发发送空转。
* 本入口与Send_Response均接收6..249字节ASDU,不含APCI;OK已接手,WAIT需业务保存重试。
* 所有调用须在所属事件循环线程串行执行;异步生产者先唤醒该线程,入队后刷新等待条件。
*/
extern IEC104_TcpSubmitResult_t IEC104_TcpServer_Enqueue_Event(
IEC104_TcpServer_t *server, const uint8_t *asdu, uint16_t asdu_length);
/**
* 功能:将单对象Type30/31、COT3原文保存到独立256条SOE区。
* 输入参数:server——服务;asdu/asdu_length——标准104原文,长度17;priority——业务等级;deferred——暂缓补报。
* 输出参数:ticket——可为NULL,仅OK写入服务期身份;deferred为true时必填。
* 返回值:OK已保存;WAIT未接手;ERROR参数或阶段非法;FATAL队列失效。
* 说明:允许离线保存;第257条只覆盖最旧SOE。CP56和品质由生产者构造,原文不重写。
* deferred占事件额度,须Resolve决定发布或取消;普通遥测不占用本区。
*/
extern IEC104_TcpSubmitResult_t IEC104_TcpServer_Enqueue_Soe(
IEC104_TcpServer_t *server, const uint8_t *asdu, uint16_t asdu_length,
IEC104_BusinessPriority_t priority, bool deferred, IEC104_SoeTicket_t *ticket);
/**
* 功能:将匹配SOE占位转为待发,或取消该占位。
* 输入参数:server——原服务;ticket——入队取得的身份;publish——true发布、false取消。
* 输出参数:无。
* 返回值:OK已处理或占位已被覆盖/清除;非法身份、阶段或队列异常返回相应错误。
* 说明:跨普通重连有效,Close/Init及其他服务的票据失效;已消失占位不重新生成事件。
*/
extern IEC104_TcpResult_t IEC104_TcpServer_Resolve_Soe(
IEC104_TcpServer_t *server, const IEC104_SoeTicket_t *ticket, bool publish);
/**
* 功能:释放指定活动轮次的NORMAL/IDLE门禁;不发送、不消费通知、不撤销已编号帧。
* 输入参数:server——TCP服务实例。
* generation——连接代次。
* activation_id——START活动轮次编号。
* 输出参数:server——TCP服务实例的更新结果。
* 返回值:按处理分支返回IEC104_TCP_SUBMIT_ERROR、IEC104_TCP_SUBMIT_FATAL、IEC104_TCP_SUBMIT_WAIT、IEC104_TCP_SUBMIT_OK。
* 说明:generation隔离TCP连接,activation_id隔离同一TCP上的STOP/START;两者须保留本轮ACTIVATED的原值。
* 应用先确认本轮初始化及所需总召完成;本接口只核对发送准入,不解析Type/QOI,也不等待主站ACK。
* OK本轮已开放(可幂等);WAIT须先分派通知或EOF收尾;ERROR为旧代次/轮次、未激活或参数非法。
* FATAL表示服务队列异常;业务不得用新轮次替换旧完成事件的activation_id重试。
* 未读通知检查覆盖完整FIFO及尚未交付的I帧;WAIT不会解除启动或EOF限制,不应原地忙重试。
* 配置关闭时仍校验身份,成功为空操作;首次开放后唤醒一次服务发送推进。
*/
extern IEC104_TcpSubmitResult_t IEC104_TcpServer_Release_Startup(
IEC104_TcpServer_t *server, uint64_t generation, uint64_t activation_id);
/**
* 功能:空闲直发不入队;控制帧、待交付请求及期限均优先。
* 输入参数:server/generation——服务及连接代次;reserve——提交后须保留的窗口和记录槽数量。
* 输出参数:无。
* 返回值:OK当前可提交;WAIT暂受通知、协议或资源限制;ERROR为参数、连接或状态非法。
* 说明:兼容模式等待全部HIGH/NORMAL;严格模式只等待同级或更高等级的可发送业务,并须处于对应业务阶段。
* 启动门禁未释放时即使两级队列为空也返回WAIT,周期快照和文件IDLE数据不能越过初始化/总召。
* Query只读,OK不预留资源;Send仍可能WAIT且未接手,调用方须丢弃快照后重取。
* reserve须小于窗口和记录容量;Send的OK表示原文已复制,不表示已写完或已ACK。
* Send的内部Drive即使返回WAIT仍执行事件交付;FATAL按现有收尾事件处理。
* 业务经Slave封装调用,以同时检查完整通知FIFO;本层检查状态通知及Connection待交付请求。
*/
extern IEC104_TcpSubmitResult_t IEC104_TcpServer_Query_Idle_Send(
const IEC104_TcpServer_t *server, uint64_t generation, uint16_t reserve);
/**
* 功能:使用默认业务等级尝试直接提交一帧IDLE业务ASDU。
* 输入参数:server/generation——服务及连接代次;asdu/asdu_length——原文及长度。
* reserve——须保留的发送窗口和记录槽数量。
* 输出参数:server——TCP服务实例的更新结果。
* 返回值:OK已接手;WAIT尚未接手;ERROR非法;FATAL为连接故障。
* 说明:WAIT不转入队列;成功后复用已有部分写入流程,OK不代表整帧已发送。
*/
extern IEC104_TcpSubmitResult_t IEC104_TcpServer_Send_Idle(
IEC104_TcpServer_t *server, uint64_t generation,
const uint8_t *asdu, uint16_t asdu_length, uint16_t reserve);
/**
* 功能:Init后有效,无客户端也可读取;返回配置上限而非可用余量,两项须分别用于reserve校验。
* 输入参数:server——TCP服务实例。
* capacity——存储容量。
* error——错误诊断。
* 输出参数:capacity——存储容量的更新结果。
* error——错误诊断的更新结果。
* 返回值:按处理分支返回checked、Result_With_Error(IEC104_TCP_INVALID_ARGUMENT, IEC104_TCP_STAGE_VALIDATE, 0, error)、Result_With_Error(IEC104_TCP_INVALID_STATE, IEC104_TCP_STAGE_LIFECYCLE, 0, error)、Result_With_Error(IEC104_TCP_OK, IEC104_TCP_STAGE_NONE, 0, error)。
* 说明:未Init/Close后INVALID_STATE,失败不改capacity;查询不推进协议、不消费通知。
*/
extern IEC104_TcpResult_t IEC104_TcpServer_Get_Send_Capacity(
const IEC104_TcpServer_t *server, IEC104_TcpSendCapacity_t *capacity, IEC104_TcpError_t *error);
/**
* 功能:提交当前请求的应答ASDU,须携带原I_FRAME事件的generation;旧代次、无连接及EOF后均拒绝。
* 输入参数:server/generation——服务及连接代次;asdu/asdu_length——应答原文及长度。
* 输出参数:server——TCP服务实例的更新结果。
* 返回值:OK已接手;WAIT未接手;ERROR非法;FATAL为连接故障。
* 说明:仅STARTED+IDLE时接手;否则在容量检查前ERROR,不入HIGH、不因拒绝断连。
* 兼容模式下,窗口及记录有余量、没有当前帧或旧HIGH且公平配额允许时,直接准备I帧并尝试一次send。
* 严格模式先入队参与业务等级仲裁;仅队满且当前有序阶段满足准入时直接准备,不抢占已编号帧。
* 准入后,已到协议期限时先入HIGH,交由Process接收待处理ACK后再检查期限;其他暂不能准备的情况也入HIGH。
* send后按真实时刻登记进度;若期间跨过ACK/TESTFR的t1,安排立即Process先接收再按原期限判定。
* 确认t1已到且尚未解除时,Process也暂停为HIGH/NORMAL创建新I帧;已有帧及控制发送仍可推进。
* 不增加宽限时间;本地发送和STOP总期限仍在发送推进时检查。
* START受理即激活,已有CON待发时应答入HIGH,实际I帧发送仍排在控制FIFO之后。
* STOP受理即停用并清空待发HIGH,不等待START_CON完成;新应答返回ERROR。
* 后到START成功受理即重新激活并取消旧STOP总计时,已有CON继续按FIFO完成。
* 本项目保留已启用状态下重复START不清理HIGH的约定;重新激活不恢复已经丢弃的HIGH。
* 不等待、不循环发送,并遵守发送重试暂停;无进展时保留当前APDU,由Process/Poll续发,不重复放入HIGH。
* OK已复制到发送缓冲或HIGH,可以复用原文;不承诺已写完或已ACK。无可用提交路径时WAIT,本次未接手。
* 受理新STOPDT_ACT时,尚在HIGH中的应答立即作废,无逐条事件;已有I帧及ACK记录继续排空。
* FATAL可能已写出字节并关闭当前连接,须处理收尾事件;HIGH及直接应答均不转给新连接。
* 所有调用在事件循环线程串行执行;返回后刷新Prepare,及时处理本地续跑、socket及定时变化。
*/
extern IEC104_TcpSubmitResult_t IEC104_TcpServer_Send_Response(
IEC104_TcpServer_t *server, uint64_t generation,
const uint8_t *asdu, uint16_t asdu_length);
/**
* 功能:带凭证的普通应答,与Send_Response采用相同调度。
* 输入参数:server/generation——服务及连接代次;asdu/asdu_length——应答原文及长度。
* 输出参数:ticket——可为NULL,仅最终OK时写入。
* 返回值:OK已接手;WAIT未接手;ERROR非法;FATAL为连接故障。
* 说明:兼容模式直交ticket=0,入HIGH则为非零;严格模式排队及有序队满直交都返回真实非零票据。
* WAIT表示未接手;ticket可NULL,仅接手成功时写入。OK不要求已写完或ACK。
* 调用串行、会话身份、FATAL和等待条件刷新约定同Send_Response;WAIT不保证公平准入。
*/
extern IEC104_TcpSubmitResult_t IEC104_TcpServer_Send_Response_Tracked(
IEC104_TcpServer_t *server, uint64_t generation,
const uint8_t *asdu, uint16_t asdu_length, uint64_t *ticket);
/**
* 功能:只读;允许STOP、断线及Close后查询。0为HANDED,未发出的票据ERROR,历史不确定为CANCELLED。
* 输入参数:server——TCP服务实例。
* ticket——应答交接票据。
* 输出参数:无。
* 返回值:按处理分支返回IEC104_RESPONSE_ERROR、IEC104_RESPONSE_HANDED、IEC104_AsduQueue_Get_Response_State(&server->queue, ticket)、ticket >= server->saved_high_next_sequence ? IEC104_RESPONSE_ERROR : IEC104_RESPONSE_CANCELLED。
* 说明:HANDED只保证交给SendBuffer;Destroy后句柄失效,不可再查询旧票据。
*/
extern IEC104_ResponseState_t IEC104_TcpServer_Get_Response_State(
const IEC104_TcpServer_t *server, uint64_t ticket);
/**
* 功能:带ACK观察的应答确保非零票据,并在首次写socket前关联观察槽。
* 输入参数:server/generation——服务及连接代次;asdu/asdu_length——应答原文及长度。
* 输出参数:ticket——必填,仅最终OK时发布可用于ACK查询的非零票据。
* 返回值:OK已接手;WAIT未接手,含观察槽不足;ERROR非法;FATAL为连接故障。
* 说明:兼容模式强制进入HIGH;严格模式仍先排队,但可使用有序队满直交,调度规则与普通应答相同。
* ticket必须非NULL;仅OK写入并占观察槽,无可用提交路径或观察槽不足返回WAIT且不接手。
* WAIT/ERROR/FATAL保持输出且不遗留观察槽;FATAL仍可能已接手原文,不可据此重交。
* ACKED/LOST结果也占槽,调用方须Release;该接口只观察通信事实,不负责复位等业务授权。
*/
extern IEC104_TcpSubmitResult_t IEC104_TcpServer_Send_Response_Acked(
IEC104_TcpServer_t *server, uint64_t generation,
const uint8_t *asdu, uint16_t asdu_length, uint64_t *ticket);
/**
* 功能:只读查询允许STOP、断线后调用;Close/Release后ERROR。
* 输入参数:server——服务实例;generation/ticket——申请观察时取得的非零代次及票据。
* 输出参数:acked_at_ms——可为NULL,仅状态为ACKED时写入确认时刻。
* 返回值:观察槽保存的ACK状态;参数非法或找不到匹配观察槽时返回ERROR。
* 说明:必须保留提交时的generation和ticket,不能用新连接代次查询旧回执。
* acked_at_ms可NULL,仅ACKED写首次确认时刻,其他状态不改输出,重复ACK不覆盖。
*/
extern IEC104_TcpAckState_t IEC104_TcpServer_Get_Ack_State(
const IEC104_TcpServer_t *server, uint64_t generation, uint64_t ticket, uint64_t *acked_at_ms);
/**
* 功能:查询提交后首次STOP/断开之前的ACK:边界到达前未ACK的QUEUED/SENT永久转为LOST,
* 输入参数:server——TCP服务实例。
* generation——连接代次。
* ticket——应答交接票据。
* acked_at_ms——ACK确认毫秒时刻。
* 输出参数:acked_at_ms——ACK确认毫秒时刻的更新结果。
* 返回值:返回Get_Ack_State(server, generation, ticket, acked_at_ms, 1)的结果。
* 说明:后续START或ACK不恢复;边界前已ACKED的事实和首次时刻保留,应用晚读不改变结果。
* 同一Poll、同一毫秒按协议受理顺序判定,不靠时间戳比较。原Get_Ack_State语义不变。
* 只读且不推进网络;参数、回执寿命和输出规则同Get_Ack_State,仅ACKED写acked_at_ms。
*/
extern IEC104_TcpAckState_t IEC104_TcpServer_Get_Active_Ack_State(
const IEC104_TcpServer_t *server, uint64_t generation, uint64_t ticket, uint64_t *acked_at_ms);
/**
* 功能:仅归还匹配的观察槽;可释放任意阶段,不删除HIGH、不撤回帧,也不改变普通交接票据。
* 输入参数:server——TCP服务实例。
* generation——连接代次。
* ticket——应答交接票据。
* 输出参数:无。
* 返回值:无。
* 说明:无效/已释放的凭证无操作;释放后同一帧的后续交接或ACK不会重新创建观察槽。
*/
extern void IEC104_TcpServer_Release_Ack(
IEC104_TcpServer_t *server, uint64_t generation, uint64_t ticket);
/**
* 功能:按104固定布局的CA及256位类型集合统计/清除尚未编号的NORMAL。
* 输入参数:server——服务实例;common_address——非0且非广播的公共地址。
* type_bitmap——32字节类型位图,按类型编号对应的位筛选。
* 输出参数:count——成功时的匹配数量;error——可选诊断。
* 返回值:OK统计完成;参数或服务状态非法返回相应错误,队列检查失败返回INTERNAL_ERROR。
* 说明:common_address为1..65534,位图全0合法;不解析COT、对象内容或站点注册身份。
* 在线、离线及EOF均可调用;须与Poll/Process串行,不清除SendBuffer或待ACK记录,不解除EOF限制。
* Count只读且不预留,Discard重新完整验证后稳定压缩;失败不改队列或计数输出,error仍填写诊断。
* 成功单位为ASDU条目;没有匹配时输出0。清除仅作用于协议队列,应用自有缓冲由调用方处理。
*/
extern IEC104_TcpResult_t IEC104_TcpServer_Count_Pending_Normal(
const IEC104_TcpServer_t *server, uint16_t common_address, const uint8_t type_bitmap[32],
uint32_t *count, IEC104_TcpError_t *error);
/**
* 功能:丢弃指定公共地址及类型集合中尚未提交为I帧的NORMAL条目。
* 输入参数:server——服务实例;common_address——非0且非广播的公共地址。
* type_bitmap——32字节类型位图,按类型编号对应的位筛选。
* 输出参数:removed——成功时的删除数量;error——可选诊断。
* 返回值:OK删除完成;参数或服务状态非法返回相应错误,队列检查失败返回INTERNAL_ERROR。
* 说明:允许离线清理;不撤销已经分配N(S)的帧,也不改变其后续发送和ACK流程。
*/
extern IEC104_TcpResult_t IEC104_TcpServer_Discard_Pending_Normal(
IEC104_TcpServer_t *server, uint16_t common_address, const uint8_t type_bitmap[32],
uint32_t *removed, IEC104_TcpError_t *error);
/**
* 功能:查询当前主站的IPv4、源端口及连接代次;仅OK写peer,不查询socket、不推进协议。
* 输入参数:server——TCP服务实例。
* peer——对端信息。
* error——错误诊断。
* 输出参数:peer仅OK时完整写出;失败保持原值,error按统一服务结果填写。
* 返回值:OK、INVALID_HANDLE/ARGUMENT/STATE、BUSY或NOT_CONNECTED。
* 说明:server须已Init且当前持有客户端(包括EOF收尾期间);未Init为INVALID_STATE,无客户端为NOT_CONNECTED。
* NULL输出为INVALID_ARGUMENT;无效句柄/重入为INVALID_HANDLE/BUSY;失败不改peer,error可为NULL。
* 结果是可独立保存的副本,不保证以后仍有同一连接;Close_Connection应携带该副本的generation。
* 处理历史事件时使用事件内peer,不可将此处查到的新主站地址归到旧代次。
*/
extern IEC104_TcpResult_t IEC104_TcpServer_Get_Remote_Address(
const IEC104_TcpServer_t *server, IEC104_TcpPeerInfo_t *peer, IEC104_TcpError_t *error);
/**
* 功能:立即结束指定代次的当前主站,保留监听、服务队列和已有业务事件;不执行STOPDT或等待发送/ACK。
* 输入参数:generation——原事件或Get_Remote_Address取得的非零身份,不能用最新代次替换旧操作的目标。
* 输出参数:server——TCP服务实例的更新结果。
* error——错误诊断的更新结果。
* 返回值:OK已断开;INVALID_*、BUSY、NOT_CONNECTED、STALE_GENERATION为操作前拒绝,不改状态。
* INTERNAL_ERROR/QUEUE_STATE表示客户端已收尾,但服务队列异常,调用方须Close服务。
* 说明:generation来自原连接事件或Get_Remote_Address,0为INVALID_ARGUMENT;非零但与当前连接不符为STALE_GENERATION。
* 未Init为INVALID_STATE,无客户端为NOT_CONNECTED;拒绝结果均不关闭连接、不产生新的收尾事件。
* 成功复用断线收尾流程:交付剩余I帧/记录及DISCONNECTED,清空HIGH,保留现存NORMAL并恢复离线缓存。
* 主动断开不新增协议故障,不补造发送完成或ACK;部分/未确认NORMAL恢复后可能重复,由业务处理。
* 队列解除绑定异常返回INTERNAL_ERROR/QUEUE_STATE:客户端已结束,监听保留,须Close服务处理异常。
* 同一事件循环线程串行调用;返回后重新Prepare并移除旧客户端注册,后续Process继续接入新主站。
* 此操作不是封禁;对端可再次连接。Close才关闭整个服务并清空缓存。
*/
extern IEC104_TcpResult_t IEC104_TcpServer_Close_Connection(
IEC104_TcpServer_t *server, uint64_t generation, IEC104_TcpError_t *error);
/**
* 功能:取得端口、诊断、会话及HIGH/NORMAL队列快照,不执行I/O;Create后、Init失败后、Close后均可用。
* 输入参数:server——尚未Destroy的句柄;status——业务提供的非NULL输出存储。
* 输出参数:error始终表达本次查询结果,允许NULL;snapshot中的last_socket_error是历史网络诊断。
* 返回值:OK已写入快照;INVALID_HANDLE/INVALID_ARGUMENT/BUSY时status保持原值。
* 说明:OK时写入status;INVALID_HANDLE/INVALID_ARGUMENT/BUSY保持status不变,但仍填写error。
* 会话/队列分别检查connection_status_valid/asdu_queue_status_valid,无效快照不妨碍读取其他服务状态。
* 队列统计在Init成功后即可读取,断线期间继续有效;Close后无效且清零,不返回历史队列占用。
* accept_paused及剩余时间按查询时刻计算;last_accept_error和连续失败计数用于观察接入异常。
* 所有调用须在同一线程串行执行;查询为常数时间,不消费ASDU或记录,也不改变发送调度。
* 接口失败诊断直接使用该次调用的error,统计数值不能代替提交返回值。
*/
extern IEC104_TcpResult_t IEC104_TcpServer_Get_Status(
const IEC104_TcpServer_t *server, IEC104_TcpServerStatus_t *status, IEC104_TcpError_t *error);
/**
* 功能:OK表示完成收尾或本就未初始化;无效句柄/重入为INVALID_HANDLE/BUSY。
* 输入参数:server——Create取得且尚未Destroy的对象,同一线程串行调用。
* 输出参数:error记录本次接口操作结果,允许NULL;不会把历史网络诊断误作本次失败。
* 返回值:OK完成或本就未初始化,INVALID_HANDLE/BUSY表示无效句柄或非法重入。
* 说明:关闭网络、清空ASDU队列并撤销接入/发送重试期限,保留未读事件及接入历史诊断。
* 不等待业务发送或ACK;重复Close有效。事件读空后可以Init重开,或Destroy归还静态槽。
* 应用负责取消注册和定时器;关闭前已取得的socket及通知不可作为下一次Init的身份使用。
*/
extern IEC104_TcpResult_t IEC104_TcpServer_Close(
IEC104_TcpServer_t *server, IEC104_TcpError_t *error);
/**
* 功能:12级业务优先级与HIGH/NORMAL/IDLE生命周期独立;0使用默认类别,显式值为1..12。
* 输入参数:server——TCP服务实例。
* generation——连接代次。
* reserve——须保留的窗口及记录槽数量。
* priority——优先级。
* 输出参数:无。
* 返回值:按处理分支返回ready、IEC104_TCP_SUBMIT_OK、checked == IEC104_CONNECTION_WAIT ? IEC104_TCP_SUBMIT_WAIT : IEC104_TCP_SUBMIT_ERROR。
* 说明:默认类别:应答INTERROGATION,事件SEQUENCE_EVENT,IDLE为MEASUREMENT。
* 严格模式应答先排队,仅队满时检查有序直交;IDLE准入只被同级或更高等级的可发送业务阻挡。
* 已编号帧、控制义务、启动门禁及协议期限均保持原契约;等级不授予绕过这些条件的权限。
*/
IEC104_TcpSubmitResult_t IEC104_TcpServer_Query_Idle_Send_Priority(
const IEC104_TcpServer_t *server, uint64_t generation, uint16_t reserve,
IEC104_BusinessPriority_t priority);
/**
* 功能:发送入口只尝试交接这一份当前值快照;未准入时不保存、不排队。
* 输入参数:server——TCP服务实例。
* generation——连接代次。
* asdu——ASDU报文。
* asdu_length——ASDU字节长度。
* reserve——须保留的窗口及记录槽数量。
* priority——优先级。
* 输出参数:server——TCP服务实例的更新结果。
* 返回值: 进入Connection后即使返回WAIT也执行共用尾部,交付本次Drive刚推进出的请求。
* 说明:进入Connection后即使返回WAIT也执行共用尾部,交付本次Drive刚推进出的请求。
*/
IEC104_TcpSubmitResult_t IEC104_TcpServer_Send_Idle_Priority(
IEC104_TcpServer_t *server, uint64_t generation,
const uint8_t *asdu, uint16_t asdu_length, uint16_t reserve,
IEC104_BusinessPriority_t priority);
/**
* 功能:按指定业务等级向当前连接提交应答,允许直接交接或进入HIGH队列。
* 输入参数:server/generation——服务及连接代次;asdu/asdu_length——应答原文及长度。
* priority——业务等级,0使用默认等级。
* 输出参数:server——TCP服务实例的更新结果。
* 返回值:OK已接手;WAIT未接手;ERROR非法;FATAL为连接故障。
* 说明:本入口不返回票据或申请ACK观察槽;接手成功不表示TCP写完或对端确认。
*/
IEC104_TcpSubmitResult_t IEC104_TcpServer_Send_Response_Priority(
IEC104_TcpServer_t *server, uint64_t generation,
const uint8_t *asdu, uint16_t asdu_length,
IEC104_BusinessPriority_t priority);
/**
* 功能:带凭证的普通HIGH应答;
* 输入参数:server——TCP服务实例。
* generation——连接代次。
* asdu——ASDU报文。
* asdu_length——ASDU字节长度。
* ticket——应答交接票据。
* priority——优先级。
* 输出参数:server——TCP服务实例的更新结果。
* ticket——应答交接票据的更新结果。
* 返回值:返回Send_Response(server, generation, asdu, asdu_length, ticket, 0, priority, NULL)的结果。
* 说明:复用原部分写入、期限和ACK路径。
*/
IEC104_TcpSubmitResult_t IEC104_TcpServer_Send_Response_Tracked_Priority(
IEC104_TcpServer_t *server, uint64_t generation,
const uint8_t *asdu, uint16_t asdu_length, uint64_t *ticket,
IEC104_BusinessPriority_t priority);
/**
* 功能:为当前连接应答同时申请交接票据与ACK观察槽;仅最终OK发布ticket。
* 输入参数:server——TCP服务实例。
* generation——连接代次。
* asdu——ASDU报文。
* asdu_length——ASDU字节长度。
* ticket——应答交接票据。
* priority——优先级。
* 输出参数:server——TCP服务实例的更新结果。
* ticket——应答交接票据的更新结果。
* 返回值:按处理分支返回IEC104_TCP_SUBMIT_ERROR、IEC104_TCP_SUBMIT_FATAL、IEC104_TCP_SUBMIT_WAIT、result。
* 说明:WAIT包含观察槽耗尽,原文尚未接手;观察槽须由调用方Release,不能把HANDED当作ACKED提前复用业务状态。
*/
IEC104_TcpSubmitResult_t IEC104_TcpServer_Send_Response_Acked_Priority(
IEC104_TcpServer_t *server, uint64_t generation,
const uint8_t *asdu, uint16_t asdu_length, uint64_t *ticket,
IEC104_BusinessPriority_t priority);
/**
* 功能:把主动上报复制到服务级NORMAL队列,不要求已经建立TCP或完成STARTDT。
* 输入参数:server——已Init且未Close的服务;asdu/asdu_length——完整ASDU及长度,不含APCI。
* 输出参数:server——TCP服务实例的更新结果。
* 返回值:OK已复制,WAIT编号窗口暂受阻,ERROR参数或生命周期非法,FATAL服务队列异常。
* 说明:仅本层访问服务队列;有连接时队列使用当前代次,离线时使用0,业务不携带内部绑定身份。
* EOF后的新事件也可入队;全部未编号NORMAL均留给下一连接,离线入队不触发推进空转。
* 启动等待同样只暂停出队;缓存、覆盖和ACK回收继续按原规则工作,不能把启动WAIT传给事件生产者。
*/
IEC104_TcpSubmitResult_t IEC104_TcpServer_Enqueue_Event_Priority(
IEC104_TcpServer_t *server, const uint8_t *asdu, uint16_t asdu_length,
IEC104_BusinessPriority_t priority);
/**
* 功能:只读当前连接的启动门禁,供业务受理时冻结等级;false不证明初始化或总召已完成。
* 输入参数:server——TCP服务实例。
* generation——连接代次。
* 输出参数:无。
* 返回值: false也可能表示身份无效或门禁未启用,不能单凭此查询认定初始化/总召已完成。
* 说明:false也可能表示身份无效或门禁未启用,不能单凭此查询认定初始化/总召已完成。
*/
bool IEC104_TcpServer_Startup_Is_Pending(const IEC104_TcpServer_t *server, uint64_t generation);
/**
* 功能:严格业务轮由应用串行驱动:Begin后维护/收集,再按1..12递增Set,最后End。
* 输入参数:server——服务实例。
* 输出参数:无。
* 返回值:有效且已启用严格模式时为true,实例无效或未初始化时为false。
* 说明:Begin不可嵌套,Set可保持同一等级;应答均可入队,IDLE/队满直交只允许当前等级且一轮最多一帧。
* Begin成功后,即使业务失败也须End;End不主动发送,已交接时须下次Begin后才能选下一新帧。
* 已编号帧、S/U、ACK和期限照常推进;业务轮不创建任务,也不是线程抢占控制。
*/
bool IEC104_TcpServer_Strict_Priority_Enabled(const IEC104_TcpServer_t *server);
/**
* 功能:开始一次不可嵌套的候选收集:撤销上轮让出和未编码候选门限,重置直交额度。
* 输入参数:server——TCP服务实例。
* 输出参数:server——TCP服务实例的更新结果。
* 返回值:按处理分支返回IEC104_TCP_SUBMIT_ERROR、IEC104_TCP_SUBMIT_OK。
* 说明:严格模式的初始NONE阶段只允许排队;本接口不发帧、不清ACK事实,也不开放启动门禁。
*/
IEC104_TcpSubmitResult_t IEC104_TcpServer_Begin_Business_Cycle(IEC104_TcpServer_t *server);
/**
* 功能:数字只许递增或保持,表示更高级生产者已经获得准备机会。
* 输入参数:server——TCP服务实例。
* priority——优先级。
* 输出参数:server——TCP服务实例的更新结果。
* 返回值:按处理分支返回IEC104_TCP_SUBMIT_ERROR、IEC104_TCP_SUBMIT_OK。
* 说明:严格模式的阶段只授权同等级IDLE/队满直交,普通应答仍可按其固有等级入队,不修改旧帧等级。
*/
IEC104_TcpSubmitResult_t IEC104_TcpServer_Set_Business_Priority(IEC104_TcpServer_t *server,
IEC104_BusinessPriority_t priority);
/**
* 功能:结束收集而不主动排空队列;Begin成功后,即使业务步骤失败也必须走到这里。
* 输入参数:server——TCP服务实例。
* 输出参数:server——TCP服务实例的更新结果。
* 返回值:按处理分支返回IEC104_TCP_SUBMIT_ERROR、IEC104_TCP_SUBMIT_OK。
* 说明:严格模式已直交意味着取得帧身份并占用额度,不要求socket已写出;下次选新帧须先Begin。
* 严格模式的未编码候选门限留到下一轮重新收集,避免End与下一次业务准备之间低级业务抢先。
*/
IEC104_TcpSubmitResult_t IEC104_TcpServer_End_Business_Cycle(IEC104_TcpServer_t *server);
/**
* 功能:只读提交准入提示,包含有序队满直交;不预约容量、不推进协议,OK后仍须核对实际提交结果。
* 输入参数:server——TCP服务实例。
* generation——连接代次。
* asdu_length——ASDU字节长度。
* priority——优先级。
* 输出参数:无。
* 返回值:查询不推进协议、不预约资源,实际接手仍以发送返回值为准。
* 说明:未读通知先交应用处理;查询不推进协议、不预约资源,实际接手仍以发送返回值为准。
*/
IEC104_TcpSubmitResult_t IEC104_TcpServer_Query_Response_Priority(const IEC104_TcpServer_t *server,
uint64_t generation, uint16_t asdu_length, IEC104_BusinessPriority_t priority);
/**
* 功能:准备预算用尽但仍立即就绪时发布候选等级,多次发布保留最高等级(数字最小)。
* 输入参数:server——TCP服务实例。
* priority——优先级。
* 输出参数:server——TCP服务实例的更新结果。
* 返回值:按处理分支返回IEC104_TCP_SUBMIT_ERROR、IEC104_TCP_SUBMIT_OK。
* 说明:不创建原文或票据,End后仍阻止更低等级选帧,下一轮Begin清除;不能用于等待外部数据/ACK。
*/
IEC104_TcpSubmitResult_t IEC104_TcpServer_Set_Pending_Business_Priority(IEC104_TcpServer_t *server,
IEC104_BusinessPriority_t priority);
#ifdef __cplusplus
}
#endif
#endif /* IEC104_TCPSERVER_H */