/* * 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 #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 至多一次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 */