/* * 104子站业务入口:拥有一个TcpServer,并把底层I帧通知转换为ASDU视图和应答接口。 * 职责分工:Slave管理业务入口和事件绑定;TcpServer管理socket、调度、队列及协议会话。 * 本层只保存不透明的TcpServer指针,通过公开函数操作它,不访问其成员或复制底层对象。 * * 生命周期:Create -> 统一启动配置/Init -> Poll或Prepare/Process -> Close -> 读空事件 -> Destroy。 * 接收路径:TcpServer_NextEvent -> 复制原文及来源身份 -> Bind_Event -> 应用处理。 * 应答路径:IEC60870_MasterConnection_Send_* -> 本文件的发送适配 -> TcpServer_Send_Response。 * 主动上报:Slave_Enqueue_Event -> 服务级NORMAL队列,不借用某个请求的连接身份。 * 本层不自动执行业务命令或发送确认;ASDU检查及业务许可仍由应用负责。 * * 两种身份分别解决不同的复用问题:serial标识本次Slave_Create,generation标识原TCP会话。 * 事件保存两者,防止延迟应答误发给重连的主站或静态槽复用后的另一服务。 * 共用站点表只管理CA路由和节点寿命;总召等业务按注册编号保留原站,点表仍由应用管理。 * 节点的引用寿命与TCP会话寿命分开,持有节点并不表示原连接仍可应答。 * 所有调用在所属事件循环线程串行执行;静态池没有锁,Create/Destroy也须跨服务串行。 */ #include "IEC104_Slave.h" #include "IEC104_TcpServer.h" #include "IEC104_TcpServer_Config.h" #include /* 104专用默认布局来自IEC104_Types.h;共用ASDU模块通过参数工作,不硬编码104布局。 * 静态只读存储供接收视图和主动上报共用,返回的参数指针不依赖某个服务或事件的寿命。 */ static const IEC60870_AppLayerParameters_t parameters104 = IEC104_APP_LAYER_PARAMETERS_DEFAULT; /* 完整类型仅在本文件可见;业务只保存Create返回的指针。 */ struct IEC104_Slave { IEC104_TcpServer_t *server; /* 私有TCP服务;NULL表示该Slave槽空闲,Close不会清除此成员。 */ uint64_t serial; /* 每次成功Create递增,Destroy保留;到UINT64_MAX后不再复用该槽。 */ IEC104_Station_t *stations; /* 调用方节点按注册顺序排列,含待回收的退役节点;不另分配站点池。 */ uint32_t station_locks; /* 固定站点集合的嵌套借用计数,不是线程锁。 */ uint32_t station_snapshots; /* 活动遍历期间不回收退役节点,保护所有游标。 */ uint64_t station_serial; /* 注册编号不随Destroy清零,避免同CA替换/服务槽复用混淆。 */ }; _Static_assert(IEC104_TCP_SERVER_CAPACITY > 0U, "Slave needs at least one service slot"); /* Slave和TcpServer各有对象池;每个Slave占用一个底层名额,直接创建TCP服务也占该名额。 */ static IEC104_Slave_t slave_pool[IEC104_TCP_SERVER_CAPACITY]; /** * 功能:将共用主站连接接口的布尔发送调用转换为从站应答提交。 * 输入参数:connection——绑定从站事件的共用连接接口;asdu——待提交ASDU。 * 输出参数:无。 * 返回值:底层返回SUBMIT_OK时为true,等待或任何错误均为false。 * 说明:复用Submit_ASDU完成事件身份检查和结果记录;true仅表示已接手。 */ static bool Send_ASDU(IEC60870_MasterConnection_t *connection, IEC60870_Asdu_t *asdu); /** * 功能:判断句柄是否指向当前占用的Slave静态槽,NULL和池外地址返回false。 * 输入参数:self——本模块实例。 * 输出参数:无。 * 返回值:true表示句柄属于当前占用的Slave槽且仍持有底层服务,否则false。 * 说明:先按地址查池再解引用;server非空只表示拥有底层对象,不代表已Init或已连接。 * 槽复用后,单独的旧句柄副本无法与新句柄区分;Destroy成功后业务必须停止使用旧句柄。 */ static bool Slave_Owned(const IEC104_Slave_t *self) { size_t index; for (index = 0U; index < IEC104_TCP_SERVER_CAPACITY; ++index) { if (self == &slave_pool[index]) { return self->server != NULL; } } return false; } /** * 功能:先在本服务的链表中按地址查找,再读取目标节点;外来节点不借用其_owner字段找服务。 * 输入参数:self——本模块实例。 * station——逻辑站点。 * 输出参数:无。 * 返回值:按处理分支返回NULL、current。 * 说明:同时接受尚未回收的退役节点,以便原业务继续Acquire/Release;这里不判断CA路由资格。 */ static IEC104_Station_t *find_owned_station(const IEC104_Slave_t *self, const IEC104_Station_t *station) { IEC104_Station_t *current; if (!Slave_Owned(self) || station == NULL) { return NULL; } for (current = self->stations; current != NULL; current = current->_next) { if (current == station) { return current; } } return NULL; } /** * 功能:活动快照可能停在任意节点,因此全部快照End前都不摘除退役节点。 * 输入参数:self——本模块实例。 * 输出参数:无。 * 返回值:无。 * 说明:无快照且已删除、引用归零时才摘链并清零;不释放调用方的节点或context存储。 * Remove/Release/快照End均尝试回收,调用方据Is_Reusable决定何时释放自己的存储。 */ static void collect_retired_stations(IEC104_Slave_t *self) { IEC104_Station_t **entry = &self->stations; if (self->station_snapshots != 0U) { return; } while (*entry != NULL) { IEC104_Station_t *station = *entry; if (!station->_registered && station->_users == 0U) { *entry = station->_next; memset(station, 0, sizeof(*station)); } else { entry = &station->_next; } } } /** * 功能:借用调用方节点,成功前不改链表或节点; * 输入参数: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。 * 说明:不创建通信资源,不分配点表。 */ IEC104_StationResult_t IEC104_Slave_Add_Station(IEC104_Slave_t *self, IEC104_Station_t *station, uint16_t common_address, void *context) { IEC104_Station_t **tail; if (!Slave_Owned(self) || station == NULL || common_address == 0U || common_address == IEC104_CA_BROADCAST) { return IEC104_STATION_INVALID_ARGUMENT; } if (station->_owner != NULL) { return IEC104_STATION_ALREADY_REGISTERED; } if (self->station_locks != 0U) { return IEC104_STATION_BUSY; } if (self->station_serial == UINT64_MAX) { return IEC104_STATION_LIMIT; } for (tail = &self->stations; *tail != NULL; tail = &(*tail)->_next) { if ((*tail)->_registered && (*tail)->_common_address == common_address) { return IEC104_STATION_DUPLICATE_CA; } } station->_next = NULL; station->_owner = self; station->_context = context; station->_users = 0U; station->_common_address = common_address; station->_id = ++self->station_serial; station->_registered = true; station->_startup_activation = station->_startup_owner = station->_startup_request = 0U; station->_startup_ticket = 0U; station->_startup_completed = false; *tail = station; return IEC104_STATION_OK; } /** * 功能:删除先退出路由,引用和快照决定实际回收时机;OK不代表节点已可释放。 * 输入参数:self——本模块实例。 * station——逻辑站点。 * 输出参数:station——逻辑站点的更新结果。 * 返回值:按处理分支返回IEC104_STATION_INVALID_ARGUMENT、IEC104_STATION_NOT_FOUND、IEC104_STATION_BUSY、IEC104_STATION_OK。 * 说明:保留中的旧节点不会挡住相同CA的新注册,原业务仍通过注册编号找到旧节点。 */ IEC104_StationResult_t IEC104_Slave_Remove_Station(IEC104_Slave_t *self, IEC104_Station_t *station) { if (!Slave_Owned(self) || station == NULL) { return IEC104_STATION_INVALID_ARGUMENT; } if (find_owned_station(self, station) == NULL || !station->_registered) { return IEC104_STATION_NOT_FOUND; } if (self->station_locks != 0U) { return IEC104_STATION_BUSY; } station->_registered = false; collect_retired_stations(self); return IEC104_STATION_OK; } /** * 功能:新请求只匹配仍注册的节点; * 输入参数:self——本模块实例。 * common_address——ASDU公共地址。 * 输出参数:无。 * 返回值:返回借用指针,不自动增加引用或决定广播范围。 * 说明:返回借用指针,不自动增加引用或决定广播范围。 */ IEC104_Station_t *IEC104_Slave_Get_Station(const IEC104_Slave_t *self, uint16_t common_address) { IEC104_Station_t *station; if (!Slave_Owned(self) || common_address == 0U || common_address == IEC104_CA_BROADCAST) { return NULL; } for (station = self->stations; station != NULL; station = station->_next) { if (station->_registered && station->_common_address == common_address) { return station; } } return NULL; } /** * 功能:不另存可失配的数量; * 输入参数:self——本模块实例。 * 输出参数:无。 * 返回值:按处理分支返回0U、count。 * 说明:上限仅由可注册CA和调用方存储决定。 */ size_t IEC104_Slave_Get_Station_Count(const IEC104_Slave_t *self) { const IEC104_Station_t *station; size_t count = 0U; if (!Slave_Owned(self)) { return 0U; } for (station = self->stations; station != NULL; station = station->_next) { if (station->_registered) { ++count; } } return count; } /** * 功能:普通遍历读取当前注册集合; * 输入参数:self——本模块实例。 * current——当前节点。 * 输出参数:无。 * 返回值:按处理分支返回NULL、station。 * 说明:跨循环固定集合须Lock,允许增删的遍历须用Snapshot。 */ IEC104_Station_t *IEC104_Slave_Next_Station(const IEC104_Slave_t *self, const IEC104_Station_t *current) { IEC104_Station_t *station; if (!Slave_Owned(self)) { return NULL; } station = current == NULL ? self->stations : find_owned_station(self, current); if (current != NULL && station != NULL) { station = station->_next; } while (station != NULL && !station->_registered) { station = station->_next; } return station; } /** * 功能:固定遍历集合,不锁点值; * 输入参数:self——本模块实例。 * 输出参数:无。 * 返回值:按处理分支返回IEC104_STATION_INVALID_ARGUMENT、IEC104_STATION_LIMIT、IEC104_STATION_OK。 * 说明:串行事件循环中的嵌套借用必须显式配对。 */ IEC104_StationResult_t IEC104_Slave_Lock_Stations(IEC104_Slave_t *self) { if (!Slave_Owned(self)) { return IEC104_STATION_INVALID_ARGUMENT; } if (self->station_locks == UINT32_MAX) { return IEC104_STATION_LIMIT; } ++self->station_locks; return IEC104_STATION_OK; } /** * 功能:归还一次站点集合借用,减少站点注册变更的保护计数。 * 输入参数:self——持有借用锁的从站服务。 * 输出参数:无。 * 返回值:OK已归还;INVALID_ARGUMENT为实例无效或没有可归还的锁。 * 说明:须与Lock_Stations配对;这是集合借用计数,不是线程互斥锁,也不锁定站点业务数据。 */ IEC104_StationResult_t IEC104_Slave_Unlock_Stations(IEC104_Slave_t *self) { if (!Slave_Owned(self) || self->station_locks == 0U) { return IEC104_STATION_INVALID_ARGUMENT; } --self->station_locks; return IEC104_STATION_OK; } /** * 功能:持有具体节点,不重新按CA路由; * 输入参数:self——本模块实例。 * station——逻辑站点。 * 输出参数:无。 * 返回值:按处理分支返回IEC104_STATION_INVALID_ARGUMENT、IEC104_STATION_NOT_FOUND、IEC104_STATION_LIMIT、IEC104_STATION_OK。 * 说明:尚被保留的退役节点也能取得引用,供原业务继续处理。 */ IEC104_StationResult_t IEC104_Slave_Acquire_Station(IEC104_Slave_t *self, IEC104_Station_t *station) { if (!Slave_Owned(self) || station == NULL) { return IEC104_STATION_INVALID_ARGUMENT; } if (find_owned_station(self, station) == NULL) { return IEC104_STATION_NOT_FOUND; } if (station->_users == UINT32_MAX) { return IEC104_STATION_LIMIT; } ++station->_users; return IEC104_STATION_OK; } /** * 功能:归还自己的引用后可能立即摘链清零; * 输入参数: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) { if (!Slave_Owned(self) || station == NULL) { return IEC104_STATION_INVALID_ARGUMENT; } if (find_owned_station(self, station) == NULL) { return IEC104_STATION_NOT_FOUND; } if (station->_users == 0U) { return IEC104_STATION_INVALID_ARGUMENT; } --station->_users; collect_retired_stations(self); return IEC104_STATION_OK; } /** * 功能:延迟事件按原注册编号找回节点,包括被引用/快照保留的退役节点,避免同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) { IEC104_Station_t *station; if (!Slave_Owned(self) || station_id == 0U) { return NULL; } for (station = self->stations; station != NULL; station = station->_next) { if (station->_id == station_id) { return station; } } return NULL; } /** * 功能:取得站点在所属服务中的身份编号。 * 输入参数:station——仍由服务持有的站点对象。 * 输出参数:无。 * 返回值:站点编号;空指针或已解除服务归属时返回0。 * 说明:有归属不等于仍在注册表中,是否注册须另查Is_Registered。 */ uint64_t IEC104_Station_Get_Id(const IEC104_Station_t *station) { return station != NULL && station->_owner != NULL ? station->_id : 0U; } /** * 功能:查询站点是否仍归属于服务且处于已注册状态。 * 输入参数:station——待查询的站点对象。 * 输出参数:无。 * 返回值:有服务归属且注册标志有效时为true,空指针或其他状态为false。 * 说明:只读取状态,不借用对象或延长其存储寿命。 */ bool IEC104_Station_Is_Registered(const IEC104_Station_t *station) { return station != NULL && station->_owner != NULL && station->_registered; } /** * 功能:判断站点存储是否已完全解除服务归属,可用于后续注册。 * 输入参数:station——待复用的站点对象。 * 输出参数:无。 * 返回值:对象非空且无所属服务时为true,否则为false。 * 说明:注销后若仍有借用,服务归属尚未释放,不能仅凭未注册状态复用该存储。 */ bool IEC104_Station_Is_Reusable(const IEC104_Station_t *station) { return station != NULL && station->_owner == NULL; } /** * 功能:只保存注册编号上界和遍历位置,不冻结IOA或点值,也不阻止站点增删。 * 输入参数:self——本模块实例。 * snapshot——快照。 * 输出参数:snapshot——快照的更新结果。 * 返回值:按处理分支返回IEC104_STATION_INVALID_ARGUMENT、IEC104_STATION_LIMIT、IEC104_STATION_OK。 * 说明:注册编号单调递增,后来加入的同CA替代节点也会落在本次上界之外。 */ IEC104_StationResult_t IEC104_Slave_StationSnapshot_Begin(IEC104_Slave_t *self, IEC104_StationSnapshot_t *snapshot) { if (!Slave_Owned(self) || snapshot == NULL || snapshot->_owner != NULL) { return IEC104_STATION_INVALID_ARGUMENT; } if (self->station_snapshots == UINT32_MAX) { return IEC104_STATION_LIMIT; } snapshot->_owner = self; snapshot->_next = self->stations; snapshot->_last_id = self->station_serial; snapshot->_self = snapshot; ++self->station_snapshots; return IEC104_STATION_OK; } /** * 功能:先推进游标再返回当前仍注册的节点;删除的未来节点跳过,新增节点不纳入。 * 输入参数:snapshot——快照。 * 输出参数:snapshot——快照的更新结果。 * 返回值:先推进游标再返回当前仍注册的节点; * 返回NULL只表示遍历完毕,仍须End归还保护。 * 说明:快照保护节点存储但不自动Acquire;返回NULL只表示遍历完毕,仍须End归还保护。 */ IEC104_Station_t *IEC104_Slave_StationSnapshot_Next(IEC104_StationSnapshot_t *snapshot) { if (snapshot == NULL || snapshot->_self != snapshot || !Slave_Owned(snapshot->_owner)) { return NULL; } while (snapshot->_next != NULL) { IEC104_Station_t *station = snapshot->_next; snapshot->_next = station->_next; if (station->_id > snapshot->_last_id) { snapshot->_next = NULL; return NULL; } if (station->_registered) { return station; } } return NULL; } /** * 功能:与Begin配对一次;最后一个快照结束会尝试回收所有无引用的退役节点。 * 输入参数:snapshot——快照。 * 输出参数:snapshot——快照的更新结果。 * 返回值: 业务若要跨End继续使用Next返回的节点,必须提前Acquire。 * 说明:业务若要跨End继续使用Next返回的节点,必须提前Acquire。 */ IEC104_StationResult_t IEC104_Slave_StationSnapshot_End(IEC104_StationSnapshot_t *snapshot) { IEC104_Slave_t *self; if (snapshot == NULL || snapshot->_self != snapshot || !Slave_Owned(snapshot->_owner)) { return IEC104_STATION_INVALID_ARGUMENT; } self = snapshot->_owner; --self->station_snapshots; memset(snapshot, 0, sizeof(*snapshot)); collect_retired_stations(self); return IEC104_STATION_OK; } /** * 功能:读取站点所属服务保存的ASDU公共地址。 * 输入参数:station——站点对象。 * 输出参数:无。 * 返回值:仍有服务归属时返回公共地址;空指针或无归属时返回0。 * 说明:本函数不检查站点是否仍在注册表内。 */ uint16_t IEC104_Station_Get_Common_Address(const IEC104_Station_t *station) { return station != NULL && station->_owner != NULL ? station->_common_address : 0U; } /** * 功能:取得站点注册时绑定的业务上下文。 * 输入参数:station——站点对象。 * 输出参数:无。 * 返回值:仍有服务归属时返回上下文指针;空指针或无归属时返回NULL。 * 说明:上下文可以本来就是NULL;返回指针不转移所有权,也不延长业务存储寿命。 */ void *IEC104_Station_Get_Context(const IEC104_Station_t *station) { return station != NULL && station->_owner != NULL ? station->_context : NULL; } /** * 功能:返回本层校验失败的结果,同时完整填写可选的error。 * 输入参数:result——本层检测出的错误;error——调用方诊断存储,允许NULL。 * 输出参数:error——错误诊断的更新结果。 * 返回值:功能:返回本层校验失败的结果,同时完整填写可选的error。 * 说明:阶段统一为VALIDATE,socket_error为0;底层操作的诊断直接透传,不在这里改写。 */ static IEC104_TcpResult_t Slave_Error(IEC104_TcpResult_t result, IEC104_TcpError_t *error) { if (error != NULL) { error->result = result; error->stage = IEC104_TCP_STAGE_VALIDATE; error->socket_error = 0; } return result; } /** * 功能:从共用连接接口取回它所属的Slave事件;接口不匹配时返回NULL。 * 输入参数:connection——连接对象。 * 输出参数:无。 * 返回值:接口不匹配时返回NULL。 * 说明:同时核对发送函数和事件内接口的地址,拒绝赋值/memcpy产生的未修复副本。 * 此处只检查接口绑定,服务所有权、serial和连接代次由发送路径继续检查。 * connection及其object必须仍指向有效存储,不能用此检查代替业务的对象寿命管理。 */ static IEC104_SlaveEvent_t *Get_Context(const IEC60870_MasterConnection_t *connection) { IEC104_SlaveEvent_t *event; if (connection == NULL || connection->send_asdu != Send_ASDU || connection->object == NULL) { return NULL; } event = (IEC104_SlaveEvent_t *)connection->object; return &event->connection == connection ? event : NULL; } /** * 功能:确认待发送ASDU使用可由本接入层处理的104应用层布局。 * 输入参数:parameters——应用层参数。 * 输出参数:无。 * 返回值:基础参数合法、COT/CA/IOA为2/2/3字节且ASDU上限不超过249时为true。 * 说明:允许业务采用更小的最大长度或不同默认OA;这里不检查具体信息对象和业务权限。 */ static bool Parameters_Compatible(const IEC60870_AppLayerParameters_t *parameters) { return IEC60870_AppLayerParameters_Valid(parameters) && parameters->sizeOfCOT == 2 && parameters->sizeOfCA == 2 && parameters->sizeOfIOA == 3 && parameters->maxSizeOfASDU <= IEC104_MAX_ASDU_LEN; } /** * 功能:完整事件和紧凑身份共用发送校验,不把旧身份替换成当前连接。 * 输入参数:self——本模块实例。 * identity——原会话身份。 * asdu——ASDU报文。 * ticket——应答交接票据。 * priority——优先级。 * 输出参数:self——本模块实例的更新结果。 * ticket——应答交接票据的更新结果。 * 返回值:按处理分支返回IEC104_TCP_SUBMIT_ERROR、IEC104_TcpServer_Send_Response_Tracked_Priority(self->server, identity->generation, data, length, ticket, priority)。 * 说明:self只在确认仍被静态池占用后解引用;队列策略、发送期限和FATAL语义保持由TcpServer处理。 */ static IEC104_TcpSubmitResult_t Submit_Response_Priority(IEC104_Slave_t *self, const IEC104_SlaveEventIdentity_t *identity, const IEC60870_Asdu_t *asdu, uint64_t *ticket, IEC104_BusinessPriority_t priority) { const uint8_t *data; uint16_t length; if (!Slave_Owned(self) || identity == NULL || identity->slave != self || identity->instance_id != self->serial || identity->generation == 0U || asdu == NULL || !Parameters_Compatible(asdu->parameters) || IEC60870_Asdu_Get_Data(asdu, &data, &length) != IEC60870_ASDU_OK) { return IEC104_TCP_SUBMIT_ERROR; } return IEC104_TcpServer_Send_Response_Tracked_Priority(self->server, identity->generation, data, length, ticket, priority); } /** * 功能:使用默认业务等级提交应答,复用实例、事件身份和ASDU格式校验。 * 输入参数:self/identity——从站服务及请求身份;asdu——待提交应答。 * 输出参数:ticket——可选交接票据,仅最终提交成功时发布。 * 返回值:OK已接手;WAIT未接手;ERROR为身份或输入非法;FATAL为连接故障。 * 说明:不修改输入ASDU;默认等级由底层带等级入口解释。 */ static IEC104_TcpSubmitResult_t Submit_Response(IEC104_Slave_t *self, const IEC104_SlaveEventIdentity_t *identity, const IEC60870_Asdu_t *asdu, uint64_t *ticket) { return Submit_Response_Priority(self, identity, asdu, ticket, (IEC104_BusinessPriority_t)0); } /** * 功能:与普通请求应答不同,空闲快照每次都必须让出尚未分派的通知。 * 输入参数:self——本模块实例。 * identity——原会话身份。 * 输出参数:无。 * 返回值:按处理分支返回IEC104_TCP_SUBMIT_ERROR、IEC104_TCP_SUBMIT_OK、IEC104_TCP_SUBMIT_WAIT。 * 说明:Query和Send共用此检查:包括I_FRAME、RECORD,以及上一帧发送尾部刚交付的通知。 * 先核对实例归属,再查代次和FIFO;外来身份不能因本实例恰有通知而被误报为可重试的WAIT。 */ static IEC104_TcpSubmitResult_t Idle_Session_Ready(const IEC104_Slave_t *self, const IEC104_SlaveEventIdentity_t *identity) { if (!Slave_Owned(self) || identity == NULL || identity->slave != self || identity->instance_id != self->serial) { return IEC104_TCP_SUBMIT_ERROR; } switch (IEC104_Slave_Check_Request(self, identity)) { case IEC104_SLAVE_REQUEST_READY: return IEC104_TCP_SUBMIT_OK; case IEC104_SLAVE_REQUEST_WAIT_EVENTS: return IEC104_TCP_SUBMIT_WAIT; default: return IEC104_TCP_SUBMIT_ERROR; } } /** * 功能:按原活动轮次放行NORMAL/IDLE;本入口只执行身份/发送门禁校验,不代替业务完成判定。 * identity保存Slave实例及TCP代次,activation_id还区分同一TCP内的不同START轮次。 * 先让出完整通知FIFO,避免旧总召完成跨过尚未分派的STOP/START释放新一轮门禁。 * WAIT不改身份或消费通知;调用方先分派通知再重试,不能用当前轮次替换旧任务的轮次。 * 输入参数:self——本模块实例。 * identity——原会话身份。 * activation_id——START活动轮次编号。 * 输出参数:self——本模块实例的更新结果。 * 返回值:按处理分支返回ready、IEC104_TcpServer_Release_Startup(self->server, identity->generation, activation_id)。 * 说明:内部调用:Idle_Session_Ready、IEC104_TcpServer_Release_Startup。 */ IEC104_TcpSubmitResult_t IEC104_Slave_Release_Startup(IEC104_Slave_t *self, const IEC104_SlaveEventIdentity_t *identity, uint64_t activation_id) { IEC104_TcpSubmitResult_t ready = Idle_Session_Ready(self, identity); if (ready != IEC104_TCP_SUBMIT_OK) { return ready; } return IEC104_TcpServer_Release_Startup(self->server, identity->generation, activation_id); } /** * 功能:逐站进度只在启用门禁且当前仍闭锁时可读写;已开放后不再补记本轮启动状态。 * 输入参数:self——本模块实例。 * identity——原会话身份。 * activation_id——START活动轮次编号。 * 输出参数:无。 * 返回值:按处理分支返回ready、IEC104_TCP_SUBMIT_ERROR、IEC104_TCP_SUBMIT_OK。 * 说明:Idle_Session_Ready先验证归属、FIFO及连接;随后再核对实际START轮次。 * 仅generation相同不足以证明任务有效:STOP/START不换TCP,迟到FINISHED仍可能来自旧轮。 * 不在此检查Type/QOI/TEST或初始化完成,这些业务语义由应用在调用Begin/Complete前确认。 */ static IEC104_TcpSubmitResult_t Startup_Context_Ready(IEC104_Slave_t *self, const IEC104_SlaveEventIdentity_t *identity, uint64_t activation_id) { IEC104_TcpServerStatus_t status; IEC104_TcpSubmitResult_t ready = Idle_Session_Ready(self, identity); if (ready != IEC104_TCP_SUBMIT_OK) { return ready; } if (activation_id == 0U || IEC104_TcpServer_Get_Status(self->server, &status, NULL) != IEC104_TCP_OK || !status.startup_event_gate || !status.startup_pending || status.activation_id != activation_id) { return IEC104_TCP_SUBMIT_ERROR; } return IEC104_TCP_SUBMIT_OK; } /** * 功能:记录本轮计划接受的全站总召尝试;站点使用注册编号,不用可被重新注册复用的CA。 * 输入参数:self——本模块实例。 * identity——原会话身份。 * activation_id——START活动轮次编号。 * station_id——站点编号。 * owner_id——业务所有者编号。 * request_id——请求编号。 * 输出参数:无。 * 返回值:按处理分支返回ready、IEC104_TCP_SUBMIT_ERROR、IEC104_TCP_SUBMIT_OK。 * 说明:owner_id为总召模块实例号,request_id为该实例内请求号,二者共同关联迟到的完成通知。 * 本函数不Acquire站点或冻结集合;应用须在整个启动流程持有Lock_Stations。 * OK只表示身份已登记,真正的成功仍须Complete及Query,BEGIN未获准/超时不会自动放行。 */ 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) { IEC104_Station_t *station; IEC104_TcpSubmitResult_t ready = Startup_Context_Ready(self, identity, activation_id); if (ready != IEC104_TCP_SUBMIT_OK) { return ready; } station = IEC104_Slave_Get_Station_By_Id(self, station_id); if (station == NULL || !station->_registered || owner_id == 0U || request_id == 0U) { return IEC104_TCP_SUBMIT_ERROR; } /* 同轮已记录成功FINISHED的站保留原请求及票据,即使原票据仍PENDING也不被后来总召覆盖。 * 未完成时允许下一次获准请求替换失败尝试;旧请求随后Complete会因身份不匹配被拒绝。 */ if (station->_startup_activation == activation_id && station->_startup_completed) { return IEC104_TCP_SUBMIT_OK; } station->_startup_activation = activation_id; station->_startup_owner = owner_id; station->_startup_request = request_id; station->_startup_ticket = 0U; station->_startup_completed = false; return IEC104_TCP_SUBMIT_OK; } /** * 功能:仅为成功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) { IEC104_Station_t *station; IEC104_TcpSubmitResult_t ready = Startup_Context_Ready(self, identity, activation_id); if (ready != IEC104_TCP_SUBMIT_OK) { return ready; } station = IEC104_Slave_Get_Station_By_Id(self, station_id); if (station == NULL || !station->_registered || owner_id == 0U || request_id == 0U || station->_startup_activation != activation_id) { return IEC104_TCP_SUBMIT_ERROR; } if (station->_startup_owner != owner_id || station->_startup_request != request_id) { return IEC104_TCP_SUBMIT_ERROR; } if (station->_startup_completed) { return IEC104_TCP_SUBMIT_OK; } station->_startup_ticket = completion_ticket; station->_startup_completed = true; return IEC104_TCP_SUBMIT_OK; } /** * 功能:只读汇总当前注册集合:每站须属于本轮、有成功完成记录,且最终应答已经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) { IEC104_Station_t *station; bool any = false; IEC104_TcpSubmitResult_t ready = Startup_Context_Ready(self, identity, activation_id); if (ready != IEC104_TCP_SUBMIT_OK) { return ready; } for (station = self->stations; station != NULL; station = station->_next) { IEC104_ResponseState_t state; if (!station->_registered) { continue; } any = true; if (station->_startup_activation != activation_id || !station->_startup_completed) { return IEC104_TCP_SUBMIT_WAIT; } state = IEC104_Slave_Get_Response_State(self, station->_startup_ticket); if (state == IEC104_RESPONSE_PENDING) { return IEC104_TCP_SUBMIT_WAIT; } if (state != IEC104_RESPONSE_HANDED) { return IEC104_TCP_SUBMIT_ERROR; } } /* 空集合没有任何成功总召证据,不能用“全部条件真”直接放行缓存。 */ return any ? IEC104_TCP_SUBMIT_OK : IEC104_TCP_SUBMIT_WAIT; } /** * 功能:不取值、不发送的准入提示; * 输入参数:self——本模块实例。 * identity——原会话身份。 * reserve——须保留的窗口及记录槽数量。 * priority——优先级。 * 输出参数:无。 * 返回值:按处理分支返回ready、IEC104_TcpServer_Query_Idle_Send_Priority(self->server, identity->generation, reserve, priority)。 * 说明:OK之后应用才构造快照,实际Send仍会重新检查通知。 */ 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) { IEC104_TcpSubmitResult_t ready = Idle_Session_Ready(self, identity); if (ready != IEC104_TCP_SUBMIT_OK) { return ready; } return IEC104_TcpServer_Query_Idle_Send_Priority(self->server, identity->generation, reserve, priority); } /** * 功能:使用默认业务等级查询该事件身份是否允许一次空闲业务发送。 * 输入参数:self/identity——从站服务及事件身份;reserve——提交后须保留的窗口和记录槽数量。 * 输出参数:无。 * 返回值:OK当前可发送;WAIT暂受通知、协议或资源限制;ERROR为身份、参数或状态非法。 * 说明:查询不接手ASDU或预留资源,实际Send_Idle仍重新核对通知和连接状态。 */ IEC104_TcpSubmitResult_t IEC104_Slave_Query_Idle_Send(const IEC104_Slave_t *self, const IEC104_SlaveEventIdentity_t *identity, uint16_t reserve) { return IEC104_Slave_Query_Idle_Send_Priority(self, identity, reserve, (IEC104_BusinessPriority_t)0); } /** * 功能:校验容器后重新核对完整会话,不能把此前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) { const uint8_t *data; uint16_t length; IEC104_TcpSubmitResult_t ready; if (!Slave_Owned(self) || asdu == NULL || !Parameters_Compatible(asdu->parameters) || IEC60870_Asdu_Get_Data(asdu, &data, &length) != IEC60870_ASDU_OK) { return IEC104_TCP_SUBMIT_ERROR; } ready = Idle_Session_Ready(self, identity); if (ready != IEC104_TCP_SUBMIT_OK) { return ready; } return IEC104_TcpServer_Send_Idle_Priority(self->server, identity->generation, data, length, reserve, priority); } /** * 功能:使用默认业务等级尝试直接发送一帧空闲业务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) { return IEC104_Slave_Send_Idle_Priority(self, identity, asdu, reserve, (IEC104_BusinessPriority_t)0); } /** * 功能:能力属于已Init的服务,不依赖活动连接; * 输入参数:self——本模块实例。 * capacity——存储容量。 * error——错误诊断。 * 输出参数:capacity——存储容量的更新结果。 * error——错误诊断的更新结果。 * 返回值:按处理分支返回Slave_Error(IEC104_TCP_INVALID_HANDLE, error)、IEC104_TcpServer_Get_Send_Capacity(self->server, capacity, error)。 * 说明:Close后历史ACTIVATED仍可能待分派,须保留INVALID_STATE。 */ IEC104_TcpResult_t IEC104_Slave_Get_Send_Capacity(const IEC104_Slave_t *self, IEC104_TcpSendCapacity_t *capacity, IEC104_TcpError_t *error) { if (!Slave_Owned(self)) { return Slave_Error(IEC104_TCP_INVALID_HANDLE, error); } return IEC104_TcpServer_Get_Send_Capacity(self->server, capacity, error); } /** * 功能:使用默认业务等级向请求所属连接提交应答。 * 输入参数:self/identity——从站服务及请求身份;asdu——待提交的应答ASDU。 * 输出参数:self——本模块实例的更新结果。 * 返回值:OK已复制接手;WAIT未接手;ERROR为身份或ASDU非法;FATAL为连接故障。 * 说明:可直接交接或进入HIGH队列;本入口不返回票据,成功不表示对端已确认。 */ IEC104_TcpSubmitResult_t IEC104_Slave_Send_Response(IEC104_Slave_t *self, const IEC104_SlaveEventIdentity_t *identity, const IEC60870_Asdu_t *asdu) { return Submit_Response(self, identity, asdu, NULL); } /** * 功能:使用默认业务等级提交应答,并按需取得交接状态票据。 * 输入参数: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) { return Submit_Response(self, identity, asdu, ticket); } /** * 功能:等级描述业务语义,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) { return Submit_Response_Priority(self, identity, asdu, NULL, 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) { return Submit_Response_Priority(self, identity, asdu, ticket, priority); } /** * 功能:查询从站服务是否启用了严格业务优先级调度。 * 输入参数:self——从站服务。 * 输出参数:无。 * 返回值:实例有效且底层服务已启用严格模式时为true,否则为false。 * 说明:只读取当前配置,不开启业务周期或改变调度状态。 */ bool IEC104_Slave_Strict_Priority_Enabled(const IEC104_Slave_t *self) { return Slave_Owned(self) && IEC104_TcpServer_Strict_Priority_Enabled(self->server); } /** * 功能:业务轮封装只校验实例并转交传输层;生产者顺序及维护调用由应用负责, * 输入参数: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) { return Slave_Owned(self) ? IEC104_TcpServer_Begin_Business_Cycle(self->server) : IEC104_TCP_SUBMIT_ERROR; } /** * 功能:设置本轮业务收集的当前等级,授予该等级直接提交的调度资格。 * 输入参数: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) { return Slave_Owned(self) ? IEC104_TcpServer_Set_Business_Priority(self->server, priority) : IEC104_TCP_SUBMIT_ERROR; } /** * 功能:报告尚未编码但已立即就绪的业务候选,保留其中最高业务等级。 * 输入参数:self——从站服务;priority——当前已就绪候选的有效业务等级。 * 输出参数:self——本模块实例的更新结果。 * 返回值:OK已登记;ERROR为实例、周期状态或等级非法。 * 说明:用于阻止低等级提前取数或构帧;不预留队列空间,不适用于仍等待外部条件或ACK的业务。 */ IEC104_TcpSubmitResult_t IEC104_Slave_Set_Pending_Business_Priority(IEC104_Slave_t *self, IEC104_BusinessPriority_t priority) { return Slave_Owned(self) ? IEC104_TcpServer_Set_Pending_Business_Priority(self->server, priority) : IEC104_TCP_SUBMIT_ERROR; } /** * 功能:结束本轮业务收集,关闭当前周期的直接提交资格。 * 输入参数:self——已成功开始业务周期的从站服务。 * 输出参数:self——本模块实例的更新结果。 * 返回值:OK结束成功;ERROR为实例无效或当前没有业务周期。 * 说明:不立即排空队列;已报告的待办等级保留到下一轮Begin,Begin成功后须配对调用。 */ IEC104_TcpSubmitResult_t IEC104_Slave_End_Business_Cycle(IEC104_Slave_t *self) { return Slave_Owned(self) ? IEC104_TcpServer_End_Business_Cycle(self->server) : IEC104_TCP_SUBMIT_ERROR; } /** * 功能:先检查实例及连接身份,防止旧业务用当前连接的空闲资源通过动作预检。 * 输入参数: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) { if (!Slave_Owned(self) || identity == NULL || identity->slave != self || identity->instance_id != self->serial || identity->generation == 0U) { return IEC104_TCP_SUBMIT_ERROR; } return IEC104_TcpServer_Query_Response_Priority(self->server, identity->generation, asdu_length, priority); } /** * 功能:查询给定事件身份所属连接是否仍有启动业务待完成。 * 输入参数:self/identity——从站服务及事件身份。 * 输出参数:无。 * 返回值:实例、服务身份和连接代次有效且启动仍待完成时为true,否则为false。 * 说明:本函数不推进启动过程,也不解除NORMAL业务暂停。 */ bool IEC104_Slave_Startup_Is_Pending(const IEC104_Slave_t *self, const IEC104_SlaveEventIdentity_t *identity) { return Slave_Owned(self) && identity != NULL && identity->slave == self && identity->instance_id == self->serial && identity->generation != 0U && IEC104_TcpServer_Startup_Is_Pending(self->server, identity->generation); } /** * 功能:查询应答票据的待交接、已交接或取消状态。 * 输入参数:self——从站服务;ticket——提交应答时取得的交接票据。 * 输出参数:无。 * 返回值:底层票据状态;实例无效时返回ERROR。 * 说明:只查询交接历史;HANDED不等于TCP写完或对端确认,需ACK结果时使用回执接口。 */ IEC104_ResponseState_t IEC104_Slave_Get_Response_State(const IEC104_Slave_t *self, uint64_t ticket) { if (!Slave_Owned(self)) { return IEC104_RESPONSE_ERROR; } return IEC104_TcpServer_Get_Response_State(self->server, ticket); } /** * 功能:使用局部回执承接底层输出,只有整体提交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) { const uint8_t *data; uint16_t length; IEC104_SlaveAckReceipt_t prepared; IEC104_TcpSubmitResult_t result; if (!Slave_Owned(self) || identity == NULL || receipt == NULL || identity->slave != self || identity->instance_id != self->serial || identity->generation == 0U || asdu == NULL || !Parameters_Compatible(asdu->parameters) || IEC60870_Asdu_Get_Data(asdu, &data, &length) != IEC60870_ASDU_OK) { return IEC104_TCP_SUBMIT_ERROR; } memset(&prepared, 0, sizeof(prepared)); prepared.identity = *identity; result = IEC104_TcpServer_Send_Response_Acked_Priority(self->server, identity->generation, data, length, &prepared.ticket, priority); if (result == IEC104_TCP_SUBMIT_OK) { *receipt = prepared; } return result; } /** * 功能:使用默认业务等级提交应答,同时申请可查询对端ACK的回执。 * 输入参数:self/identity——从站服务及请求身份;asdu——待提交应答。 * 输出参数:receipt——必填,仅最终OK时写入服务身份、连接代次和票据。 * 返回值:OK已接手并建立观察;WAIT未接手,含观察槽耗尽;ERROR非法;FATAL为连接故障。 * 说明:OK不表示已收到ACK;调用方使用完回执后须调用Release_Ack归还观察资源。 */ 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) { return IEC104_Slave_Send_Response_Acked_Priority(self, identity, asdu, receipt, (IEC104_BusinessPriority_t)0); } /** * 功能:查询是历史通信事实,不要求Check_Request为READY; * 输入参数: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)。 * 说明:动作提交条件由业务选择相应ACK契约。 */ IEC104_SlaveAckState_t IEC104_Slave_Get_Ack_State(const IEC104_Slave_t *self, const IEC104_SlaveAckReceipt_t *receipt, uint64_t *acked_at_ms) { if (!Slave_Owned(self) || receipt == NULL || receipt->identity.slave != self || receipt->identity.instance_id != self->serial) { return IEC104_SLAVE_ACK_ERROR; } return (IEC104_SlaveAckState_t)IEC104_TcpServer_Get_Ack_State(self->server, receipt->identity.generation, receipt->ticket, acked_at_ms); } /** * 功能:历史活动期结果不依赖当前通知是否读空; * 输入参数: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)。 * 说明:实例身份仍须匹配,避免静态槽复用混淆回执。 */ IEC104_SlaveAckState_t IEC104_Slave_Get_Active_Ack_State(const IEC104_Slave_t *self, const IEC104_SlaveAckReceipt_t *receipt, uint64_t *acked_at_ms) { if (!Slave_Owned(self) || receipt == NULL || receipt->identity.slave != self || receipt->identity.instance_id != self->serial) { return IEC104_SLAVE_ACK_ERROR; } return (IEC104_SlaveAckState_t)IEC104_TcpServer_Get_Active_Ack_State(self->server, receipt->identity.generation, receipt->ticket, acked_at_ms); } /** * 功能:归还回执占用的ACK观察资源,并清空本服务所属的回执。 * 输入参数:self——从站服务;receipt——此前取得的回执,可为NULL。 * 输出参数:receipt——身份属于本服务时清零;空指针、无效实例或外来回执保持不变。 * 返回值:无。 * 说明:释放观察资源不撤销已接手的应答,也不改变已经发生的发送或确认事实。 */ void IEC104_Slave_Release_Ack(IEC104_Slave_t *self, IEC104_SlaveAckReceipt_t *receipt) { if (!Slave_Owned(self) || receipt == NULL || receipt->identity.slave != self || receipt->identity.instance_id != self->serial) { return; } IEC104_TcpServer_Release_Ack(self->server, receipt->identity.generation, receipt->ticket); memset(receipt, 0, sizeof(*receipt)); } /** * 功能:根据已接收的有效I帧请求构造否定应答,并提交到该请求所属连接。 * 输入参数:self——从站服务;event——有效请求事件;cause——44..49,表示未知字段或遥控软压板/时间戳错误。 * 输出参数:self——本模块实例的更新结果。 * 返回值:OK已接手应答;WAIT暂未接手;ERROR为事件、原因或状态非法;FATAL为连接故障。 * 说明:在局部缓冲构造副本并置否定标志,不修改原请求;待分派的连接状态通知会阻止提交。 */ IEC104_TcpSubmitResult_t IEC104_Slave_Reject_Request(IEC104_Slave_t *self, const IEC104_SlaveEvent_t *event, int cause) { uint8_t bytes[IEC104_MAX_ASDU_LEN]; const uint8_t *data; uint16_t length, reply_length; IEC60870_Asdu_t reply; IEC104_SlaveEventIdentity_t identity; IEC104_TcpServerStatus_t status; if (cause < IEC60870_ASDU_COT_UNKNOWN_TYPE || cause > IEC60870_ASDU_COT_COMMAND_TIME_ERROR || !IEC104_Slave_Get_Event_Identity(self, event, &identity) || event->transport.type != IEC104_TCP_EVENT_I_FRAME || event->asdu_result != IEC60870_ASDU_OK || IEC104_TcpServer_Get_Status(self->server, &status, NULL) != IEC104_TCP_OK) { return IEC104_TCP_SUBMIT_ERROR; } /* 本次事件之后尚未消费的启停通知表明链路已停用或曾停用,不能跨启停提交应答。 */ if (status.pending_state_event_count != 0U || IEC60870_Asdu_Get_Data(&event->asdu, &data, &length) != IEC60870_ASDU_OK || IEC60870_Asdu_Build_Response(¶meters104, data, length, cause, 1, bytes, sizeof(bytes), &reply_length) != IEC60870_ASDU_OK || IEC60870_Asdu_Create_From_Buffer(&reply, ¶meters104, bytes, reply_length) != IEC60870_ASDU_OK) { return IEC104_TCP_SUBMIT_ERROR; } return Submit_Response(self, &identity, &reply, NULL); } /** * 功能:把应答交给产生该事件的原服务、原会话。 * 输入参数:connection——事件内已绑定的接口;asdu——布局兼容的完整ASDU,可独立于接收视图。 * 输出参数:ticket——应答交接票据的更新结果。 * 返回值:透传OK/WAIT/ERROR/FATAL并记录在原事件中;普通send_asdu包装为bool。 * 说明:先检查Slave所有权和serial,再由TcpServer检查generation、启停状态及发送容量。 * OK表示已复制接手,不代表写完或收到ACK;WAIT未接手,业务保存原事件/ASDU后择机重试。 * 不查找当前新连接来替换旧身份;FATAL可能已经写出字节,不能作为未发送直接重放。 */ static IEC104_TcpSubmitResult_t Submit_ASDU(IEC60870_MasterConnection_t *connection, const IEC60870_Asdu_t *asdu, uint64_t *ticket) { IEC104_SlaveEvent_t *event = Get_Context(connection); IEC104_SlaveEventIdentity_t identity; if (event == NULL) { return IEC104_TCP_SUBMIT_ERROR; } identity.slave = event->_owner; identity.instance_id = event->_owner_serial; identity.generation = event->_generation; event->_last_submit_result = Submit_Response(event->_owner, &identity, asdu, ticket); return event->_last_submit_result; } /** * 功能:将共用主站连接接口的布尔发送调用转换为从站应答提交。 * 输入参数:connection——绑定从站事件的共用连接接口;asdu——待提交ASDU。 * 输出参数:无。 * 返回值:底层返回SUBMIT_OK时为true,等待或任何错误均为false。 * 说明:复用Submit_ASDU完成事件身份检查和结果记录;true仅表示已接手。 */ static bool Send_ASDU(IEC60870_MasterConnection_t *connection, IEC60870_Asdu_t *asdu) { return Submit_ASDU(connection, asdu, NULL) == IEC104_TCP_SUBMIT_OK; } /** * 功能:104专用带凭证入口; * 输入参数:connection——连接对象。 * asdu——ASDU报文。 * ticket——应答交接票据。 * 输出参数:ticket——应答交接票据的更新结果。 * 返回值:返回Submit_ASDU(connection, asdu, ticket)的结果。 * 说明:与共用连接接口采用相同的HIGH FIFO发送策略。 */ IEC104_TcpSubmitResult_t IEC104_Slave_Send_ASDU_Tracked( IEC60870_MasterConnection_t *connection, const IEC60870_Asdu_t *asdu, uint64_t *ticket) { return Submit_ASDU(connection, asdu, ticket); } /** * 功能:修改ASDU的传送原因和否定标志,再沿原连接提交确认或终止。 * 输入参数:cause——目标COT;negative——目标P/N;asdu——允许原地修改的ASDU。 * 输出参数:asdu——按顺序设置COT与P/N;connection所属事件记录本次提交结果。 * 取得有效事件后即更新提交结果;后续失败不回滚已完成的ASDU修改。 * 返回值:true已接手;false表示字段修改或提交失败,详细提交结果保存在事件中。 * 说明:按COT、P/N顺序修改,后续失败不回滚已经成功的修改;不执行业务,也不自动重试。 */ static bool Send_Confirmation(IEC60870_MasterConnection_t *connection, IEC60870_Asdu_t *asdu, int cause, bool negative) { IEC104_SlaveEvent_t *event = Get_Context(connection); if (event == NULL) { return false; } event->_last_submit_result = IEC104_TCP_SUBMIT_ERROR; if (IEC60870_Asdu_Set_COT(asdu, cause) != IEC60870_ASDU_OK || IEC60870_Asdu_Set_Negative(asdu, negative ? 1 : 0) != IEC60870_ASDU_OK) { return false; } return Send_ASDU(connection, asdu); } /** * 功能:共用激活确认入口:COT=7,P/N由业务指定; * 输入参数:connection——连接对象。 * asdu——ASDU报文。 * negative——否定确认标志。 * 输出参数:asdu——COT改为7并设置P/N;connection所属事件记录提交结果。 * 沿用Send_Confirmation的修改顺序,失败不回滚已经完成的字段修改。 * 返回值:激活确认被发送层接手返回true;WAIT、非法请求或发送故障返回false。 * 说明:沿用Send_Confirmation的修改及提交契约。 */ static bool Send_ACT_CON(IEC60870_MasterConnection_t *connection, IEC60870_Asdu_t *asdu, bool negative) { return Send_Confirmation(connection, asdu, IEC60870_ASDU_COT_ACTIVATION_CON, negative); } /** * 功能:共用激活终止入口:COT=10、P/N=0; * 输入参数:connection——连接对象。 * asdu——ASDU报文。 * 输出参数:asdu——COT改为10且P/N清零;connection所属事件记录提交结果。 * 沿用Send_Confirmation的修改顺序,失败不回滚已经完成的字段修改。 * 返回值:激活终止被发送层接手返回true;WAIT、非法请求或发送故障返回false。 * 说明:由业务处理完成后调用,不自动跟随ACT_CON发送。 */ static bool Send_ACT_TERM(IEC60870_MasterConnection_t *connection, IEC60870_Asdu_t *asdu) { return Send_Confirmation(connection, asdu, IEC60870_ASDU_COT_ACTIVATION_TERMINATION, false); } /** * 功能:共用参数查询入口:有效事件接口返回静态只读参数; * 输入参数:connection——连接对象。 * 输出参数:无。 * 返回值:共用参数查询入口:有效事件接口返回静态只读参数; * 说明:不要求原连接仍在线,也不表示可以发送。 */ static const IEC60870_AppLayerParameters_t *Get_Parameters(IEC60870_MasterConnection_t *connection) { return Get_Context(connection) != NULL ? ¶meters104 : NULL; } /** * 功能:让目标事件的ASDU视图和共用发送接口指向目标自身的存储。 * 输入参数:event——事件。 * 输出参数:event->asdu/connection/asdu_result;不改来源身份、原文和历史提交结果。 * 返回值:无。 * 说明:前提:transport原文已复制完毕,事件地址在后续使用期间保持稳定。 * 非I帧不提供ASDU接口;I帧视图构造失败时保留原通知供诊断,connection保持清零。 * 视图借用本事件中APCI之后的ASDU字节,不再借用TcpServer或Receiver的内部缓冲。 */ static void Bind_Event(IEC104_SlaveEvent_t *event) { uint16_t length; memset(&event->asdu, 0, sizeof(event->asdu)); memset(&event->connection, 0, sizeof(event->connection)); event->asdu_result = IEC60870_ASDU_UNSUPPORTED; if (event->transport.type != IEC104_TCP_EVENT_I_FRAME) { return; } event->asdu_result = IEC60870_ASDU_ERROR; length = event->transport.data.i_frame.apdu_length; if (length < IEC104_APCI_LEN || length > IEC104_MAX_APDU_LEN) { return; } event->asdu_result = IEC60870_Asdu_Create_From_Buffer(&event->asdu, ¶meters104, event->transport.data.i_frame.apdu + IEC104_APCI_LEN, (uint16_t)(length - IEC104_APCI_LEN)); if (event->asdu_result != IEC60870_ASDU_OK) { return; } event->connection.object = event; event->connection.send_asdu = Send_ASDU; event->connection.send_act_con = Send_ACT_CON; event->connection.send_act_term = Send_ACT_TERM; event->connection.get_application_layer_parameters = Get_Parameters; } /** * 功能:从静态池取得一个Slave,并为它取得一个私有TcpServer。 * 输入参数:无。 * 输出参数:无。 * 返回值:成功返回不透明句柄;任一池无可用槽或身份编号耗尽时返回NULL。 * 说明:不创建socket、不分配堆内存;只有取得底层服务后才占用Slave槽并递增serial。 * 成功后由业务配对Destroy;不能自行分配、复制、清零或free句柄指向的对象。 */ IEC104_Slave_t *IEC104_Slave_Create(void) { size_t index; for (index = 0U; index < IEC104_TCP_SERVER_CAPACITY; ++index) { IEC104_Slave_t *self = &slave_pool[index]; if (self->server == NULL && self->serial != UINT64_MAX) { IEC104_TcpServer_t *server = IEC104_TcpServer_Create(); if (server == NULL) { return NULL; } self->server = server; ++self->serial; return self; } } return NULL; } /** * 功能:归还已关闭且通知已读空的Slave及其底层服务。 * 输入参数:self——Create取得且未Destroy的句柄;error——可选的本次调用诊断。 * 输出参数:self——本模块实例的更新结果。 * error——错误诊断的更新结果。 * 返回值:OK时句柄失效;运行中为INVALID_STATE,通知未读空为EVENTS_PENDING,失败保留对象。 * 说明:先由TcpServer检查并归还底层槽,再释放Slave槽;保留serial隔离旧事件。 * 常规顺序为Close -> NextEvent读空 -> Destroy;尚未Init或Init失败后也可直接归还。 */ IEC104_TcpResult_t IEC104_Slave_Destroy(IEC104_Slave_t *self, IEC104_TcpError_t *error) { IEC104_TcpResult_t result; if (!Slave_Owned(self)) { return Slave_Error(IEC104_TCP_INVALID_HANDLE, error); } if (self->stations != NULL || self->station_locks != 0U || self->station_snapshots != 0U) { return Slave_Error(IEC104_TCP_INVALID_STATE, error); } result = IEC104_TcpServer_Destroy(self->server, error); if (result == IEC104_TCP_OK) { self->server = NULL; } return result; } /** * 功能:初始化所拥有的TCP服务,开始监听并建立服务级发送队列。 * 输入参数:self——有效Slave句柄;config——本次监听和协议配置,底层复制后使用。 * 输出参数:error——本次诊断,允许NULL;底层返回的阶段和网络错误保持原样。 * 返回值:OK已监听,其他结果区分参数、配置、生命周期或网络失败。 * 说明:成功不表示已有主站,之后必须驱动Poll或Prepare/Process;失败不销毁句柄。 * 再次Init前须Close并读空旧通知,旧事件的连接身份不会因重新初始化而更新。 */ IEC104_TcpResult_t IEC104_Slave_Init(IEC104_Slave_t *self, const IEC104_SlaveConfig_t *config, IEC104_TcpError_t *error) { if (!Slave_Owned(self)) { return Slave_Error(IEC104_TCP_INVALID_HANDLE, error); } return IEC104_TcpServer_Init(self->server, config, error); } /** * 功能:为外部事件循环查询socket关注集合、等待期限及本地待处理工作。 * 输入参数:self——已Init的服务;info——非NULL快照存储;error——可选诊断。 * 输出参数:info——查询信息的更新结果。 * error——错误诊断的更新结果。 * 返回值:OK时写出info;失败保持info不变,不进行收发或协议推进。 * 说明:有待消费事件或need_process时不得阻塞等待;状态改变后须重新Prepare。 * 快照中的socket仅供注册,所有权仍属于内部TcpServer,业务不能直接读写或关闭。 */ IEC104_TcpResult_t IEC104_Slave_Prepare(const IEC104_Slave_t *self, IEC104_TcpWaitInfo_t *info, IEC104_TcpError_t *error) { if (!Slave_Owned(self)) { return Slave_Error(IEC104_TCP_INVALID_HANDLE, error); } return IEC104_TcpServer_Prepare(self->server, info, error); } /** * 功能:把外部事件循环的一批就绪、定时或本地通知交给底层有界推进。 * 输入参数:self——已Init的服务;ready——必填就绪批次,身份来自对应Prepare/注册快照。 * 输出参数:error——可选诊断;返回值与TcpServer_Process一致,OK也包括没有进展。 * 返回值:返回值与TcpServer_Process一致,OK也包括没有进展。 * 返回后消费NextEvent,再Prepare更新关注集合。 * 说明:不等待;返回后消费NextEvent,再Prepare更新关注集合。旧通知不得替换为新token。 * 客户端故障通过收尾事件交付,服务级失败则由调用方保存诊断后Close。 */ IEC104_TcpResult_t IEC104_Slave_Process(IEC104_Slave_t *self, const IEC104_TcpReady_t *ready, IEC104_TcpError_t *error) { if (!Slave_Owned(self)) { return Slave_Error(IEC104_TCP_INVALID_HANDLE, error); } return IEC104_TcpServer_Process(self->server, ready, error); } /** * 功能:独立主循环使用的准备、至多一次网络等待和有界推进组合入口。 * 输入参数:self——已Init的服务;max_wait_ms——本轮网络等待上限,0不等待;error可为NULL。 * 输出参数:self——本模块实例的更新结果。 * error——错误诊断的更新结果。 * 返回值:OK表示服务可继续;客户端断线不一定使本函数失败,须读取NextEvent。 * 说明:等待还受协议期限和本地工作约束;max_wait_ms不保证整个函数的执行耗时。 * 不创建后台线程、不调用业务处理函数;每轮返回后由应用消费通知。 */ IEC104_TcpResult_t IEC104_Slave_Poll(IEC104_Slave_t *self, uint32_t max_wait_ms, IEC104_TcpError_t *error) { if (!Slave_Owned(self)) { return Slave_Error(IEC104_TCP_INVALID_HANDLE, error); } return IEC104_TcpServer_Poll(self->server, max_wait_ms, error); } /** * 功能:取出最早的TCP通知,并为有效I帧建立ASDU视图和原连接的发送接口。 * 输入参数:self——有效句柄,Close后仍可读取;event——地址稳定的非NULL输出存储。 * 输出参数:self——本模块实例的更新结果。 * event——事件的更新结果。 * 返回值:READY替换整个event;EMPTY/ERROR保持上次事件及其视图不变。 * 说明:先读入临时量,只有取得通知后才覆盖输出;保存原服务serial和连接generation。 * READY仅表示取得事件,I帧还须检查asdu_result;视图失败仍保留原文,不自动确认。 * 不进行I/O;下一次READY会覆盖同一event,延迟处理须另存并调用Copy_Event修复自引用。 */ IEC104_TcpEventResult_t IEC104_Slave_NextEvent(IEC104_Slave_t *self, IEC104_SlaveEvent_t *event) { IEC104_TcpEvent_t received; IEC104_TcpEventResult_t result; if (!Slave_Owned(self) || event == NULL) { return IEC104_TCP_EVENT_ERROR; } result = IEC104_TcpServer_NextEvent(self->server, &received); if (result != IEC104_TCP_EVENT_READY) { return result; } memset(event, 0, sizeof(*event)); event->transport = received; event->_owner = self; event->_owner_serial = self->serial; event->_generation = received.generation; event->_last_submit_result = IEC104_TCP_SUBMIT_ERROR; Bind_Event(event); return IEC104_TCP_EVENT_READY; } /** * 功能:只校验事件自身布局和自引用,不要求原服务或TCP会话仍存活。 * 输入参数:event——事件。 * 输出参数:无。 * 返回值:事件身份字段、类型和适用的ASDU自引用一致时返回true,否则false。 * 说明:Copy_Event允许保存历史原文;Get_Event_Identity在此基础上额外校验当前服务实例。 * 解析失败的I帧仍是有效通知,由业务处理其asdu_result,不在此丢弃诊断信息。 */ static bool Event_Valid(const IEC104_SlaveEvent_t *event) { const uint8_t *data; uint16_t length; if (event == NULL || event->_owner == NULL || event->_owner_serial == 0U || event->_generation == 0U || event->_generation != event->transport.generation || event->transport.type < IEC104_TCP_EVENT_CONNECTED || event->transport.type > IEC104_TCP_EVENT_DEACTIVATED) { return false; } if (event->transport.type == IEC104_TCP_EVENT_I_FRAME && event->asdu_result == IEC60870_ASDU_OK) { if (event->connection.object != event || Get_Context(&event->connection) != event || event->asdu.parameters != ¶meters104 || IEC60870_Asdu_Get_Data(&event->asdu, &data, &length) != IEC60870_ASDU_OK || data != event->transport.data.i_frame.apdu + IEC104_APCI_LEN || (uint32_t)length + IEC104_APCI_LEN != event->transport.data.i_frame.apdu_length) { return false; } } return true; } /** * 功能:把事件复制到稳定的目标存储,同时重建目标ASDU视图及发送接口的自引用。 * 输入参数:source——NextEvent或本函数产生的有效事件;destination——目标事件存储。 * 输出参数:destination——目标存储的更新结果。 * 返回值:true已复制或源/目标为同一合法对象;false校验失败且不修改目标。 * 说明:先核对源视图仍借用源原文,避免传播普通赋值形成的悬空绑定。 * 保留原服务、代次和最近提交结果,不查询当前主站、不发送;历史事件也可复制保存。 * 复制只延长原文和接口存储的寿命,不能使已关闭或已被替换的原连接重新可用。 */ bool IEC104_Slave_Copy_Event(IEC104_SlaveEvent_t *destination, const IEC104_SlaveEvent_t *source) { if (destination == NULL || !Event_Valid(source)) { return false; } if (destination != source) { *destination = *source; Bind_Event(destination); } return true; } /** * 功能:验证业务收到的Slave事件,交付可保存的服务实例和原连接身份。 * 输入参数:self为所属服务;event为原事件或Copy_Event副本;identity为非NULL输出。 * 输出参数:identity——原会话身份的更新结果。 * 返回值:true写出身份;false为非法来源/布局/视图或参数,保持输出不变。 * 说明:只匹配服务实例,不用当前TCP代次拒绝历史通知;是否仍可推进另由Check_Request判断。 */ bool IEC104_Slave_Get_Event_Identity(const IEC104_Slave_t *self, const IEC104_SlaveEvent_t *event, IEC104_SlaveEventIdentity_t *identity) { IEC104_SlaveEventIdentity_t copy; if (!Slave_Owned(self) || identity == NULL || !Event_Valid(event) || event->_owner != self || event->_owner_serial != self->serial) { return false; } memset(©, 0, sizeof(copy)); copy.slave = self; copy.instance_id = event->_owner_serial; copy.generation = event->_generation; *identity = copy; return true; } /** * 功能:统一判断业务是否应先处理通知、放弃失效请求,或继续当前会话的工作。 * 输入参数:identity为Get_Event_Identity的只读结果,允许零初始化表示尚未绑定会话。 * 输出参数:无。 * 返回值:ERROR为参数/查询失败;WAIT_EVENTS优先于会话判断;STALE为原身份不再可用;READY可继续。 * 说明:检查通知FIFO、服务实例、TCP代次和传输激活状态,不执行I/O或保留发送窗口。 * 先读空通知可避免同一代次STOP后又START时,仅凭最终激活状态误续旧业务。 */ IEC104_SlaveRequestState_t IEC104_Slave_Check_Request(const IEC104_Slave_t *self, const IEC104_SlaveEventIdentity_t *identity) { IEC104_TcpServerStatus_t status; if (!Slave_Owned(self) || identity == NULL || IEC104_TcpServer_Get_Status(self->server, &status, NULL) != IEC104_TCP_OK) { return IEC104_SLAVE_REQUEST_ERROR; } if (status.pending_event_count != 0U) { return IEC104_SLAVE_REQUEST_WAIT_EVENTS; } if (identity->slave != self || identity->instance_id != self->serial || identity->generation == 0U || identity->generation != status.generation || !status.connected || !status.connection_status_valid || !status.connection.data_transfer_started) { return IEC104_SLAVE_REQUEST_STALE; } return IEC104_SLAVE_REQUEST_READY; } /** * 功能:补充共用发送接口bool结果,查询这个事件连接最近一次提交的具体状态。 * 输入参数:connection——event.connection的地址;不是Slave句柄,也不是底层socket。 * 输出参数:无。 * 返回值:OK/WAIT/ERROR/FATAL;尚未发送或接口绑定无效时返回ERROR。 * 说明:记录只在提交时更新,不随后续Poll或主站ACK更新;发送完成事实应查看RECORD事件。 */ IEC104_TcpSubmitResult_t IEC104_Slave_Get_Last_Submit_Result( const IEC60870_MasterConnection_t *connection) { const IEC104_SlaveEvent_t *event = Get_Context(connection); return event != NULL ? event->_last_submit_result : IEC104_TCP_SUBMIT_ERROR; } /** * 功能:取得本接入使用的104应用层参数,供业务构造主动上报或独立应答ASDU。 * 输入参数:self——有效Slave句柄,不要求已Init或当前在线。 * 输出参数:无。 * 返回值:静态只读参数地址;无效句柄返回NULL,调用方不能修改或释放该参数。 * 说明:内部调用:Slave_Owned。 */ const IEC60870_AppLayerParameters_t *IEC104_Slave_Get_Application_Layer_Parameters( const IEC104_Slave_t *self) { return Slave_Owned(self) ? ¶meters104 : NULL; } /** * 功能:校验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) { const uint8_t *data; uint16_t length; if (!Slave_Owned(self) || asdu == NULL || !Parameters_Compatible(asdu->parameters) || IEC60870_Asdu_Get_Data(asdu, &data, &length) != IEC60870_ASDU_OK) { return IEC104_TCP_SUBMIT_ERROR; } return IEC104_TcpServer_Enqueue_Event_Priority(self->server, data, length, priority); } /** * 功能:使用默认业务等级将主动事件复制到服务级NORMAL队列。 * 输入参数:self——从站服务;asdu——待排队的事件ASDU。 * 输出参数:self——本模块实例的更新结果。 * 返回值:OK已接手;WAIT暂时无法接手;ERROR为实例或输入非法;FATAL为队列状态故障。 * 说明:事件不绑定请求身份,可在无活动连接时缓存;成功不表示已经发送。 */ IEC104_TcpSubmitResult_t IEC104_Slave_Enqueue_Event(IEC104_Slave_t *self, IEC60870_Asdu_t *asdu) { return IEC104_Slave_Enqueue_Event_Priority(self, asdu, (IEC104_BusinessPriority_t)0); } /** * 功能:将单对象Type30/31、COT3遥信交给本从站的独立SOE区。 * 输入参数:self/asdu——从站和标准104原文;priority——业务等级;deferred——是否暂缓;ticket——可选身份输出。 * 输出参数:ticket仅在接手成功时写入;deferred为true时不可为空。 * 返回值:底层OK/WAIT/ERROR/FATAL;无效从站或ASDU返回ERROR。 * 说明:不借用调用方原文,普通遥测不占SOE额度;成功不代表主站已确认。 */ 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) { const uint8_t *data; uint16_t length; if (!Slave_Owned(self) || asdu == NULL || !Parameters_Compatible(asdu->parameters) || IEC60870_Asdu_Get_Data(asdu, &data, &length) != IEC60870_ASDU_OK) { return IEC104_TCP_SUBMIT_ERROR; } return IEC104_TcpServer_Enqueue_Soe(self->server, data, length, priority, deferred, ticket); } /** * 功能:发布或取消本从站先前保存的SOE补报占位。 * 输入参数:self——原从站;ticket——入队身份;publish——发布或取消。 * 输出参数:无。 * 返回值:无效从站返回INVALID_HANDLE;其余返回底层处理结果。 * 说明:只处理仍存在的原占位;覆盖、筛选清除或关闭后不得创建替代事件。 */ IEC104_TcpResult_t IEC104_Slave_Resolve_Soe(IEC104_Slave_t *self, const IEC104_SoeTicket_t *ticket, bool publish) { if (!Slave_Owned(self)) { return IEC104_TCP_INVALID_HANDLE; } return IEC104_TcpServer_Resolve_Soe(self->server, ticket, publish); } /** * 功能:事件分类只在Slave集中映射;底层队列按固定104布局匹配CA与Type,不解释对象。 * 输入参数:kind——类别。 * bitmap——位图。 * 输出参数:bitmap——位图的更新结果。 * 返回值:按处理分支返回0、1。 * 说明:这里不查站点表:队列没有station_id,不能区分同CA历次注册留下的原文。 * SystemCommand在调用前负责检查受理时的站点仍注册,并在应用侧清除相同CA的待发事件。 */ static int Event_Class_Bitmap(IEC104_SlaveEventClass_t kind, uint8_t bitmap[32]) { unsigned type; if (kind != IEC104_SLAVE_EVENTS_TIME_TAGGED) { return 0; } memset(bitmap, 0, 32U); for (type = 30U; type <= 40U; ++type) { bitmap[type / 8U] |= (uint8_t)(1U << (type % 8U)); } return 1; } /** * 功能:按公共地址和事件类别统计尚未提交为I帧的NORMAL事件。 * 输入参数:self——从站服务;common_address——目标站点公共地址;kind——支持的事件类别。 * 输出参数:count——成功时的匹配数量;error——可选诊断。 * 返回值:OK统计成功;INVALID_HANDLE/INVALID_ARGUMENT为本层校验失败,其余错误由底层返回。 * 说明:当前类别筛选为带时标事件;已编号或等待ACK的帧不计入,也不校验当前站点注册关系。 */ 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) { uint8_t bitmap[32]; if (!Slave_Owned(self)) { return Slave_Error(IEC104_TCP_INVALID_HANDLE, error); } if (!Event_Class_Bitmap(kind, bitmap)) { return Slave_Error(IEC104_TCP_INVALID_ARGUMENT, error); } return IEC104_TcpServer_Count_Pending_Normal(self->server, common_address, bitmap, count, 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) { uint8_t bitmap[32]; if (!Slave_Owned(self)) { return Slave_Error(IEC104_TCP_INVALID_HANDLE, error); } if (!Event_Class_Bitmap(kind, bitmap)) { return Slave_Error(IEC104_TCP_INVALID_ARGUMENT, error); } return IEC104_TcpServer_Discard_Pending_Normal(self->server, common_address, bitmap, removed, error); } /** * 功能:读取当前主站的IPv4、源端口和连接代次副本,不执行网络查询。 * 输入参数: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) { if (!Slave_Owned(self)) { return Slave_Error(IEC104_TCP_INVALID_HANDLE, error); } return IEC104_TcpServer_Get_Remote_Address(self->server, peer, error); } /** * 功能:按事件捕获的原连接身份主动断开主站,保留监听和服务级NORMAL。 * 输入参数:self——所属Slave;event——本服务事件或Copy_Event副本;error——可选诊断。 * 输出参数:self——本模块实例的更新结果。 * error——错误诊断的更新结果。 * 返回值:OK已断开;其他服务/已复用Slave的事件为INVALID_ARGUMENT;当前无连接为NOT_CONNECTED; * 仍有连接但代次不同为STALE_GENERATION;底层服务异常通过原结果和error返回。 * 说明:来源serial先由本层检查,原generation再由TcpServer核对;不用当前代次代替旧身份。 * 不等待STOPDT或ACK,成功后继续读取收尾事件,再Prepare更新监听条件。 */ IEC104_TcpResult_t IEC104_Slave_Close_Connection(IEC104_Slave_t *self, const IEC104_SlaveEvent_t *event, IEC104_TcpError_t *error) { if (!Slave_Owned(self)) { return Slave_Error(IEC104_TCP_INVALID_HANDLE, error); } if (event == NULL || event->_owner != self || event->_owner_serial != self->serial || event->_generation == 0U) { return Slave_Error(IEC104_TCP_INVALID_ARGUMENT, error); } return IEC104_TcpServer_Close_Connection(self->server, event->_generation, 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)。 * 说明:校验与完整事件关闭入口一致。 */ IEC104_TcpResult_t IEC104_Slave_Close_Connection_By_Identity(IEC104_Slave_t *self, const IEC104_SlaveEventIdentity_t *identity, IEC104_TcpError_t *error) { if (!Slave_Owned(self)) { return Slave_Error(IEC104_TCP_INVALID_HANDLE, error); } if (identity == NULL || identity->slave != self || identity->instance_id != self->serial || identity->generation == 0U) { return Slave_Error(IEC104_TCP_INVALID_ARGUMENT, error); } return IEC104_TcpServer_Close_Connection(self->server, identity->generation, error); } /** * 功能:取得内部TCP服务、队列和最近会话的状态副本,不推进协议或消费队列。 * 输入参数: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) { if (!Slave_Owned(self)) { return Slave_Error(IEC104_TCP_INVALID_HANDLE, error); } return IEC104_TcpServer_Get_Status(self->server, status, error); } /** * 功能:关闭监听和当前连接,清空待发ASDU,但保留已生成的业务及收尾通知。 * 输入参数: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) { if (!Slave_Owned(self)) { return Slave_Error(IEC104_TCP_INVALID_HANDLE, error); } return IEC104_TcpServer_Close(self->server, error); }