525 lines
43 KiB
C
525 lines
43 KiB
C
/*
|
||
* 模块:IEC104控制命令业务层,45..51及58..64,COT=6激活、COT=8撤销。
|
||
* 职责:校验请求、选择/执行匹配、撤销、阶段期限、原文确认和事务收尾。
|
||
* 状态命令QU仅接受0..3,设定值QL仅接受0;51/64无此字段。未支持的限定词独立否定,
|
||
* 不改变既有事务;公共编解码仍保留完整位域,应用还须拒绝设备未实现的输出方式。
|
||
* 点表、闭锁、远方/就地策略及实际输出由应用负责;本模块不判定设备操作是否安全。
|
||
* 每个Slave至多一个实例,每实例至多一个未释放事务;其他业务仍独立推进。
|
||
* 静态存储、无动态分配、不保存回调;所有入口须与Slave在同一事件循环串行调用。
|
||
* 只有Accept调用应用动作,先消费事件、再至多调用一次;Handle_Event/Process不调用应用。
|
||
* 返回信息由Submit_Return_Info沿原连接HIGH提交,确认/返回信息/终止保持FIFO顺序。
|
||
* TEST=1仅演练协议:合法选择回肯定ACT_CON,匹配执行/直接执行回肯定ACT_CON及ACT_TERM,
|
||
* 匹配撤销回肯定DEACT_CON;全部保留T位,不交付应用事件、不调用动作、不产生返回信息。
|
||
* 测试与真实请求共用唯一事务槽,T位参与匹配;槽被另一种请求占用时独立忙否定,不能接管原选择。
|
||
* TEST仍检查点表、类型/模式、QU/QL、时标及SBO匹配;时标过期始终否定,无静默选项。
|
||
*
|
||
* 接入顺序:先Create,再按Slave通知FIFO分派Handle_Event;每轮Process后读空NextEvent。
|
||
* SELECT/EXECUTE事件由Accept或Reject消费;EXECUTE启动成功后,先Report_Result,
|
||
* 再逐帧Submit_Return_Info,全部OK后Complete;最终读取FINISHED清理应用资源。
|
||
* Report_Result也可晚于返回信息,但必须早于Complete,且设备结果产生后应及时报告。
|
||
* 固定执行收尾:SUCCEEDED后Complete回肯定ACT_TERM,FAILED后Complete回否定ACT_TERM。
|
||
* 等待执行结果超时由模块自动安排否定ACT_TERM并立即FINISHED(EXECUTE_TIMEOUT),结果仍未知。
|
||
* 该超时不关闭TCP;应用仍须驱动Process/网络发送残留回复,并独立维护实际设备的忙状态。
|
||
* WAIT表示本次应用操作尚未接手,保留输入并在读取通知/推进网络后重试;OK不得重复提交。
|
||
* 动作/确认/设备结果/FINISHED是不同节点:FINISHED只结束协议事务,不撤销物理输出。
|
||
* STOP、断线或Cancel不回滚动作,也不把原连接的返回信息转交到新连接。
|
||
* 提交OK表示发送层已复制;正常FINISHED还要等事务尾进入SendBuffer,不等待ACK。
|
||
* FINISHED.return_info_undelivered在结束时冻结;Cancel不撤回已入HIGH的帧,保守补报可能重复。
|
||
*
|
||
* 退出顺序:Cancel、读完FINISHED、Slave_Close、读空并分派通知、Destroy,
|
||
* 然后由应用移除站点并销毁Slave。模块不负责Slave或应用持有引用的释放。
|
||
*/
|
||
#ifndef IEC104_COMMAND_H
|
||
#define IEC104_COMMAND_H
|
||
|
||
#include "IEC104_Slave.h"
|
||
#include "IEC60870_Time.h"
|
||
#include <stddef.h>
|
||
|
||
#ifdef __cplusplus
|
||
extern "C" {
|
||
#endif
|
||
|
||
/* 不透明静态池句柄;Destroy成功后失效,不得按值复制内部对象或继续使用旧指针。 */
|
||
typedef struct IEC104_Command IEC104_Command_t;
|
||
|
||
/* 供无副作用的类型常量使用;45..51映射bit0..6,58..64映射bit7..13。
|
||
* 范围外为0,不作非法移位。Create接受全部14位,默认全部启用。 */
|
||
#define IEC104_COMMAND_TYPE_BIT(type) ((uint16_t)( \
|
||
((type) >= 45U && (type) <= 51U) ? (1U << ((type) - 45U)) : \
|
||
(((type) >= 58U && (type) <= 64U) ? (1U << ((type) - 51U)) : 0U)))
|
||
|
||
/* 点级执行方式;0为非法值,必须显式选定一种方式。51/64仅允许DIRECT。 */
|
||
typedef enum {
|
||
IEC104_COMMAND_MODE_DIRECT = 1, /* 只接受直接执行,选择请求回否定确认。 */
|
||
IEC104_COMMAND_MODE_SELECT_EXECUTE /* 须先选择,执行必须匹配仍有效的本事务选择。 */
|
||
} IEC104_CommandMode_t;
|
||
|
||
/* 同一CA/IOA仅一项;按common_address、ioa严格升序排列,Create校验、受理时二分查找。
|
||
* 表由应用拥有,从Create到Destroy须保持有效且只读;可放在静态const存储中。
|
||
* 库不复制点表、不持有设备指针。动态闭锁、权限和数值限值仍由应用在Accept前判断。 */
|
||
typedef struct {
|
||
uint16_t common_address; /* 1..65534;允许先配置,受理时该CA仍必须已注册。 */
|
||
uint32_t ioa; /* 1..0xFFFFFF,控制点地址。 */
|
||
uint16_t type_mask; /* 非零,限14种已知类型;实际可用类型与全局type_mask取交集。 */
|
||
IEC104_CommandMode_t mode; /* 此点所有允许类型共用同一种执行方式。 */
|
||
} IEC104_CommandPoint_t;
|
||
|
||
/* 创建时按值复制的配置,但points所指数组仍借用,不能在实例存活期间修改或释放。
|
||
* 期限以Net单调时钟计算,等于边界即到期;
|
||
* 决定/执行期限为0仅禁用时长限制,等待阶段遇到时钟倒退仍终结;选择期限必须非零。
|
||
* Report_Result后计完成期限,Complete后计交接期限;提前ENDED的残留回复也限时清理。
|
||
* 新增两项期限为0时,同时禁用该阶段的超时及计时回退处理;FINISHED仍须应用读取。 */
|
||
typedef struct {
|
||
uint16_t type_mask; /* 默认启用45..51、58..64全部14种;应用可裁剪,不能为空。 */
|
||
/* 选择保持上限,单位ms,默认30000且不得为0;同实例所有选择执行点共用。
|
||
* 选择动作返回STARTED(含NULL选择)后计时,包含选择确认的发送等待;
|
||
* 匹配执行被Handle_Event受理即停止,随后进入决定期限,不必等满此时长。
|
||
* 自动选择后紧接执行可用10000作为联调起点,人工确认可保留30000;
|
||
* 应结合主站流程及通信/调度余量在Create前确定。保持期间占唯一事务槽。
|
||
* DIRECT点不进入选择保持;此参数与命令时标时差time_tag_max_delay_ms独立。 */
|
||
uint32_t select_timeout_ms;
|
||
/* 工作事件生成至Accept/Reject的阶段上限,默认15000;0禁用时长限制。
|
||
* 不保证此期间始终可执行:带时标命令在Accept前仍须满足time_tag_max_delay_ms。
|
||
* 两个数值都是可配置的工程默认,不能用决定期限替代命令的新鲜度检查。 */
|
||
uint32_t decision_timeout_ms;
|
||
uint32_t execute_timeout_ms; /* 动作STARTED至Report_Result,默认60000;0禁用时长限制。
|
||
* 到期/时钟回退安排否定ACT_TERM,结果仍未知,不关闭连接。 */
|
||
uint32_t complete_timeout_ms; /* Report_Result返回OK至Complete,成功/失败结果均适用;默认30000。
|
||
* 到期不发ACT_TERM:应用仍须在期限内显式声明返回信息阶段结束。 */
|
||
uint32_t handover_timeout_ms; /* Complete至最后应答交接,默认60000;也用于ENDED残留回复清理。
|
||
* 执行超时安排TERM后,从进入ENDED另起清理期限;读取FINISHED或发送WAIT不刷新。 */
|
||
uint32_t time_tag_max_delay_ms; /* 默认10000;0只关闭时差检查,仍拒绝IV=1/UTC换算失败。 */
|
||
int16_t master_utc_offset_minutes; /* 主站标准时区,默认480,范围-1439..1439;SU另由公共层处理。 */
|
||
bool negative_on_expired; /* TEST=0默认true否定COT49,受理/动作前均适用;false静默。TEST始终否定。 */
|
||
const IEC104_CommandPoint_t *points; /* 按CA/IOA排序的只读点表,默认NULL;模式由各点决定。 */
|
||
size_t point_count; /* 点数,默认0;须与points同时为空或同时非空。 */
|
||
} IEC104_CommandConfig_t;
|
||
|
||
/* 可按值保存的请求快照;不含站点/ASDU等借用指针。
|
||
* state为单命令0/1、双命令1/2、步调节1降/2升;具体操作含义由应用点表定义。
|
||
* accepted_ms为Handle_Event受理时刻,不是网络接收时间;决定计时不含此前Slave通知排队时间。 */
|
||
typedef struct {
|
||
uint64_t generation, receive_serial; /* 原连接代次、当前工作请求的I帧接收编号。 */
|
||
uint64_t station_id; /* 站点注册身份;同CA重新注册后此值不同。 */
|
||
uint16_t common_address; /* 请求公共地址CA,不接受广播65535。 */
|
||
uint8_t originator_address, type_id; /* 请求源发地址OA、类型45..51或58..64。 */
|
||
uint32_t ioa; /* 非零24位信息对象地址;已通过配置点表的许可检查。 */
|
||
bool is_select, selected; /* S/E及本事务匹配选择标志;51/64两者恒为false。 */
|
||
uint8_t state, qualifier; /* 基础45..47:状态/QU(0..3);48..50:0/QL(仅0);51:0/0。 */
|
||
union {
|
||
int16_t normalized; /* 48/61:原始定点编码,实际值为normalized/32768.0。 */
|
||
int16_t scaled; /* 49/62:有符号标度值。 */
|
||
float short_float; /* 50/63:有限IEEE 754 binary32。 */
|
||
uint32_t bitstring; /* 51/64:32位数据,不包含选择位。 */
|
||
} value; /* 按type_id读取;状态命令清零。 */
|
||
bool has_time; /* 58..64为true,字段含义与对应基础类型相同。 */
|
||
IEC60870_CP56Time2a_t time; /* 解码后的原始时标,保留IV/SU,不是可直接发送的字节布局。 */
|
||
uint64_t time_utc_ms; /* UTC纪元毫秒,含毫秒余数;无时标为0。Accept动作前复查时差。 */
|
||
uint64_t accepted_ms; /* 当前工作请求受理时的单调毫秒。 */
|
||
} IEC104_CommandRequest_t;
|
||
|
||
/* SELECT和EXECUTE为待决定工作事件;FINISHED仅通知清理,无需应答。 */
|
||
typedef enum {
|
||
IEC104_COMMAND_SELECT = 1, /* 应用检查策略并Accept/Reject选择,可执行返校动作。 */
|
||
IEC104_COMMAND_EXECUTE, /* 应用Accept/Reject执行;selected区分选择后执行和直接执行。 */
|
||
IEC104_COMMAND_FINISHED /* 该事务唯一的结束通知,原因及副作用标志在事件中给出。 */
|
||
} IEC104_CommandEventType_t;
|
||
|
||
/* 首次结束时冻结,后续STOP/Cancel不会覆盖;枚举不表示设备输出已停止。 */
|
||
typedef enum {
|
||
IEC104_COMMAND_FINISH_NONE = 0, /* 工作事件的占位值,不是FINISHED的正常原因。 */
|
||
IEC104_COMMAND_FINISH_COMPLETED, /* 应用报告成功,Complete后最后应答已交接。 */
|
||
IEC104_COMMAND_FINISH_EXECUTION_FAILED, /* 输出已启动,但应用报告失败,协议收尾已交接。 */
|
||
IEC104_COMMAND_FINISH_REJECTED, /* 应用Reject,或动作返回NOT_STARTED。 */
|
||
IEC104_COMMAND_FINISH_ACTION_FAILED, /* 动作返回FAILED/非法值,可能存在副作用。 */
|
||
IEC104_COMMAND_FINISH_MISMATCH, /* 选择确认被接手后,同一点执行的类型/OA/值/限定词不符。 */
|
||
IEC104_COMMAND_FINISH_DEACTIVATED, /* 主站COT=8成功撤销尚未启动执行的事务。 */
|
||
IEC104_COMMAND_FINISH_SELECT_TIMEOUT, /* 选择保持到期,释放选择,已被发送层接手的确认无法撤回。 */
|
||
IEC104_COMMAND_FINISH_DECISION_TIMEOUT, /* 未及时Accept/Reject,模块安排否定确认。 */
|
||
IEC104_COMMAND_FINISH_EXECUTE_TIMEOUT, /* 未及时Report_Result,结果未知;安排否定TERM,连接继续运行。 */
|
||
IEC104_COMMAND_FINISH_CANCELLED, /* 本地Cancel结束事务。 */
|
||
IEC104_COMMAND_FINISH_STOPPED, /* 原连接STOPDT停用。 */
|
||
IEC104_COMMAND_FINISH_DISCONNECTED, /* 原连接断开。 */
|
||
IEC104_COMMAND_FINISH_CONNECTION_CHANGED, /* 新连接代次或会话身份已失效。 */
|
||
IEC104_COMMAND_FINISH_SEND_ERROR, /* 发送ERROR/FATAL,且不是等待分派正常STOP通知。 */
|
||
IEC104_COMMAND_FINISH_SERVICE_ERROR, /* Slave服务错误或内部身份/应答资源无法继续使用。 */
|
||
IEC104_COMMAND_FINISH_COMPLETE_TIMEOUT, /* 已报告结果,未在期限内Complete;不安排ACT_TERM。 */
|
||
IEC104_COMMAND_FINISH_HANDOVER_TIMEOUT, /* Complete后必要回复仍未交接;已入HIGH的帧不撤回。 */
|
||
IEC104_COMMAND_FINISH_TIME_EXPIRED, /* Accept动作前复查时标已过期,未调用本次动作。 */
|
||
IEC104_COMMAND_FINISH_TIME_REJECTED, /* Accept动作前基准不可用、回退、越界或时标超前。 */
|
||
IEC104_COMMAND_FINISH_DUPLICATE_SELECT /* 同点合法重复选择终结旧选择,否定确认针对新请求。 */
|
||
} IEC104_CommandFinishReason_t;
|
||
|
||
/* 事件是可保存的纯值,应答须原样传回;调用方不能用修改request改变实际执行内容。
|
||
* 任何工作事件曾被取走的事务,恰好交付一次FINISHED;后者无需应答。
|
||
* 应用跨循环持有站点/context或异步动作时,应在首个工作事件时自行Acquire,
|
||
* FINISHED清理且物理输出确已结束后Release,不能等读到FINISHED后才申请引用。 */
|
||
typedef struct {
|
||
IEC104_CommandEventType_t type; /* 决定事件的处理方式,参与身份校验。 */
|
||
uint64_t instance_id, transaction_id, event_serial; /* 实例、事务、事件三层身份,原样回传。 */
|
||
IEC104_CommandRequest_t request; /* 最后接纳的工作请求,不被撤销/不匹配请求覆盖。 */
|
||
IEC104_CommandFinishReason_t reason; /* 仅FINISHED有效;工作事件为NONE。 */
|
||
bool select_effect, execute_effect; /* 仅FINISHED有效:对应动作曾STARTED/FAILED,可能需清理。 */
|
||
bool return_info_undelivered; /* 仅FINISHED有效:有已接手返回信息尚未进入SendBuffer或无法确认。
|
||
* 结束时冻结;不涵盖应用尚未提交OK的帧,不表示对端是否收到。 */
|
||
} IEC104_CommandEvent_t;
|
||
|
||
typedef enum {
|
||
IEC104_COMMAND_ACTION_NOT_STARTED = 0, /* 必须保证没有任何副作用。 */
|
||
IEC104_COMMAND_ACTION_STARTED, /* 选择生效或输出启动;输出结果另行报告。 */
|
||
IEC104_COMMAND_ACTION_FAILED /* 未报告启动成功,但可能已留下副作用。 */
|
||
} IEC104_CommandActionResult_t;
|
||
|
||
/* Accept同步调用的动作,不保存函数/context指针。
|
||
* context为应用传入的上下文,可为NULL;request由模块内部快照构造,仅本次调用有效。
|
||
* 须短时返回,不得保存request指针、推进Slave或发布上报;设备的异步完成用Report_Result报告。
|
||
* 回调期间仅可Get_Status/Get_Transaction;其他修改入口拒绝重入。
|
||
* 返回值须准确说明是否有副作用,非法值按FAILED处理,模块不会重试动作。 */
|
||
typedef IEC104_CommandActionResult_t (*IEC104_CommandAction_t)(void *context,
|
||
const IEC104_CommandRequest_t *request);
|
||
|
||
typedef enum {
|
||
IEC104_COMMAND_RESULT_SUCCEEDED = 1, /* 启动后设备实际执行成功。 */
|
||
IEC104_COMMAND_RESULT_FAILED /* 启动后设备实际执行失败,不等同于拒绝启动。 */
|
||
} IEC104_CommandResult_t;
|
||
typedef enum {
|
||
IEC104_COMMAND_REJECT_NEGATIVE = 1, /* 通用策略拒绝,回COT=7、P/N=1。 */
|
||
IEC104_COMMAND_REJECT_UNKNOWN_IOA, /* 点表不存在此IOA,回COT=47、P/N=1。 */
|
||
IEC104_COMMAND_REJECT_INTERLOCK, /* 应用确认遥控执行软压板状态错误,回COT=48、P/N=1。 */
|
||
IEC104_COMMAND_REJECT_TIME /* 应用确认遥控执行时间戳错误,回COT=49、P/N=1。 */
|
||
} IEC104_CommandRejectCause_t;
|
||
typedef enum {
|
||
IEC104_COMMAND_EVENT_ERROR = -1, /* 参数/来源/服务错误;不能据此重放已产生的动作。 */
|
||
IEC104_COMMAND_EVENT_IGNORED = 0, /* 不接手,I帧可继续交后续处理器。 */
|
||
IEC104_COMMAND_EVENT_HANDLED = 1 /* 已接手,包括校验拒绝/计数丢弃,不应再走44兜底。 */
|
||
} IEC104_CommandEventResult_t;
|
||
typedef enum {
|
||
IEC104_COMMAND_NEXT_ERROR = -1, /* 句柄/参数/重入或服务错误,输出未写入。 */
|
||
IEC104_COMMAND_NEXT_EMPTY = 0, /* 暂无可交付事件,可能须先读Slave通知;输出未写入。 */
|
||
IEC104_COMMAND_NEXT_READY = 1 /* 已交付纯值事件,同一事件不会再次出队。 */
|
||
} IEC104_CommandNextResult_t;
|
||
/* 以下为共同分类;OK究竟消费事件、记录结果还是接手ASDU,以各接口说明为准。
|
||
* WAIT均未接手本次应用输入;Submit_Return_Info的OK表示原文已由HIGH路径接手,不保证相对NORMAL的采集顺序。 */
|
||
typedef enum {
|
||
IEC104_COMMAND_REPLY_STALE = -2, /* 身份/阶段已失效、事件已消费或事务结束,不得重试旧操作。 */
|
||
IEC104_COMMAND_REPLY_ERROR = -1, /* 参数/用法/重入或服务错误,检查接口具体前置条件。 */
|
||
IEC104_COMMAND_REPLY_WAIT = 0, /* 等待通知/确认/FIFO/网络,保留输入,推进事件循环后重试。 */
|
||
IEC104_COMMAND_REPLY_OK = 1 /* 本次操作已接手;不保证设备成功、网络ACK或FINISHED已就绪。 */
|
||
} IEC104_CommandReplyResult_t;
|
||
typedef enum {
|
||
IEC104_COMMAND_PHASE_SELECT_WAIT = 1, /* 等应用决定选择;决定期限从事件生成开始。 */
|
||
IEC104_COMMAND_PHASE_SELECTED, /* 已选择,等待匹配执行;选择确认可能仍未交接。 */
|
||
IEC104_COMMAND_PHASE_EXECUTE_WAIT, /* 等应用决定执行;已停止选择期限。 */
|
||
IEC104_COMMAND_PHASE_EXECUTING, /* 已启动,等待结果/返回信息/Complete/最后应答交接。 */
|
||
IEC104_COMMAND_PHASE_ENDED /* 协议已结束,可能仍保留FINISHED或未交接应答。 */
|
||
} IEC104_CommandPhase_t;
|
||
|
||
typedef struct {
|
||
bool active; /* 尚未ENDED;不是当前连接是否可操作的保证。 */
|
||
IEC104_CommandPhase_t phase; /* 当前协议阶段;结果报告和Complete不另建阶段。 */
|
||
bool confirm_submitted; /* 当前工作请求的确认已交给发送层,不表示写完或ACK。 */
|
||
/* result_reported:结果已冻结、执行期限停止;completed:已接手Complete,返回阶段关闭;
|
||
* term_submitted:ACT_TERM已被发送层接手;提前取消/断线可能不提交,不能据此等事务结束。
|
||
* 执行结果超时会安排TERM,但result_reported和completed仍为false,不伪造应用结果或Complete。 */
|
||
bool result_reported, completed, term_submitted;
|
||
} IEC104_CommandTransactionInfo_t;
|
||
|
||
/* 累计计数从Create起维护;查询不改变阶段、不做超时转换。
|
||
* busy表示事务槽仍占用,包含待消费FINISHED及模块内待提交应答;正常完成另等尾帧HANDED。
|
||
* 提前结束时,已入HIGH的帧可在槽释放后继续交接;独立短应答不占事务槽。
|
||
* need_process不因发送WAIT持续置true;每轮网络推进后仍须Process重试。
|
||
* 计数用途是诊断,不是可靠账单;各计数可重叠,unsigned long到达上限后自然回绕。 */
|
||
typedef struct {
|
||
uint64_t generation; /* 当前已分派的连接代次,断线后为0。 */
|
||
/* active:模块已处理ACTIVATED且尚未停用,不代替操作前的实时会话校验;
|
||
* events_pending:须优先读取Slave通知;need_process:有可立即推进的内部工作;
|
||
* timer_active:当前启用了非零时长期限;原决定/选择/执行阶段另检查时钟倒退。
|
||
* 完成/交接/ENDED清理阶段仅在对应期限非零时检查回退。 */
|
||
bool active, events_pending, need_process, timer_active;
|
||
bool busy; /* 唯一事务槽仍占用,此时其他站点/其他IOA也不能新建事务。 */
|
||
bool time_base_valid; /* 持有时间基准;不表示推算时尚未越界,STOP/断线不清除。 */
|
||
/* 当前阶段期限剩余毫秒;无期限/已到期/时钟倒退时为0。
|
||
* 不表示命令时标还有效多久,也不保证Accept可执行;查询不做动作前时效判断。 */
|
||
uint32_t timeout_remaining_ms;
|
||
/* pending_replies为模块仍持有的应答数,不含发送层已接手的帧和应用保留的返回信息;
|
||
* pending_events为尚未取走的工作事件或FINISHED数,本版最多1。 */
|
||
unsigned pending_replies, pending_events;
|
||
/* accepted:受理的选择/执行数(选择后执行计两次,含无应用事件的TEST);
|
||
* selected/executed:真实应用路径对应STARTED次数,TEST不增加;
|
||
* completed/execution_failed:协议成功/失败收尾数,completed含TEST;action_failed:动作FAILED结束数。 */
|
||
unsigned long accepted, selected, executed, completed, execution_failed, action_failed;
|
||
/* submitted:所有已被发送层接手的帧,含返回信息;negative_submitted:其中P/N=1的应答;
|
||
* return_info_submitted:已接手返回信息;waits:发送接口明确返回WAIT的次数。 */
|
||
unsigned long submitted, negative_submitted, return_info_submitted, waits;
|
||
unsigned long return_info_undelivered; /* 结束时有未确认交接返回信息的事务数,非ASDU数量。 */
|
||
/* rejected:接收校验/点策略/匹配/忙/无选择/重复选择等拒绝数;app_rejected:Reject或NOT_STARTED数;
|
||
* busy_rejected:因事务槽占用拒绝数;overloads:独立应答池满或事务/事件序号耗尽次数;
|
||
* dropped_requests:过载丢新数及决定期间同OA同点激活的静默丢弃数(不含选择阶段的重复选择),
|
||
* 静默不计rejected/busy_rejected/overloads;重复选择复归只计rejected,不计busy_rejected/cancelled;
|
||
* cancelled:本地取消、停用、断线、换代、发送/服务错误导致的事务结束总数。 */
|
||
unsigned long rejected, app_rejected, busy_rejected, overloads, dropped_requests, cancelled;
|
||
/* deactivated:成功撤销数;mismatches:选择失配数;其余三个为各期限导致的结束数。 */
|
||
unsigned long deactivated, mismatches, select_timeouts, decision_timeouts, execute_timeouts;
|
||
/* 事务期限或时间基准检查发现单调时钟倒退的次数;两个检查的计数可能重叠。 */
|
||
unsigned long clock_errors;
|
||
unsigned long time_expired; /* 过期激活或TEST撤销;真实激活静默时不计rejected,否定时另计rejected。 */
|
||
unsigned long time_rejected; /* CP56编码/IV/换算/基准/倒退/推算/超前错误;同时计rejected,不含过期。 */
|
||
unsigned long complete_timeouts, handover_timeouts; /* 两种新增收尾原因,不计completed。 */
|
||
unsigned long dropped_replies; /* 新期限清理时丢弃的本事务模块回复帧数,不含已进HIGH的帧。 */
|
||
unsigned long action_time_expired, action_time_rejected; /* Accept复查失败,不混入受理时标计数。 */
|
||
unsigned long confirm_room_waits; /* Accept确认容量不足次数,不混入发送接口waits。 */
|
||
} IEC104_CommandStatus_t;
|
||
|
||
/**
|
||
* 功能:填写本版默认配置:全局启用45..51、58..64,点表为空;应用须配置具体点才能接收工作事件。
|
||
* 输入参数:config为输出结构;NULL时无操作。
|
||
* 输出参数:启用全部14种类型,点表为空;选择/决定/执行期限为30000/15000/60000毫秒,
|
||
* 完成/交接(及清理)期限为30000/60000毫秒,
|
||
* 收尾规则固定:成功肯定ACT_TERM,报告失败后Complete或执行结果超时否定ACT_TERM。
|
||
* 返回值:无。
|
||
* 说明:决定15s、选择30s、执行60s、完成30s、交接/清理60s。
|
||
* 成功肯定ACT_TERM,报告失败后Complete或等待执行结果超时否定ACT_TERM;业务超时不关闭连接。
|
||
* 时标窗口10s,主站时区UTC+8,过期激活默认安排否定COT49;仅TEST=0可显式关闭。
|
||
* 选择30s为可调整的工程默认;应用可在本函数之后、Create之前修改select_timeout_ms。
|
||
* 默认启用带时标类型;受理前须设置可信时间基准,或显式关闭时差检查。
|
||
* 入参:config为调用方可写结构;NULL时无操作。返回:无;不创建实例或启动计时。
|
||
*/
|
||
void IEC104_Command_Config_Default(IEC104_CommandConfig_t *config);
|
||
|
||
/**
|
||
* 功能:从静态池创建并绑定一个遥控实例;不自动开启Slave或消费其通知。
|
||
* 输入参数:slave为有效服务句柄,寿命覆盖本实例;config按值复制,但其中点表借用至Destroy。
|
||
* 输出参数:成功时初始化空事务、空回复池和零统计,不建立网络监听,也不调用应用代码。
|
||
* 返回值:成功为实例句柄;配置/点表/Slave非法、重复绑定、池或实例身份序号耗尽时为NULL。
|
||
* 说明:入参:slave为有效Slave,寿命须覆盖实例;config非NULL,按值复制,调用后可修改原结构;
|
||
* 但config->points数组仍借用,须直到Destroy成功都有效且不可变,不能传短命局部数组。
|
||
* 必须在开始消费Slave通知之前创建,以完整接收CONNECTED/ACTIVATED。
|
||
* 池容量IEC104_COMMAND_CAPACITY默认等于TCP服务容量;独立应答容量
|
||
* IEC104_COMMAND_REPLY_CAPACITY默认4,均在编译模块时通过宏配置。
|
||
* points=NULL且point_count=0表示合法空表;已启用类型的新激活通过前序校验后回未知IOA。
|
||
* 非空表须按CA/IOA严格升序且唯一;CA/IOA、类型掩码、mode须合法,51/64不得配置为选择执行。
|
||
* 点类型掩码可含全局未启用的已知类型,但不能绕过全局type_mask;没有隐式默认点或通配点。
|
||
* 点表不支持运行时更新;修改策略须停服并取消收尾、Destroy,再以新表Create。
|
||
* 重建后须重新建立连接并完整分派CONNECTED/ACTIVATED,且重新设置时间基准,不继承旧实例会话。
|
||
*/
|
||
IEC104_Command_t *IEC104_Command_Create(IEC104_Slave_t *slave, const IEC104_CommandConfig_t *config);
|
||
|
||
/**
|
||
* 功能:设置可信站内时间基准;utc_ms为UTC纪元毫秒,base_ms为同一时刻的Net单调毫秒。
|
||
* 输入参数:self——本模块实例。
|
||
* utc_ms——UTC毫秒时刻。
|
||
* base_ms——单调时间基准。
|
||
* 输出参数:self——本模块实例的更新结果。
|
||
* 返回值:!Owned(self) || self->in_action || utc_ms > COMMAND_MAX_UTC_MS || base_ms > IEC104_Net_Now_Ms()时返回false;其余分支返回false、true。
|
||
* 说明:不读Clock、不保存回调;影响激活受理及Accept动作前复查,STOP/断线保留基准。
|
||
* 句柄无效、动作回调内、utc_ms超出TIME_MAX_SECONDS*1000+999或base_ms晚于当前Net时间时
|
||
* 返回false且保留原基准;成功返回true。允许尚未激活或离线时设置。
|
||
* max非零时,Accept通过决定期限和旧回复门禁后再次检查;时标到期不得启动动作。
|
||
*/
|
||
bool IEC104_Command_Set_Time_Base(IEC104_Command_t *self, uint64_t utc_ms, uint64_t base_ms);
|
||
|
||
/**
|
||
* 功能:本站时间不可信时清除基准;不取消已受理事务。无效句柄或动作回调内无操作。
|
||
* 输入参数:self——本模块实例。
|
||
* 输出参数:self——本模块实例的更新结果。
|
||
* 返回值:无。
|
||
* 说明:后续受理及Accept复查使用新状态。
|
||
*/
|
||
void IEC104_Command_Clear_Time_Base(IEC104_Command_t *self);
|
||
|
||
/**
|
||
* 功能:归还静态实例槽;不隐式Cancel,不关闭Slave,也不代替应用释放站点引用。
|
||
* 输入参数:self为待销毁句柄。
|
||
* 输出参数:成功清零实例;不隐式Cancel、不读取FINISHED、不关闭Slave。
|
||
* 返回值:成功true,句柄随即失效;条件不满足或句柄无效为false,实例保留。
|
||
* 说明:入参:self为待销毁实例;事务槽、未读事件及全部独立应答槽必须均空,且不在动作回调内。
|
||
*/
|
||
bool IEC104_Command_Destroy(IEC104_Command_t *self);
|
||
|
||
/**
|
||
* 功能:本地结束事务,原因CANCELLED;保留欠应用的FINISHED,清空模块尚持有的全部应答。
|
||
* 输入参数:self为实例句柄;无效句柄或动作回调中调用时无操作。
|
||
* 输出参数:活动事务以CANCELLED结束,所有独立回复丢弃;会话激活状态保持,后续仍可接新请求。
|
||
* 返回值:无。
|
||
* 说明:已交发送层的帧无法撤回;保持会话激活,不回滚物理动作。
|
||
* 入参:self为实例;回调中/无效句柄无操作。返回:无;应用仍须读完FINISHED。
|
||
* ENDED事务保持首次终结原因,不重复产生FINISHED。
|
||
*/
|
||
void IEC104_Command_Cancel(IEC104_Command_t *self);
|
||
|
||
/**
|
||
* 功能:接收Slave通知并推进会话/请求状态;不调用应用动作,不保存event或其ASDU借用指针。
|
||
* 输入参数:self为实例;event须来自所属Slave的NextEvent或合法Copy_Event副本。
|
||
* 输出参数:连接/启停通知更新会话并按原因取消旧事务;I帧交Request处理。
|
||
* 返回值:激活且视图可用时接手配置内的控制类型,当前会话状态通知也为HANDLED;
|
||
* 未激活的I帧、视图不可用、未接手类型或旧代次通知为IGNORED;
|
||
* 参数、来源、重入或服务错误为ERROR。非法请求可否定或丢新计数,HANDLED不表示已应答。
|
||
* SELECT_WAIT/SELECTED期间,同会话、同station_id、同IOA、同T的有效重复选择终结旧选择,
|
||
* 否定ACT_CON回显新请求;不要求OA/值/QU/类型与旧选择相同,但须通过时标及点策略校验。
|
||
* 即首次选择已获肯定确认,再次选择被否定时,首次选择仍会失效,不能继续凭它执行;
|
||
* 已被发送层接手的首次肯定确认不会撤回,模块仍持有的旧确认会清除,不另追加ACT_TERM。
|
||
* 计rejected,旧事件失效;已投递工作事件的事务交付一次FINISHED(DUPLICATE_SELECT)。
|
||
* 否定使用事务自带回复,WAIT或独立短回复池满不阻止旧选择失效;回复/FINISHED收尾后回收槽。
|
||
* 应用按FINISHED清理原返校资源;槽回收后须重新选择获准、确认被接手,才能再受理执行。
|
||
* EXECUTE_WAIT已受理执行请求,即使设备尚未动作也不按上述选择复归;EXECUTING同样隔离。
|
||
* SELECT_WAIT/EXECUTE_WAIT期间,其余同会话、同station_id、同IOA、同T的合法激活按OA区分:
|
||
* 同OA静默丢弃,计dropped_requests;不同OA计rejected/busy_rejected,独立否定ACT_CON回显新请求,
|
||
* 遵循短回复的WAIT/满槽丢新规则。两者均返回HANDLED,不覆盖原请求/事件、不刷新期限;
|
||
* 同OA不比较其余命令字段,此分支仍在时差及点策略之前。格式校验和撤销规则不变。
|
||
* 撤销在COT/CA校验后先查点地址:未知IOA回47,已知点无匹配可撤销事务才回否定9;
|
||
* 地址错误沿用独立短回复,不取消原事务、不刷新其期限,T/OA及请求对象保持回显。
|
||
* QU/QL在同点匹配之前校验:未支持的值独立回否定7/9,不吞成重发、不撤销原选择。
|
||
* TEST通过上述校验后自动模拟确认流程,不生成SELECT/EXECUTE/FINISHED事件;
|
||
* 测试SBO必须先选择并等确认被发送层接手,执行须匹配T/OA及原命令;异OA执行/撤销不取消测试选择,
|
||
* 同T的有效重复选择仍按上述规则复归,TEST不交付FINISHED,且始终与真实事务隔离。
|
||
* 新激活通过时标及既有选择匹配后,先查点再查忙:无点回47;点类型/执行模式不符回否定7。
|
||
* 点级策略拒绝与全局未知类型不同:已识别类型不因该点禁用而回44。
|
||
* 点策略拒绝不建立事务、不生成工作事件/FINISHED,按独立短回复的背压规则交接。
|
||
* 对IGNORED的I帧继续分派后续业务,最后由应用兜底;不要对HANDLED再发44。
|
||
* 说明:入参:self为实例;event是所属Slave按FIFO取出的通知,须在通知内容仍有效时分派。
|
||
* 全部连接/启停通知必须送达;通知消费不受队列里后续WAIT_EVENTS阻挡。
|
||
*/
|
||
IEC104_CommandEventResult_t IEC104_Command_Handle_Event(IEC104_Command_t *self,
|
||
const IEC104_SlaveEvent_t *event);
|
||
|
||
/**
|
||
* 功能:推进会话检查、到期转换、发送队首及事务回收;不调用应用代码。
|
||
* 输入参数:self为实例句柄。
|
||
* 输出参数:每轮至多推进2*(1+独立回复容量)步;队首WAIT或有待消费通知时立即让出。
|
||
* 返回值:true包括无事、背压等待或事务已终结;false为参数/重入或服务错误。
|
||
* 发送故障也可能已经转成FINISHED,此函数返回true不代表链路或设备执行成功。
|
||
* 执行结果超时安排否定TERM并立即产生FINISHED,不关闭连接、不自动重做设备动作。
|
||
* 说明:入参:self为实例;每轮网络/通知处理后调用,最多推进2*(1+独立应答槽数)步。
|
||
* 队首WAIT立即让出,不能用紧循环等待发送;需处理Slave通知/网络后再次调用。
|
||
*/
|
||
bool IEC104_Command_Process(IEC104_Command_t *self);
|
||
|
||
/**
|
||
* 功能:取出一条应用事件,同一工作事件最多交付一次;取出不等于Accept/Reject消费。
|
||
* 输入参数:self为实例;event为非NULL输出结构,只有READY时改写。
|
||
* 输出参数:工作事件交付记录当前和历史交付标志;FINISHED交付清通知义务并尝试释放事务槽。
|
||
* 返回值:READY/EMPTY/ERROR,见NextResult;EMPTY也可能表示须先读Slave通知。
|
||
* 工作事件交付前检查会话/期限,已有FINISHED可在离线或尚有Slave通知时读取。
|
||
* 入口独立检查ENDED残留回复的清理期限;FINISHED已读时也可清理并释放槽,返回EMPTY。
|
||
* 读取FINISHED可能立即释放模块的站点引用,应用跨循环引用必须此前已自行Acquire。
|
||
* 本次触发执行结果超时即可读取FINISHED,否定TERM仍由Process交接;两者不互相等待。
|
||
* 此时事务查询的result_reported/completed仍为false;FINISHED不是设备动作完成证明,
|
||
* 设备尚忙时应用须继续保留自己的资源引用,并拒绝会与现有动作冲突的新命令。
|
||
* 说明:入参:self为实例;event非NULL,接收可按值保存的事件副本,仅READY时写入。
|
||
*/
|
||
IEC104_CommandNextResult_t IEC104_Command_NextEvent(IEC104_Command_t *self,
|
||
IEC104_CommandEvent_t *event);
|
||
|
||
/**
|
||
* 功能:接受一个已由NextEvent交付的工作事件;先消费身份,再同步至多调用一次action。
|
||
* 输入参数:self/event为实例及原工作事件;action/context仅在本次调用借用,不保存。
|
||
* SELECT允许action=NULL,表示逻辑选择生效而无硬件副作用;EXECUTE必须提供action。
|
||
* 输出参数:先等模块旧回复、复查时标和HIGH容量,再准备确认、消费事件和调用动作。
|
||
* 按结果进入选择保持、执行等待结果或ENDED;动作后只提交本次确认。
|
||
* 返回值:OK只表示工作事件已消费,不表示动作STARTED或确认已交接;动作失败也返回OK。
|
||
* WAIT为未读Slave通知、模块旧回复或HIGH确认空间不足;事件未消费,动作未调用。
|
||
* STALE为身份/阶段失效或动作前时标复查终结,不得执行输出;
|
||
* ERROR为参数/重入/服务或确认资源错误,动作未调用。
|
||
* 动作前检查HIGH能容纳2字节条目头及本次确认;动作后只提交本次确认,不推进旧回复。
|
||
* 此容量准入依赖串行调用及回调不修改协议状态;STOP/断线/发送故障仍可能阻止确认。
|
||
* 即使action返回STARTED,提交确认时仍可能结束事务;应用应查询事务并继续接收FINISHED。
|
||
* 说明:入参:self为实例;event须原样传回SELECT/EXECUTE事件;context原样转交action,不保存。
|
||
* SELECT的action可为NULL,选择生效但select_effect=false;EXECUTE必须提供action。
|
||
*/
|
||
IEC104_CommandReplyResult_t IEC104_Command_Accept(IEC104_Command_t *self,
|
||
const IEC104_CommandEvent_t *event, IEC104_CommandAction_t action, void *context);
|
||
|
||
/**
|
||
* 功能:不调用动作,消费工作事件,按指定原因安排否定应答,以REJECTED结束事务。
|
||
* 输入参数:self/event为实例和原事件;cause为通用拒绝、未知IOA、软压板状态错误或时间戳错误。
|
||
* 输出参数:以当前工作请求否定回显7/47/48/49,计app_rejected并产生FINISHED(REJECTED)。
|
||
* 返回值:OK表示事件已消费且应答已安排,可能已提交或因随后故障被取消;
|
||
* WAIT未消费、须先处理通知;STALE身份/阶段已失效;ERROR参数/原因/重入或服务错误。
|
||
* FINISHED可先于否定应答交接,读取FINISHED不代表槽已释放。
|
||
* 说明:event为尚未消费的SELECT/EXECUTE;cause使用RejectCause枚举,不直接传线上的COT值。
|
||
* 软压板状态由应用确认;显式时间拒绝不受过期静默配置影响,不增加自动时标检查计数。
|
||
*/
|
||
IEC104_CommandReplyResult_t IEC104_Command_Reject(IEC104_Command_t *self,
|
||
const IEC104_CommandEvent_t *event, IEC104_CommandRejectCause_t cause);
|
||
|
||
/**
|
||
* 功能:报告设备结果,结果只记录一次并冻结;不发返回信息,也不隐式Complete。
|
||
* 输入参数:self/event为实例及启动成功的原EXECUTE事件;result为SUCCEEDED或FAILED。
|
||
* 输出参数:写入事务result并记录完成期限起点;不发送确认/终止、不关闭返回信息阶段、不调用应用。
|
||
* 返回值:OK已记录;WAIT因未读通知尚未记录;STALE事务结束/超时或事件不符;
|
||
* ERROR参数/结果非法、已报告/已Complete、重入或服务错误。
|
||
* 本次触发执行结果超时后返回STALE;模块已安排否定TERM,不能重新报告结果或重做动作。
|
||
* 说明:本函数及下列Submit_Return_Info/Complete只接受Accept动作返回STARTED的原EXECUTE事件。
|
||
* 入参:self为实例,event为上述事件,result为SUCCEEDED或FAILED。
|
||
* 可早于ACT_CON交接;设备完成后应及时报告,OK停止执行期限并启动complete_timeout_ms。
|
||
*/
|
||
IEC104_CommandReplyResult_t IEC104_Command_Report_Result(IEC104_Command_t *self,
|
||
const IEC104_CommandEvent_t *event, IEC104_CommandResult_t result);
|
||
|
||
/**
|
||
* 功能:通过原连接HIGH提交一帧返回信息,不经过可覆盖的NORMAL队列。
|
||
* 输入参数:self/event为实例和启动成功的EXECUTE令牌;asdu为调用方持有的完整监视ASDU。
|
||
* 输出参数:完整验证104布局、对象、类型、COT、CA及标志;OK后累计发送和返回信息计数。
|
||
* 返回值:OK为发送层已复制到HIGH或SendBuffer,可释放/复用ASDU缓冲,不能重交;WAIT须保留ASDU重试;
|
||
* ERROR为ASDU/参数/重入/服务错误或Complete后仍待收尾,尚未接手;STALE为事务/事件失效。
|
||
* 正常STOP且通知待分派时先WAIT;其他发送ERROR/FATAL终结事务并返回STALE,不可重试旧ASDU。
|
||
* 必要的后续变位由应用另按COT=3上报。
|
||
* 正常结束等待最后一条事务应答进入SendBuffer;异常结束以FINISHED的冻结标志决定补报。
|
||
* 同一HIGH生命周期的返回信息遵守FIFO,最后一条已交接即可证明已接手的前缀全部交接。
|
||
* 返回信息不等待NORMAL排空;同一测点跨HIGH/NORMAL的采样顺序由应用与主站另行约定。
|
||
* 应用未提交OK的后缀仍由应用管理;成功提交不表示对端ACK,断线不会迁移到新连接。
|
||
* 说明:入参:self为实例;event为启动成功的原EXECUTE;asdu为有效、完整的监视方向ASDU。
|
||
* 类型1..21/30..40,至少一对象,COT=11或3,P/N=0,TEST/CA与命令一致;完整校验对象。
|
||
* IOA可与命令IOA不同;应用EXECUTE事件只来自TEST=0,模拟命令不产生返回信息。
|
||
* 调用可以早于或晚于Report_Result,但须早于Complete。
|
||
* 模块有更早待交应答、确认未接手、HIGH无空间或未读通知时WAIT,不缓存ASDU、也不占排序位置。
|
||
*/
|
||
IEC104_CommandReplyResult_t IEC104_Command_Submit_Return_Info(IEC104_Command_t *self,
|
||
const IEC104_CommandEvent_t *event, const IEC60870_Asdu_t *asdu);
|
||
|
||
/**
|
||
* 功能:声明本事务不再产生返回信息;固定安排ACT_TERM并由Process完成后续交接。
|
||
* 输入参数:self/event为实例及启动成功的原EXECUTE事件;设备结果必须已经Report_Result。
|
||
* 输出参数:分配终止FIFO序号,置completed并启动交接期限;成功肯定终止,失败否定终止。
|
||
* 两种已报告结果都占用终止序号,P/N在Submit_Head组包时确定;不会把失败改写成成功。
|
||
* 返回值:OK立即关闭返回阶段,不必重调;WAIT为未读通知,尚未接手;
|
||
* ERROR为尚未报告结果、仍待收尾时重复调用、参数/重入/服务错误;已结束/事件不符为STALE。
|
||
* OK后启动handover_timeout_ms;正常完成须所有必要回复已被接手且事务尾为HANDED。
|
||
* 成功回COT=10/P/N=0,已报告FAILED回COT=10/P/N=1;正常FINISHED须等TERM进入SendBuffer。
|
||
* 到期丢弃本事务模块残留回复,已进入HIGH的帧不撤回;FINISHED冻结补报结果。
|
||
* 等待执行结果超时由模块自动安排否定TERM并立即FINISHED,本接口返回STALE。
|
||
* 超时TERM表示命令服务未确认成功,结果仍未知;否定TERM不能证明物理输出已停止。
|
||
* 说明:入参:self为实例,event为启动成功的原EXECUTE;结果须已报告,全部返回信息须已提交OK。
|
||
* 允许零帧返回信息;可在确认未交接时调用,模块保持确认先于ACT_TERM的顺序。
|
||
*/
|
||
IEC104_CommandReplyResult_t IEC104_Command_Complete(IEC104_Command_t *self,
|
||
const IEC104_CommandEvent_t *event);
|
||
|
||
/**
|
||
* 功能:只读查询仍占槽的事务,可在动作回调内使用,不做会话推进或期限转换。
|
||
* 输入参数:self为实例;event为本事务历史SELECT/EXECUTE或已取FINISHED;info为非NULL输出。
|
||
* 输出参数:当前阶段、是否尚未ENDED、确认/结果/Complete/终止状态;不推进会话或期限。
|
||
* 返回值:true写入快照,ENDED的active=false;无效参数/身份、槽已回收时false且不修改info。
|
||
* 不保留历史事务;刚读出的FINISHED若已触发槽回收,使用它查询也会false。
|
||
* 说明:入参:self为实例;event可为该事务任一已交付的SELECT/EXECUTE/FINISHED;info非NULL。
|
||
*/
|
||
bool IEC104_Command_Get_Transaction(const IEC104_Command_t *self,
|
||
const IEC104_CommandEvent_t *event, IEC104_CommandTransactionInfo_t *info);
|
||
|
||
/**
|
||
* 功能:只读查询会话、调度提示及累计计数,可在动作回调内使用。
|
||
* 输入参数:self为实例;status为非NULL输出,可在动作回调内使用。
|
||
* 输出参数:在累计统计副本上即时计算会话通知、事务占用、待交回复/事件及期限剩余量。
|
||
* 返回值:true写入快照;句柄/参数/Slave服务无效时false且不修改status。
|
||
* events_pending优先读Slave通知;need_process用于立即调度,timer_active配合剩余时间等待。
|
||
* need_process=false不免除每轮网络推进后的Process,也不代表应用没有待重试的ASDU/Complete。
|
||
* 说明:入参:self为实例,status非NULL接收快照;计算剩余时间但不转换已到期事务。
|
||
*/
|
||
bool IEC104_Command_Get_Status(const IEC104_Command_t *self, IEC104_CommandStatus_t *status);
|
||
|
||
#ifdef __cplusplus
|
||
}
|
||
#endif
|
||
#endif /* IEC104_COMMAND_H */
|