910 lines
60 KiB
C
910 lines
60 KiB
C
/*
|
||
* 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 */
|