/* * IEC104系统命令:104/107测试回显、70初始化结束和105进程/事件缓冲复位。 * Handle_Event/Process不调用应用;Execute_Next仅同步调用一次本次传入的action。 * 全部入口与Slave在同一事件循环串行调用;回调不得推进Slave或重入修改入口。 * QRP=1及已启用的专用QRP在首次STOP/断开前肯定确认按时被协议ACK即确定授权;会话清理不撤销。 * Take_Reset一次性交给应用;显式Cancel仍可主动放弃,且不撤回发送层已接手的确认。 * 广播105按受理时站点快照逐站决定,以实际CA回复;QRP=2逐站清未提交CP56事件。 * 应用先清该站自己的缓冲,库随后清该CA的NORMAL。广播不授权整机复位。 * 专用QRP128..255由应用显式启用,和QRP1同样在ACK后经Take_Reset交出动作许可;库不解释其业务。 * TEST=1的105通过库配置/报文校验后肯定回显并保留T;不调用应用、不清事件、不创建动作授权。 * 专用QRP的肯定测试回复不代表应用批准真实动作;T=0仍须应用决定及有效ACK。 * Create必须早于消费Slave通知;每轮读空并分派通知后执行Process、Execute_Next和Take_Reset。 * 配置统一由IEC104_Startup_Config_Default初始化,默认每次实际START重报已登记的COI。 * 模块不执行实际设备复位,不持久化COI,不保证Type70是START后的第一条I帧。 * 完整状态机、支持范围及示例接入见docs/104/IEC104_SystemCommand_设计架构.md。 */ #ifndef IEC104_SYSTEM_COMMAND_H #define IEC104_SYSTEM_COMMAND_H #include "IEC104_Slave.h" #ifdef __cplusplus extern "C" { #endif typedef struct IEC104_SystemCommand IEC104_SystemCommand_t; /* 功能位按位组合;TEST_COMMAND同时启用104/107,独立于请求COT中的TEST位。 * 105的三个RESET功能都关闭才整体IGNORED,单独关闭的QRP回否定ACT_CON。 */ #define IEC104_SYSTEM_COMMAND_FEATURE_TEST_COMMAND 0x01U /* Type104/107,原文测试回显。 */ #define IEC104_SYSTEM_COMMAND_FEATURE_INIT_END 0x02U /* Type70,按站点快照上送COI。 */ #define IEC104_SYSTEM_COMMAND_FEATURE_RESET_PROCESS 0x04U /* Type105/QRP1,ACK后交出授权。 */ #define IEC104_SYSTEM_COMMAND_FEATURE_RESET_EVENTS 0x08U /* Type105/QRP2,本CA事件清除。 */ #define IEC104_SYSTEM_COMMAND_FEATURE_RESET_PRIVATE 0x10U /* Type105/QRP128..255,显式启用后ACK交授权。 */ /* 两种策略都须先登记COI。ONCE已完成后不会因重连自动重发;未完成轮次仍可在下次激活重试。 * EVERY_START以实际ACTIVATED通知为边界,覆盖同TCP的STOP/START和重连后的START; * 已激活时重复收到START不会形成新激活轮次,也不会仅凭这条重复请求再发Type70。 */ typedef enum { IEC104_SYSTEM_COMMAND_INIT_ONCE = 0, /* 每次登记完整交接一轮;未完成的轮次允许重试。 */ IEC104_SYSTEM_COMMAND_INIT_EVERY_START = 1 /* 每次实际ACTIVATED后再按最近COI发一轮。 */ } IEC104_SystemCommandInitPolicy_t; typedef struct { uint8_t features; /* 默认0x0F,仅标准功能;专用功能须显式加0x10,其他未知位使Create失败。 */ IEC104_SystemCommandInitPolicy_t init_policy; /* 统一配置为EVERY_START;专项可显式采用ONCE。 */ uint32_t decision_timeout_ms; /* 105受理至回调开始前,默认15000ms;0禁用。 */ /* 默认30000ms;从返回ACCEPT的那次回调开始前base_ms算到首次有效ACK,包含回调耗时。 * 正常推进时,确认尚未提交而到期会取消许可并原位转否定ACT_CON,WAIT继续保留回复; * 确认已被发送层接手后到期只取消许可,不再发送相反确认。STOP/断线/Cancel仍按清理处理。 * 0仅禁用业务期限;尚未编号的确认不受链路t1覆盖,可能一直等待容量或观察槽。 */ uint32_t reset_ack_timeout_ms; } IEC104_SystemCommandConfig_t; /* 纯值请求;回调指针只在本次调用有效。Take_Reset交出后station_id不保证节点仍存活。 */ typedef struct { IEC104_SlaveEventIdentity_t identity; /* 原Slave实例和TCP代次;可用于按原身份关闭连接。 */ uint64_t receive_serial, station_id; /* 原接收流水号(诊断)、原站注册编号(查context)。 */ uint16_t common_address; /* 实际目标CA,广播也不返回65535;QRP2不区分同CA历次注册。 */ uint8_t originator_address, qualifier; /* 原OA、QRP(1/2或已启用的128..255);TEST请求不会进入此回调。 */ uint64_t accepted_ms, base_ms; /* Net单调毫秒:受理采样、本次回调开始前采样。 */ } IEC104_SystemCommandResetRequest_t; typedef enum { IEC104_SYSTEM_COMMAND_DECISION_REJECT = 0, /* 必须没有副作用。 */ IEC104_SYSTEM_COMMAND_DECISION_ACCEPT = 1 /* QRP1/专用QRP仅许可;QRP2已清本CA应用缓冲。 */ } IEC104_SystemCommandDecision_t; /* 同步短时;QRP1/专用QRP不得在回调中执行动作,仅判定是否许可。允许Get_Status和站点只读查询。 * 禁止推进/修改Slave。专用QRP的具体动作由应用约定,库不清NORMAL、不将其解释为整机复位。 * 只按station_id取原站context;不得按CA重查替换节点。每请求的每个目标至多调用一次。 * 广播某站拒绝不阻止后站;应用只授权本CA,不可将一个站的ACCEPT解释为整机许可。 * QRP2返回ACCEPT后库清除失败会返回FAULT,应用动作不可重做或假定已回滚。 */ typedef IEC104_SystemCommandDecision_t (*IEC104_SystemCommandResetAction_t)(void *context, const IEC104_SystemCommandResetRequest_t *request); typedef enum { IEC104_SYSTEM_COMMAND_EVENT_ERROR = -1, /* 参数、重入、归属或内部准备失败;不能继续44兜底。 */ IEC104_SYSTEM_COMMAND_EVENT_IGNORED = 0, /* 非目标类型、功能关闭、旧会话或无关通知。 */ IEC104_SYSTEM_COMMAND_EVENT_HANDLED = 1 /* 含受理、拒绝、丢新、状态处理,不表示已经应答。 */ } IEC104_SystemCommandEventResult_t; typedef enum { IEC104_SYSTEM_COMMAND_EXECUTE_FAULT = -2, /* 动作已调用、库清除失败;继续Process尝试否定。 */ IEC104_SYSTEM_COMMAND_EXECUTE_ERROR = -1, /* 未调用action;参数/重入/前置查询失败。 */ IEC104_SYSTEM_COMMAND_EXECUTE_EMPTY = 0, /* 队首不是DECIDE,未调用action。 */ IEC104_SYSTEM_COMMAND_EXECUTE_WAIT = 1, /* 队首DECIDE保留,先读通知;未调用action。 */ IEC104_SYSTEM_COMMAND_EXECUTE_OK = 2 /* 队首转为回复;可因预检拒绝而未调用action。 */ } IEC104_SystemCommandExecuteResult_t; /* 只读调度与累计计数;计数从Create起累计,Cancel、启停、重连不清零。 * submitted类计数只到发送层接手,不能据此推断已写完、已ACK或实际设备已复位。 * pending_tasks只统计任务FIFO;ACK动作提交后的授权槽、Type70轮次另由专属标志表示。 * 下述ACK动作指QRP1与已启用的专用QRP,不包括QRP2。 */ typedef struct { uint64_t generation; /* 已分派会话代次;尚无会话或已消费DISCONNECTED时为0。 */ /* active为模块维护的激活状态;events_pending要求先分派Slave通知;decide_pending仅指队首DECIDE。 */ bool active, events_pending, decide_pending; bool send_waiting; /* FIFO与Type70各自等待标志的汇总,不用于互相清除。 */ /* 分别为Type70最后凭证仍PENDING、ACK动作观察仍QUEUED/SENT、已具备可领取授权。 * reset_ready表示至少一个授权可领取;广播须等同批回复结束且全部ACK结果确定。 * 已确定授权可跨STOP/断线/换代等待Take_Reset;领取前仍须读空通知。 */ bool handoff_pending, ack_pending, reset_ready; /* 已登记COI、ARMED状态、启动许可、SENDING或HANDOFF状态;ARMED不一定允许立即开始。 */ bool init_registered, init_armed, init_start_allowed, init_round_active; /* 最近非空Type70轮次完整交接时的实际START编号;0表示尚无完成事实。 * 仅末帧HANDED后更新,不以全部提交OK、空轮或首站成功代替;HANDED也不是socket写完或ACK。 * 新轮尚未完成时保留旧值。先分派通知,再结合active、当前generation/activation_id以及 * init_armed/init_round_active判断;累计init_rounds或一个非零历史编号不能证明本轮已初始化。 */ uint64_t init_completed_activation_id; /* need_process表示当前可推进的清理/提交/完成事实;回调内不要求重入推进。 * timer_active只计启用且尚未处理的DECIDE期限及ACK动作确认/ACK期限,不计普通回复。 */ bool need_process, timer_active; uint32_t timeout_remaining_ms; /* 上述期限的最小剩余值;到期或无计时任务时为0。 */ unsigned pending_tasks; /* FIFO占槽数;单播ACK动作在WAIT_ACK后不占;广播逐站回复完才释放整条任务。 */ /* 两种测试命令合计:accepted为合法104/107入槽数,answered为肯定确认提交OK数。 * answered不表示socket写完或收到ACK;否定确认计入negative_submitted,WAIT不重复计数。 */ unsigned long test_accepted, test_answered; /* reset_accepted为合法105请求入槽数(广播只计一次);reset_refused按目标站计决定拒绝 * 或ACK动作提交前到期转否定次数(含部分失败), * 不含Handle_Event校验拒绝。reset_busy为授权槽忙拒绝;reset_cancelled为已ACCEPT的ACK动作取消; * ack_timeouts是reset_cancelled中因业务ACK期限到期的部分。 */ unsigned long reset_accepted, reset_refused, reset_busy, reset_cancelled, ack_timeouts; unsigned long reset_cancelled_handed; /* 确认已被发送层接手,不等于已写出。 */ unsigned long resets_released; /* Take_Reset成功交给应用的次数,不是实际设备复位次数。 */ /* QRP2成功清除的目标站次数、从NORMAL删除的ASDU条数(不计应用缓存),以及执行前原站失效次数。 */ unsigned long events_cleared_requests, events_discarded, station_mismatches; /* 应用ACCEPT后NORMAL清除失败次数;action返回非ACCEPT/REJECT值的次数。 */ unsigned long partial_failures, invalid_decisions; /* Type70整轮交接数、单帧提交OK数、未完成轮次终止数、未发出任何一帧的空轮数。 */ unsigned long init_rounds, init_frames, init_retries, init_empty_rounds; /* 全部提交OK数(含Type70及ACK动作确认),以及其中P/N=1的回复数。 */ unsigned long submitted, negative_submitted; /* rejected仅计Handle_Event校验拒绝;waits计两个发送来源的每次提交WAIT。 * cancelled计普通FIFO任务取消,已ACCEPT的ACK动作与Type70分别计专属取消/轮次计数。 * overloads/dropped_requests同时统计满槽丢新;timeouts仅计DECIDE到期转否定,每条一次。 */ unsigned long rejected, waits, cancelled, overloads, dropped_requests, timeouts; } IEC104_SystemCommandStatus_t; /* 配置由IEC104_Startup_Config_Default的system_config参数初始化,再按部署设置期限与功能。 * 统一策略为标准功能0x0F、EVERY_START、决定15000ms及ACK30000ms;应用仍须显式登记COI。 */ /** * 功能:每Slave一个实例,必须早于消费其通知。复制config,不保存回调、不启动网络。 * 输入参数:slave——所属从站服务。 * config——配置。 * 输出参数:无。 * 返回值: 参数非法、重复绑定或池满返回NULL,不消费通知或自动启动Type70轮次。 * 说明:广播只占一个FIFO槽;内部IEC104_SYSTEM_COMMAND_RESET_CAPACITY默认4,限定待领取QRP1/专用授权数。 * 额外槽仅用于同一广播的不同站,槽不足的站在action前否定;单播仍保持全局复位忙规则。 * 无效Slave/config、未知功能位、非法策略、重复绑定或静态池耗尽时返回NULL。 */ IEC104_SystemCommand_t *IEC104_SystemCommand_Create(IEC104_Slave_t *slave, const IEC104_SystemCommandConfig_t *config); /** * 功能:无效句柄、尚有任务、复位授权/观察槽、进行中的Type70轮次/快照或回调中返回false。 * 输入参数:self——本模块实例。 * 输出参数:self——本模块实例的更新结果。 * 返回值: 无效句柄、动作回调重入或尚有持有责任返回false。 * 说明:不隐式Cancel、不关闭Slave;true后句柄失效。 */ bool IEC104_SystemCommand_Destroy(IEC104_SystemCommand_t *self); /** * 功能:应用显式放弃工作(含已确定但未领取的READY),归还模块引用/ACK观察槽;保留COI登记。 * 输入参数:self——本模块实例。 * 输出参数:self——本模块实例的更新结果。 * 返回值:无。 * 说明:自动STOP/断线清理与此不同:先冻结有效ACK事实,保留已确定的复位决定。 * 已提交确认不撤回,不关闭Slave,后续可继续受理;无效句柄或回调中无操作。 */ void IEC104_SystemCommand_Cancel(IEC104_SystemCommand_t *self); /** * 功能:COI低7位3..31、INIT_END关闭、无效句柄或回调中返回false,其余登记成功返回true。 * 输入参数:self——本模块实例。 * coi——初始化原因。 * 输出参数:self——本模块实例的更新结果。 * 返回值:!Owned(self) || self->in_action || !(self->config.features & IEC104_SYSTEM_COMMAND_FEATURE_INIT_END) || (reason >= 3U && reason <= 31U)时返回false;其余分支返回false、true。 * 说明:活动轮仍使用原COI,新登记只覆盖唯一pending值;空轮等待新的登记或ACTIVATED。 * 已激活时登记也可触发下一轮,不必等待下次START;本调用不发送报文。 */ bool IEC104_SystemCommand_Set_Initialization(IEC104_SystemCommand_t *self, uint8_t coi); /** * 功能:所有Slave通知按FIFO分派;输入事件始终只读,不调用应用、不在本入口发送回复。 * 输入参数:self——本模块实例。 * event——事件。 * 输出参数:self——本模块实例的更新结果。 * 返回值:按处理分支返回IEC104_SYSTEM_COMMAND_EVENT_ERROR、ended ? IEC104_SYSTEM_COMMAND_EVENT_HANDLED : IEC104_SYSTEM_COMMAND_EVENT_ERROR、IEC104_SYSTEM_COMMAND_EVENT_IGNORED、IEC104_SYSTEM_COMMAND_EVENT_HANDLED、Request(self, event, &identity)。 * 说明:104校验固定AA 55,107解析测试序号并校验CP56字段;合法请求保留OA/CA/T及原载荷排普通ACT_CON。 * 两种测试命令均不支持广播,不因T=0产生设备动作;只回一次确认,不追加ACT_TERM。 * 合法105 TEST直接排普通肯定ACT_CON(T=1),不进入DECIDE、不占授权/ACK观察槽。 * 非法限定词、未启用功能及其他报文错误仍按原原因拒绝;非空广播逐站以具体CA回复。 * I帧返回HANDLED后不再兜底;生命周期通知仍应继续分派给其他业务实例。 */ IEC104_SystemCommandEventResult_t IEC104_SystemCommand_Handle_Event(IEC104_SystemCommand_t *self, const IEC104_SlaveEvent_t *event); /** * 功能:每轮网络推进并读空通知后调用,含WAIT重试、全FIFO决定到期转换和ACK结果处理。 * 输入参数:self——本模块实例。 * 输出参数:self——本模块实例的更新结果。 * 返回值:!Owned(self) || self->in_action时返回false;state == IEC104_SLAVE_REQUEST_ERROR时返回false;state != IEC104_SLAVE_REQUEST_READY时返回true;!Advance_Reset(self, now, true)时返回false;其余分支返回false、true。 * 说明:QRP1/专用QRP提交前到期保留原槽转否定回复,同时撤销动作许可;提交后的肯定确认不改写。 * 有界推进,不调用action;参数、重入、会话/ACK查询及内部准备失败返回false。 * true也包含让出通知、等待发送以及发送故障后取消完成,不表示已应答或已复位。 */ bool IEC104_SystemCommand_Process(IEC104_SystemCommand_t *self); /** * 功能:action非NULL,context原样传入;只决定FIFO队首105的当前目标,每次至多调用一次,不保存函数/参数。 * 输入参数:self——本模块实例。 * action——动作回调。 * context——调用方上下文。 * 输出参数:self——本模块实例的更新结果。 * 返回值: QRP2应用已接受但库侧清事件失败返回FAULT,不回滚或重复应用动作。 * 说明:ACCEPT或拒绝后回复由Process提交;提交WAIT不再调用action。EMPTY不表示模块全空。 * FAULT仍留有待发否定回复,应用应记录部分失败并继续Process,不能重做已发生的清除。 */ IEC104_SystemCommandExecuteResult_t IEC104_SystemCommand_Execute_Next(IEC104_SystemCommand_t *self, IEC104_SystemCommandResetAction_t action, void *context); /** * 功能:只有授权READY、通知已读空且服务查询无错误才写出、释放授权并返回true;其余不改输出。 * 输入参数:self——本模块实例。 * request——请求。 * 输出参数:request——请求的更新结果。 * 返回值:成功交出首个可领取的复位请求时返回true;无可领取授权、通知未读或查询失败时返回false。 * 说明:QRP1和已启用的专用QRP共用本入口;应用须按输出的原qualifier及目标CA执行约定动作。 * 广播须等同批全部回复提交完成,且肯定确认均已有效ACK或取消/超时;然后逐站领取。 * STOP/断线清理后,只保留已确定站的许可;每条输出仅代表其实际CA,不代表整机许可。 * 原连接已STOP/断开/换代仍可领取,输出保留原身份;成功后复位责任交给应用,仅能领取一次。 * 须在每轮Step中调用,不能仅等新网络事件;显式Cancel可主动放弃尚未领取的决定。 */ bool IEC104_SystemCommand_Take_Reset(IEC104_SystemCommand_t *self, IEC104_SystemCommandResetRequest_t *request); /** * 功能:只读取得有效SystemCommand实例绑定的Slave,用于跨业务协调前校验归属。 * 输入参数:self——待查询实例;NULL、池外地址或已销毁实例返回NULL。 * 返回值:原绑定Slave的借用指针,不延长其寿命;调用方仍须遵守先销毁业务再销毁Slave。 * 说明:不查询连接、不消费通知、不改变实例;本入口不能证明某轮初始化已完成。 */ IEC104_Slave_t *IEC104_SystemCommand_Get_Slave(const IEC104_SystemCommand_t *self); /** * 功能:只读,回调内允许;无效句柄/输出或服务、凭证、ACK查询失败返回false且不改输出。 * 输入参数:self——本模块实例。 * status——状态快照。 * 输出参数:status——全部查询成功后写回快照,失败保持原值。 * 返回值: Process再次查询会取消错误授权并报告false,调用者按服务错误清理。 * 说明:失败时不得继续使用旧快照做调度;查询不会取消授权、处理到期或推进发送。 * 立即续跑:events_pending || need_process || decide_pending || reset_ready。 * 等待网络上限取timeout_remaining_ms;Get_Status不代替每轮Process。 */ bool IEC104_SystemCommand_Get_Status(const IEC104_SystemCommand_t *self, IEC104_SystemCommandStatus_t *status); #ifdef __cplusplus } #endif #endif /* IEC104_SYSTEM_COMMAND_H */