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

910 lines
60 KiB
C
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
/*
* 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 */