/* * 104子站业务入口:内部持有TcpServer,NextEvent自动提供ASDU及原连接的发送接口。 * 服务来自静态池;业务只驱动Slave的事件循环,无需创建TCP对象或手动绑定generation。 * 仅包含本头文件即可使用服务接口、共用ASDU及IEC60870_MasterConnection_Send_*应答接口。 * * 常规顺序:Create -> 统一启动配置/Init -> 循环Poll、NextEvent -> Close -> NextEvent读空 -> Destroy。 * 应用配置入口为IEC104_Startup_Config_Default;本层只接收配置,不依赖业务协调模块。 * 自有事件循环可用Prepare/应用等待/Process替代Poll;两种方式使用同一套底层调度。 * 处理I_FRAME前检查asdu_result==IEC60870_ASDU_OK,再通过&event.connection提交业务应答。 * 主动上报由Enqueue_Event提交;NextEvent不自动执行请求、确认或终止业务。 * 应用未接手的I帧可在当前事件处理时交给Reject_Request,沿普通应答路径回否定回显。 * * 带error参数的接口允许error为NULL;非NULL时完整填写本次结果、阶段和网络错误。 * 服务结果须比较IEC104_TCP_OK;事件结果须比较IEC104_TCP_EVENT_READY,不能混用真假判断。 * 所有操作在同一事件循环线程串行执行,Create/Destroy也须跨服务串行。 */ #ifndef IEC104_SLAVE_H #define IEC104_SLAVE_H #include "IEC60870_Slave.h" #include "IEC104_TcpTypes.h" #ifdef __cplusplus extern "C" { #endif /* 不透明的子站句柄:完整结构只在IEC104_Slave.c定义,业务不能访问或分配内部成员。 * Slave与TcpServer是两个分别管理的对象;这里是持有关系,不可把两种句柄互相强转。 */ typedef struct IEC104_Slave IEC104_Slave_t; /* 复用TCP监听和协议配置的值类型,不暴露TcpServer的对象布局或操作接口。 */ typedef IEC104_TcpServerConfig_t IEC104_SlaveConfig_t; /* 共用逻辑站点:调用方提供零初始化、固定地址的存储,Add后直到Is_Reusable为true均须存活。 * 字段仅供库维护,禁止直接改写、复制、清零或搬移已注册节点;不拥有context指向的业务数据。 * 同一Slave按CA唯一,多个Slave可分别注册相同CA;节点本身只能属于一个Slave。 * 站点不分配socket、发送队列或点表,IOA及点值仍由context对应的应用管理。 */ typedef struct IEC104_Station { struct IEC104_Station *_next; /* 注册顺序链,也保留尚不能回收的已删除节点。 */ IEC104_Slave_t *_owner; /* 回收后才清NULL;Remove成功不一定立即解除所有权。 */ void *_context; /* 调用方业务上下文,须与节点一起保留至可复用。 */ uint64_t _id; /* 本次注册的唯一编号;同CA重新注册得到新编号。 */ uint32_t _users; /* 显式Acquire引用数;活动快照另由Slave统一保护。 */ uint16_t _common_address; /* ASDU公共地址,不是点的IOA或连接编号。 */ bool _registered; /* 是否参与新请求的CA路由,独立于节点是否仍被引用。 */ /* 可选启动同步的逐站进度,不保存ASDU/点值;只有下方Startup接口可修改。 * owner为总召模块实例号,request区分其请求;activation区分同TCP的STOP/START。 * 新轮由Begin覆盖旧元数据,查询先匹配轮次,因此无需在每次断线遍历清零全部站点。 */ uint64_t _startup_activation, _startup_owner, _startup_request, _startup_ticket; bool _startup_completed; /* 已登记COMPLETED及其票据;票据可能仍PENDING,不能单独据此放行。 */ } IEC104_Station_t; /* 跨循环遍历的轻量快照,仅固定注册编号上界,不复制点表/点值、不阻止增删。 * 零初始化并保持地址不变,Begin/End配对;内部字段只读,活动期间禁止复制或搬移。 */ typedef struct IEC104_StationSnapshot { IEC104_Slave_t *_owner; /* Begin至End期间保护所属服务的退役节点。 */ IEC104_Station_t *_next; /* 下次扫描位置;即使该节点被删除也不能提前回收。 */ uint64_t _last_id; /* Begin时的注册编号上界,排除后来新增或同CA替换的节点。 */ const struct IEC104_StationSnapshot *_self; /* 校验地址未变,拒绝活动快照的副本。 */ } IEC104_StationSnapshot_t; /* 站点操作结果,与TCP发送/网络错误分开;须显式比较OK。 */ typedef enum { IEC104_STATION_OK = 0, IEC104_STATION_INVALID_ARGUMENT, IEC104_STATION_DUPLICATE_CA, IEC104_STATION_ALREADY_REGISTERED, IEC104_STATION_NOT_FOUND, IEC104_STATION_BUSY, IEC104_STATION_LIMIT } IEC104_StationResult_t; /** * 功能:注册到服务末尾;CA须1..65534,0和广播65535不能成为站点。context允许NULL。 * 输入参数:self——本模块实例。 * station——逻辑站点。 * common_address——ASDU公共地址。 * context——调用方上下文。 * 输出参数:station——逻辑站点的更新结果。 * 返回值:按处理分支返回IEC104_STATION_INVALID_ARGUMENT、IEC104_STATION_ALREADY_REGISTERED、IEC104_STATION_BUSY、IEC104_STATION_LIMIT、IEC104_STATION_DUPLICATE_CA、IEC104_STATION_OK。 * 说明:无固定站点池上限、无堆分配;容量取决于应用提供的节点与实际RAM。 * 重复CA/已注册节点/站点表锁定时失败且不改变任何节点。所有操作与Slave事件循环串行。 */ IEC104_StationResult_t IEC104_Slave_Add_Station(IEC104_Slave_t *self, IEC104_Station_t *station, uint16_t common_address, void *context); /** * 功能:立即从CA查找/普通遍历中移除;已有引用和快照延迟回收节点,不中断已接手业务。 * 输入参数:self——本模块实例。 * station——逻辑站点。 * 输出参数:station——逻辑站点的更新结果。 * 返回值:按处理分支返回IEC104_STATION_INVALID_ARGUMENT、IEC104_STATION_NOT_FOUND、IEC104_STATION_BUSY、IEC104_STATION_OK。 * 说明:OK仅表示已移除,Is_Reusable为true后才可释放/复用节点和context;不撤回已接手ASDU。 * 显式Lock仍返回BUSY;重复删除返回NOT_FOUND。已移除CA可由另一个节点重新注册。 */ IEC104_StationResult_t IEC104_Slave_Remove_Station(IEC104_Slave_t *self, IEC104_Station_t *station); /** * 功能:按CA查找借用节点;无效服务、未知CA、0及65535返回NULL。不会自动接受或应答任何请求。 * 输入参数:self——本模块实例。 * common_address——ASDU公共地址。 * 输出参数:无。 * 返回值:返回借用指针,不自动增加引用或决定广播范围。 * 说明:跨事件循环保存节点前须Acquire;短时查找后直接使用可不占用,期间不得删除节点。 * 广播是否允许、涉及哪些站、如何应答由各业务决定,不能把65535当作某个默认站。 */ IEC104_Station_t *IEC104_Slave_Get_Station(const IEC104_Slave_t *self, uint16_t common_address); /** * 功能:不另存可失配的数量; * 输入参数:self——本模块实例。 * 输出参数:无。 * 返回值:按处理分支返回0U、count。 * 说明:上限仅由可注册CA和调用方存储决定。 */ size_t IEC104_Slave_Get_Station_Count(const IEC104_Slave_t *self); /** * 功能:注册编号在同一Slave槽内不复用;可找到仍被引用保留的已删除节点,避免按CA误取替代站点。 * 输入参数:self——本模块实例。 * station_id——站点编号。 * 输出参数:无。 * 返回值: 与按CA查找一样只返回借用指针; * 说明:与按CA查找一样只返回借用指针;需要独立持有时仍须Acquire。 */ IEC104_Station_t *IEC104_Slave_Get_Station_By_Id(const IEC104_Slave_t *self, uint64_t station_id); /** * 功能:取得站点在所属服务中的身份编号。 * 输入参数:station——仍由服务持有的站点对象。 * 输出参数:无。 * 返回值:站点编号;空指针或已解除服务归属时返回0。 * 说明:有归属不等于仍在注册表中,是否注册须另查Is_Registered。 */ uint64_t IEC104_Station_Get_Id(const IEC104_Station_t *station); /** * 功能:查询站点是否仍归属于服务且处于已注册状态。 * 输入参数:station——待查询的站点对象。 * 输出参数:无。 * 返回值:有服务归属且注册标志有效时为true,空指针或其他状态为false。 * 说明:只读取状态,不借用对象或延长其存储寿命。 */ bool IEC104_Station_Is_Registered(const IEC104_Station_t *station); /** * 功能:判断站点存储是否已完全解除服务归属,可用于后续注册。 * 输入参数:station——待复用的站点对象。 * 输出参数:无。 * 返回值:对象非空且无所属服务时为true,否则为false。 * 说明:注销后若仍有借用,服务归属尚未释放,不能仅凭未注册状态复用该存储。 */ bool IEC104_Station_Is_Reusable(const IEC104_Station_t *station); /** * 功能:Begin记录当前注册上界;Next按注册顺序借用节点,跳过已删除节点,不包含后来新增节点。 * 输入参数:self——本模块实例。 * snapshot——快照。 * 输出参数:snapshot——快照的更新结果。 * 返回值:按处理分支返回IEC104_STATION_INVALID_ARGUMENT、IEC104_STATION_LIMIT、IEC104_STATION_OK。 * 说明:即使Next返回NULL也须End。快照期间退役节点的存储仍须保留;不锁点值,不做堆分配。 * Next返回值跨End使用前须Acquire;这些接口与所有站点操作在同一事件循环串行调用。 */ IEC104_StationResult_t IEC104_Slave_StationSnapshot_Begin(IEC104_Slave_t *self, IEC104_StationSnapshot_t *snapshot); /** * 功能:先推进游标再返回当前仍注册的节点;删除的未来节点跳过,新增节点不纳入。 * 输入参数:snapshot——快照。 * 输出参数:snapshot——快照的更新结果。 * 返回值:先推进游标再返回当前仍注册的节点; * 返回NULL只表示遍历完毕,仍须End归还保护。 * 说明:快照保护节点存储但不自动Acquire;返回NULL只表示遍历完毕,仍须End归还保护。 */ IEC104_Station_t *IEC104_Slave_StationSnapshot_Next(IEC104_StationSnapshot_t *snapshot); /** * 功能:与Begin配对一次;最后一个快照结束会尝试回收所有无引用的退役节点。 * 输入参数:snapshot——快照。 * 输出参数:snapshot——快照的更新结果。 * 返回值: 业务若要跨End继续使用Next返回的节点,必须提前Acquire。 * 说明:业务若要跨End继续使用Next返回的节点,必须提前Acquire。 */ IEC104_StationResult_t IEC104_Slave_StationSnapshot_End(IEC104_StationSnapshot_t *snapshot); /** * 功能:按注册顺序遍历,current为NULL时取首站;非法/外来节点或末尾返回NULL。 * 输入参数:self——本模块实例。 * current——当前节点。 * 输出参数:无。 * 返回值:按处理分支返回NULL、station。 * 说明:短时串行遍历不修改站点表;跨循环保留游标或要求固定站点集合时须配对Lock/Unlock。 * Lock可嵌套,阻止Add/Remove及Slave_Destroy,允许查找和Acquire/Release;不锁点值或网络。 * 最后一次Unlock后所有未Acquire的借用节点/游标均不可继续依赖旧集合。 */ IEC104_Station_t *IEC104_Slave_Next_Station(const IEC104_Slave_t *self, const IEC104_Station_t *current); /** * 功能:固定遍历集合,不锁点值; * 输入参数:self——本模块实例。 * 输出参数:无。 * 返回值:按处理分支返回IEC104_STATION_INVALID_ARGUMENT、IEC104_STATION_LIMIT、IEC104_STATION_OK。 * 说明:串行事件循环中的嵌套借用必须显式配对。 */ IEC104_StationResult_t IEC104_Slave_Lock_Stations(IEC104_Slave_t *self); /** * 功能:归还一次站点集合借用,减少站点注册变更的保护计数。 * 输入参数:self——持有借用锁的从站服务。 * 输出参数:无。 * 返回值:OK已归还;INVALID_ARGUMENT为实例无效或没有可归还的锁。 * 说明:须与Lock_Stations配对;这是集合借用计数,不是线程互斥锁,也不锁定站点业务数据。 */ IEC104_StationResult_t IEC104_Slave_Unlock_Stations(IEC104_Slave_t *self); /** * 功能:业务持有引用:每次成功Acquire必须配对一次Release,计数溢出返回LIMIT、零计数释放报错。 * 输入参数:self——本模块实例。 * station——逻辑站点。 * 输出参数:无。 * 返回值:按处理分支返回IEC104_STATION_INVALID_ARGUMENT、IEC104_STATION_NOT_FOUND、IEC104_STATION_LIMIT、IEC104_STATION_OK。 * 说明:只占用指定站点,其他站仍可增删;不能用一个业务的Release替另一个业务归还引用。 * 异步业务须一直持有到延迟事件和清理完成;引用不代表原连接仍有效,仍须Check_Request。 */ IEC104_StationResult_t IEC104_Slave_Acquire_Station(IEC104_Slave_t *self, IEC104_Station_t *station); /** * 功能:归还自己的引用后可能立即摘链清零; * 输入参数:self——本模块实例。 * station——逻辑站点。 * 输出参数:无。 * 返回值:按处理分支返回IEC104_STATION_INVALID_ARGUMENT、IEC104_STATION_NOT_FOUND、IEC104_STATION_OK。 * 说明:没有其他寿命保护时,不再使用该节点或context。 */ IEC104_StationResult_t IEC104_Slave_Release_Station(IEC104_Slave_t *self, IEC104_Station_t *station); /** * 功能:station须为NULL或仍有效的调用方节点;已回收/NULL时返回0或NULL,退役但被引用时仍可读取。 * 输入参数:station——站点对象。 * 输出参数:无。 * 返回值:仍有服务归属时返回公共地址;空指针或无归属时返回0。 * 说明:context只读出指针,库不读取其内容,也不规定点表、权限或各业务状态的布局。 */ uint16_t IEC104_Station_Get_Common_Address(const IEC104_Station_t *station); /** * 功能:取得站点注册时绑定的业务上下文。 * 输入参数:station——站点对象。 * 输出参数:无。 * 返回值:仍有服务归属时返回上下文指针;空指针或无归属时返回NULL。 * 说明:上下文可以本来就是NULL;返回指针不转移所有权,也不延长业务存储寿命。 */ void *IEC104_Station_Get_Context(const IEC104_Station_t *station); /* transport保存原通知;I_FRAME且asdu_result为OK时,asdu和connection可直接使用。 * asdu借用本对象transport中的字节;确认/终止会原地修改这份副本的COT/P/N。 * 具体对象、地址及业务权限仍须由应用校验,ASDU_OK不代表允许执行请求。 * NextEvent为EMPTY/ERROR时整个输出保持不变;READY会替换上次事件。 * 使用期间地址必须稳定。延迟处理可直接读入任务存储,或使用Copy_Event复制; * 禁止用赋值/memcpy搬移含自引用的事件。一个事件的多个应答沿用同一connection。 * transport元数据、connection及以下内部字段只读;用ASDU接口修改报文。 * 内部字段保存原服务实例和原代次,重连、重新Init及静态槽复用均不重新绑定旧请求。 */ typedef struct { IEC104_TcpEvent_t transport; /* 原通知的独立副本;只有type对应的data成员有效。 */ IEC60870_Asdu_t asdu; /* 借用本事件I帧中APCI之后的字节;仅asdu_result为OK时可用。 */ IEC60870_AsduResult_t asdu_result; /* 非I_FRAME为UNSUPPORTED;异常原文为ERROR。 */ IEC60870_MasterConnection_t connection; /* 仅ASDU_OK的I_FRAME提供发送函数。 */ IEC104_Slave_t *_owner; /* 以下字段由模块维护:产生本事件的Slave地址。 */ uint64_t _owner_serial; /* 原Slave_Create编号,防止静态槽销毁重用后旧应答串入新服务。 */ uint64_t _generation; /* 原TCP会话代次,防止断线重连后把旧应答发给新主站。 */ IEC104_TcpSubmitResult_t _last_submit_result; /* 此接口最近的提交结果,不表示实时发送/ACK状态。 */ } IEC104_SlaveEvent_t; /* Get_Event_Identity校验后给出的来源身份,可按值保存,不借用事件原文或自引用视图。 * 三个字段只读,调用Check_Request时原样传回;slave只用于身份比较,不延长服务寿命。 * 不同Slave实例的局部编号可能相同,不能丢弃slave而只比较两个编号。 */ typedef struct { const IEC104_Slave_t *slave; /* 产生事件的服务句柄。 */ uint64_t instance_id; /* 区分该服务静态槽的历次使用。 */ uint64_t generation; /* 原TCP会话代次;断线重连后旧身份不会重新绑定。 */ } IEC104_SlaveEventIdentity_t; /* 可按值保存的单帧ACK回执;ticket非零,必须按原服务、实例、代次查询和释放。 * 复制回执不会增加观察槽或引用数;任意副本Release后,所有副本均失效。 */ typedef struct { IEC104_SlaveEventIdentity_t identity; uint64_t ticket; } IEC104_SlaveAckReceipt_t; typedef enum { IEC104_SLAVE_ACK_ERROR = -1, /* 参数/身份/回执无效,或已Release、服务已Close。 */ IEC104_SLAVE_ACK_QUEUED = 0, /* HIGH中等待交接。 */ IEC104_SLAVE_ACK_SENT = 1, /* SendBuffer接手,尚未有效ACK;可能尚未写完。 */ IEC104_SLAVE_ACK_ACKED = 2, /* 有效累计N(R)已覆盖,首次ACK时刻保持不变。 */ IEC104_SLAVE_ACK_LOST = 3 /* 交接前取消或断开时未ACK;Active查询另含首次STOP前未ACK。 */ } IEC104_SlaveAckState_t; /* 此类别仅指监视方向CP56类型30..40,不包含所有带时标命令,也不包含CP24类型。 */ typedef enum { IEC104_SLAVE_EVENTS_TIME_TAGGED = 1 } IEC104_SlaveEventClass_t; /* 业务请求推进检查,与发送容量/ACK状态无关;须按枚举值显式分支。 */ typedef enum { IEC104_SLAVE_REQUEST_ERROR = -1, /* 非法服务/NULL身份,或服务状态查询失败。 */ IEC104_SLAVE_REQUEST_STALE = 0, /* 身份未绑定、服务/代次不符,或原连接不再处于激活状态。 */ IEC104_SLAVE_REQUEST_WAIT_EVENTS = 1, /* 先按FIFO处理Slave通知,再检查请求,防止漏过STOP/撤销。 */ IEC104_SLAVE_REQUEST_READY = 2 /* 原请求会话仍可处理;实际发送是否接手以发送接口为准。 */ } IEC104_SlaveRequestState_t; /** * 功能:从静态池取得子站及其私有TCP服务,无malloc、无网络操作;容量不足返回NULL。 * 输入参数:无。 * 输出参数:无。 * 返回值:成功返回不透明句柄;任一池无可用槽或身份编号耗尽时返回NULL。 * 说明:容量由IEC104_TCP_SERVER_CAPACITY决定,与直接使用TcpServer共享底层名额。 * 成功后配对Close、读空事件、Destroy;业务不得自行分配、复制或free服务对象。 */ IEC104_Slave_t *IEC104_Slave_Create(void); /** * 功能:只销毁已关闭且事件读空的服务;失败保留句柄。成功后所有旧句柄失效。 * 输入参数:self——Create取得且未Destroy的句柄;error——可选的本次调用诊断。 * 输出参数:self——本模块实例的更新结果。 * error——错误诊断的更新结果。 * 返回值:OK时句柄失效;运行中为INVALID_STATE,通知未读空为EVENTS_PENDING,失败保留对象。 * 说明:未Init或Init失败后也可直接销毁;运行中为INVALID_STATE,未读事件为EVENTS_PENDING。 * 站点须Remove并归还引用,快照须End,站点表锁须Unlock,否则INVALID_STATE;Close/Init保留站点。 * 旧事件仍可读其原文字节,但发送接口不能用于新的服务实例。error允许NULL。 */ IEC104_TcpResult_t IEC104_Slave_Destroy(IEC104_Slave_t *self, IEC104_TcpError_t *error); /** * 功能:初始化网络和监听,复制config;成功后用Prepare/Process或Poll驱动。 * 输入参数:self——有效Slave句柄;config——本次监听和协议配置,底层复制后使用。 * 输出参数:error——本次诊断,允许NULL;底层返回的阶段和网络错误保持原样。 * 返回值:OK已监听,其他结果区分参数、配置、生命周期或网络失败。 * 说明:初始化成功只表示可以接入主站;TCP连接及104激活状态分别由事件/状态查询反映。 * 失败不会销毁句柄;再次Init要求服务已Close且旧事件读空。 */ IEC104_TcpResult_t IEC104_Slave_Init(IEC104_Slave_t *self, const IEC104_SlaveConfig_t *config, IEC104_TcpError_t *error); /** * 功能:只读查询调度条件。need_process或pending_event_count非零时不得阻塞等待。 * 输入参数:self——已Init的服务;info——非NULL快照存储;error——可选诊断。 * 输出参数:info——查询信息的更新结果。 * error——错误诊断的更新结果。 * 返回值:OK时写出info;失败保持info不变,不进行收发或协议推进。 * 说明:socket只供事件循环注册;业务不得直接recv/send/close。 */ IEC104_TcpResult_t IEC104_Slave_Prepare(const IEC104_Slave_t *self, IEC104_TcpWaitInfo_t *info, IEC104_TcpError_t *error); /** * 功能:有界处理一批socket/定时就绪,不等待;ready的service_token及socket token来自原注册。 * 输入参数:self——已Init的服务;ready——必填就绪批次,身份来自对应Prepare/注册快照。 * 输出参数:error——可选诊断;返回值与TcpServer_Process一致,OK也包括没有进展。 * 返回值:返回值与TcpServer_Process一致,OK也包括没有进展。 * 返回后消费NextEvent,再Prepare更新关注集合。 * 说明:返回后读取NextEvent并重新Prepare;旧通知的身份不可替换成当前token。 */ IEC104_TcpResult_t IEC104_Slave_Process(IEC104_Slave_t *self, const IEC104_TcpReady_t *ready, IEC104_TcpError_t *error); /** * 功能:独立循环入口:组合准备、最多等待max_wait_ms和有界推进;0不等待。 * 输入参数:self——已Init的服务;max_wait_ms——本轮网络等待上限,0不等待;error可为NULL。 * 输出参数:self——本模块实例的更新结果。 * error——错误诊断的更新结果。 * 返回值:OK表示服务可继续;客户端断线不一定使本函数失败,须读取NextEvent。 * 说明:有待消费通知时不阻塞等待,调用方仍须读取NextEvent;等待上限不等于整个调用的耗时上限。 */ IEC104_TcpResult_t IEC104_Slave_Poll(IEC104_Slave_t *self, uint32_t max_wait_ms, IEC104_TcpError_t *error); /** * 功能:按原FIFO取一个事件,自动绑定原服务/代次并创建I帧的可写ASDU视图。 * 输入参数:self——有效句柄,Close后仍可读取;event——地址稳定的非NULL输出存储。 * 输出参数:self——本模块实例的更新结果。 * event——事件的更新结果。 * 返回值:READY替换整个event;EMPTY/ERROR保持上次事件及其视图不变。 * 说明:READY交付事件;EMPTY/ERROR保持输出。不执行业务、不自动确认、不进行I/O。 * I_FRAME须检查asdu_result;解析失败仍交付原事件,connection为空,不丢弃诊断原文。 */ IEC104_TcpEventResult_t IEC104_Slave_NextEvent(IEC104_Slave_t *self, IEC104_SlaveEvent_t *event); /** * 功能:把事件及原文字节复制到稳定的任务存储,重建目标ASDU与接口的自引用。 * 输入参数:source——NextEvent或本函数产生的有效事件;destination——目标事件存储。 * 输出参数:destination——目标存储的更新结果。 * 返回值:true已复制或源/目标为同一合法对象;false校验失败且不修改目标。 * 说明:不改变原服务实例/代次,不提交或重发任何报文;源和目标相同时只校验。 * true成功;false为NULL、非法事件/视图或未经本函数修复的按值副本,目标保持原值。 */ bool IEC104_Slave_Copy_Event(IEC104_SlaveEvent_t *destination, const IEC104_SlaveEvent_t *source); /** * 功能:校验event的服务归属、身份字段和有效I帧视图,再写出来源身份;失败不改identity。 * 输入参数:self为所属服务;event为原事件或Copy_Event副本;identity为非NULL输出。 * 输出参数:identity——原会话身份的更新结果。 * 返回值:true写出身份;false为非法来源/布局/视图或参数,保持输出不变。 * 说明:self须为当前有效服务,event须由NextEvent/Copy_Event取得;identity为非NULL输出。 * 允许同一服务的历史连接事件,不要求原连接仍在线,便于按FIFO处理断开/重连通知。 * 其他服务、已销毁复用实例及未经Copy_Event修复的I帧副本返回false;不进行I/O或消费事件。 */ bool IEC104_Slave_Get_Event_Identity(const IEC104_Slave_t *self, const IEC104_SlaveEvent_t *event, IEC104_SlaveEventIdentity_t *identity); /** * 功能:检查由Get_Event_Identity取得的请求身份是否仍允许业务推进,不发送、不消费通知。 * 输入参数:identity为Get_Event_Identity的只读结果,允许零初始化表示尚未绑定会话。 * 输出参数:无。 * 返回值:ERROR为参数/查询失败;WAIT_EVENTS优先于会话判断;STALE为原身份不再可用;READY可继续。 * 说明:服务查询成功后,未读通知优先返回WAIT_EVENTS;读空后再判断来源、代次和激活状态。 * 零初始化身份在通知读空后返回STALE,可用于业务尚未绑定会话时的检查。 * READY不预留发送资源,不保证窗口/队列有空间;也不检查总召等业务自己的阶段或期限。 */ IEC104_SlaveRequestState_t IEC104_Slave_Check_Request(const IEC104_Slave_t *self, const IEC104_SlaveEventIdentity_t *identity); /** * 功能:完成本轮应用启动流程后放行NORMAL/IDLE。identity及activation_id必须来自同一活动轮次。 * 输入参数:self——本模块实例。 * identity——原会话身份。 * activation_id——START活动轮次编号。 * 输出参数:self——本模块实例的更新结果。 * 返回值:按处理分支返回ready、IEC104_TcpServer_Release_Startup(self->server, identity->generation, activation_id)。 * 说明:不自动判断初始化/总召完成;完整通知FIFO未读先WAIT,旧实例/代次/启动轮次为ERROR。 * OK本轮开放且允许幂等,FATAL为队列异常。NORMAL入队和HIGH应答不受本门禁阻塞。 * 统一配置入口开启门禁;每次实际START都须重新完成业务判定,主站未总召时不自动超时放行。 * 放行不清除NORMAL原文,不等于主站已收到;已发送事件仍沿用既有ACK回收规则。 */ IEC104_TcpSubmitResult_t IEC104_Slave_Release_Startup(IEC104_Slave_t *self, const IEC104_SlaveEventIdentity_t *identity, uint64_t activation_id); /** * 功能:可选的逐站启动同步记账;不判断Type/QOI/TEST,应用仅为本轮已批准的真实全站总召调用。 * 输入参数:self——本模块实例。 * identity——原会话身份。 * activation_id——START活动轮次编号。 * station_id——站点编号。 * owner_id——业务所有者编号。 * request_id——请求编号。 * 输出参数:无。 * 返回值:按处理分支返回ready、IEC104_TCP_SUBMIT_ERROR、IEC104_TCP_SUBMIT_OK。 * 说明:Begin记录业务实例owner_id与request_id;同站新请求替换尚未完成的尝试,已完成站保持完成。 * Complete仅匹配原站注册号、轮次、owner/request,保存成功结束帧的交接票据;0表示直接交接。 * 只传FINISHED(COMPLETED)的原票据;其他事件的0票据不能当作成功证据。重复Complete不替换票据。 * OK已记录;WAIT要求先分派通知;ERROR身份/阶段/请求不匹配。不会发送或自动开放门禁。 * 应用在启动流程中Lock_Stations冻结所需站集合,所有退出路径须Unlock;不锁点值。 * Query在非空的全部已注册站本轮完成且票据HANDED时返回OK,缺站/未完成/尚PENDING为WAIT; * CANCELLED或ERROR票据为ERROR。OK不是主站ACK;随后仍须Release_Startup校验当前轮次。 * 三个辅助接口均要求配置已开启且本轮仍闭锁;它们不负责创建总召、不持有额外站点引用。 */ IEC104_TcpSubmitResult_t IEC104_Slave_Startup_Begin_Station(IEC104_Slave_t *self, const IEC104_SlaveEventIdentity_t *identity, uint64_t activation_id, uint64_t station_id, uint64_t owner_id, uint64_t request_id); /** * 功能:仅为成功FINISHED登记最终应答的票据,不在这里把“已提交”提升为“已交接”。 * 输入参数:self——本模块实例。 * identity——原会话身份。 * activation_id——START活动轮次编号。 * station_id——站点编号。 * owner_id——业务所有者编号。 * request_id——请求编号。 * completion_ticket——完成应答票据。 * 输出参数:无。 * 返回值:按处理分支返回ready、IEC104_TCP_SUBMIT_ERROR、IEC104_TCP_SUBMIT_OK。 * 说明:completion_ticket=0可表示直接HANDED,但本函数不解析事件,调用方必须先核对COMPLETED。 * 即使已记录完成也先验证owner/request;幂等调用保留首张票据,不能以新票据替换旧PENDING。 */ IEC104_TcpSubmitResult_t IEC104_Slave_Startup_Complete_Station(IEC104_Slave_t *self, const IEC104_SlaveEventIdentity_t *identity, uint64_t activation_id, uint64_t station_id, uint64_t owner_id, uint64_t request_id, uint64_t completion_ticket); /** * 功能:只读汇总当前注册集合:每站须属于本轮、有成功完成记录,且最终应答已经HANDED。 * 输入参数:self——本模块实例。 * identity——原会话身份。 * activation_id——START活动轮次编号。 * 输出参数:无。 * 返回值: 未完成或PENDING返回WAIT,取消/错误票据返回ERROR; * 说明:调用方用Lock_Stations保持集合稳定;广播和逐CA总召均落到同一份逐站元数据。 * 未完成或PENDING返回WAIT,取消/错误票据返回ERROR;均不清进度、不发送、不自动解除门禁。 * HANDED保证结束帧在后续NORMAL选帧之前进入发送器,不证明写完或主站ACK。 */ IEC104_TcpSubmitResult_t IEC104_Slave_Query_Startup_Stations(IEC104_Slave_t *self, const IEC104_SlaveEventIdentity_t *identity, uint64_t activation_id); /** * 功能:当前值快照的空闲直发;每次调用都核对归属及完整通知FIFO,未读通知返回WAIT。 * 输入参数:self/identity——从站服务及事件身份;reserve——提交后须保留的窗口和记录槽数量。 * 输出参数:无。 * 返回值:OK当前可发送;WAIT暂受通知、协议或资源限制;ERROR为身份、参数或状态非法。 * 说明:不进入HIGH/NORMAL,不跨STOP/重连补发;STOP受理后不再编号,已编号的当前帧仍按既有流程收尾。 * Query只读且不预留资源;Send重新检查准入,WAIT未接手,下次须重新取当前值。 * Send的OK已复制原文,不表示已写完或已ACK;ERROR身份/参数/配置非法,FATAL须处理收尾通知。 * reserve同时保留窗口与记录槽;>=1且在途只有IDLE时,当前帧写完后单帧应答不因IDLE占槽而等ACK。 */ IEC104_TcpSubmitResult_t IEC104_Slave_Query_Idle_Send(const IEC104_Slave_t *self, const IEC104_SlaveEventIdentity_t *identity, uint16_t reserve); /** * 功能:使用默认业务等级尝试直接发送一帧空闲业务ASDU。 * 输入参数:self/identity——从站服务及事件身份;asdu——待提交原文。 * reserve——提交后须保留的窗口和记录槽数量。 * 输出参数:self——本模块实例的更新结果。 * 返回值:OK已接手;WAIT尚未接手;ERROR非法;FATAL为连接故障。 * 说明:WAIT不把原文转入队列;待分派通知优先,实际发送仍遵循底层部分写入流程。 */ IEC104_TcpSubmitResult_t IEC104_Slave_Send_Idle(IEC104_Slave_t *self, const IEC104_SlaveEventIdentity_t *identity, const IEC60870_Asdu_t *asdu, uint16_t reserve); /** * 功能:查询配置的窗口及记录容量,不依赖客户端,不返回即时余量;失败时capacity保持不变。 * 输入参数:self——本模块实例。 * capacity——存储容量。 * error——错误诊断。 * 输出参数:capacity——存储容量的更新结果。 * error——错误诊断的更新结果。 * 返回值:按处理分支返回Slave_Error(IEC104_TCP_INVALID_HANDLE, error)、IEC104_TcpServer_Get_Send_Capacity(self->server, capacity, error)。 * 说明:未Init或Close后INVALID_STATE;历史ACTIVATED仍可在Close后被应用读出,不应据此计reserve配置错误。 */ IEC104_TcpResult_t IEC104_Slave_Get_Send_Capacity(const IEC104_Slave_t *self, IEC104_TcpSendCapacity_t *capacity, IEC104_TcpError_t *error); /** * 功能:查询该事件连接最近一次发送的OK/WAIT/ERROR/FATAL;空或无效接口返回ERROR。 * 输入参数:connection——event.connection的地址;不是Slave句柄,也不是底层socket。 * 输出参数:无。 * 返回值:OK/WAIT/ERROR/FATAL;尚未发送或接口绑定无效时返回ERROR。 * 说明:connection传&event.connection;结果仅在该接口提交时更新,不随Poll或ACK自动改变。 * true/OK为已接手,不代表已写完或已ACK;仅WAIT可保存原事件/ASDU等待重试。 * 确认/终止提交失败也不恢复已修改的字段;FATAL可能已写出字节。 */ IEC104_TcpSubmitResult_t IEC104_Slave_Get_Last_Submit_Result( const IEC60870_MasterConnection_t *connection); /** * 功能:使用原事件连接提交HIGH应答并返回交接凭证,沿用当前配置的业务调度。 * 输入参数:connection——连接对象。 * asdu——ASDU报文。 * ticket——应答交接票据。 * 输出参数:ticket——应答交接票据的更新结果。 * 返回值:返回Submit_ASDU(connection, asdu, ticket)的结果。 * 说明:OK已接手,不能重交;WAIT未接手,允许重取当前值后再试。 * ERROR为参数/身份/阶段非法,FATAL可能已发出字节;均不可当作背压盲目重试。 * 先处理Slave通知;本调用与网络推进串行,不保证HIGH与NORMAL之间的点值先后。 * 同时更新Get_Last_Submit_Result;不改变普通MasterConnection_Send_*的排队行为。 * ticket可NULL,仅接手成功写入;兼容模式直交为0,严格模式排队或直交均为非零可查询票据。 */ IEC104_TcpSubmitResult_t IEC104_Slave_Send_ASDU_Tracked( IEC60870_MasterConnection_t *connection, const IEC60870_Asdu_t *asdu, uint64_t *ticket); /** * 功能:按Get_Event_Identity保存的原身份提交独立ASDU,无需长期保存完整SlaveEvent。 * 输入参数:self/identity——从站服务及请求身份;asdu——待提交的应答ASDU。 * 输出参数:self——本模块实例的更新结果。 * 返回值:OK已复制接手;WAIT未接手;ERROR为身份或ASDU非法;FATAL为连接故障。 * 说明:identity可按值保存;三个字段保持原值,self必须是原服务,旧实例/旧代次不能发送。 * 两个入口都可直接发送或排入HIGH,Tracked仅增加交接凭证输出,不改变调度。 * 两者均直接返回OK/WAIT/ERROR/FATAL,不借用输入、不保存最近结果。 * 调用前须处理Slave通知并检查请求是否仍有效;此入口不管理业务撤销或业务超时。 * OK后不可重交;WAIT后允许重读当前值重试,FATAL可能已发出字节。 */ IEC104_TcpSubmitResult_t IEC104_Slave_Send_Response(IEC104_Slave_t *self, const IEC104_SlaveEventIdentity_t *identity, const IEC60870_Asdu_t *asdu); /** * 功能:使用默认业务等级提交应答,并按需取得交接状态票据。 * 输入参数:self/identity——从站服务及请求身份;asdu——待提交应答。 * 输出参数:ticket——可为NULL,仅最终OK时写入。 * 返回值:OK已接手;WAIT未接手;ERROR非法;FATAL为连接故障。 * 说明:票据用于Get_Response_State;HANDED仅表示交接,不是对端ACK。 */ IEC104_TcpSubmitResult_t IEC104_Slave_Send_Response_Tracked(IEC104_Slave_t *self, const IEC104_SlaveEventIdentity_t *identity, const IEC60870_Asdu_t *asdu, uint64_t *ticket); /** * 功能:只读票据状态,允许STOP、断线及Close后调用;不要求active且不触发协议推进。 * 输入参数:self——从站服务;ticket——提交应答时取得的交接票据。 * 输出参数:无。 * 返回值:底层票据状态;实例无效时返回ERROR。 * 说明:HANDED只表示SendBuffer接手;不确定历史为CANCELLED;Destroy后旧服务及票据失效。 */ IEC104_ResponseState_t IEC104_Slave_Get_Response_State(const IEC104_Slave_t *self, uint64_t ticket); /** * 功能:与普通应答采用相同业务调度;仅OK写回执并占ACK观察槽。非OK不改输出、无观察槽遗留。 * 输入参数:self/identity——从站服务及请求身份;asdu——待提交应答。 * 输出参数:receipt——必填,仅最终OK时写入服务身份、连接代次和票据。 * 返回值:OK已接手并建立观察;WAIT未接手,含观察槽耗尽;ERROR非法;FATAL为连接故障。 * 说明:identity、asdu、receipt均须非NULL;使用原请求身份,提交前仍须由业务完成Check_Request检查。 * 观察槽不足也返回WAIT。ACKED/LOST不会自动归还槽,业务完成后必须Release。 * 取消观察不撤回已接手的确认;FATAL可能已接手报文,不得重交。 */ IEC104_TcpSubmitResult_t IEC104_Slave_Send_Response_Acked(IEC104_Slave_t *self, const IEC104_SlaveEventIdentity_t *identity, const IEC60870_Asdu_t *asdu, IEC104_SlaveAckReceipt_t *receipt); /** * 功能:只读且不推进网络;acked_at_ms可NULL,只有ACKED写出首次ACK时刻。 * 输入参数:self——本模块实例。 * receipt——ACK回执。 * acked_at_ms——ACK确认毫秒时刻。 * 输出参数:acked_at_ms——ACK确认毫秒时刻的更新结果。 * 返回值:按处理分支返回IEC104_SLAVE_ACK_ERROR、(IEC104_SlaveAckState_t)IEC104_TcpServer_Get_Ack_State(self->server, receipt->identity.generation, receipt->ticket, acked_at_ms)。 * 说明:STOP/断线后可查询历史结果;Release或服务Close之后ERROR。其他返回值不修改时刻输出。 * ACKED只证明有效累计N(R)已覆盖该帧;是否仍允许执行业务动作,另由原会话状态和业务期限决定。 */ IEC104_SlaveAckState_t IEC104_Slave_Get_Ack_State(const IEC104_Slave_t *self, const IEC104_SlaveAckReceipt_t *receipt, uint64_t *acked_at_ms); /** * 功能:只观察提交后首次STOP/断开之前的ACK;此前未ACK则永久LOST,STOP后START再ACK也不恢复。 * 输入参数:self——本模块实例。 * receipt——ACK回执。 * acked_at_ms——ACK确认毫秒时刻。 * 输出参数:acked_at_ms——ACK确认毫秒时刻的更新结果。 * 返回值:按处理分支返回IEC104_SLAVE_ACK_ERROR、(IEC104_SlaveAckState_t)IEC104_TcpServer_Get_Active_Ack_State(self->server, receipt->identity.generation, receipt->ticket, acked_at_ms)。 * 说明:此前已ACKED则保留首次ACK事实和时刻,不因通知晚分派或连接结束改为LOST。 * 只读、不要求Check_Request为READY;身份、寿命、输出保持规则同Get_Ack_State。 * 同一Poll及同一毫秒以协议受理顺序为准,普通Get_Ack_State仍可记录STOP后的有效ACK。 */ IEC104_SlaveAckState_t IEC104_Slave_Get_Active_Ack_State(const IEC104_Slave_t *self, const IEC104_SlaveAckReceipt_t *receipt, uint64_t *acked_at_ms); /** * 功能:只释放匹配观察槽并清空本回执;不撤回报文,迟到ACK不恢复观察。 * 输入参数:self——从站服务;receipt——此前取得的回执,可为NULL。 * 输出参数:receipt——身份属于本服务时清零;空指针、无效实例或外来回执保持不变。 * 返回值:无。 * 说明:可在等待、已ACK或LOST时调用;无效服务、NULL或其他实例的回执无操作。 */ void IEC104_Slave_Release_Ack(IEC104_Slave_t *self, IEC104_SlaveAckReceipt_t *receipt); /** * 功能:对应用未接手的I帧当场回否定回显:复制请求,只改COT=cause(44..49)和P/N=1。 * 输入参数:self——从站服务;event——有效请求事件;cause——44..49,表示未知字段或遥控软压板/时间戳错误。 * 输出参数:self——本模块实例的更新结果。 * 返回值:OK已接手,不表示已写完或已ACK; * WAIT为HIGH剩余空间不足、未接手,兜底应答可丢弃并计数,不要求重试; * ERROR为参数/事件非法、cause越界、原连接停用/断开/换代,或有未读启停通知; * FATAL为发送故障,可能已写出字节,不得重试,继续读取断线收尾通知。 * 未读启停通知使本请求不跨启停提交;该检查不能识别已经被应用读完的历史启停。 * 说明:保留TEST、OA、CA、VSQ及对象原文;不修改输入事件或其最近提交结果。48/49的业务适用性由调用方判断。 * 沿原连接走普通应答路径,直接构帧或复制进HIGH,按提交顺序发送,不另建暂存队列。 * 仅在串行事件循环中、本次NextEvent之后且读取后续事件之前调用,无需先读空通知。 * 不得保存事件后延迟调用;延迟应答仍用Copy_Event/Check_Request并在启停、断线时取消。 */ IEC104_TcpSubmitResult_t IEC104_Slave_Reject_Request(IEC104_Slave_t *self, const IEC104_SlaveEvent_t *event, int cause); /** * 功能:返回标准104只读参数2/2/3、最大249,供主动上报构造ASDU;无效句柄返回NULL。 * 输入参数:self——有效Slave句柄,不要求已Init或当前在线。 * 输出参数:无。 * 返回值:静态只读参数地址;无效句柄返回NULL,调用方不能修改或释放该参数。 * 说明:参数为静态常量,已取得的指针不借用服务存储。 */ const IEC60870_AppLayerParameters_t *IEC104_Slave_Get_Application_Layer_Parameters( const IEC104_Slave_t *self); /** * 功能:校验104布局后把ASDU复制到NORMAL,支持离线缓存;本次不直接写socket。 * 输入参数:self——从站服务;asdu——待排队的事件ASDU。 * 输出参数:self——本模块实例的更新结果。 * 返回值:OK已接手;WAIT暂时无法接手;ERROR为实例或输入非法;FATAL为队列状态故障。 * 说明:空间不足沿用NORMAL覆盖最旧原文的策略;返回OK表示已接手。 */ IEC104_TcpSubmitResult_t IEC104_Slave_Enqueue_Event(IEC104_Slave_t *self, IEC60870_Asdu_t *asdu); /** * 功能:将单对象带CP56的Type30/31、COT3遥信保存到独立SOE区。 * 输入参数:self/asdu——从站与标准104原文;priority——业务等级;deferred——是否先保留补报占位。 * 输出参数:ticket——可选身份输出,仅OK写入;deferred为true时不可为空。 * 返回值:OK已保存,WAIT未接手,ERROR输入非法,FATAL服务队列失效。 * 说明:完整保存17字节原文;256条满后仅覆盖最旧SOE,普通缓存不能挤占;成功不表示ACK。 */ IEC104_TcpSubmitResult_t IEC104_Slave_Enqueue_Soe(IEC104_Slave_t *self, IEC60870_Asdu_t *asdu, IEC104_BusinessPriority_t priority, bool deferred, IEC104_SoeTicket_t *ticket); /** * 功能:发布或取消先前保存的SOE补报占位。 * 输入参数:self——原从站;ticket——入队身份;publish——true转待发,false删除占位。 * 输出参数:无。 * 返回值:OK已处理或原占位已消失;其它值表示无效句柄、身份、阶段或服务错误。 * 说明:保留原采集时刻和受理顺序;覆盖或QRP2清除后不复生,关闭服务后旧票据失效。 */ IEC104_TcpResult_t IEC104_Slave_Resolve_Soe(IEC104_Slave_t *self, const IEC104_SoeTicket_t *ticket, bool publish); /** * 功能:TIME_TAGGED仅含Type30..40,按CA匹配,不区分同CA历次注册。CA为1..65534。 * 输入参数:self——从站服务;common_address——目标站点公共地址;kind——支持的事件类别。 * 输出参数:count——成功时的匹配数量;error——可选诊断。 * 返回值:OK统计成功;INVALID_HANDLE/INVALID_ARGUMENT为本层校验失败,其余错误由底层返回。 * 说明:只统计/清除尚未在本连接编号的NORMAL,保留已编号帧;允许离线及EOF状态。 * 不验证站点仍注册,不清除应用缓存;调用方负责站点授权及自有待发事件的同步处理。 * Count不预留,Discard重新验证整个桶再移动;两者都须在Poll/Process之外串行调用。 * 成功写ASDU条目数,无匹配时为0;失败不改计数输出或原文字节,error允许NULL并按结果填写。 */ IEC104_TcpResult_t IEC104_Slave_Count_Pending_Events(const IEC104_Slave_t *self, uint16_t common_address, IEC104_SlaveEventClass_t kind, uint32_t *count, IEC104_TcpError_t *error); /** * 功能:按公共地址和事件类别丢弃尚未提交为I帧的NORMAL事件。 * 输入参数:self——从站服务;common_address——目标站点公共地址;kind——支持的事件类别。 * 输出参数:removed——成功时的删除数量;error——可选诊断。 * 返回值:OK删除完成;INVALID_HANDLE/INVALID_ARGUMENT为本层校验失败,其余错误由底层返回。 * 说明:只删除未编号候选,不撤销在途或等待ACK的帧;站点归属由调用业务自行核对。 */ IEC104_TcpResult_t IEC104_Slave_Discard_Pending_Events(IEC104_Slave_t *self, uint16_t common_address, IEC104_SlaveEventClass_t kind, uint32_t *removed, IEC104_TcpError_t *error); /** * 功能:取得当前主站地址副本;尚未连接返回NOT_CONNECTED,不使用历史请求代替当前状态。 * 输入参数:self——已Init的服务;peer——非NULL输出存储;error——可选诊断。 * 输出参数:peer——对端信息的更新结果。 * error——错误诊断的更新结果。 * 返回值:仅OK写peer;无当前连接为NOT_CONNECTED,其他失败也保持peer原值。 * 说明:这是当前状态;历史事件的地址应从事件自身读取,不能用新主站地址替代旧来源。 */ IEC104_TcpResult_t IEC104_Slave_Get_Remote_Address(const IEC104_Slave_t *self, IEC104_TcpPeerInfo_t *peer, IEC104_TcpError_t *error); /** * 功能:关闭指定事件的原连接,保留监听/NORMAL;无需业务提取或传入generation。 * 输入参数:self——所属Slave;event——本服务事件或Copy_Event副本;error——可选诊断。 * 输出参数:self——本模块实例的更新结果。 * error——错误诊断的更新结果。 * 返回值:OK已断开;其他服务/已复用Slave的事件为INVALID_ARGUMENT;当前无连接为NOT_CONNECTED; * 仍有连接但代次不同为STALE_GENERATION;底层服务异常通过原结果和error返回。 * 说明:event须来自本服务实例;其他服务或已销毁复用实例的事件为INVALID_ARGUMENT。 * 当前无连接为NOT_CONNECTED;仍有连接但原代次已过期为STALE_GENERATION,不影响新连接。 * 成功后继续读取收尾事件;本操作不等待STOPDT或ACK。 */ IEC104_TcpResult_t IEC104_Slave_Close_Connection(IEC104_Slave_t *self, const IEC104_SlaveEvent_t *event, IEC104_TcpError_t *error); /** * 功能:使用已保存的事件身份关闭原连接,适用于不保留完整事件的延迟业务。 * 输入参数:self——本模块实例。 * identity——原会话身份。 * error——错误诊断。 * 输出参数:self——本模块实例的更新结果。 * error——错误诊断的更新结果。 * 返回值:按处理分支返回Slave_Error(IEC104_TCP_INVALID_HANDLE, error)、Slave_Error(IEC104_TCP_INVALID_ARGUMENT, error)、IEC104_TcpServer_Close_Connection(self->server, identity->generation, error)。 * 说明:身份来自Get_Event_Identity;原服务实例不符为INVALID_ARGUMENT,旧连接代次为STALE_GENERATION。 * 无连接为NOT_CONNECTED;OK保留监听/NORMAL并交付收尾通知,不影响后来复用槽位的新连接。 */ IEC104_TcpResult_t IEC104_Slave_Close_Connection_By_Identity(IEC104_Slave_t *self, const IEC104_SlaveEventIdentity_t *identity, IEC104_TcpError_t *error); /** * 功能:只读取得服务、队列、连接状态副本;Create后、Init失败后、Close后也可调用。 * 输入参数:self——有效句柄;status——非NULL输出存储;error——可选诊断。 * 输出参数:status——状态快照的更新结果。 * error——错误诊断的更新结果。 * 返回值:OK写入status,失败保持输出;Create后、Init失败后和Close后均可查询。 * 说明:会话和队列各自有有效标志,connected与data_transfer_started含义不同。 */ IEC104_TcpResult_t IEC104_Slave_Get_Status(const IEC104_Slave_t *self, IEC104_TcpServerStatus_t *status, IEC104_TcpError_t *error); /** * 功能:关闭监听和当前连接,保留未读通知;随后NextEvent读空,再Destroy归还静态槽。 * 输入参数:self——尚未Destroy的句柄;error——可选的本次调用诊断。 * 输出参数:self——本模块实例的更新结果。 * error——错误诊断的更新结果。 * 返回值:OK已收尾或本来未初始化;无效句柄、重入按底层约定返回错误。 * 说明:不等待业务发送/ACK,不归还对象池名额;读空事件后可重新Init或Destroy。 * 自建事件循环还须撤销旧socket注册和定时器,不能将其通知用于下一次Init。 */ IEC104_TcpResult_t IEC104_Slave_Close(IEC104_Slave_t *self, IEC104_TcpError_t *error); /** * 功能:显式业务等级:0沿用默认分类,1..12对应具名业务类别。身份、WAIT及回执契约与原入口相同。 * 输入参数:self——本模块实例。 * identity——原会话身份。 * reserve——须保留的窗口及记录槽数量。 * priority——优先级。 * 输出参数:无。 * 返回值:按处理分支返回ready、IEC104_TcpServer_Query_Idle_Send_Priority(self->server, identity->generation, reserve, priority)。 * 说明:默认应答INTERROGATION、事件SEQUENCE_EVENT、IDLE为MEASUREMENT;业务模块可显式传入实际类别。 * 严格模式Response先排队,队满时可在当前有序阶段直交;IDLE只在本次准入成功时交接,不缓存WAIT快照。 * 等级随事务确定,不能仅从ASDU类型或COT推断;同类报文可因初始化/普通总召等来源拥有不同等级。 */ IEC104_TcpSubmitResult_t IEC104_Slave_Query_Idle_Send_Priority(const IEC104_Slave_t *self, const IEC104_SlaveEventIdentity_t *identity, uint16_t reserve, IEC104_BusinessPriority_t priority); /** * 功能:校验容器后重新核对完整会话,不能把此前Query的OK当作预约。 * 输入参数:self——本模块实例。 * identity——原会话身份。 * asdu——ASDU报文。 * reserve——须保留的窗口及记录槽数量。 * priority——优先级。 * 输出参数:self——本模块实例的更新结果。 * 返回值:按处理分支返回IEC104_TCP_SUBMIT_ERROR、ready、IEC104_TcpServer_Send_Idle_Priority(self->server, identity->generation, data, length, reserve, priority)。 * 说明:WAIT未保存ASDU;OK由底层SendBuffer接手,后续本地写出和ACK仍通过既有发送记录反映。 */ IEC104_TcpSubmitResult_t IEC104_Slave_Send_Idle_Priority(IEC104_Slave_t *self, const IEC104_SlaveEventIdentity_t *identity, const IEC60870_Asdu_t *asdu, uint16_t reserve, IEC104_BusinessPriority_t priority); /** * 功能:使用局部回执承接底层输出,只有整体提交OK才发布给调用方; * 输入参数:self——本模块实例。 * identity——原会话身份。 * asdu——ASDU报文。 * receipt——ACK回执。 * priority——优先级。 * 输出参数:self——本模块实例的更新结果。 * receipt——ACK回执的更新结果。 * 返回值:按处理分支返回IEC104_TCP_SUBMIT_ERROR、result。 * 说明:失败不暴露半份身份/票据。 */ IEC104_TcpSubmitResult_t IEC104_Slave_Send_Response_Acked_Priority(IEC104_Slave_t *self, const IEC104_SlaveEventIdentity_t *identity, const IEC60870_Asdu_t *asdu, IEC104_SlaveAckReceipt_t *receipt, IEC104_BusinessPriority_t priority); /** * 功能:校验ASDU布局后复制到服务级NORMAL队列,用于主动上报。 * 输入参数:self——已Init的服务;asdu——合法且与104布局兼容的ASDU,不包含APCI。 * priority——0沿用事件级4,显式1..12由生产者按业务指定;本入口不按Type猜测故障级6。 * 输出参数:self——本模块实例的更新结果。 * 返回值:OK已复制,WAIT未接手可重试,ERROR参数/状态非法,FATAL底层队列异常。 * 说明:允许首次接入前及断线期间缓存,本次不直接写socket;空间不足可覆盖最旧NORMAL。 * Close清空缓存;重连恢复可能重复,业务应按自身语义处理。请求应答使用事件connection。 * 等级只决定严格模式的候选次序,不改变NORMAL覆盖、离线缓存及启动门禁规则。 */ IEC104_TcpSubmitResult_t IEC104_Slave_Enqueue_Event_Priority(IEC104_Slave_t *self, IEC60870_Asdu_t *asdu, IEC104_BusinessPriority_t priority); /** * 功能:等级描述业务语义,HIGH生命周期不变; * 输入参数:self——本模块实例。 * identity——原会话身份。 * asdu——ASDU报文。 * priority——优先级。 * 输出参数:self——本模块实例的更新结果。 * 返回值:返回Submit_Response_Priority(self, identity, asdu, NULL, priority)的结果。 * 说明:兼容模式忽略排序等级,严格模式先排队并受有序直交规则约束。 */ IEC104_TcpSubmitResult_t IEC104_Slave_Send_Response_Priority(IEC104_Slave_t *self, const IEC104_SlaveEventIdentity_t *identity, const IEC60870_Asdu_t *asdu, IEC104_BusinessPriority_t priority); /** * 功能:按指定业务等级提交应答,并按需取得交接状态票据。 * 输入参数:self/identity——从站服务及请求身份;asdu——应答原文;priority——业务等级,0使用默认值。 * 输出参数:ticket——可为NULL,仅最终OK时写入。 * 返回值:OK已接手;WAIT未接手;ERROR非法;FATAL为连接故障。 * 说明:身份与格式检查由共用入口完成;业务等级不改变HIGH应答的连接生命周期。 */ IEC104_TcpSubmitResult_t IEC104_Slave_Send_Response_Tracked_Priority(IEC104_Slave_t *self, const IEC104_SlaveEventIdentity_t *identity, const IEC60870_Asdu_t *asdu, uint64_t *ticket, IEC104_BusinessPriority_t priority); /** * 功能:只读原身份所属连接的启动门禁;用于受理时分类,不是业务完成凭证。 * 输入参数:self/identity——从站服务及事件身份。 * 输出参数:无。 * 返回值:实例、服务身份和连接代次有效且启动仍待完成时为true,否则为false。 * 说明:本函数不推进启动过程,也不解除NORMAL业务暂停。 */ bool IEC104_Slave_Startup_Is_Pending(const IEC104_Slave_t *self, const IEC104_SlaveEventIdentity_t *identity); /** * 功能:严格业务轮:Begin先维护/收集,再按1..12递增Set并重试对应生产者,最后End。 * 输入参数:self——从站服务。 * 输出参数:无。 * 返回值:实例有效且底层服务已启用严格模式时为true,否则为false。 * 说明:原文入队在所有阶段均允许;IDLE及队满旁路仅限当前等级,一轮最多直交一帧。 * 使用本接口后,每次I帧交接都须Begin新业务轮;连续Poll不会跳过应用候选准备。 * Begin不可嵌套,成功后无论业务是否成功都须End;End不主动发送,维护、超时和清理不能随低级发送暂停。 * 这些接口只控制选下一完整帧的时机,不切换线程,也不打断正在发送的帧。 */ bool IEC104_Slave_Strict_Priority_Enabled(const IEC104_Slave_t *self); /** * 功能:业务轮封装只校验实例并转交传输层;生产者顺序及维护调用由应用负责, * 输入参数:self——本模块实例。 * 输出参数:self——本模块实例的更新结果。 * 返回值:返回Slave_Owned(self) ? IEC104_TcpServer_Begin_Business_Cycle(self->server) : IEC104_TCP_SUBMIT_ERROR的结果。 * 说明:不创建任务、不切换线程,也不根据ASDU类型重新猜测调用方已确定的业务等级。 */ IEC104_TcpSubmitResult_t IEC104_Slave_Begin_Business_Cycle(IEC104_Slave_t *self); /** * 功能:设置本轮业务收集的当前等级,授予该等级直接提交的调度资格。 * 输入参数:self——从站服务;priority——当前业务等级。 * 输出参数:self——本模块实例的更新结果。 * 返回值:OK设置成功;ERROR为实例、周期状态或等级顺序非法。 * 说明:须处于Begin_Business_Cycle与End_Business_Cycle之间,按高到低的业务顺序推进。 */ IEC104_TcpSubmitResult_t IEC104_Slave_Set_Business_Priority(IEC104_Slave_t *self, IEC104_BusinessPriority_t priority); /** * 功能:结束本轮业务收集,关闭当前周期的直接提交资格。 * 输入参数:self——已成功开始业务周期的从站服务。 * 输出参数:self——本模块实例的更新结果。 * 返回值:OK结束成功;ERROR为实例无效或当前没有业务周期。 * 说明:不立即排空队列;已报告的待办等级保留到下一轮Begin,Begin成功后须配对调用。 */ IEC104_TcpSubmitResult_t IEC104_Slave_End_Business_Cycle(IEC104_Slave_t *self); /** * 功能:只读准入提示,包含当前阶段的队满直交;不预约资源,实际接手仍以提交返回值为准。 * 输入参数:self——本模块实例。 * identity——原会话身份。 * asdu_length——ASDU字节长度。 * priority——优先级。 * 输出参数:无。 * 返回值:按处理分支返回IEC104_TCP_SUBMIT_ERROR、IEC104_TcpServer_Query_Response_Priority(self->server, identity->generation, asdu_length, priority)。 * 说明:通过只代表当时的容量/阶段预检通过,未锁定容量或票据;后续仍须检查实际提交结果。 */ IEC104_TcpSubmitResult_t IEC104_Slave_Query_Response_Priority(const IEC104_Slave_t *self, const IEC104_SlaveEventIdentity_t *identity, uint16_t asdu_length, IEC104_BusinessPriority_t priority); /** * 功能:准备预算用尽但仍立即就绪时发布候选等级,多次发布保留最高等级(数字最小)。 * 输入参数:self——从站服务;priority——当前已就绪候选的有效业务等级。 * 输出参数:self——本模块实例的更新结果。 * 返回值:OK已登记;ERROR为实例、周期状态或等级非法。 * 说明:End后继续拦住更低等级,下一轮Begin清除;不生成原文或票据,不能用于等待外部数据/ACK。 */ IEC104_TcpSubmitResult_t IEC104_Slave_Set_Pending_Business_Priority(IEC104_Slave_t *self, IEC104_BusinessPriority_t priority); #ifdef __cplusplus } #endif #endif /* IEC104_SLAVE_H */