添加遥控业务代码
CI / L0 静态门禁 (pre-commit) (push) Failing after 2m51s
CI / L0.5 主机侧单测 (MSVC) (push) Successful in 18s

This commit is contained in:
STF
2026-10-30 20:03:19 -07:00
parent 7596f3371a
commit cd42b4d61d
126 changed files with 70586 additions and 149 deletions
File diff suppressed because it is too large Load Diff
@@ -0,0 +1,94 @@
# IEC104 时钟同步模块设计
`IEC104_ClockSynchronization.c/h`处理Type 103(`C_CS_NA_1`)时钟同步请求。模块负责请求校验、排队、站点路由、执行期限及ACT_CON;实际设时仅由应用显式调用`Execute_Next`时提供的同步action完成。`Handle_Event`和`Process`不会调用应用代码,模块不保存action/context,不直接依赖`IEC60870_Clock`或修改系统时钟。
源码:[IEC104_ClockSynchronization.h](../../104/business/IEC104_ClockSynchronization.h)、[IEC104_ClockSynchronization.c](../../104/business/IEC104_ClockSynchronization.c)。接入流程见[完整调用流程](IEC104_完整调用流程.md#flow-clock-synchronization),接口见[API汇总](IEC104_API接口汇总.md#file-24),运行入口见[子站示例](../examples/IEC104子站示例.md)。
## 1. 业务边界
- 只执行Type 103、COT=6的校时激活,动作结束只回ACT_CON,不发送ACT_TERM。
- ACT_CON回显原请求的16字节ASDU,替换COT、P/N并规范VSQ=1;多站广播另替换为目标站CA。CP56原文、SU、OA、TEST及其余对象字节保持原值,不以本站读时或补偿后的时间改写确认。
- 不支持COT=5读时、COT=8撤销或自定义确认时间;这些COT按45处理。没有NTP客户端、网络时延测量、时间质量老化或周期校时线程。
- 同内容的新请求不合并,也不保证幂等。主站重发旧时标可能再次回拨时钟;权限、允许步进幅度及设备副作用由应用action决定。
原文回显是对请求的确认,不是本次执行时刻的测量值。已有`IEC60870_Time`负责CP56/SU/时区转换,`IEC60870_Clock_Set`可作为应用的设备适配;设置失败也不承诺硬件未部分改变,协议模块不提供回滚。
## 2. 对象与固定存储
ClockSynchronization使用独立静态实例池,不占用总召/计数量的召唤引擎实例。`IEC104_CLOCK_SYNCHRONIZATION_CAPACITY`默认等于TCP服务容量,`IEC104_CLOCK_SYNCHRONIZATION_TASK_CAPACITY`默认4。一个Slave至多绑定一个校时实例;Create复制配置并借用Slave,须在开始消费该Slave的通知之前创建。每实例固定任务槽由合法待执行请求及待发否定/错误应答共用,不使用malloc,也不复制整份SlaveEvent。
任务保存原服务身份、必要请求字段、16字节原文及发送状态。应答严格按受理顺序FIFO提交,不越过等待执行或等待发送的旧任务。Execute_Next选最早EXECUTE,可越过较早的REPLY执行下一动作,但对应确认仍在原位等待,不插队。需要新槽而已满时丢弃新请求并增加overloads和dropped_requests;保留连接与已有任务,不覆盖旧任务、不额外执行动作,也不承诺每个超载请求都有响应。
所有调用在同一事件循环串行执行。action必须同步返回,不得保存请求指针、等待异步完成或重入任何修改本模块的入口;action内允许只读`Get_Status`。不为应用创建线程、定时器或时钟锁。Destroy之前先Cancel并完成清理,业务对象的寿命不得超过借用的Slave。
2026-10-29 Windows x64 GCC测得ClockTask为104字节、默认4槽实例为568字节、Request为80字节、Status为72字节;默认单服务的静态实例数组为568字节。此数值不含既有Slave/TCP/发送队列,不能作为MCU预算。示例main的x64单函数栈帧由768增至800字节,执行入口为240字节;完整单函数测量及产物见[测试说明](../test/IEC104测试文档.md#校时固定存储与栈测量),未将单帧结果当作最坏调用链。
### 2.1 请求校验顺序
非103返回IGNORED;以下规则按表中顺序判断,命中后不执行后续业务动作,输入Slave事件保持不变。
| 检查 | 处理 |
| --- | --- |
| 数量不是1,或不足16字节、无法保留唯一完整对象 | rejected加一,HANDLED丢弃,无应答 |
| COT不是6 | COT=45、P/N=1 |
| 定向CA未注册,或广播没有任何可用站点 | COT=46、P/N=1;无站广播保留65535 |
| IOA不是0 | COT=47、P/N=1 |
| SQ、尾字节、P/N、CP56字段、IV、TEST或本站时间范围非法 | 否定ACT_CON,COT=7、P/N=1 |
| 请求有效且有槽 | 保存EXECUTE,accepted加一,等待应用显式执行 |
| 需要保存而槽满 | 丢新并计overloads/dropped_requests,不断链 |
可应答的畸形单对象规范为16字节、VSQ=1,保留原16字节中的其他内容,仅修改COT/P/N及必要的广播目标CA。COT/CA/IOA错误优先于时标等内容错误;错误请求不刷新已有任务期限。HANDLED包含拒绝和丢弃,不表示已经发送响应。
## 3. 时间基准与执行期限
配置`master_utc_offset_minutes`默认为480,表示源报文标准当地时间减UTC的分钟数,合法范围-1439..1439,不包含夏令时。`master_time`保留原CP56解析值,转换时由`CP56_To_Seconds`检查IV并扣除SU对应的一小时;不得先清SU、先减小时或重复补时区。
`accepted_ms`是Handle_Event受理请求时的64位单调毫秒值,`base_ms`是本次执行检查所用的同一单调时钟采样。请求交给action时,`utc_ms`和固定UTC+8的`local_time`均对应`base_ms`。它不是设备设置成功或硬件真正生效的时刻。
计算使用已通过检查的UTC完整秒数:
```c
base_utc_ms = (uint64_t)utc_seconds * UINT64_C(1000) + master_time.time.ms;
limit_ms = ((uint64_t)IEC60870_TIME_MAX_SECONDS - UINT64_C(480) * 60U)
* UINT64_C(1000) + 999U;
```
受理前检查`base_utc_ms <= limit_ms`,保证该时刻可转换为本站日历;CP56转换成合法UTC秒数本身不保证固定UTC+8仍在2099年内。执行时先检查`base_ms >= accepted_ms`,再检查经过时间不大于`limit_ms - base_utc_ms`,之后才相加。最后以`utc_ms / 1000`和`utc_ms % 1000`调用`Seconds_To_Local`,成功后才调用action。不能先窄化为32位再检查,也不能在32位域中乘1000。
这里只补偿受理至执行检查之间的本站滞留,不补偿网络传输、Slave通知FIFO等待及action内部耗时。两次执行不同请求分别按各自受理时刻计算;重新收到旧时标不会自动补上它在主站重试前经过的时间。
`execute_timeout_ms`默认15000,0表示禁用。期限只覆盖尚未调用action的请求,从accepted_ms起算,`elapsed >= timeout`即到期。过期检查和执行补偿使用同一次单调时间采样,避免刚通过期限后又取时、越过边界仍执行动作。动作一旦调用,无论返回true或false,均不再受此执行期限控制;发送等待继续受链路及单帧期限约束。
到期请求转为否定ACT_CON并计timeouts,不调用action。单调时钟倒退显式判断:开启执行期限时按超时处理,禁用期限时按time_errors处理;补偿越界或日历转换失败也不执行action。0及连续相等的单调读数有效。期限不是标准规定的固定时限,也不替代链路t0..t3。
## 4. 执行、应答与发布顺序
正常任务从EXECUTE转为REPLY:`Execute_Next`先检查当前会话、未读通知和期限,再调用本次传入的action一次。true表示动作报告成功,false表示动作报告失败;二者分别生成肯定、否定ACT_CON。action调用期间`confirm_pending`已为true,调用返回后直到确认被发送层接手或任务取消仍保持该屏障。
执行过action的ACT_CON一律通过`Slave_Try_Send_Response`尝试提交,false结果也使用Try。已有HIGH/NORMAL待发原文、当前帧、窗口或记录背压时返回WAIT,模块保留原确认并在Process中重试,**不得再次调用action**。原请求校验失败产生的错误/否定应答通过普通`Slave_Send_Response`直接提交或进入HIGH。
Try返回OK表示原文已被发送层接手、帧顺序已确定,不表示写完socket或对端ACK。已经编号的I帧继续由发送层处理;业务不能因后续STOP撤回它。ERROR若确认来自原会话正常STOP、且通知尚待消费,则先让出等待通知取消;其余ERROR及FATAL取消尚未交接任务。FATAL可能已经写出字节,不重试、不回滚时钟,并继续排空连接通知。
Try只等待提交时已经存在的待发内容,没有为校时建立发送队列隔离区。持续新增NORMAL可能使确认一直WAIT。需要保证校时确认先于新的带时标上报时,应用在`confirm_pending`期间暂停产生这类新上报,继续推进网络以排空已有内容。取时、执行校时、发布及Try提交必须由应用串行协调;该状态不是跨线程锁。
## 5. 站点与广播
定向请求按Slave共用站点表匹配CA,动作请求保留原注册编号station_id;广播station_id为0。应用根据自己的context和该身份取得设备资源。CA=65535使用共用站点快照:受理时确定目标集合,之后新增站点不加入,同CA替代节点不承接旧请求。
广播只执行一次action,因为同一Slave的这些逻辑站共用本次校时动作;随后按快照顺序对仍有效的目标站分别提交同一结果,各应答CA替换为目标站CA。不按站重复设时。发送WAIT期间当前站被删除时,跳过该目标继续后续站;快照/引用按生命周期归还。
广播没有任何可用站点时不调用action,不建立虚构站点;保留原CA=65535生成一帧错误应答。错误COT优先45,COT合法而没有站点则46。具体校验失败不影响已有任务,也不刷新其执行期限。
## 6. 生命周期与事件循环
连接、启停和断线通知须交付所有业务实例;I帧依次交给总召、计数量、校时,均未接手才调用同步Reject_Request兜底。Slave通知优先处理,WAIT_EVENTS表示先继续读通知,不能绕过STOP/START历史仅凭最终激活状态执行旧任务。
每轮读空通知后调用校时Process处理超时及队首应答,再由应用显式调用Execute_Next执行当前允许的请求,继续Process提交确认。Process每步先检查会话和通知,单次最多推进2倍任务容量的步数;队首EXECUTE、发送WAIT或未读通知时让出,不在内部等待应用。等待前重新查询状态:有本地工作时立即推进,有执行期限时用最近剩余值限制等待;发送WAIT后可以等待网络,但网络推进并读空通知后仍要重试Process。
STOP、断线、服务实例/连接代次失效及Cancel取消尚未交接的任务和广播遍历。已经执行的时钟修改保留,不生成补偿动作,也不通过否定应答伪装成未执行。已交接的确认继续按发送层实际状态收尾。模块没有BEGIN/FINISHED业务事件队列;应用以显式执行结果及只读状态观察进度。
## 7. 构建、示例与验证
在Slave及其依赖之外加入`104/business/IEC104_ClockSynchronization.c`,头文件搜索路径包含`104/`、`104/business/`和`common/`。本模块使用公共时间转换工具和Net单调时钟,不要求链接`IEC60870_Clock.c`;应用需要实际设备读写时再选择Clock或自身平台适配。
示例默认只更新模拟时钟,不修改Windows系统时间。实际系统设时必须通过示例的显式模式选择,并由Windows权限决定是否成功;自动回归及本机TCP测试使用模拟模式。协议测试、内存测量和运行限制统一见[测试说明](../test/IEC104测试文档.md)及[示例说明](../examples/IEC104子站示例.md)。
@@ -0,0 +1,218 @@
# IEC104 子站连接协调层
`IEC104_Connection.c/h`是TCP内部的连接协调模块,把接收器、链路状态和发送管理接成一条子站连接。TcpServer提供TCP字节、实际写入结果和单调时间;Connection安排模块调用顺序,不创建socket、线程或系统定时器。
业务的连接与收发统一通过`IEC104_Slave.h`接入,Slave内部持有并调用TcpServer。本文供维护TCP内部实现时阅读,下文的调用方指TcpServer;业务不包含Connection或SendManager头文件,不创建这些对象,也不调用其接口。业务接入示例见[TCP服务设计](IEC104_TcpServer_设计架构.md#4-业务接入)。
## 1. 对象与存储
每个`IEC104_Connection_t`内含独立的Receiver、CONTROLLED角色Link、SendBuffer及SendManager。Manager引用该对象内的Link和SendBuffer,因此**Init成功后不能复制或移动Connection**。所有操作在同一个执行上下文串行进行,内含对象的字段和修改接口不再由业务直接操作。
TcpServer持有Connection,并提供一个ASDU队列、一个控制槽数组及一个发送记录数组。ASDU队列随服务初始化,位于Connection之外,首次连接前和断线期间均可缓存NORMAL原文;它仍属于TcpServer内部存储。各对象、数组、输入和输出存储不得重叠;所有借用存储在Close前持续有效。无动态分配、无业务回调。
各模块的协作边界如下:
| 模块 | 自己维护的规则 | Connection使用方式 |
|---|---|---|
| Link | 启停门控、停止排空、S确认条件和探测进度 | `Can_Prepare_*`查询控制帧准备资格;`Get_Status`提供观察状态和未确认接收数量 |
| Receiver | 半帧/完整帧进度、原文保留及绑定 | `Get_Status`区分新成帧与旧帧;`Peek/Release`交付原文;`Abort`负责清理 |
| SendManager | Link/Buffer初始化及运行期修改、帧与记录关联、ACK交接 | `Submit_Response`准备应答或入HIGH;`Handle_*`统一接收和完成;`Get_Status`提供记录概况;`Get_Deadlines`提供发送期限、队首身份及控制容量 |
| Connection | 调用顺序、过程时间、故障及连接代次 | 先推进STOP确认,再推进普通确认及t3;状态变化立即交给内部通知适配器 |
Link查询与对应Prepare共用同一份准入判断;查询不构帧、不预留控制槽、不消耗帧编号。返回可准备后,Manager仍须检查实际容量并完成准备,WAIT留待下一次驱动。同一连接全程串行调用。
运行期间Connection对Link仅作只读访问,Link和SendBuffer的修改统一由SendManager提交;TESTFR_CON经Manager处理,发送状态也由Manager查询,不直接操作SendBuffer。Connection和SendManager的完整结构体定义保留在内部头文件中,供上层内部对象静态嵌入;TcpServer的公开头文件隐藏这些定义。协议配置统一定义为`IEC104_Types.h`中的`IEC104_ProtocolConfig_t`,本层保留`IEC104_ConnectionConfig_t`内部别名。初始化通过Manager在最终Link/Buffer地址建立绑定,Connection不再修补其内部指针;成功后的对象地址仍须保持不变。
内部初始化关系示例(展示对象绑定顺序;实际存储位于TcpServer内部,业务使用TcpServer的Create/Init):
```c
#include "IEC104_Connection.h"
static IEC104_Connection_t connection;
static IEC104_AsduQueue_t queue;
static uint8_t high_bytes[1024], normal_bytes[4096];
static IEC104_SendBufferControlFrame_t controls[4];
static IEC104_IFrameSendRecordStorage_t records[12];
static int Init_Service_Queue(void)
{
/* 只在服务启动时初始化一次;无连接期间也可由TcpServer缓存NORMAL。 */
return IEC104_AsduQueue_Init(&queue, high_bytes, sizeof high_bytes,
normal_bytes, sizeof normal_bytes, 0U) == IEC104_ASDU_QUEUE_OK;
}
static int Open_New_Connection(uint64_t generation, uint64_t now_ms)
{
IEC104_ConnectionConfig_t config;
IEC104_Connection_Config_Default(&config);
/* 首次连接与重连都绑定已有服务队列;旧连接先Close/Detach,不能重置离线原文。 */
if (IEC104_AsduQueue_Rebind(&queue, generation) != IEC104_ASDU_QUEUE_OK) {
return 0;
}
if (IEC104_Connection_Init(&connection, &queue, controls, 4, records, 12,
&config, generation, now_ms) != IEC104_CONNECTION_OK) {
/* 恢复离线绑定;失败仍须停止接入并由服务层收尾,不能继续使用异常队列。 */
(void)IEC104_AsduQueue_Detach(&queue, generation);
return 0;
}
return 1;
}
```
服务启动先调用一次Init_Service_Queue,再在每次接入时调用Open_New_Connection。连接的`generation`非零且跨连接不复用;队列的代次0仅表示离线缓存,不能用于Connection或发送提交。配置默认k=12、w=8、t1=15000ms、t2=10000ms、t3=20000ms;本地发送及STOP总期限各15000ms,HIGH严格优先。k/w范围1..32767,所有时间期限必须非零,且`t2_ms < t1_ms`;相等或大于均由Init返回ERROR,Connection和队列保持原值。配置在Init时复制,之后通过新连接Init更换。
队列须已绑定同代次,没有保留或已覆盖的待ACK条目;可以已有待发NORMAL。成功初始化清空HIGH、保留NORMAL,链路为STOPPED。调用失败不覆盖Connection或队列。对象首次使用不必预先清零,但运行中不得重新Init;应先按第6节完成Close。
初始化按预检后提交组织:先在局部Connection中校验Receiver及配置;`SendManager_Init_Connection`在局部Link/Buffer/Manager上完成校验,最后清理HIGH,之后将Link和Buffer提交到最终地址并建立绑定。Connection随后复制已初始化的子对象及其余连接字段,没有可失败步骤。构造接口不读取旧目标对象内容,不提供运行会话迁移或任意重绑功能。
## 2. 已连接的完整流程
```text
收到STARTDT_ACT -> Feed受理、立即STARTED并排队STARTDT_CON -> ACTIVATED
Prepare_Next_Send -> 实际写TCP -> Handle_Send_Progress
CON完整写完 -> 仅释放发送任务,不再改变启停状态
TcpServer_Enqueue_Event -> 服务ASDU队列(无连接时也可调用)
TcpServer_Send_Response -> Connection_Submit_Response(校验当前连接代次)
-> Manager.Submit_Response直接准备I帧,或暂存HIGH
服务事件及HIGH积压 -> Prepare_Next_Send生成I帧
两条路径共用发送缓冲和记录
实际写TCP -> Handle_Send_Progress提交整帧完成
Feed收到有效I/S累计ACK -> 更新记录并释放对应NORMAL原文
TcpServer经Connection.Peek_Confirmed_Record读取 -> 复制RECORD事件 -> Remove_Confirmed_Record
业务调用TcpServer_NextEvent -> 处理事件副本
```
准备APDU、TCP整帧写完、对端ACK、转入事件队列、业务处理事件是不同阶段。队列HIGH原文在交接时出队,直接应答不进入ASDU队列;两者的HIGH I帧记录仍等待本地完成及ACK。NORMAL原文等待ACK或被队列覆盖;收到ACK后释放原文,记录保留到TcpServer成功复制为RECORD事件并调用Remove。尚未转移的确认记录仍占记录容量,满时新I帧等待,S/U仍可发送。业务稍后读取事件副本,不负责释放Manager记录。
## 3. 接收与业务读取
`Connection_Feed(connection, generation, data, length, now_ms, &consumed)`最多消费到一帧末尾。TCP输入有多帧时,调用方按consumed推进,继续喂入剩余部分;半帧留在Receiver等待下次输入。`consumed`必填,任何返回都以它为本次实际消费量;参数/旧代次错误消费0字节。
| 返回值 | 当前状态及调用方动作 |
|---|---|
| OK | 输入尚未成帧,或本次S/U已受理并释放;还有未消费尾部时继续Feed |
| FRAME_READY | I帧已通过链路检查、累计ACK已处理;TcpServer经Peek复制I_FRAME事件,成功入队后Release并继续Feed尾部 |
| WAIT | 当前控制请求尚未受理,通常是控制槽已满;保留尾部,驱动发送或Tick后重试 |
| ERROR | 接口参数、身份、阶段或时钟非法;修正调用,不跳过未消费字节 |
| FATAL | 冻结连接,停止正常收发并进入收尾 |
保留完整帧时再次Feed消费0字节,不能把未消费尾部丢弃或忙循环反复调用。一次调用在重试中释放旧帧时也不顺带消费新输入,调用方仍按consumed推进。
Receiver在APDU边界遇到非0x68字节时立即返回FRAME_ERROR,不跳过垃圾重新同步。完整I帧先通过Parse_APCI检查APCI和6字节ASDU公共头空间,再经Parse_ASDU_Header按已知固定长度Type ID、VSQ数量和SQ位检查最低载荷长度。任何格式或最低长度失败均由Connection登记FRAME故障并返回FATAL,随后TcpServer收尾;该帧不会推进V(A)/V(R),其携带的ACK不生效,也不会生成I_FRAME事件。未知/变长类型及零对象的业务合法性仍由应用检查。
I/S统一交给Manager检查序号及累计ACK。I帧受理后设置`rx_link_applied`,后续Tick、Prepare或重复Feed只报告当前帧,不能重复推进V(R)或释放发送原文。S帧没有待业务读取的ASDU,受理后自动释放。
子站受理STOP后立即处于STOPPED/STOP_DRAINING,禁止新I帧;后到START成功受理才重新开放。非法I帧不推进V(A)/V(R),不设置rx_link_applied,不交付业务,Connection冻结并由TcpServer断链。停止等待期间仍处理合法S确认。
`Peek_Received_Frame`向TcpServer返回`IEC104_ConnectionReceivedFrame_t`,包含完整APDU、APCI及ASDU借用地址。TcpServer把完整APDU复制到I_FRAME事件后,用本次`receive_serial`和连接代次调用`Release_Received_Frame`,然后内部视图失效。Release只归还接收空间,不再次处理ACK。相同代次的旧Release也会被编号检查拒绝,不能误释放下一帧。业务通过NextEvent取得独立副本,再用Codec或自己的解析器读取ASDU;链路受理不代表ASDU格式或业务执行已经成功。
普通通知满时仍可处理排在前面的S/U;I帧无处交付时保留原帧并暂停续收。启停使用独立配额:TcpServer通过Set_Transfer_Observer安装内部容量查询和通知复制函数,Connection在改变状态的ACT受理前查容量,满时WAIT保留原帧;状态改变后立即复制通知,再继续检查期限。该适配不调用业务、不重入修改接口,仅只读取得状态快照。重复ACT不产生状态变化,无须新槽。已有发送及协议期限继续推进;NextEvent释放容量后安排Process重试。
U帧路由:
| U帧 | Connection动作 |
|---|---|
| STARTDT_ACT | 先预留控制槽,成功后立即STARTED/IDLE、排CON并取消旧STOP总计时;WAIT保留原请求和状态;实际变化立即通知 |
| STOPDT_ACT | 受理即STOPPED/STOP_DRAINING,清空HIGH并关闭新I帧;停止确认满足后排CON;不等待首个START_CON完成 |
| TESTFR_ACT | 排队TESTFR_CON;控制槽满时保留当前请求 |
| TESTFR_CON | 经Manager.Handle_Testfr_Con提交;OK时结束本端探测t1,IGNORED时保持计时并释放接收帧;不占用控制槽 |
| STARTDT_CON / STOPDT_CON | 格式合法时消费并忽略;不应答、不改变启停或确认期限、不刷新t3,也不产生业务通知 |
反向启停CON在查询启停通知容量及准备控制应答之前释放,不占通知或控制发送槽,不因自身等待资源而阻挡后续输入。该例外只适用于通过Codec完整格式校验的两种CON,其他格式错误及I/S序号、ACK错误仍按原规则冻结连接。忽略后照常执行期限检查和已有控制义务,已到期的真实故障仍可结束连接。
子站START受理后立即开放I/S处理,新的本端报文仍须排在已有CON之后。任何阶段后到START成功受理都立即激活,不再暂存;先前已经排队的STOP_CON仍按FIFO写出,完成不能再次停用链路。
首个START_CON尚未完成时收到STOP,立即停用并推进确认;原CON及部分写入位置保留,不以STOP_CON替换它。Advance_Control每轮最多推进两项,使已覆盖接收数据的S与STOP_CON可依次排队,不必等S完成才生成CON。
START成功受理取消旧STOP计时;新的STOP以原received_at_ms开始总期限。STOP_CON入队时保存其frame_id,只有匹配的最后一帧完成才能结束该停止期限;旧CON完成不影响后续请求。重复STOP不延长有效期限,WAIT尚未受理也不改变状态。取消停止不恢复已丢弃HIGH,不重置I帧t1、S快照和本地发送期限。
## 4. 实际发送
`Submit_Response(connection, generation, asdu, length, now_ms, &head_info)`供TcpServer提交当前请求的应答。它拒绝旧代次、无效原文、已关闭会话和未结束的接收批次;FAILED返回FATAL。先只读查询协议等待时间:期限已到时调用Manager.Enqueue(HIGH),通过启停准入后仅复制到HIGH,交回Process先处理socket中的ACK,再检查是否超时,避免应答入口抢先判定确认丢失。
未到期路径先Drive,再由Manager判断实际准入;期限已到路径直接Enqueue(HIGH),也使用同一准入函数。两条路径均只在STARTED/IDLE接手,其他状态在容量检查前ERROR且不入HIGH;拒绝不冻结或断开连接。已有控制帧时应答暂存HIGH,不越过FIFO发送。
返回SEND_READY时head_info为新应答帧,TcpServer只尝试一次非阻塞写入;OK表示已缓存HIGH;WAIT表示尚未接手;ERROR表示输入/状态/容量不符;FATAL进入收尾。成功后原文已复制,返回后不再借用业务输入。旧HIGH、当前帧、窗口、记录容量及公平配额都由Manager检查,不在Connection重做调度。
STOP受理清空尚未组帧的HIGH,即使它们此前已返回OK;没有逐条作废事件。当前I帧和记录继续完成及等待ACK,NORMAL保持原生命周期。从停用状态重新START仍清理HIGH并重置配额,已启动时重复START保留HIGH。
`Prepare_Next_Send`先重试保留接收帧、检查本地发送及STOP期限并推进控制义务,再向Manager取得待发送数据。**只有SEND_READY时head_info有效**;EMPTY表示没有当前连接可发送的项(可能仍有EOF后留给下一连接的未编号NORMAL),WAIT表示门控、窗口、容量阻塞或旧确认t1已到。TcpServer在EOF时通过AsduQueue停止选取全部未编号NORMAL,已有当前帧及HIGH/控制发送仍走本接口,不在Connection另设EOF状态。接收WAIT不阻止已有发送帧继续写出。发送阶段不直接报告I帧ACK或TESTFR_CON超时故障,调用方须按Get_Wait_Time及时接收并Tick,不能只调用发送接口。
TcpServer在WAIT之后转移已确认记录,若实际释放了记录槽,须重新调用Prepare_Next_Send,不能沿用释放前的WAIT判断EOF收尾。若仍WAIT,内部只读接口`Get_Record_Wait`区分本地可恢复的记录容量等待:记录槽已满、最早记录已完整写出且已ACK,同时Link的`Can_Prepare_I_Frame`允许新I帧,且上次准备时刻没有到期的确认t1,才报告`record_wait=1`。Link查询与实际构帧共用Plan_I_Frame,不在连接层另写启停、k窗口或序号边界规则。查询不推进协议、不移除记录、不分配N(S),仅OK写输出;只用于紧随WAIT的EOF收尾判断,不能替代实际发送准备或期限调度。
准备新I帧前,Connection使用`Collect_Deadlines`取得Manager报告的当前帧存在状态和确认期限。已有I/S/U继续按原顺序发送,包括已编号但尚未写出字节的当前I帧,不能撤回或交错。没有已有帧时,`Get_Confirmation_Timeout`从同一视图选择I帧ACK或TESTFR确认超时:任一等待达到t1就返回WAIT,不调用Manager选择HIGH/NORMAL,不消耗N(S)、记录槽或待发条目。此限制在接收批次内、预算续收期间及常规发送阶段都有效。有效确认解除全部已到期等待后自动恢复;部分ACK若留下另一项已到期等待,仍保持限制。不新增持久状态、恢复计时器或固定宽限时间。
TcpServer把`head_info.pending_data`至`remaining_bytes`交给Net写操作,再把本次成功写入的增量及原`frame_id`传给`Handle_Send_Progress`。同一连接最多一个未回报的写操作。部分发送必须继续当前APDU,不能交错发送另一帧;若后续替换为异步传输,也必须在结束I/O借用后才能调用Connection_Close。
| 写入结果 | 提交方式 |
|---|---|
| 成功写入部分字节 | 回报本次增量,返回OK,保留剩余字节和原期限 |
| EAGAIN / 暂不可写 | 可回报0或等待下次可写事件;继续调用Tick,不延长期限 |
| 写完剩余字节 | 回报实际增量;FRAME_WRITTEN表示对应Link完成、记录更新及缓冲释放均完成 |
| 最终发送错误 | Handle_Send_Failure,匹配当前帧时提交失败并冻结连接 |
完成回报会自动重试受阻的接收请求和控制过程。因此极少数情况下,写入已记账后,后续接收/控制处理失败使本次返回FATAL;此时不能重报写入增量,应冻结后读取记录判断事实。completion仅在FRAME_WRITTEN时写入。
`Handle_Send_Progress`使用实际写入后的单调时刻登记进度、整帧完成及TESTFR起点,不借用send前的旧时刻。它与Submit_Response、Prepare_Next_Send的内部Drive只检查本地发送和STOP期限,继续推进保留帧及控制义务;I帧ACK和TESTFR_CON的t1交给接收阶段判定。这样,即使提交应答时尚未到期、send返回后已经到期,也不会在处理socket中待解析的确认前直接冻结连接。TcpServer安排立即续跑,按原始期限处理确认或报告超时,不增加恢复期限或宽限时间。
本地已知整帧完成必须先回报,再处理覆盖该I帧的ACK,或处理依赖本次发送完成的U帧。异步事件循环须保证这一提交顺序;不能用收到ACK来推定本地发送成功,也不能在Connection之外再次调用底层Complete。
## 5. 时间与驱动
所有`now_ms`使用同一单调毫秒时钟,允许0,按本连接调用顺序不倒退。时钟倒退返回ERROR;旧代次事件在改变时刻前被拒绝。系统定时器只负责唤醒,`Tick`按连接保存的当前过程起点重新计算,不接收旧回调保存的时间差。Tick不准备新的业务I帧。
| 期限/门限 | 起点与结束条件 |
|---|---|
| 本地发送期限 | 当前帧原queued_at_ms;0字节、部分发送和重试不续期;到期提交发送失败 |
| I帧t1 | 最早已整帧完成但未ACK记录的written_at_ms;ACK推进后采用下一记录的原始起点 |
| TESTFR t1 | 本次TESTFR_ACT整帧完成时启动;匹配CON受理后结束;其他收发活动不续期 |
| w/t2确认 | 已受理I帧数量达到w,或连续未确认区间达到t2时安排S;S完成或I捎带完成后更新确认位置 |
| t3空闲 | 除反向STARTDT_CON/STOPDT_CON外,完整合法APDU按成帧时刻更新活动;本地整帧完成也更新;半包、0字节、Peek和WAIT重试不刷新 |
| STOP总期限 | 本轮STOP受理时启用,以原成帧时刻received_at_ms为起点,包含受理前WAIT,至本轮最后一帧STOP_CON完整写出;成功受理START也结束旧期限;重复STOP及旧CON完成均不续期或误清新期限 |
未受理的STOP不会提前设置`stop_timer_active`;受理时才用保留的原成帧时刻建立期限。因此受理前的WAIT已经用尽总期限时,受理后的同轮超时检查即可报告STOP_TIMEOUT。
`Connection_Get_Wait_Time(connection, generation, now_ms, max_wait_ms, &wait_ms)`供TcpServer_Prepare查询协议等待上限,Poll也复用相同查询。它只读汇总上述期限,把等待时长限制在0..max_wait_ms;已到期取0,没有更早期限则保留调用方上限。仅OK修改输出;无效参数/代次、倒退时钟、内部状态异常或尚未结束的接收批次返回ERROR,FAILED返回FATAL。查询不修改last_now_ms或任何计时起点,不准备报文、不登记故障,也不替代Tick;业务不直接调用此内部接口。
`Collect_Deadlines`是本层唯一的期限收集入口,超时检查、发送准入、EOF记录等待判定、控制推进及Get_Wait_Time共用它。Manager.Get_Deadlines提供队首身份、本地发送剩余时间、最早已完成未ACK记录的t1剩余时间以及控制容量;底层各帧的原始时间戳继续由原模块保存。Connection汇入自身TESTFR、STOP、t2、t3的剩余时间,只在栈上形成临时视图,不保存同步副本。活动标志与剩余时间分开,起点0合法,到期剩余时间为0。
控制推进后会重新收集期限,避免继续使用排入S/STOP_CON前的容量或准入状态。t2/t3同时经过Link的Can_Prepare查询和Manager报告的control_has_room判断;已有S在途、探测正在进行或控制槽满时,不因不可推进的旧t2/t3不断唤醒。门控或容量恢复后按原起点重试。时间计算先校验时钟再作64位差值,不用起点加期限。
Check_Timeouts保持本地发送、I帧ACK、TESTFR、STOP的故障优先顺序。本地发送到期时使用同一次查询取得的frame_id向Manager报告失败。接收批次仅决定何时执行确认超时故障;期限视图仍报告实际到期,因此发送准入和等待时间不会把暂缓误当作续期。
t2采用固定存储:保存当前连续未确认接收区间的最早到达时刻,只有Link快照报告`unconfirmed_rx_count == 0`时清除,含义是全部已收I帧都已实际发出确认。S或I仅确认区间前缀时,剩余部分沿用原起点,可能提前发S,不会因部分确认把等待时间向后推。START_CON是否已完成不再限制S准备,实际S发送仍排在已有CON之后。t2到期时Connection请求立即确认,是否允许构帧仍由Link判断。
Feed在接收批次之外先提交已到达的接收事实,再检查全部期限;发送准备和写入回报仅因本地发送及STOP期限直接报告超时,对端确认t1故障由接收阶段判定。发送准备仍查询确认是否到期,用于暂停新I帧准入,不提前冻结连接。同一时刻若先调用Tick触发FATAL,后续事件不能恢复该连接。TcpServer在Process的接收阶段结束时驱动Tick并按实际事件顺序串行提交,Poll复用该推进核心。发送后若查询到期限已到,则登记process_pending,下一轮立即接收;Prepare也始终把到期的协议等待时间报告为0。业务根据TcpServer_Prepare返回的socket/定时/本地条件调度Process,或直接使用Poll。Tick的OK不表示发送缓冲为空,TcpServer后续仍调用内部Prepare_Next_Send检查待发送内容;公开TcpServer_Prepare只查询调度条件,不推进协议。
TcpServer在Process的接收阶段调用`Begin_Receive_Batch(connection, generation)`,然后在预算内Feed、复制I_FRAME事件并释放内部帧,按需完成非阻塞发送。应用将同一轮就绪和定时通知合批交付;批次内只暂缓I帧ACK和TESTFR_CON的t1判定,避免前面的其他报文先触发超时,使后面的有效确认来不及处理。本地发送期限、STOP总期限及格式/协议错误仍立即处理。没有调用Begin时,Feed仍执行即时的完整超时检查。
同一轮接收必须以`Tick`或`Yield_Receive_Batch`结束;重复Begin返回ERROR,Close清除全部批次状态。2026-10-20起,仅因调度预算让出且还有已到达输入时,TcpServer先固定用户态尾部和内核待收字节数,再调用Yield结束当前轮次。`receive_batch_pending`只暂缓对端确认期限;Get_Wait_Time返回0,调用方必须立即续收,不能跨阻塞等待,也不得把后来到达的输入加入旧快照。本地发送和STOP总期限、控制推进及协议错误不受该标志影响。
快照耗尽、接收无进展或真正容量背压时必须调用Tick,清除续收标志并检查全部期限,不能借此等待业务消费或推迟无ACK连接的失败。接口不修改任何期限起点,也不判断内核实际收到字节的时刻。未调用Begin/Yield的Feed保持原行为,发送接口不替代接收及Tick的确认期限检查。异步接入仍须先提交已经完成的本地写入,再喂入依赖该完成的ACK。
## 6. 故障、关闭与恢复
Connection状态为`ACTIVE -> FAILED -> CLOSED`,正常收尾也可从ACTIVE直接Close。ACTIVE只表示可以处理当前连接事件,不表示已经STARTED。
`Connection_Get_Status`组合各模块的数值快照,允许在FAILED/CLOSED时查询;参数、代次或模块状态非法返回ERROR且不改输出。CLOSED不再读取已解除绑定的Receiver/Manager,接收与记录数量为0,链路字段仅为历史值。记录回收接口只要求Manager存储合法,不因Link运行状态异常而阻断读取。
格式/链路错误、发送失败和期限到达会记录首次故障并进入FAILED,后续普通收发入口返回FATAL。此时不自动清空发送记录或NORMAL原文:`Get_Record_By_Offset`可读取全部记录,`Peek_Confirmed_Record`及Remove仍可消费已确认回执,已受理I帧也仍可Peek/Release。`Get_Status`返回阶段、首次原因、启停状态和保留帧概况。这些接口均由TcpServer在内部使用,向业务交付公开的记录事件和状态快照。传输异常由TcpServer调用`Handle_Transport_Closed`冻结;有序EOF采用正常收尾路径,复制剩余记录后调用Connection_Close,不新增故障。未ACK业务仍须根据事件中的记录字段处理。
故障分类按失败来源保留:Receiver的起始字节、长度/APCI或ASDU最低长度错误为FRAME;Manager明确返回PROTOCOL_ERROR的I/S接收拒绝为PROTOCOL。格式合法的反向STARTDT_CON/STOPDT_CON消费并忽略,不登记故障。本地会话或记录预检失败、有效ACK受理后的原文释放失败、合法U帧的控制交接失败均为INTERNAL。START/STOP/TESTFR的合法重复或无匹配确认继续按既有规则受理或忽略。实际发送失败登记TRANSPORT,各类超时保留独立分类;后续清理异常不覆盖已经登记的首次故障。
TcpServer内部的收尾与恢复顺序:
1. 停止实际收发,关闭/取消并等待旧I/O结束,确保没有传输仍借用缓冲。
2. 在Connection_Close之前复制剩余I帧、发送记录及断开通知到事件队列;记录区分本地完成和peer_acknowledged,未ACK不能证明对端未收到。
3. 调用`Connection_Close(旧代次)`,解除内部借用。重复Close同代次返回OK,外部ASDU队列保留。
4. 调用`AsduQueue_Detach(旧代次)`清空HIGH、恢复现存NORMAL待发状态并解除绑定;代次0期间继续接受NORMAL,已覆盖原文无法恢复。转换失败须停止服务,不得重新Init覆盖缓存。
5. 新连接建立时调用`AsduQueue_Rebind(新代次)`,再调用`Connection_Init(新代次)`。新连接重新进行STARTDT,不沿用旧序号;首次连接同样绑定服务启动时建立的队列。
同一TCP上的STOP/START不调用Rebind。旧代次的Feed、发送完成、Tick、Release和Close均不能影响新连接。代次检查解决身份隔离,不能代替结束旧I/O或同步线程;调用方仍须保证被旧I/O引用的内存不会提前复用。
## 7. 构建与边界
Connection部分的生产构建依赖包含:`IEC104_Connection.c`、`IEC104_Receiver.c`、`IEC104_SendManager.c`、`IEC104_SendBuffer.c`、`IEC104_AsduQueue.c`、`IEC104_Codec.c`、`IEC60870_Codec.c`、`IEC104_Link.c`和`IEC104_Link_Slave_StartStop.c`。不依赖主站启停实现、旧全局接收器或日志模块;完整TCP构建还需TcpServer及所选Net后端。
本层负责单条子站连接的内部模块协作。`IEC104_TcpServer.c/h`由Slave持有,负责监听调度、连接生命周期、收发预算和业务事件队列;网络操作及单调计时通过`IEC104_Net.h`执行,当前提供`IEC104_Net_Windows.c`后端。应用使用Slave_Prepare/Process接入自己的事件循环,或使用Slave_Poll组合等待和推进,通过Slave_NextEvent取得ASDU及应答接口;TcpServer在复制事件成功后统一释放协议帧和记录。初始化及收尾见[TCP服务设计](IEC104_TcpServer_设计架构.md)。Connection不依赖Net或操作系统接口;借出的socket仅供应用注册,真实I/O仍在TCP内部,业务不直接驱动Connection。ASDU信息对象处理、业务去重及冗余组切换仍由业务层负责。旧`IEC104.c/h`保留作为历史接口,不参与当前TcpServer接入路径,同一会话不能重复喂给旧全局接收器。
@@ -0,0 +1,48 @@
# IEC104 计数量召唤
`IEC104_CounterInterrogation.c/h`实现 Type 101(C_CI_NA_1)的规则与创建入口,状态机、事件、广播、期限及发送背压由`IEC104_Interrogation`共用引擎维护。总召和计数量召唤各有实例,忙状态独立;共享连接、HIGH队列和发送窗口,任一业务关闭连接都会影响另一业务。
## 1. 请求与数据
请求为104的2/2/3地址布局、单对象、SQ=0、IOA=0、COT=6。QCC低6位RQT为1..4分组或5总请求,高2位FRZ为0读取、1冻结、2冻结并复位、3仅复位。COT=8不支持,返回未知传送原因45。未知CA和非零IOA分别返回46、47;限定词、P/N、忙状态及可可靠回显的畸形单对象请求回否定ACT_CON。无法对应单对象的请求丢弃并统计。输入原文不修改。
读取数据限Type15(SQ=0/1)和Type37(SQ=0)。数据COT使用`request.data_cause`:RQT=5为37,分组1..4为38..41。CA必须为事件中的实际站地址,OA、TEST保持原请求,P/N=0。249字节上限分别容纳30、48、16个对象,并受配置对象数限制。IOA分组、冻结值、BCR序号和品质由应用负责。
## 2. 两种完成方式
| 请求 | 应用处理 | 线路顺序 |
|---|---|---|
| FRZ=0 | BEGIN接受;NEED_DATA提交冻结值;Complete_Data结束 | ACT_CON → 数据批次 → ACT_TERM |
| FRZ=1..3 | BEGIN中通过Execute_Begin执行动作 | 动作完成 → ACT_CON;随后FINISHED |
冻结及复位不产生NEED_DATA,也不发送ACT_TERM。流程依据IEC60870-5-101:2003 §7.4.8模式C的冻结/冻结并复位流程;读取另按模式B进行。目标主站若要求额外终止帧,应作为单独兼容需求评估。Type16及撤销不在104计数量模块的支持范围内。
因此拿动作的BEGIN去调用Submit_Batch会因事件类型不匹配返回STALE,不会发送数据;ERROR仍用于有效NEED_DATA的非法批次。这与最初“无数据也产生NEED_DATA”的草案不同。
`gi_submitted`在计数量实例中统计成功提交完成响应的事务:读取的ACT_TERM或动作的ACT_CON;不是主站ACK计数。总召实例原含义不变。多站读取仍为全部确认、逐站数据、全部终止;多站动作逐站执行和确认,每站独立FINISHED,不保证同时冻结或失败回滚。
## 3. 动作执行与失败边界
应用用`IEC104_CounterInterrogation_Execute_Begin(self, event, action, context)`处理FRZ=1..3。回调签名为`bool action(void *context, const IEC104_InterrogationRequest_t *request)`。接口先检查实例、事件、会话及期限;WAIT/STALE不会调用动作,事件消费后再次调用不会重复执行。TEST动作请求被否定,不调用动作。
回调必须同步、短时完成,不得重入协议接口或推进网络;返回false表示未改变计数器,库生成否定确认。应用须先完成分组、资源等检查,再整体提交修改,不能部分清零后返回false。成功后确认等待不再因业务期限变成否定确认;传输层的发送期限、STOP和断线仍有效。已执行动作不会因连接断开或本地Cancel而撤销。
这个接口适合内存计数器或已准备完成的本地原子提交,不提供异步外部电表事务。异步冻结需要另行管理设备命令、迟到完成和不可撤销结果,不能简单“先发设备命令,稍后Reply_Begin”。主站重新发送一个新请求仍可能再次冻结;本模块不提供跨请求去重或断电持久化事务。
读取的BEGIN继续使用`Reply_Begin`;拒绝未配置分组也使用该接口。不得在可重试的BEGIN处理分支直接清零,再调用Reply_Begin。
## 4. 数据一致性与接入
一次读取必须固定同一冻结版本,包含值、序号、品质及可选时标。应用可复制快照、持有不可变版本,或阻止读取期间改写相关冻结区。WAIT后重组包仍取同一版本。多个Slave共享数据源时同样需要协调,不能只避让本地定时器。Type37时标由应用给出,本模块不读取墙钟。
创建顺序为Slave、站点、总召实例、计数量实例、Slave_Init。计数量调用`IEC104_CounterInterrogation_Create`,配置沿用Config_Default;使用多站广播时,两个实例必须各有独占状态数组。所有连接/启停通知交给两个实例;I帧依次交总召、计数量,均IGNORED才兜底。
每轮先推进Slave并读空通知,再推进两种业务并读取事件。合并两个实例的need_process、events_pending及最小剩余期限;发送WAIT后网络有进展时必须重试。示例轮换两实例的先后次序,避免固定优先级长期占据小窗口。退出时两实例分别Cancel、读完FINISHED、Destroy,然后释放站点与Slave。
## 5. 构建与边界
引擎及种类模块集中在`104/business/`,头文件搜索路径为`104/`、`104/business/`和`common/`。引擎依赖只读规则,不引用具体种类符号。总召工程加入`104/business/IEC104_Interrogation.c`和`104/business/IEC104_GeneralInterrogation.c`;计数量再加入`104/business/IEC104_CounterInterrogation.c`。只用计数量时不需要总召规则文件。默认实例池为TCP服务容量的两倍;只用一种业务可显式定义`IEC104_INTERROGATION_CAPACITY=1`。
规则表及Create_With_Rules属于内部接口;业务使用两个公开创建入口及共用驱动接口。现有总召Create签名保留,所有调用方重新编译。该引擎仍绑定104的Slave、传输及地址布局,尚不是101串口业务适配层。
可运行验证入口及当前记录见[测试说明](../test/IEC104测试文档.md),模拟计数器操作见[示例说明](../examples/IEC104子站示例.md)。
@@ -0,0 +1,458 @@
# IEC104 总召业务模块
`104/business/IEC104_Interrogation.c/h`在`IEC104_Slave`之上实现共用召唤引擎,Type100规则和原Create入口位于同目录的`IEC104_GeneralInterrogation.c/h`。通信服务负责连接、启停、收发和会话身份;引擎负责请求准入、业务阶段、数据批次检查、应答调度及终结通知。本文描述总召行为,应用通过`BEGIN / NEED_DATA / FINISHED`事件提供点表和数据;计数量的差异见第12节。
当前采用**每个实例至多一个未终结总召,忙时否定所有新的总召激活**。空闲时支持全站和全部16个分组,忙时不区分相同或不同QOI。任务池仍保留4个槽,用于一个总召及待发送短应答;没有后续总召等待队列,也没有独立排队超时。
本文描述库本身的设计,不依赖应用模拟点表或可执行程序。完整接入位置见[完整调用流程](IEC104_完整调用流程.md#flow-interrogation),函数声明及返回值汇总见[API接口汇总](IEC104_API接口汇总.md#file-21)。
## 1. 职责与调用关系
所有接口由所属事件循环串行调用。模块不创建socket、线程或系统定时器,不动态分配内存,也不会在`Process`中跳转执行应用代码。异步采样可以由应用自己的线程或设备驱动完成,但结果须回到所属事件循环后提交。
```text
应用事件循环
├─ IEC104_Slave:Poll / Prepare / Process / NextEvent
│ └─ TcpServer → Connection → Link / Receiver / SendManager → Net
└─ IEC104_Interrogation
Handle_Event ← 应用逐条转交Slave通知
Process → 沿保存的原连接身份提交确认、终止及短应答
Submit_Batch → 沿保存的原连接身份尝试直接提交数据,不入队等待
NextEvent → BEGIN / NEED_DATA / FINISHED
Reply_Begin / Submit_Batch / Complete_Data / Fail_Request ← 应用显式应答
```
| 模块 | 自己维护的规则 | 与总召的关系 |
|---|---|---|
| Slave | 服务生命周期、事件来源、连接代次、启停及提交结果 | 总召通过公共接口取得原身份、校验会话和提交应答 |
| TcpServer及内部通信模块 | TCP字节流、APCI序号、k/w、t0..t3、HIGH容量和发送完成 | 总召不直接操作socket、链路状态或发送窗口 |
| Interrogation | 一个总召的准入与阶段、短应答、业务事件及业务期限 | 不持有应用点表,不主动读取设备 |
| 应用 | IOA、分组成员、数据源、遍历状态、资源清理 | 根据业务事件决定接受、逐批取值交付或终结数据 |
`Slave_Get_Event_Identity`校验事件来源;`Slave_Check_Request`判断是否有未读通知、原会话是否仍可提交。总召不自行拼凑TCP状态快照判断连接是否有效。应用应使用Slave和总召公开接口,不访问不透明对象内部字段。
## 2. 对象、身份与固定存储
`IEC104_Interrogation_t`是不透明的静态池句柄,通过`Create`取得,`Destroy`归还。一个Slave只能绑定一个总召实例;须在开始消费Slave通知前创建。配置按值复制,调用方配置返回后可复用;Slave须存活到总召实例销毁之后。
设置config.use_station_registry=true后,总召按请求CA选取本Slave的已注册站点,65535逐站遍历;config.station须NULL,common_address忽略。当前任务持有节点引用,删除使该站立即退出新请求路由,已有任务继续使用原节点。BEGIN携带station_id,应用跨循环保留context时应立即按编号查节点并Acquire,FINISHED清理后Release,防止同CA替换串站。默认false兼容原单CA调用,可选config.station仍固定绑定一个站点并持有到Destroy。注册、引用、延迟回收及快照契约见[共用站点表](IEC104_API接口汇总.md#station-registry)。
| 存储 | 默认容量 | 保存内容与约束 |
|---|---|---|
| 召唤实例池 | `2 * IEC104_TCP_SERVER_CAPACITY` | 同一Slave的总召及计数量各一个;各实例会话、配置、任务及事件独立 |
| 每实例协议任务池 | 4槽 | 至多一个未终结总召;其他槽仅保存单帧应答,也允许4槽全是应答 |
| 每实例业务事件FIFO | 4槽,最小2槽 | 单目标预留FINISHED位置;多目标终结记录保存在调用方状态区,按需交付 |
| 多站广播状态区 | 调用方提供,每目标站一项 | 保存站引用、身份、计时及进度,不保存点值或数据ASDU |
| 总召数据存储 | 不设置私有批次缓冲 | WAIT不接手数据;OK时发送层已复制到当前APDU |
编译实现文件时可覆盖`IEC104_INTERROGATION_CAPACITY`、`IEC104_INTERROGATION_TASK_CAPACITY`、`IEC104_INTERROGATION_EVENT_CAPACITY`。增加任务槽只增加短应答积压容量,不允许第二个总召。任务池设为1仍可工作,但当前总召占槽且短应答不能立即提交时,新请求只能丢弃并计数。
协议任务只保存`InterrogationResponse`:由`Slave_Get_Event_Identity`取得的原服务/实例/连接代次,加10字节Type100 ASDU。合法请求复制原文并处理应答CA;可可靠应答的畸形单对象请求只保存规范为10字节、VSQ=1的否定应答副本,不执行激活或撤销。错误IOA、QOI、OA、TEST等字段仍完整保留。每次发送临时建立ASDU视图,调用`Slave_Send_Response`或`Slave_Try_Send_Response`;任务不保存完整SlaveEvent或自引用接口,源事件出队后可立即复用。固定任务槽及`order[]`调度规则保持不变,非队首短应答完成后仍立即释放对应槽。
2026-10-27按默认4任务槽、4业务事件槽测量,Windows x64 GCC的`sizeof`如下;这是结构存储尺寸,不是STM32的链接占用,Keil结果须另行实测。
| 项目 | 精简前 | 精简后 |
|---|---:|---:|
| 每任务请求存储 | 400字节(完整SlaveEvent) | 40字节(原身份及10字节ASDU,含对齐) |
| 每任务 | 480字节 | 120字节 |
| 每实例4个任务合计 | 1920字节 | 480字节 |
| 每个总召实例 | 2400字节 | 960字节 |
每实例减少1440字节(60%)。任务槽数、业务事件FIFO、TCP通知环、HIGH/NORMAL容量、k窗口及事件覆盖策略均保持原样,节省来自请求表示,不减少背压容量。立即应答也不再在栈上复制完整SlaveEvent;GCC `-O2 -fstack-usage`中该函数从464降至96字节,但这不是ARMCC或完整调用链的实测栈水位。
上表保留请求存储精简阶段的比较。当前Windows x64默认配置实测:总召1240字节、每任务168字节、紧凑请求40字节、业务事件80字节、配置40字节。相对逐站完整执行版本的1192字节,管理对象增加48字节;多目标广播另需调用方提供每站48字节的状态区,13站为624字节。单目标不要求状态区。广播共用一个任务及一套应用取数游标,HIGH/NORMAL和任务/事件容量不变。数值不是目标板RAM实测;站点及Slave开销见[共用站点表](IEC104_API接口汇总.md#station-registry)。
业务事件是纯值结构,可以复制和跨循环保存。`instance_id`区分静态池槽的历次使用,`request_id`在实例内递增,`batch_index`区分本次取数交互;编号耗尽时拒绝新建,不回绕复用。TCP的`generation`属于另一层身份,防止旧请求向新连接发送。
## 3. 请求校验与单总召准入
### 3.1 接收范围及校验顺序
总召使用`C_IC_NA_1`,Type=100、SQ=0、一个对象、IOA=0。支持激活COT=6和撤销COT=8,请求P/N须为0,CA可为已注册站地址或广播65535(0xFFFF);兼容模式只接受其配置站。实际站CA限于1..65534。QOI=20为全站,21..36为第1..16组;分组内容由应用维护。
先校验事件身份,再保护长度并读取类型字节。非100返回`IGNORED`,总召不代替其他业务发送UNKNOWN_TYPE;公共ASDU视图不可用时也返回`IGNORED`,由公共入口处理。正常网络路径的公共头及最低载荷已由Receiver检查,真实截短/帧错误仍沿连接层原策略处理。Type100先判断是否存在唯一完整对象,可靠时按`COT → CA → IOA → 布局/QOI/P/N → 事务状态`处理,避免忙状态掩盖地址或传送原因错误。
| 条件 | 结果 |
|---|---|
| Type不是100,或公共视图不可用 | `IGNORED`;公共入口应先过滤不可用视图,再分派其他业务 |
| Type100对象数为0或大于1,无法确定唯一完整IOA/QOI | 计入rejected并返回`HANDLED`,丢弃新请求,不生成应答 |
| Type100单对象完整,但SQ=1或有多余尾字节 | 仅回否定COT=7/9,COT/CA/IOA错误仍优先45/46/47;不执行激活或撤销 |
| COT不是6或8 | 回COT=45,P/N=1 |
| CA既不是本站地址也不是65535 | 回COT=46,P/N=1,保留请求中的错误CA |
| IOA不是0 | 回COT=47,P/N=1 |
| 激活QOI超范围或P/N非法 | 回否定ACT_CON,COT=7、P/N=1 |
| 撤销QOI超范围、P/N非法或没有匹配对象 | 回否定DEACT_CON,COT=9、P/N=1 |
| 合法激活,已有未终结总召 | 回否定ACT_CON,不替换原请求,不建立第二个总召 |
| 合法激活,空闲且有任务槽 | 保存请求、分配request_id,进入START |
| 合法激活,空闲但任务槽被短应答占满 | 尝试否定确认;不能提交或保存时丢弃新请求并计数 |
确认和错误应答调整COT及P/N;请求CA为65535时,应答CA改为本站地址,其他CA原样保留。OA、TEST、IOA和QOI保持原文,包括错误请求中的原值。畸形单对象的否定副本规范为10字节、VSQ=1,原输入事件不修改;该容错应答是本项目策略,不是将畸形命令视作有效命令。忙拒绝同样使用否定ACT_CON,没有另设“忙”的专用传送原因。
上述请求错误不会关闭TCP、取消已有总召、重置原期限或生成其FINISHED(INVALID_REQUEST),其他CA任务继续。否定应答复用原HIGH/FIFO背压与满槽丢弃策略,不扩大任务或缓冲容量。无唯一对象的丢弃只计入rejected;dropped_requests仍专指无法安全提交/保存的容量丢弃。内部服务故障、会话失效及发送失败继续走原失败路径。
### 3.2 忙状态的起止点
忙状态从合法激活被保存为START开始,早于生成BEGIN和提交肯定ACT_CON。因此,同一批网络通知连续包含多个激活时,只有第一个可建立总召,后续请求立即进入否定应答路径。不能等到应用接受后才设置忙,否则等待应用期间会接入多个总召。
忙状态覆盖BEGIN尚未生成、等待应用接受、确认等待发送、等待数据、有效批次未获发送机会及终止等待发送。相同QOI、不同QOI、不同OA或TEST的新激活都不能覆盖原请求。
| 终结方式 | 何时释放总召资格 |
|---|---|
| 正常完成 | ACT_TERM被发送层接手,释放任务;不等待TCP写完或主站ACK |
| 应用拒绝BEGIN | 生成FINISHED(REJECTED),原任务转为否定REPLY |
| 肯定确认提交前超时或BEGIN数据源失败 | 终结原因保留为对应TIMEOUT或SOURCE_ERROR,原槽转为否定REPLY,保留TCP及其他任务 |
| 主站匹配撤销 | 结束原业务,原任务转为肯定撤销REPLY |
| 本地Cancel、STOP、断线或确认后失败 | 取消总召及本模块待发短应答,保留应有的FINISHED |
单站终结并转为REPLY后不再占用总召资格;多目标广播中某站拒绝、超时或定向撤销时,仍为其他站保留总召资格。广播网络流程结束后进入FINISHING,gi_pending为false,但仍占用状态区并忙拒绝新激活,直到全部FINISHED出队。此前被拒绝的请求不会自动启动,主站需要重新发起。
### 3.3 广播地址与本站地址
广播CA表示请求面向所有站。`IEC104_Types.h`以`IEC104_CA_BROADCAST`定义0xFFFF(65535),它不是实际站地址。开启共用站点表后,多目标广播采用c104的三阶段顺序:先按注册顺序完成各站BEGIN及ACT_CON,再逐站处理全部数据,最后逐站ACT_TERM及FINISHED。例如两站线上顺序为CON1、CON2、DATA1、DATA2、TERM1、TERM2;每站数据可有多批或为空。各站有独立request_id、进度和期限,但共享一个任务和一个取数位置。兼容单站及仅含一个目标的广播保持单目标流程。
接收合法多目标广播时,把目标节点引用保存到`config.broadcast_states`;`broadcast_capacity`须覆盖当时的注册站数。数组由调用方持有至Destroy,地址稳定,不得读写或与其他实例重叠;无需逐项初始化。容量不足在任何肯定确认前整轮拒绝,各站收到否定ACT_CON,并累计overloads,不截取部分站执行。单目标不需要此数组,注册表本身仍无固定站数上限。
目标集合不冻结IOA或点值。后来新增或同CA重建的节点下轮广播才参加;尚未选入BEGIN便被删除的站跳过。已选中站持原引用完成,尤其已确认但尚未取数的站不能因删除而静默消失;应用通过station_id取得原context。无法继续取数时显式Fail_Request。没有注册站时广播回复COT=46并保留65535。忙或错误广播仍使用共用站点快照遍历实际CA,无槽保存遍历时整体丢弃新请求并计数。
每次Process最多推进2倍任务容量步,默认8步;剩余可提交应答通过need_process继续调度。多目标每站状态区保留终结原因,NextEvent按FIFO空位逐个交付,即使13站也只需2槽事件FIFO。发送WAIT不推进当前发送项,仍须重试。确认前拒绝或超时只结束该站并继续确认其他站;确认后取数失败或超时关闭原连接,整轮取消,各已交付BEGIN都有FINISHED。CA选站、QOI选组,两者独立,广播支持20..36。
以仅注册CA=7为例(广播多站时逐站应用同一规则):
| 请求或交互 | CA的处理 |
|---|---|
| 激活或撤销CA=7 | 接受本站寻址,后续应答CA=7 |
| 激活或撤销CA=65535 | 映射到本站7,后续应答CA=7 |
| BEGIN / NEED_DATA / FINISHED | request.common_address均为7,应用无需判断原请求是否广播 |
| Submit_Batch | 必须提供CA=7;CA=65535或其他站地址返回ERROR且不消费当前交互 |
| 肯定/否定ACT_CON、ACT_TERM、肯定/否定DEACT_CON、广播请求的错误应答 | CA均为7,发送等待与确认前失败不改变这条规则 |
| 其他CA且前置校验已通过 | COT=46、P/N=1,保留原错误CA,避免伪装成本站请求 |
输入的`const SlaveEvent`始终保持原文。Request完整解析Type100后选择实际目标站,广播从首站开始;未知CA保留原值。错误原因仍按COT、CA、IOA、QOI/P/N优先检查。撤销匹配本轮活动站集合,不依赖注册表首站或当前取数位置。
内部Copy_Response_Request保存原身份及10字节ASDU,再用临时视图调用Asdu_Set_CA。广播每次切换站点才更新副本CA,同一站的WAIT重试只重建视图、设置COT/P/N并沿用原CA。副本不借用调用方事件,也不重新绑定当前连接。
任务仅保留info这一份业务元数据,数据COT、OA、TEST及CA均按当前任务info检查;CA必须等于当前目标站。错误短应答不生成BEGIN。数据批次不自动改写地址,非法批次返回ERROR供应用修正;同一IOA在不同CA下属于不同点。
`IEC60870_Asdu_Set_CA`是共用ASDU层的字段接口,按COT宽度定位CA并按CA宽度写入小端字节,支持构造容器和借用可写原文。1字节CA只允许0..255,2字节允许0..65535;参数或容器无效时返回ERROR且不修改原文。它不负责站地址的业务合法性,总召配置仍拒绝0和65535。
该规则仅属于Type100处理器。即使CA=65535,Type101等其他有效类型仍返回IGNORED,后续业务模块自行决定其寻址及应答规则。
## 4. 协议阶段与完成含义
```text
空闲收到合法激活
→ START:保存请求,已占用总召资格
→ 业务事件有空位,生成BEGIN,启动业务计时
├─ Reply_Begin(false) → FINISHED(REJECTED) → REPLY(否定ACT_CON)
└─ Reply_Begin(true) → CONFIRM
→ 提交肯定ACT_CON成功 → DATA
→ NEED_DATA → Submit_Batch → OK → 下一个NEED_DATA
→ WAIT → 保留事件和游标,重读当前值后重试
→ NEED_DATA → Complete_Data → TERMINATE
→ 提交ACT_TERM成功 → FINISHED(COMPLETED) → 释放任务
任何未终结阶段:新激活 → 否定REPLY;原总召阶段与进度不变
匹配撤销:停止当前业务 → FINISHED(已取出BEGIN时)→ REPLY(肯定DEACT_CON)
START/CONFIRM超时或BEGIN失败:终结当前业务 → REPLY(否定ACT_CON),保留连接
DATA/TERMINATE超时或NEED_DATA失败:关闭原连接,取消本模块任务,不发成功ACT_TERM
```
| 阶段 | 等待或动作 | 推进条件 |
|---|---|---|
| START | 等事件空位生成BEGIN,随后等应用决定 | 单目标需要BEGIN及终结预留;多目标终结位置由状态区保证 |
| CONFIRM | 提交肯定ACT_CON | 多目标继续下一站确认,全部确认完成后开始数据 |
| DATA | 生成NEED_DATA,应用读取当前值并尝试直接提交 | Submit_Batch返回OK才消费交互、增加批次和对象计数 |
| TERMINATE | 提交ACT_TERM | 发送层接手后终结;发送WAIT时仍然忙 |
| REPLY | 一条否定确认、错误应答或撤销确认 | 提交成功即释放,不产生新的取数交互 |
| FINISHING | 多目标网络流程结束,等待应用读完FINISHED | 最后一个终结事件出队后释放任务及节点引用,才接受新总召 |
| IDLE | 状态查询时表示没有协议任务 | 不表示业务FIFO一定为空,仍可能有FINISHED待取 |
`Reply_Begin / Complete_Data`成功表示应用决定已被模块接手,后续`Process`提交确认或终止。`Submit_Batch`返回OK则表示数据已被发送层接手并确定帧顺序;不再等待Process提交本批。`FINISHED(COMPLETED)`表示ACT_TERM已被发送层接手;这些成功状态均不保证报文写完或被主站确认。发送层可能随后因STOP或连接故障终止传输。
## 5. 应用事件与资源生命周期
### 5.1 三类业务事件
| 事件 | 应用需要做什么 | 应答接口 |
|---|---|---|
| BEGIN | 根据QOI检查数据源并决定是否接受;可延至首个NEED_DATA建立取数游标,不采样整轮数据 | `Reply_Begin(true/false)`;数据源失败可`Fail_Request` |
| NEED_DATA | 应用选择本批IOA与类型,读取当前值和品质后构造非空批次;暂未就绪则保存本事件,继续驱动通信 | `Submit_Batch`、`Complete_Data`、`Fail_Request`三者择一 |
| FINISHED | 停止对应采样工作,按实例/请求编号释放资源 | 无需应答 |
`NextEvent`主动取出事件;事件入队不会执行应用代码。BEGIN或NEED_DATA只有被取出之后才允许应答。工作事件只发出一次,应用暂未就绪时保存事件,不能反复等待模块发出同一事件。
模块核对实例、请求、批次、事件类型、当前阶段和已取出标志。应答时须原样传回事件;实际元数据和发送身份始终使用内部保存的原请求,不依赖应用回传字段构造发送目标。
| 应答结果 | 调用方处理 |
|---|---|
| OK=1 | 交互已消费,不要重复应答;输入ASDU可复用 |
| WAIT=0 | 有未读Slave通知,或Submit_Batch暂不能直接发送;保留事件及游标,推进通信、读空通知后重试;数据批次须重新读取当前值组包 |
| STALE=-2 | 事件已失效或不匹配,停止重试;按FINISHED清理资源 |
| ERROR=-1 | 参数或批次不合法等;通常不消费交互,可修正后重试。NEED_DATA阶段Fail_Request关闭失败是例外,任务仍已终结 |
### 5.2 FINISHED预留
单目标生成BEGIN需要两个业务位置:一个用于BEGIN,一个预留给未来FINISHED。NEED_DATA不能占用终结预留,始终保持`实际事件数 + 终结预留数 ≤ 事件容量`。多目标广播改由每站状态区保存终结记录,因此BEGIN只需一个FIFO空位,所有站可以先确认而不扩大FIFO。pending_events包含尚在状态区中等待入队的FINISHED,可能大于FIFO容量。
应用取出BEGIN后,无论正常完成、拒绝、撤销、STOP、断线、取消或超时,都恰好产生一次FINISHED。BEGIN尚未生成或尚未取出便取消时,移除工作事件并释放预留,不产生FINISHED,因为应用尚未取得请求。取消同时移除未读NEED_DATA;已经取出的旧事件再应答返回STALE。
历史FINISHED保留到应用读取。业务FIFO容量不足时,新的唯一总召可能停留在START等待空位;它已经占用总召资格,但尚未生成BEGIN,不启动业务期限。应用必须及时读完终结事件,不能只等待新的网络通知。默认容量4时可以同时保留旧FINISHED及下一次BEGIN;测试使用最小容量2验证这个边界。
多目标广播进入FINISHING后,连续NextEvent即可读完全部终结记录,无需靠Process搬运。应用不能假定BEGIN与FINISHED严格交替。示例在首个NEED_DATA建立唯一游标,Complete_Data返回OK后立即归还该站取数资源;失败/取消则按FINISHED清理仍在取数的站。若应用在BEGIN另行建立每站资源,须按request_id管理并等对应FINISHED清理。
## 6. 数据批次与发送路径
应用以`Asdu_Create`及信息对象接口构造批次,再调用`Submit_Batch`。模块立即尝试不排队提交,不保存待发批次、应用点表、对象指针或数据源回调。WAIT时输入存储也可复用,但同一业务事件和遍历位置须保留到成功或终结。
IOA、数据类型、分组成员和遍历方式均由调用者决定。BEGIN用于检查数据源和判断是否接受,遍历状态可延至首个NEED_DATA建立,不向库登记或冻结完整IOA列表。应用自行保证总召或分组点的遍历完整性,包括点表变化时如何避免漏点、重复点;库不强制点表在整轮期间保持不变。
推荐接入方式是在每次NEED_DATA组包时读取本批点的当前值和品质,不默认在BEGIN冻结整轮数值。值与品质的读取一致性由数据源保证;逐批取值不承诺整轮所有点属于同一采样时刻。需要固定时刻快照的应用可以自行实现,但必须另行处理快照与突发上报的顺序,不能把快照当成库提供的一致性保证。
总召数据通过`Slave_Try_Send_Response → TcpServer_Try_Send_Response → Connection_Try_Submit_Response → SendManager_Try_Submit_Response`提交,Slave按保存的原身份校验服务实例及连接代次。只有当前发送缓冲空闲、HIGH和NORMAL均无未提交条目、链路和发送窗口允许时,才直接准备I帧并确定N(S)。否则返回WAIT,不把旧值放入HIGH等待。NORMAL中仅保留已提交、待ACK的原文不单独阻挡本批,仍须满足k窗口;不要求等待全部ACK或整轮总召结束。
应用须把“更新当前点值并发布突发”与“读取本批当前值并调用Submit_Batch”放在同一串行执行上下文,或用等效同步保证二者不交错。WAIT之后只保留事件和游标,每次重试重新取值:已积压的突发先发送,随后总召读取最新值;总召返回OK后,本帧顺序已固定,后来发布的突发不能插入该帧之前。这同时避免旧NORMAL被新总召越过,以及新突发之后重发WAIT期间缓存的旧总召值。
这个保证依赖应用发布顺序:库不比较测点版本,无法识别应用在读取之后才迟到发布的旧采样,也无法修正调用者仍使用BEGIN数值快照的做法。突发发送不因总召被暂停;若HIGH/NORMAL持续有待发条目,总召数据可能持续WAIT,本路径没有强制抢占或最长完成时间。应用应按实际负载安排上报频率和批次,不能通过重试旧数值消除等待。
| 检查项 | 要求 |
|---|---|
| 应用层参数 | COT/CA/IOA长度分别为2/2/3 |
| 数据Type | 1、3、5、7、9、11、13、20、21,均为本模块支持的无时标监视信息 |
| 数据COT | 等于原请求QOI:全站20,第1..16组为21..36 |
| CA | 等于配置的本站地址,与业务事件request.common_address一致;不能是65535 |
| OA/TEST | 与原请求一致 |
| P/N | 0 |
| 数量与长度 | 至少1个对象,不超过配置上限及249字节;完整布局有效 |
| SQ及类型切换 | 每批允许SQ=0/1;一个ASDU同一Type,不同批次可切换Type |
返回OK时发送层已复制本批原文,应用可立即复用输入缓冲并推进自己的游标,`batch_index / objects_submitted`也已增加。返回WAIT时不消费NEED_DATA、不推进计数、不保存原文,也不重复生成NEED_DATA;应用先处理通知,交互仍有效时在通信推进后重读同一遍历位置并再次调用Submit_Batch。发送ERROR若确认为正常STOP导致的拒绝,返回WAIT等待通知,随后终结为STOPPED;其他发送ERROR/FATAL以SEND_ERROR终结并返回STALE,不能重试原事件。参数或批次校验ERROR则不消费交互,允许修正。
空数据集或已经遍历完毕使用`Complete_Data`,不能用空ASDU代替结束。未配置分组可以在BEGIN时拒绝;接受的空组仍按ACT_CON → ACT_TERM正常结束。累计量数据不在当前总召批次范围,留给总电度业务。模块不检查IOA是否属于请求的分组,分组筛选和取值由应用负责。
确认、终止和短应答沿原请求connection走普通HIGH应答接口;数据沿同一connection走不排队提交接口,不使用NORMAL,也不进入HIGH等待。只有上一批返回OK后才能完成数据阶段,因此终止不会越过尚未接手的数据。已接手帧按通信层规则发送,不能被新应答越过,也不能通过Cancel撤回。
## 7. 短应答调度与满槽处理
### 7.1 Handle_Event中的提前提交
忙拒绝、地址或COT错误、非法QOI、撤销确认等只需要单帧应答,先尝试提交现有HIGH接口。提前提交必须同时满足:没有未读Slave通知、原会话仍可发送、没有更早形成的REPLY。
```text
形成短应答
→ 有旧REPLY或未读Slave通知:暂不提交
→ 可安全提交:Copy_Response_Request复制请求并写入已确定的应答CA,调整COT/P/N,调用原HIGH接口
├─ 已接手:累计submitted,否定时累计negative_submitted,不占新任务槽
├─ WAIT:未接手,保留/保存为REPLY
├─ ERROR且确认为正常STOP拒绝:保留/保存为REPLY,先交付停用通知
└─ 实际提交错误:按SEND_ERROR等失败路径处理
→ 需要保存但池已满:只丢弃新请求,增加overloads和dropped_requests
```
立即提交不修改调用方事件,不增加绕过通信队列的公开模式。发送成功后本地副本即可释放;WAIT后如需保存任务,以已确定的应答CA建立稳定请求副本,后续只按阶段设置COT/P/N并重试提交。实际连接或发送错误仍按失败路径处理,不能当作普通满槽丢弃。
### 7.2 Process中的选择规则
单帧应答按形成顺序FIFO提交。调度器分别查找唯一总召和最早REPLY,不要求总召位于任务索引队首。总召正在等应用或业务事件空位时,直接处理REPLY;双方都可推进时轮转,避免总召一直挡住短应答,也避免短应答持续占据所有推进机会。
Send_Response内部会推进保留的接收帧并交付通知。Process每步检查FIFO;发送返回值还须区分以下情况,Process、立即应答和Submit_Batch共用同一STOP判定:
| 发送返回值 | 后续处理 |
|---|---|
| OK | 按已接手事实记账/推进,下一次提交前检查通知;不撤回或重发本帧 |
| WAIT | 保留任务并让出;先处理通知,再按原背压规则恢复 |
| ERROR且确认为正常STOP拒绝 | 设置events_pending并让出,保留任务/业务事件,由DEACTIVATED终结为STOPPED |
| 其他ERROR或FATAL | 保留SEND_ERROR失败路径;FATAL可能已写出部分或整帧,不能转成可重试WAIT |
只有ERROR分支额外查询状态:请求须仍属于原服务/实例/代次,TCP仍连接,会话ACTIVE且无故障、队列状态有效,传输已停用并且通知未读,才按正常STOP拒绝让出。不能仅凭FIFO非空忽略错误。成功路径不增加查询;正常STOP拒绝不累计waits、不推进游标、不停止或刷新取数期限。应用先读取Slave通知,旧NEED_DATA随后返回STALE;立即应答保存的短任务也由STOP清理。
Process提交确认、终止或短应答遇到WAIT就结束本轮,保存请求和阶段,下次优先检查最早REPLY。每一步都重新检查Slave通知,发送过程中产生的新通知也必须先处理。不会跨过未读STOP/START或撤销继续发送旧事务。数据WAIT由持有NEED_DATA的应用在通信推进后重读并重试。
`Process(gi)`没有预算参数,也不内部等待:当前站REPLY或终止成功后继续广播或释放任务;DATA只生成NEED_DATA。没有就绪任务、发送WAIT、有未读Slave通知或已推进2倍任务容量步时返回;剩余本地工作由need_process提示续跑。每步发送前重查通知,不执行应用代码。
### 7.3 4个槽的含义
任务池的容量与“同时允许几个总召”是两个独立约束。总召资格上限恒为1,任务池还为无法立即发送的短应答提供存储。忙应答占槽并不代表原激活已被保存,发完否定确认后即释放,不会再生成该请求的BEGIN。
满槽时保留已有任务、应用事件及进度,不主动关闭TCP,不挤掉最早应答。只有新的、无法安全提交或保存的请求被丢弃。`EVENT_HANDLED`包括这种丢弃;应用不能把它当成“主站已经收到应答”,也不能再次投递同一Slave通知。`dropped_requests`用于观察这个情况,主站可能等待超时或自行重试。
## 8. 业务期限与驱动
内部`Task_Timeout`按同一时刻汇总最近剩余时间、超时原因和已确认广播站的总期限到期标志。`Get_Status`读取该结果安排唤醒,`Expire`据此选择拒绝当前站或关闭原连接,不再二次遍历广播站或重新取时判定。结果只在本次调用中使用,不在任务内保存第二份期限状态。
| 配置 | 默认值 | 起止点 |
|---|---|---|
| `begin_timeout_ms` | 15000ms | BEGIN入业务FIFO至应用接受、拒绝或报告失败,包含未取事件的时间 |
| `data_timeout_ms` | 15000ms | 每次NEED_DATA入队至首次有效批次尝试、声明结束或报告失败,每批重新计时 |
| `total_timeout_ms` | 0(默认禁用) | 启用后从BEGIN生成至ACT_TERM被发送层接手,覆盖取数、事件容量等待和发送等待,不等待主站ACK |
三项默认值是本项目的可配置业务策略,不是IEC104规定的总召时限,也不代替链路t0..t3。每项0表示禁用。执行总期限默认关闭,避免慢链路的累计发送等待触发固定整体截止;BEGIN和每批取数期限仍各为15000ms,底层单帧发送、确认和链路探测期限继续有效。需要限制整次总召耗时时,可显式将`total_timeout_ms`设为非零。没有`queue_timeout_ms`;START尚未生成BEGIN时不计业务期限,但此时仍拒绝后续总召。及时消费业务事件是应用的驱动义务,模块不会通过后台线程保证进度。
所有期限使用Net提供的64位单调毫秒时钟,以经过时间比较,避免校时和绝对截止相加溢出。0毫秒有效。业务应答停止对应阶段期限,下一次NEED_DATA重新计时;显式总期限在同一站内不因新批次、忙应答或重试而延长。每站从自己的BEGIN独立计时,包含等待其他站确认、取数及终止的时间;已确认但不在当前取数位置的站也会被检查,到期关闭原连接并取消整轮。没有额外跨全部CA的整体定时器,同一时刻两项到点优先报告TOTAL_TIMEOUT。
有效批次因发送背压返回WAIT时置`data_send_waiting=true`,说明应用已响应,本批取数计时停止,之后不再恢复,下一批NEED_DATA才重新计时。无效批次或因未读Slave通知而提前返回WAIT不停止取数计时。发送等待仍受底层链路期限及显式启用的总期限约束;模块不替应用重读或重试数据,调用方必须持续驱动保留的事件。
Process和有效应用应答都会检查期限。先消费Slave通知,再判断超时,使已经到达的STOP、撤销或断线优先终结事务。到期后旧交互失效,迟到应答返回STALE;具体处理按肯定ACT_CON是否已被发送层接手划分:
| 失败发生的阶段 | 处理方式 | 连接及其他任务 |
|---|---|---|
| START:BEGIN超时、总超时或Fail_Request | 终结当前业务,复用原槽保存否定ACT_CON;保留BEGIN_TIMEOUT、TOTAL_TIMEOUT或SOURCE_ERROR | 保留TCP及已有短应答 |
| CONFIRM:肯定ACT_CON尚未提交成功,总期限到点 | 转为否定ACT_CON,终结原因仍为TOTAL_TIMEOUT | 保留TCP及已有短应答 |
| DATA / TERMINATE:取数超时、总超时或NEED_DATA阶段Fail_Request | 沿原请求关闭连接,取消本模块任务,不补发成功ACT_TERM | 原连接其他业务也会受影响,不关闭后来复用服务槽的新连接 |
分界是发送层接手肯定ACT_CON,不是应用调用Reply_Begin(true),也不是TCP写完或主站ACK。CONFIRM提交返回WAIT时仍可以拒绝激活;肯定确认即使仅进入HIGH或当前发送缓冲,也已经进入DATA,不能再改发否定确认。确认后的断链是本项目当前执行失败策略,不增加按超时类型区分的配置开关。
内部Reject_Request统一处理应用主动拒绝、BEGIN失败和确认前超时,Fail_Interrogation按阶段选择拒绝请求或关闭连接。不能直接从超时处理调用公开Reply_Begin(false):BEGIN可能尚未取出,该接口的校验也会再次检查期限。内部转换先Finish,再将原槽改为REPLY并移到应答顺序末尾;无需空闲任务槽,保留原QOI/OA/TEST,应答CA使用本站地址,旧工作事件立即失效。BEGIN已取出才产生FINISHED,具体失败原因不会统一改成REJECTED。
否定确认继续按现有调度发送,WAIT保留重试,不再计算已终结请求的业务期限。Process检查到确认前超时后会重新检查Slave通知,在本轮继续推进短应答;应用应答接口检查到超时则返回STALE,调用方仍须驱动Process。失败转换完成即释放总召资格,但原槽要到否定确认提交或取消后才归还。主站可以重新发起请求,模块不自动重放旧请求。
等待前查询`Get_Status`。若`timer_active=true`,以`timeout_remaining_ms`限制下一次Poll或应用等待的上限,0表示立即推进;false表示当前没有启用的业务期限,不代表业务已经结束。状态查询只读,不触发发送、终结或超时。
`need_process=true`表示应立即调用总召Process:例如新请求有空位生成BEGIN、业务应答接手后可提交下一帧、读取旧FINISHED后解除事件容量等待,或业务期限已到期。该值按Process同一选择规则计算,既考虑总召,也考虑排队的短应答;它不是`!waiting`,也不保证发送层一定接手。当前帧提交WAIT后暂停本地续跑,避免空转;每次Slave_Poll/Process推进网络并读空Slave通知后,仍须调用总召Process重试,不能以此标志为false跳过网络进展。
应用持有的数据WAIT也须在上述网络推进后重试,不能只等need_process置位或新的NEED_DATA。`data_send_waiting`表示已交付有效数据但等待发送机会;`application_waiting`只表示仍等待应用首次有效应答,两者都不是发送就绪查询。
Get_Status实时检查Slave FIFO;`events_pending=true`时`need_process=false`,先处理可能存在的STOP、撤销或断线。`pending_events`表示另一条业务FIFO,应及时读取;每次读取事件或调用应答接口后重新查询状态。外部事件循环还须合并Slave_Prepare的等待条件,总召的标志不替代TCP的need_process及链路期限。
## 9. 撤销、取消与连接变化
主站撤销为Type100、COT=8,在忙拒绝判断之前按原连接代次、目标CA、OA、TEST和QOI匹配,包括已选中但BEGIN尚未生成的START。定向撤销匹配站,其他站继续;已确认但尚未取数、数据已交完等终止、或已删除的原站均可匹配。尚未选入BEGIN的未来站没有活动事务。广播撤销停止整轮,对每个仍活动的站发送肯定COT=9,不向已结束或尚未启动的未来站补发确认。
撤销确认组复用原任务槽,排在已有短应答之后;即使任务池满也能撤销。当前站待发的否定ACT_CON不会被其他站的撤销确认覆盖。一组撤销确认尚未提交完时,新的重叠撤销按未匹配拒绝;不能安全保存否定回复时按既有满槽策略计数丢弃。已被发送层接手的帧不回滚,不再为被撤销站发送ACT_TERM。
匹配成功后,先通过Copy_Response_Request保存撤销请求并写入应答CA,使用原激活的info和进度生成FINISHED(DEACTIVATED),随后把原槽转换为肯定DEACT_CON。转换不需要额外任务槽,池满仍可撤销;形成的确认排在已有REPLY之后,条件允许时立即提交。已被发送层接手的帧继续在确认前按原顺序发送,本地未提交批次丢弃,不再提交原总召ACT_TERM。
| 操作或通知 | 本模块行为 | 网络确认 |
|---|---|---|
| 匹配COT=8 | 停止当前总召,旧工作事件失效,必要时FINISHED(DEACTIVATED) | 肯定COT=9 |
| 不匹配或重复撤销 | 当前总召保持原状 | 否定COT=9 |
| `Cancel` | 取消总召及待发短应答,保留必要的FINISHED(CANCELLED) | 不自动发送撤销确认或ACT_TERM |
| STOPDT对应DEACTIVATED通知 | 停止本模块任务,必要时FINISHED(STOPPED) | 链路STOP确认由通信层负责 |
| DISCONNECTED | 取消任务、清除已处理代次,必要时FINISHED(DISCONNECTED) | 无业务成功确认 |
| 新CONNECTED或会话已失效 | 旧任务终结为CONNECTION_CHANGED,不跨代次重放 | 后续新激活重新建立事务 |
COT=8的总召撤销与Slave的DEACTIVATED通知不是同一事件:前者结束一个业务,后者表示STOPDT停用。FINISHED表示应用可以清理资源,不承诺撤销确认已发送完成。
非法批次返回ERROR并保留交互,应用可以修正;数据源确实不能继续则调用`Fail_Request`。BEGIN阶段回否定确认并保留连接,NEED_DATA阶段关闭原连接,两者都终结为SOURCE_ERROR。确认后失败仍可能影响同连接其他业务。接受BEGIN前应检查数据源和必要业务资源,减少确认后才发现无法执行的情况;无需预先采样或编码全部数据,仍可逐批交付。
## 10. 应用接入与退出顺序
创建前使用`Config_Default`初始化配置,再按站地址、单批大小和实际业务耗时调整。公开API共12个,调用功能如下:
| 接口(省略IEC104_Interrogation_前缀) | 功能 |
|---|---|
| Config_Default | 填写CA=1、单批127对象及三项默认业务期限 |
| Create | 复制配置、借用Slave,取得静态池实例 |
| Destroy | 任务及业务事件全部为空时归还实例,不关闭Slave |
| Cancel | 本地取消任务并保留应有终结事件 |
| Handle_Event | 校验并接收应用转交的Slave通知,处理准入、短应答及会话变化 |
| Process | 自动推进就绪任务,遇等待条件返回 |
| NextEvent | 主动读取业务事件,只有READY写出结果 |
| Reply_Begin | 应答已取出的BEGIN,明确接受或拒绝 |
| Submit_Batch | 校验当前NEED_DATA对应的非空ASDU,立即尝试不排队提交;WAIT须重读数据后重试 |
| Complete_Data | 声明数据耗尽,后续Process提交ACT_TERM |
| Fail_Request | 报告数据源失败;BEGIN转否定确认并保留连接,NEED_DATA关闭原连接,均保留SOURCE_ERROR |
| Get_Status | 查询进度、累计计数及最近业务期限,不产生副作用 |
```text
Slave_Create / Config_Default / Init
→ Interrogation_Config_Default / Create
→ 循环
1. 驱动Slave,逐条读取并转交连接通知及请求
2. Slave通知未读空时继续处理通知
3. Interrogation_Process
4. Interrogation_NextEvent,处理BEGIN / NEED_DATA / FINISHED
5. 应用数据就绪时显式应答,继续推进
6. 查询Slave等待条件及Interrogation的need_process、事件和期限,再安排等待
→ Interrogation_Cancel
→ 读完业务事件并清理FINISHED对应资源
→ Slave_Close,读空收尾通知
→ Interrogation_Destroy
→ Slave_Destroy
```
网络驱动可以使用Slave的Poll,也可以接入应用自己的Prepare/Process事件循环。数据暂未就绪不能停止驱动网络;应用也不能在忙等待循环中反复调用Process而不处理事件。
`Destroy`不会隐式取消或丢弃事件。即使没有活动总召,只要还有REPLY或未读FINISHED就返回false;调用方完成清理后再销毁。实例创建失败要清理已创建的Slave,不能继续使用NULL句柄。
## 11. 状态与统计
| 字段 | 解释 |
|---|---|
| generation / active | 最近已处理的连接代次和启用状态,不能代替实时会话查询 |
| gi_pending | 总召网络流程未终结;FINISHING虽为false,状态区清理前仍忙拒绝新激活 |
| phase | 当前站阶段,收尾为FINISHING;仅有应答为REPLY,无任务为IDLE |
| pending_requests | 总召、FINISHING及短应答占用的任务槽数,不是等待执行的总召数 |
| pending_events | FIFO事件及状态区中待交付的FINISHED,不包含预留位置 |
| waiting / application_waiting | 存在发送、应用或事件容量等待;后者表示仍等待应用首次有效应答 |
| data_send_waiting | 当前批次已有效尝试但发送WAIT;不保存原文,应用须保留事件、重读数据并重试 |
| events_pending | 当前Slave通知尚未读空,应先处理网络通知 |
| need_process | 当前有需立即推进的本地工作、到期期限或失效会话;发送WAIT后等待网络推进再重试 |
| timer_active / timeout_remaining_ms | 是否启用业务期限及距最近期限的剩余毫秒 |
| batch_index / objects_submitted | 当前总召已提交的批次和对象数;仅有REPLY时保留最早应答的历史进度 |
| submitted / gi_submitted | 被发送层接手的ASDU数 / ACT_TERM提交成功的总召次数 |
| waits | 实际提交返回发送WAIT的次数,不统计应用等待循环次数 |
| rejected | 校验、忙、应用决定、确认前失败和容量原因拒绝的请求数,含无法可靠应答而丢弃的畸形请求 |
| negative_submitted | 发送层已接手的否定应答数,不等于主站已收到 |
| overloads / dropped_requests | 任务池满或广播状态区不足的次数 / 无法安全提交或保存的新请求丢弃数 |
| cancelled | 取消的协议任务数,包含待发REPLY;不等于FINISHED数量 |
| deactivated / timeouts | 成功匹配主站撤销次数 / 执行业务超时次数 |
| last_finish_reason | 最近合法总召的终结原因,BEGIN尚未交付时取消也会更新 |
状态为独立副本,累计计数从Create开始,Cancel和重连不清零。`waiting=true`不代表所有任务都无法推进:总召等数据时仍可提交短应答。`gi_pending=false`也不表示可以直接Destroy,仍须检查待发应答及业务事件。
确认前超时增加timeouts及rejected,BEGIN阶段Fail_Request增加rejected;两者都不增加cancelled或gi_submitted。只有否定确认被发送层接手才增加negative_submitted。REPLY等待期间反复Process不会重复累计超时或交付FINISHED,last_finish_reason保留原终结原因。
## 12. 总电度扩展与设计边界
Type100与Type101分别使用GeneralInterrogation和CounterInterrogation只读规则,共用引擎通过创建时传入的规则执行解析、限定词和数据检查以及完成方式选择,不引用具体种类符号。总召旧Create名称保留;计数量使用CounterInterrogation_Create。同一Slave每种规则至多一个实例;不能复用总召的gi_pending作为全局准入开关。
计数量RQT=1..5、FRZ=0..3;读取接受Type15/37,COT为37..41。冻结/复位通过Execute_Begin先检查请求再执行一次同步动作,肯定ACT_CON提交后完成,不产生NEED_DATA或ACT_TERM。TEST动作拒绝;已执行动作不会因超时转为否定,也不因断线回滚。请求结构追加freeze/data_cause,总召分别为0/QOI。完整约定见[计数量设计](IEC104_CounterInterrogation_设计架构.md)。
接入多个业务处理器时,连接、启停和断线通知应广播给每个相关模块,不能因某个模块返回HANDLED就停止广播;I帧按业务类型分派,未接手的交给后续处理器,最后再由应用兜底。总召模块不实现总电度冻结、复位或累计量点表。
多个业务可以分别持有任务,但仍共享连接、HIGH容量和发送窗口,应用需要持续驱动各模块。业务忙相互独立不代表发送时延相互独立;STOP、断线和任一业务触发的连接关闭会影响同连接所有业务。
本设计参考了[lib60870-C多客户端示例](https://github.com/mz-automation/lib60870/blob/master/lib60870-C/examples/multi_client_server/multi_client_server.c)按连接限制活动总召、忙时及会话槽满时否定确认的做法。该示例仅处理QOI=20,本项目保留20..36分组支持,使用应用主动读取事件、固定请求副本和明确的WAIT重试。其会话槽保存不同连接的活动总召,不能理解为同一连接的后续总召队列。
业务期限、静态容量和忙拒绝是本项目的实现策略。当前不提供多QOI待执行队列,不自动替主站重试,也不通过应用回调获得下一批数据。若现场要求保存连续分组请求,需要单独定义准入、主站确认等待和取消语义,不能仅扩大任务槽数量。
## 13. 验证与调用方迁移
总召基线回归98组,计数量另有12组,合计110组,使用真实Slave/TCP提交路径及可控单调时钟;HIGH缩到251字节、业务FIFO缩到2槽。覆盖原有突发排序、部分写入、取数期限、k=1窗口及到期ACK;多站覆盖13站三阶段顺序、非空混合批次、状态区不足与跨实例重叠、已确认未来站删除/同CA重建、超出FIFO容量的无损FINISHED、各阶段定向及满槽广播撤销、拒绝与撤销同时等待、非当前站总期限,以及总期限禁用、BEGIN先到期和两项同时到期的处理优先级。畸形请求覆盖否定/丢弃边界、输入不变、基础截短仍被Receiver拒绝、原任务/期限保持、背压满槽和广播撤销隔离。提交期STOP覆盖三个入口、真实通知容量背压、FATAL与STOP并存、非STOP的ERROR、OK/WAIT伴随新回执及START后重新总召。真实TCP回环验证命令行单站,使用Windows后端和k=1逐帧核对业务字节。
| 验证范围 | 应满足的结果 |
|---|---|
| 全站及全部16组 | QOI、数据COT、OA、TEST及点对象验证正确 |
| 广播全站及全部16组 | 业务事件、确认、数据、终止均用本站CA;输入Slave事件保持原文 |
| 广播错误、忙拒绝及确认前失败 | 副本建立时使用本站CA,立即提交和等待重试均保持该地址;其他错误CA仍按原值回显 |
| 广播数据地址 | Submit_Batch拒绝65535及其他站地址,应用修正为本站CA后可重试 |
| BEGIN生成前后、确认/数据/终止等待 | 相同和不同QOI的新激活均否定,原身份和进度不变 |
| 完成后重新发起 | 不自动启动被拒绝请求;主站重发后产生新request_id并获得完整期限 |
| 总电度类型隔离 | 总召空闲和忙时,本站或广播CA的Type101均返回IGNORED,不产生总召否定应答 |
| 短应答及满槽 | 安全时提前提交,积压保持FIFO;满槽只丢新请求,旧工作事件仍有效 |
| 远方撤销 | 本站/广播激活与本站/广播撤销四种组合均匹配实际站CA,其他身份仍严格检查;满槽仍可复用原槽 |
| 业务FIFO满 | FINISHED保留;BEGIN前不计业务期限,读出旧FINISHED后才能启动当前请求 |
| 本地续跑 | 事件空位恢复及业务应答后need_process置位;发送WAIT时不空转,网络推进后继续发送;未读Slave通知优先 |
| 三项执行期限 | 迟到应答不能绕过期限,忙应答不刷新总期限,先处理已到达的STOP/撤销 |
| 确认前失败 | 未读BEGIN超时不交付FINISHED;已交付时恰好终结一次,否定确认保留QOI/OA/TEST并使用本站CA |
| 满槽及发送等待期间失败 | 原槽转REPLY,不挤掉旧应答;按形成顺序发送,保留TCP,同连接重试可以完成 |
| 肯定确认提交边界 | CONFIRM发送WAIT时超时回否定确认;确认已接手但尚未写出时,取数失败及超时仍关闭原连接 |
| STOP、断线及实例复用 | 旧请求不能跨会话发送或接受迟到应用应答 |
| 真实TCP连续分组请求 | 第一个完成,后续得到否定确认;结束后重发的请求分别正常完成 |
| 真实TCP广播流程 | 全站、分组、忙拒绝、非法QOI及撤销均返回本站CA;连接继续工作 |
从先前多QOI排队版本迁移时,删除`queue_timeout_ms`、`queued_interrogations`、`queue_timeouts`字段访问,以及`QUEUED / FINISH_QUEUE_TIMEOUT`分支。所有调用方须重新编译并以Config_Default初始化配置。`Process`继续只接收实例,不增加预算参数;原12个总召接口保留,其中Create实现迁至GeneralInterrogation.c,工程须加入此源文件。计数量另增2个入口。`FINISH_OVERLOAD`仅保留旧枚举值,当前满槽不以此终结已有总召。
状态新增`need_process`和`data_send_waiting`,所有调用方须与库一起重新编译。原来用`pending_requests != 0 && !waiting`决定是否立即续跑的代码应改为读取need_process,并保留网络推进后调用总召Process的步骤。Submit_Batch现立即尝试提交,OK时进度已推进;WAIT时只保留业务事件和游标,每次重试须重新读取当前值,不能继续复用旧构造结果。Reply_Begin和Complete_Data仍由Process发送后续确认或终止。
请求存储精简只改变内部表示,总召公开函数、业务事件及配置字段不变。Slave新增按身份发送、尝试发送和关闭原连接的接口;总召内部使用,调用方继续按原方式驱动总召即可。完整SlaveEvent及Copy_Event保留原语义,其他业务无需迁移。
确认前失败修复不新增接口、配置字段或枚举值。调用方收到BEGIN阶段Fail_Request的OK或超时后的STALE时,不应再假定TCP已经断开,须继续处理FINISHED并驱动Process发送否定确认。
早期单站广播支持新增`IEC60870_Asdu_Set_CA`,当时未改变总召配置及事件布局。当前多CA版本新增use_station_registry与request.station_id,所有调用方须重新编译。新应用启用站点表,按事件实际CA构造数据,不把65535填入数据ASDU;BEGIN获取引用,FINISHED归还。Remove的OK已改为立即退出路由,释放内存须另查Is_Reusable,原先“Remove成功即可释放”的调用代码必须迁移。
广播发送顺序与[c104 Server.cpp](https://github.com/Fraunhofer-FIT-DIEN/iec104-python/blob/main/src/Server.cpp)一致:全部站确认、逐站数据、全部站终止。c104使用shared_ptr;这里用调用方节点、显式引用及轻量状态区,并保留可重试WAIT、业务事件和各站明确收尾。仍只允许一轮总召,不引入每站独立发送任务或动态发送队列。新增broadcast_states/broadcast_capacity及FINISHING,调用方须重新编译;启用多目标广播前配置状态区,并适配多个BEGIN先于首个FINISHED的事件顺序。
地址处理重构新增语义常量`IEC104_CA_BROADCAST`,将地址准备集中到内部副本创建,并移除任务中重复的header。公开函数签名和事件字段保持原样,应用无需增加调用。59组可控网络及真实TCP回归继续检查确认/数据/终止WAIT、错误地址、原事件不变、广播/本站交叉撤销和确认前失败,避免内部重构改变协议行为。
测试验证本模块的功能和边界,不代表已通过正式协议一致性认证。现场仍须确定主站对否定确认的处理、各分组点表、采样一致性及业务期限取值。
File diff suppressed because it is too large Load Diff
@@ -0,0 +1,550 @@
# IEC104 TCP子站服务与网络适配
业务默认使用`IEC104_Slave.h`统一入口;Slave拥有并驱动本模块,自动为I帧提供ASDU及原连接应答接口。本文保留独立TCP接入与内部维护的接口说明,下文的TCP调用方通常为Slave。业务示例见[README](README.md#子站统一入口)。
`IEC104_TcpServer.c/h`负责IPv4监听调度、连接生命周期、收发预算和业务事件队列,通过现有`IEC104_Connection`驱动子站协议。应用可用Prepare查询监听和定时条件,在自己的事件循环中等待,再调用Process推进;独立TCP循环也可用Poll组合这三个步骤。业务事件通过NextEvent主动取出,TCP模块不保存或调用业务函数。真实网络操作和单调计时通过`IEC104_Net.h`调用;当前提供的实现为`IEC104_Net_Windows.c`,尚未提供Linux或其他平台后端。当前仅提供模块,暂不提供独立运行入口。同时维护一条活动主站连接;额外连接被接受后关闭,原连接继续运行。
## 1. 构建与接入
应用工程需编译以下源文件:
```text
104/IEC104_TcpServer.c
104/IEC104_Net_Windows.c
104/IEC104_Connection.c
104/IEC104_Receiver.c
104/IEC104_SendManager.c
104/IEC104_SendBuffer.c
104/IEC104_AsduQueue.c
104/IEC104_Codec.c
common/IEC60870_Codec.c
104/IEC104_Link.c
104/IEC104_Link_Slave_StartStop.c
```
应用先调用Create取得静态池中的不透明句柄,再调用`IEC104_TcpServer_Config_Default`取得配置并Init;成功后在同一线程使用Prepare/Process或Poll驱动,并通过NextEvent处理事件,退出时Close、读完剩余事件,最后Destroy归还静态槽。具体接口和接入示例见下文。独立程序的入口、事件循环、退出控制和日志由应用负责。
配置中的`bind_address`默认`0.0.0.0`,表示监听本机全部IPv4接口;主站填写子站电脑实际IP和相同端口。同机运行可配置`127.0.0.1`。`port`默认2404;设为0时由系统分配,Init成功后调用Get_Status,从输出快照的`bound_port`读取实际端口。
业务I帧复制为`IEC104_TCP_EVENT_I_FRAME`事件,链路确认由Connection处理;总召、校时、遥控等ASDU业务应答需要接入对应业务处理。应用可使用`IEC60870_Asdu.h`进行命令解析、监视对象构造和原文应答构造,依赖及示例见[README](README.md#asdu信息对象模块);TCP不自动调用这些接口或执行命令。U帧启停和TESTFR应答由现有协议模块自动生成,TCP模块负责实际发送。TCP建立/断开与数据传输激活/停用分别通过CONNECTED、DISCONNECTED、ACTIVATED、DEACTIVATED交付,业务不必通过查询快照推断启停变化。
统一子站入口在以上依赖之外编译`IEC104_Slave.c`、`IEC60870_Slave.c`、`IEC60870_Asdu.c`、`IEC60870_InformationObjects.c`和`IEC60870_Time.c`。Slave内部保存服务句柄,由NextEvent创建ASDU视图并绑定原服务实例及连接代次;业务不再创建手动SlaveConnection。TcpServer本身继续独立于共用发送接口和完整对象编解码;发送/通知/启停策略不变。
以上路径均相对于项目根目录;工程需将 `104/` 和 `common/` 加入头文件搜索路径,并按所用模块选择源文件。应用工程需增加`IEC104_Net_Windows.c`并链接Windows库`Ws2_32`,MinGW参数为`-lws2_32`。平台实现按编译链接选择,同一工程只链接一个Net实现。
`IEC104_TcpServer.h`只包含`IEC104_TcpTypes.h`(其依赖`IEC104_Types.h`),不包含Connection、Net或其他运行对象的定义,也不要求`_WIN32`。业务只看到公开配置、事件、状态和调度值类型;内部对象完整定义在`IEC104_TcpServer.c`。库内Windows依赖集中在Net后端;应用自己的事件循环适配代码负责把借出的标准整数socket转换为本平台注册类型。业务解析ASDU公共头时显式包含 `IEC60870_Codec.h`,完整对象解析包含 `IEC60870_Asdu.h`。接口迁移见下一节;平台解耦不代表已经提供其他操作系统后端。
## 2. 对外接口与存储
| 接口 | 用途 |
|---|---|
| `IEC104_TcpServer_Create` | 从静态池取得不透明句柄;无可用槽返回NULL,不申请网络资源 |
| `IEC104_TcpServer_Destroy` | 归还已关闭且事件读空的静态槽;运行中或尚有事件时拒绝 |
| `IEC104_TcpServer_Config_Default` | 设置默认监听地址、端口及公开协议参数 |
| `IEC104_TcpServer_Init` | 初始化Net后端、非阻塞监听和服务队列;成功后即可缓存NORMAL |
| `IEC104_TcpServer_Prepare` | 只读查询完整socket关注集合、定时条件、待取事件数量和本地续跑标志 |
| `IEC104_TcpServer_Process` | 输入一批socket/定时/本地通知,有界推进接受、收发和协议,不执行等待 |
| `IEC104_TcpServer_Poll` | 组合Prepare、至多一次Net_Wait和Process;max_wait_ms限制网络等待 |
| `IEC104_TcpServer_NextEvent` | 按FIFO复制并取出一个事件;READY=1、EMPTY=0、ERROR=-1 |
| `IEC104_TcpServer_Enqueue_Event` | 复制服务级主动上报ASDU;无连接也可缓存,不需要generation |
| `IEC104_TcpServer_Send_Response` | 提交当前连接应答,先检查启停准入,通过后尝试一次非阻塞发送或暂存HIGH;须携带原事件generation |
| `IEC104_TcpServer_Get_Status` | 复制端口、代次、事件数、诊断、会话状态及HIGH/NORMAL积压与容量 |
| `IEC104_TcpServer_Get_Remote_Address` | 只读复制当前主站的IPv4、源端口和连接代次;无连接返回NOT_CONNECTED |
| `IEC104_TcpServer_Close_Connection` | 仅关闭匹配代次的当前主站,保留监听和现存NORMAL,继续接受新连接 |
| `IEC104_TcpServer_Close` | 结束当前连接、保存收尾事件、清空ASDU队列并关闭网络资源;保留未读事件 |
Init/Prepare/Process/Poll/Close_Connection/Close/Get_Remote_Address/Get_Status/Destroy统一返回`IEC104_TcpResult_t`,只有`IEC104_TCP_OK`(值为0)表示成功,其他值均为明确的失败分类。调用方必须显式比较枚举,不使用`if (!Init(...))`或将结果直接当作循环条件。这些接口的最后一个参数统一为可选的`IEC104_TcpError_t *error`;不需要详情时传NULL。不提供旧签名、布尔返回值或Ex兼容包装。
| 结果(均带`IEC104_TCP_`前缀) | 含义与处理 |
|---|---|
| `OK` | 本次操作成功;Poll空闲、暂不能接入或单条连接已收尾时也可成功 |
| `INVALID_ARGUMENT` | 必填指针为NULL,或就绪批次数量、事件位、重复项等不合法 |
| `INVALID_HANDLE` | 句柄为NULL或不属于当前已占用的静态槽,修正对象生命周期 |
| `INVALID_CONFIG` | 配置范围或地址字符串结束符检查失败,修正配置后重试Init |
| `INVALID_STATE` | Init/Destroy时服务仍在运行,或Prepare/Process/Poll/Get_Remote_Address/Close_Connection时尚未Init |
| `BUSY` | Process/Poll/Send_Response/Close_Connection/Close期间发生重入;所有调用须回到所属线程串行执行 |
| `EVENTS_PENDING` | Close后尚有未读事件,先通过NextEvent读空,再Init/Destroy |
| `NETWORK_ERROR` | 网络初始化、监听、等待或不可恢复的接入失败,按error的阶段和原生码诊断;接入资源暂缺由内部暂停重试 |
| `INTERNAL_ERROR` | 队列/协议会话初始化、等待期限查询或内部一致性异常,停止服务并检查实现 |
| `GENERATION_EXHAUSTED` | 代次用尽,Close并读完事件后Destroy;该槽不再重新分配 |
| `REGISTRATION_EXHAUSTED` | socket注册编号用尽,同样关闭并归还;不回绕分配旧身份 |
| `NOT_CONNECTED` | Get_Remote_Address/Close_Connection时服务已Init,但没有当前主站;不返回旧地址、不产生新的断开事件 |
| `STALE_GENERATION` | Close_Connection指定的非零代次不匹配当前主站,拒绝操作,不关闭新连接 |
`error`包含与返回值一致的`result`、失败`stage`和本次网络错误的`socket_error`。每次调用均完整覆盖,成功为OK/NONE/0,非网络错误的原生码为0;即使句柄无效或Destroy成功也能取得诊断。诊断存储由业务持有,不得与config/status/info/ready等输入输出重叠。需要保存首个失败时,清理或查询调用可传NULL,避免覆盖自己保存的error。阶段包括VALIDATE、LIFECYCLE、NET_INIT、LISTEN、WAIT、ACCEPT、GENERATION、QUEUE_INIT、QUEUE_STATE、CONNECTION_INIT、SCHEDULE和REGISTRATION;LISTEN包含后端的地址内容解析、socket创建、绑定及监听,QUEUE_STATE表示服务队列异常或无法解除旧绑定,SCHEDULE表示无法取得可靠的协议等待上限,REGISTRATION表示无法继续分配socket注册身份。
在服务队列正常的情况下,客户端EOF、收发错误、协议错误和超时只结束该客户端,Process/Poll仍返回OK并保留监听;连接原因经DISCONNECTED事件中的`IEC104_TcpFault_t`交付。服务级推进或期限查询失败后保存本次error,再Close并读完事件。应用事件循环自身的等待/注册失败由应用诊断和处理,不伪装成TCP协议故障。Get_Status中的`last_socket_error`是历史后端诊断,可能来自更早的连接或可恢复错误,不能用它判断本次接口是否失败。该字段、error及连接事件中的原生错误码仅用于日志,当前Windows后端使用Winsock错误;跨平台业务按公开结果及连接故障分类处理。
正常TCP有序关闭在没有既有故障时交付`fault=IEC104_TCP_FAULT_NONE`和`socket_error=0`。例如TRANSPORT表示传输异常,I_ACK_TIMEOUT表示I帧确认超时,不能把所有非零fault都当作协议错误。公开的connection快照只包含会话阶段、故障、尚未转成RECORD事件的记录数量及已提交的STARTDT状态;已经进入事件FIFO的记录不计入该数量。Connection内部启停过程、接收借用和队列字段不再透传。启动状态也不表示窗口和发送容量一定可用,业务仍以提交结果为准。DISCONNECTED保留关闭协议前的阶段和故障,phase可能仍为ACTIVE;其中`pending_send_records`扣除本次收尾已成功转为RECORD事件的记录,全部转移成功时为0,不表示这些帧全部已ACK。当前TCP是否连通应查询Get_Status的connected。
内部Connection调用返回ERROR、EOF时设置NORMAL发送限制失败,以及其他内部异常均按INTERNAL收尾,不冒充网络传输错误。已冻结连接返回FATAL时保留其首次原因;Send_Response遇到未约定的内部返回值也归INTERNAL,正常的业务参数或启停准入拒绝仍只返回SUBMIT_ERROR。实际网络失败通过Connection登记TRANSPORT;若发送失败或传输关闭回报未能返回预期FATAL,则由TcpServer补记INTERNAL,同时保留本次原生socket_error。收尾读取或保存记录失败也补记INTERNAL;已有协议、传输或超时故障优先保留。状态无法可靠查询时status_valid仍为0,不能读取无效快照推断故障类别。
子站收到格式合法的STARTDT_CON或STOPDT_CON时消费并忽略,不因该帧断连,不回复、不切换启停状态、不产生业务通知,也不解除确认等待或刷新t3。该处理不占通知和控制发送槽;后续输入及原有期限检查照常推进。起始字节、长度/APCI、ASDU最低长度、I/S序号或ACK错误仍沿用原故障规则。
每个APDU的首字节必须为0x68,接收器不跳过前导垃圾;遇到错误起始字节立即登记FRAME故障并断开。报文体仍按声明长度收集,其中的0x68是普通数据,不参与重新同步。
`IEC104_TcpServer_t`是不完整类型,应用只能声明其指针,不能直接定义对象、清零、复制或访问成员。内部静态池保存真实结构体,地址与对齐由编译器保证,不使用malloc,也不需要业务准备字节数组并强转。`IEC104_TcpServer_Config.h`中的`IEC104_TCP_SERVER_CAPACITY`默认1,表示同时持有的服务器句柄数;需要多个监听服务时,调整该值或为TcpServer.c增加编译参数`-DIEC104_TCP_SERVER_CAPACITY=数量`。每个服务仍只接受一条活动主站连接,容量增加也会增加静态内存。
默认每个槽持有Connection、ASDU队列、2048字节TCP接收暂存、1024/4096字节HIGH/NORMAL队列、8个控制槽、32条发送记录和一个变长事件字节环。2048字节能容纳每轮8个满长APDU(2040字节),保留原有每轮交付预算;接收预算让出后的确认超时检查采用下文的固定输入快照规则。容量统一在配置头文件中设置,编译期检查普通、启停及收尾容量。内部容量变化只需要重新构建模块,业务头文件不暴露这些容量或内部结构大小。静态槽在Close后仍占用,直到Destroy成功才归还;首次Init失败也必须重试或Destroy,不能丢弃句柄。
公开提交接口接受6..249字节ASDU,因此`IEC104_TCP_HIGH_CAPACITY`至少为`IEC104_ASDU_HIGH_ENTRY_HEADER_LEN + IEC104_MAX_ASDU_LEN`,`IEC104_TCP_NORMAL_CAPACITY`至少为`IEC104_ASDU_NORMAL_ENTRY_HEADER_LEN + IEC104_MAX_ASDU_LEN`;当前x64 ABI下分别为251和265字节。每级总容量还须不超过UINT32_MAX,头长由sizeof推导,过小的配置在编译期拒绝。`Send_Response`直接准备时不经过HIGH,回退排队时使用HIGH;`Enqueue_Event`始终使用NORMAL。该约束保证合法长度不会仅因直接发送转为排队而被判SUBMIT_ERROR;HIGH空闲不足仍返回WAIT,NORMAL仍按原规则覆盖旧原文或因编号窗口受阻返回WAIT。
同一服务的全部调用及业务入队必须串行执行;Create/Destroy还须在各服务之间串行。句柄在Destroy后失效,应立即清空业务保存的指针。Destroy不隐式关闭服务或丢弃事件;业务先Close、读空NextEvent,再归还槽。
业务通知FIFO按实际长度存放,头部`TcpEventHeader_t`含generation、payload_length、type;载荷直接复制公开data成员的有效前缀。I_FRAME只保存`offsetof(IEC104_TcpIFrameEvent_t, apdu) + apdu_length`字节;RECORD和连接/启停通知分别保存对应公开结构的sizeof。头部及载荷均用memcpy读写,跨环尾时分两段复制,不留下空隙,也不强转环内结构体指针。
配置宏名和条数推导保持不变:`EVENT_CLOSE_RESERVE = RECORD_CAPACITY + 2`,`EVENT_NORMAL_CAPACITY = EVENT_CAPACITY - EVENT_STATE_RESERVE - EVENT_CLOSE_RESERVE`。普通配额默认30,表示按最长I帧通知计算的保证条数,供CONNECTED、I_FRAME及正常RECORD共享;启停配额默认4,仍限制ACTIVATED/DEACTIVATED的未读条数;收尾保证32条记录、1个最长I帧及1个DISCONNECTED。全部尺寸由sizeof/offsetof推导,编译器`-D`覆盖仍有效;编译期同时检查字节索引和最短通知可能达到的公开16位计数范围。
当前x64 ABI下头部16字节,I帧通知为`30 + APDU长度`字节,RECORD为64字节,连接及启停通知为72字节:
| 区域 | 字节容量计算 | 默认值 |
|---|---|---:|
| 普通 | 普通保证条数 × 最长I帧通知 | 30 × 285 = 8550 |
| 启停 | 启停保证条数 × 连接通知 | 4 × 72 = 288 |
| 收尾 | 最长I帧 + 全部记录 + DISCONNECTED | 285 + 32 × 64 + 72 = 2405 |
| 字节环合计 | 普通 + 启停 + 收尾 | 11243 |
事件环与接收暂存合计从23680降至13291字节,减少43.9%。2026-10-19字节环改造后,MinGW x64服务对象从31848降至21464字节;2026-10-20调度修复增加8字节,当前为21472字节。完整对象大小还取决于其他内部结构及目标ABI。16字节APDU每项46字节;普通区空闲时可存185条,仍为已受理但等待交付的下一帧保留收尾空间。这里的普通通知区与NORMAL发送队列独立,NORMAL覆盖旧原文不会释放通知FIFO空间。
普通入口同时检查非启停占用加本项不超普通区、总占用加本项不侵占收尾区;CONNECT可按自身实际大小接入,但旧启停通知必须先读完。启停入口统一检查条数配额及完整收尾预留。Append先检查空间,再写头部和载荷,最后提交字节占用及通知计数。全部已入队通知按顺序逐条保存,不覆盖、不合并。
普通通知满仍可按TCP顺序处理前面的S/U,ACK记账不等待业务取出回执。已确认回执在普通空间不足或本轮交付预算用尽时暂留内部,可能晚于随后发生的启停通知交付;保持不因回执积压而暂缓启停受理及CON发送的行为。启停变化由Connection在ACT受理时通过内部适配器立即交付:先查询启停容量,状态改变后复制事件。重复ACT不改变状态时不占新配额;CON完整写出仅确认发送结果。
启停专用槽满时保留完整ACT并返回WAIT,尚未受理、不改变状态;TCP输入按原顺序等待,不越过该请求。已有CON继续写出,发送不再等待状态通知槽。NextEvent消费事件后安排Process重试;原有协议期限继续生效,长期不消费仍可能超时。
I帧按本帧实际长度检查普通空间;不足时将已受理帧保留在Receiver,设置`receive_paused=1`并暂停后续Feed/recv,同时停止转移回执,避免较短的RECORD插到该I帧前面。不覆盖请求、不自动回复业务拒绝,也不因通知积压主动断开连接。NextEvent腾出普通空间后安排本地Process,先复制该帧、Release,再恢复原来的输入尾部和接收关注;不重复处理该帧序号或ACK。等待期间已有发送及协议期限继续推进,不能延长计时来掩盖积压。TCP有序,保留I帧会阻挡其后的S/U;应用必须及时消费事件,持续积压仍可能导致原有协议超时。若此时关闭连接,收尾顺序为剩余I帧、全部记录、DISCONNECTED。旧启停通知须先读完,其他旧通知也须释放出新连接建连通知及完整收尾预留所需的容量,才允许接入新会话。
每轮最多交付8条通知;预算或本类配额耗尽时先返回应用,下一轮继续。普通区放不下最长通知才视为配额用尽,下一轮仍按每项实际长度判断。receive_paused只表示已受理I帧等待普通通知空间,不代表STOP停用或启停ACT等待通知容量。应用仍通过NextEvent消费事件;适配器仅连接TcpServer和Connection,不是业务回调。
NextEvent先检查游标、计数、类型、载荷长度及I帧APDU长度,在清零的临时公开结构中展开;全部校验通过后才写输出并出队。EMPTY/ERROR不改输出,损坏项也不部分出队;短APDU后的数组尾部清零,历史代次照常交付。副本无任何借用指针,可独立保存、按值复制,无需Release。Close保留未消费事件;Close后尚未读空时再次Init或Destroy均返回EVENTS_PENDING。读空后可以Init重开,或Destroy归还槽;同一静态槽重新Create仍保留generation计数。旧事件可以作为历史记录保留,但不能配上另一个服务器句柄重新提交。
`iec104_tcp_event_ring_test.c`以可控Net后端覆盖跨环尾、容量预留、损坏项原子拒绝、短帧背压恢复、回执次序、断线重连及分包。该测试直接包含TcpServer实现,构建时不要再次链接TcpServer.c或Net_Windows:
```powershell
New-Item -ItemType Directory -Path .build -Force | Out-Null
gcc -std=c11 -O2 -I104 -Icommon -Wall -Wextra -Werror test/iec104_tcp_event_ring_test.c 104/IEC104_Connection.c 104/IEC104_Receiver.c 104/IEC104_SendManager.c 104/IEC104_SendBuffer.c 104/IEC104_AsduQueue.c 104/IEC104_Codec.c common/IEC60870_Codec.c 104/IEC104_Link.c 104/IEC104_Link_Slave_StartStop.c -o .build/iec104_tcp_event_ring_test.exe
if ($LASTEXITCODE -ne 0) { throw 'TCP event ring build failed' }
./.build/iec104_tcp_event_ring_test.exe
if ($LASTEXITCODE -ne 0) { throw 'TCP event ring tests failed' }
```
2026-10-19验证:默认配置、`RECORD_CAPACITY=3/EVENT_CAPACITY=12/STATE_RESERVE=2`、`RECORD_CAPACITY=40/EVENT_CAPACITY=100/STATE_RESERVE=6/RX_CAPACITY=4096`均通过11个专项场景,Windows生产库以`-Wall -Wextra -Werror`构建通过,GCC静态分析通过。公开头文件去注释后保持一致,Connection/Net文件哈希以及Process_Input、Read_Client、Receive_Input函数均未改变。接口过期的旧回归测试及专用辅助文件已删除,当前入口和构建命令见[测试说明](../test/IEC104测试文档.md)。
以下是2026-10-19存储改造的历史性能测量,不包含2026-10-20新增的内核输入快照查询及独立发送调度,不能作为当前版本的性能结论。不能保证recv次数及每帧耗时在所有输入下完全相同。模拟Net、每批8帧并安排一次空输入推进发送的对照中,16字节和255字节APDU分别处理160万帧,修改前后均调用recv 40万次(包含空输入检查);5次串行测量的每帧耗时中位数如下,包含测试报文生成、Poll及NextEvent,不代表真实socket的端到端延迟:
| APDU长度 | 固定槽 | 字节环 |
|---|---:|---:|
| 16字节 | 0.125微秒 | 0.148微秒 |
| 255字节 | 0.137微秒 | 0.166微秒 |
一次积压16个满长APDU(4080字节)时,recv调用由1次变为2次,这是暂存从4096缩至2048字节的直接结果;每轮最多交付8条的调度预算保持不变。测量输出与验证记录保存在`.build/fifo-byte-ring-20261019/benchmark-results.json`及`verification.json`。
绑定地址目前只支持数字IPv4字符串,不解析主机名。Init复制配置,`protocol`使用`IEC104_Types.h`中的`IEC104_ProtocolConfig_t`;Connection也使用此公共配置,保留原类型名作为兼容别名。配置必须满足`0 < t2_ms < t1_ms`;`t2_ms >= t1_ms`在申请网络资源及初始化服务队列前返回`INVALID_CONFIG`,error阶段为`VALIDATE`。默认t2=10000ms、t1=15000ms满足该约束。Get_Status返回独立副本,失败不改输出,Create后、Init失败后以及Close后都可查询;关闭后端口为0,最近代次保留。Windows后端保持`SO_EXCLUSIVEADDRUSE`策略,避免同一地址被重复监听。
原TCP调用方需要迁移以下用法并重新编译:
| 原用法 | 现在的用法 |
|---|---|
| 直接定义或清零`IEC104_TcpServer_t server` | 持有`IEC104_TcpServer_t *server = IEC104_TcpServer_Create()`,完成后Destroy |
| Init/Poll/Close/Get_Status/Destroy返回值按0/1判断 | 为调用增加error或NULL末参数,并显式比较`IEC104_TCP_OK` |
| `config.poll_interval_ms`及`Poll(server, error)` | 移除该配置项,直接使用`Poll(server, max_wait_ms, error)`指定本轮等待上限 |
| 接口失败后只查询`last_socket_error` | 直接读取本次`IEC104_TcpError_t`的result/stage/socket_error |
| 读取`server.bound_port/last_socket_error/generation` | Get_Status取得对应快照字段 |
| `config.connection` | `config.protocol`,各协议配置字段含义不变 |
| 入队结果使用`IEC104_ConnectionResult_t`及`IEC104_CONNECTION_*` | 使用`IEC104_TcpSubmitResult_t`及`IEC104_TCP_SUBMIT_*` |
| `Enqueue_Normal` / `Enqueue_High`及`IEC104_TcpEnqueueResult_t` | 分别迁移为`Enqueue_Event` / `Send_Response`及`IEC104_TcpSubmitResult_t`;结果常量改为`IEC104_TCP_SUBMIT_*`,无旧入口包装 |
| 通用业务入队入口及重连保留开关 | 主动上报调用Enqueue_Event;连接应答调用Send_Response;NORMAL随服务保留,Close清空,无兼容包装 |
| 直接使用Connection状态枚举或内部`dt_state` | 使用`IEC104_TCP_SESSION_*`、`IEC104_TCP_FAULT_*`及`data_transfer_started` |
| 发送记录中的`frame_id`、`i_frame_snapshot`、`asdu_priority` | 使用事件generation及`value.frame_serial/send_number/receive_number/apdu_length/priority` |
发送事件不再公开NORMAL队列的内部条目编号。业务身份应由ASDU业务层维护,发送记录只表达传输与链路确认事实。
### 2.1 ASDU队列积压查询
`IEC104_TcpServer_Get_Status`同时提供`high_queue`和`normal_queue`,两者均为`IEC104_TcpAsduQueueStatus_t`数值副本。业务通过Slave_Get_Status取得同一快照,不取得队列指针,不读取Connection、SendManager或字节环成员。状态结构新增字段,库与调用方须一起重新编译;不新增兼容入口。
| 字段 | 含义 |
|---|---|
| `pending_asdu_count` | 队列中尚未交给发送模块的ASDU条目数;不含已组帧、部分写出或等待ACK的帧 |
| `stored_asdu_count` | 队列中仍保留ASDU原文的条目总数;不是累计入队次数 |
| `capacity_bytes` | 本级队列的实际总容量,单位字节 |
| `used_bytes` | 全部保留条目占用的字节数,包含内部条目头及ASDU原文 |
| `free_bytes` | 当前未占用的字节数;与used_bytes相加等于capacity_bytes |
先检查Get_Status返回`IEC104_TCP_OK`,再检查`status.asdu_queue_status_valid`。标志为1时两级统计均有效;与`connection_status_valid`相互独立。Init成功后,即使尚未接入主站或已经断线,也能查询NORMAL缓存。尚未成功Init、Close后或内部队列不可用时,标志为0且两份统计清零;此时表示统计不可用,不能按“没有积压”处理。重复Init被拒绝不会清除仍在运行的服务或使其队列统计失效。
HIGH原文在交给发送模块后立即出队,因此其pending与stored相等;直接进入发送缓冲的应答不经过HIGH队列。NORMAL原文通常保留到ACK后才释放,因此stored可能大于pending。例如10条NORMAL中已有4条交给发送模块且尚未确认,原文均未被覆盖时,pending为6、stored为10。字节占用统计这10条原文及条目头,不统计独立发送缓冲、APCI或发送记录;已覆盖原文对应的待ACK帧不再计入队列统计。
受理新STOPDT_ACT时立即清空HIGH待发应答,不产生逐条作废事件;队列数量归零不代表这些应答已发送。断线收尾也会清空HIGH,并将仍保留的NORMAL恢复为待发;断线期间新增NORMAL继续计入pending。收到EOF后暂留给下一连接的NORMAL也计入pending,因此待发数量不等于“本轮允许立即发送的数量”。队列为空也不表示主站已经确认或业务已经完成,传输完成事实仍从RECORD事件获取;`connection.pending_send_records`另含尚未交付为事件的记录,不能作为队列积压相加计算。
统计用于观察积压趋势及容量占用,不预留空间。ASDU长度不同,free_bytes不能直接换算为可接收条数;NORMAL空间不足时仍可能覆盖旧原文,HIGH直接发送时也可能不占队列。业务提交仍以Enqueue_Event/Send_Response返回值为准。Get_Status只做常数时间查询,不执行I/O、不消费ASDU或推进协议;与其他接口一样,应在服务所属线程串行调用。
### 2.2 接入暂停与错误诊断
`IEC104_TcpServerStatus_t`另提供以下只读字段。可恢复接入失败由模块安排重试,Process/Poll返回OK,不新增业务事件;应用通过这些字段观察持续接入异常。状态结构新增字段后,库与调用方须一起重新编译。
| 字段 | 含义 |
|---|---|
| `accept_paused` | 查询时刻仍在接入暂停期为1;到期立即为0,与是否有接入容量无关 |
| `accept_retry_remaining_ms` | 本次暂停剩余毫秒数;未暂停为0;查询不会刷新期限 |
| `last_accept_error` | 最近一次Net_Accept错误的原生码;初始为0,后续错误更新,成功、WOULD_BLOCK及客户端断开不清除 |
| `consecutive_accept_failures` | Net_Accept连续返回RETRY、RETRY_LATER或ERROR的次数;到UINT32_MAX饱和,OK或WOULD_BLOCK清零 |
连续失败计数只描述接入调用结果,WOULD_BLOCK表示当前没有待接入连接,计数清零不证明资源已经恢复。`last_accept_error`独立于可能被客户端收尾或接入成功覆盖的`last_socket_error`,便于保留接入失败线索;二者均不代表当前API调用失败。成功接入额外客户端并随即关闭也属于Net_Accept的OK,会清零连续失败次数。
Close_Connection和客户端自然断开不提前结束接入暂停,也不清除接入诊断;整个服务Close时撤销重试期限,保留最近错误及连续失败计数供查询。下一次Init重置这些诊断;Destroy结束对象生命周期后不再保留。固定100毫秒暂停不开放配置,持续失败继续按此间隔重试,不自动升级为服务级错误。
## 3. 收发循环
Net后端交付的监听socket与客户端socket均为非阻塞。调度分为两个公开步骤:`Prepare(server, &info, error)`只查询等待条件;`Process(server, &ready, error)`只做有界非阻塞推进。等待由应用的事件循环统一安排,库不会在Prepare或Process中再次调用Net_Wait。
`Poll(server, max_wait_ms, error)`是独立TCP循环的组合入口,内部使用相同的准备和推进核心,并在中间至多调用一次Net_Wait。0表示只查询就绪,正数限制本轮网络等待,UINT32_MAX仍表示有限毫秒数;实际等待还受协议期限、接入/发送重试期限、本地工作和未读事件约束。该参数只约束等待,不保证整个函数的执行耗时。两个入口没有两套收发实现;同一服务由一个串行调度者管理,不应同时给Poll和另一个事件循环安排等待。
Prepare通过内部`Connection_Get_Wait_Time`查询当前帧本地发送、最早未ACK的I帧t1、TESTFR t1、STOP总期限以及可准备S/TESTFR的t2/t3。它不推进协议、不准备发送帧、不更新计时起点、不关闭连接。查询异常返回INTERNAL_ERROR/SCHEDULE且不修改输出;已失败会话则标记立即推进,由Process执行收尾。TcpServer不读取Connection、Link或SendManager的计时字段。
S确认已在途、TESTFR已发送或等待CON、控制槽已满时,当前不能新增控制帧的t2/t3不反复触发零等待;已有帧仍受本地发送期限约束,等待CON仍受t1约束。容量或协议门控恢复后,按原始期限重新推进。
每轮Process共用最多32次Feed、32次发送尝试、4次accept和8条通知交付的预算;断线收尾必须一次完整交付,不受通知预算限制。可读/接入通知一直保留到实际操作返回WOULD_BLOCK;预算耗尽或交付用尽本类配额时,可立即推进的工作由下次Prepare要求续跑,不依赖新的边沿;接入/发送暂停期间则等待各自的重试期限。发送预算耗尽、有界无进展重试、活动连接的HIGH入队、未EOF时的NORMAL入队及NextEvent释放通知槽也会安排本地推进;无连接或EOF后的NORMAL只缓存。普通区满但尚无受阻I帧时仍关注可读;出现`receive_paused`后撤销客户端READ关注,并停止为该受阻输入反复安排本地续跑,保留接收边沿供恢复使用。协议WAIT仍等待控制发送或期限解除。已准备好待发字节、未处于发送重试暂停且不因启停通知槽不足而暂缓时才关注可写;消费通知后通过本地唤醒恢复,不能把“业务发送队列非空但等待STARTDT/ACK”作为持续关注可写的理由。
Net_Accept返回RETRY_LATER时,立即结束本轮接入并保存`accept_retry_at_ms = Now_Ms() + 100`,保留`accept_pending`及当前连接。普通RETRY仍可在本轮4次预算内继续;若整轮4次全部为RETRY,也进入相同暂停,避免每轮有预算却跨轮不断立即重试。曾有OK接入进度的预算耗尽仍按原规则续跑,额外客户端被接入后关闭同样算进度。WOULD_BLOCK清除接入待处理标志,真正的监听失败仍返回NETWORK_ERROR。
暂停状态统一定义为`now_ms < accept_retry_at_ms`,不另存需要解除的标志;等于期限即已到期。Prepare只读取一次时钟,用于监听关注、本地续跑、协议期限和接入期限的合并。暂停期间移除监听READ关注,`accept_pending`不单独触发need_process;Process末尾真正调用Accept_Clients之前再次按当前时钟检查期限,客户端收发、NextEvent或迟到监听通知均不能提前触发accept,也不能刷新暂停期限。暂停只限制接入,当前客户端的收发和协议期限继续推进。
到期后保留的accept_pending配合原有容量规则安排本地重试,不依赖新的监听边沿。无客户端且通知容量仍不足时,不恢复监听关注、不因接入请求续跑,也不把已过期的接入期限保留为零等待定时器;业务消费NextEvent后再恢复接入。客户端在暂停期间断开不会提前结束暂停,新主站仍须等待剩余时间。
`Send_Response`仅在Connection返回`OK`(已入HIGH)或`SEND_READY`(已准备APDU)时,为本次提交设置`process_pending`。`WAIT`/`ERROR`不因提交失败新增本地唤醒,也不清除已有标志;后续就绪I帧和确认记录仍照常交付。接收恢复、发送重试、预算续跑、事件消费及协议期限继续按各自条件安排推进。HIGH满且发送受k窗口限制时,失败提交不会反复把Poll等待强制归零;业务保留应答,在后续调度间隙重试。
当前接收轮次产生业务事件后,不再继续recv;已有TCP尾部在Feed及通知预算内处理,然后以Tick或Yield_Receive_Batch结束当前轮次。发送始终使用独立的32次预算,不能因8条通知预算耗尽而跳过;部分发送及不可写仍按原规则处理。旧回执转移安排在输入处理后,避免先交付旧回执而延误已到达的ACK。应用先取出并处理事件,再执行下一轮Process/Poll,使应答有机会在下一次读取EOF之前发送或入HIGH。EOF后停止接收,继续有界排空当前可发送内容,不因接收尾部保留而反复立即调度。
同一轮收到的socket就绪与定时事件应合成一个ready批次。Process先处理已有输入,再准备下一次发送;本地/定时唤醒也允许非阻塞查看已到达的输入。每轮接收以Connection的`Begin_Receive_Batch`开始。仅因Feed/通知预算或交付让出而停止时,TcpServer保留用户态尾部,并通过`Net_Pending_Input`只查询一次当时内核中的剩余字节数,形成有限输入快照。还有快照输入时调用`Yield_Receive_Batch`结束这一轮,暂缓I帧ACK及TESTFR_CON判定,Prepare返回`need_process=1/timeout_ms=0`要求立即续收;不能阻塞等待。后续recv长度不超过快照的剩余字节数,不把新到达的流量加入旧快照。
快照处理完后立即用`Tick`按原起点检查确认期限,持续的新I/S流量不能无限延长旧t1。真正的通知容量背压、无法解除的WAIT、recv无进展或EOF仍用Tick结束批次;该机制不承诺隔离业务长期积压。本地发送和STOP总期限、格式及序号错误始终有效。它不读取内核到达时间戳,也不重置任何计时起点。2026-10-20的调度测试覆盖7/8/9/33个前置I帧、任意recv分段、满长突发、固定快照外的新流量、TESTFR确认、连续接收下发送、部分发送及真实缺失确认。
### 3.1 接入应用自己的事件循环
`IEC104_TcpWaitInfo_t`中的字段按以下规则使用:
| 字段 | 应用处理 |
|---|---|
| `sockets[0..socket_count)` | 当前完整关注集合,最多两项;新增/更新注册,移除旧集合中已不存在的项及已撤销的READ/WRITE位 |
| 每项`socket/token/events` | 保存数值句柄及注册身份,按READ/WRITE注册;返回就绪时回传原身份,只填写实际就绪位 |
| `service_token` | 本次Init身份,保存在定时器、本地唤醒和就绪批次中 |
| `timer_active/timeout_ms` | 协议检查与接入/发送重试共用的最近等待上限;活动时替换一次性定时器,0毫秒立即调度;非活动时取消;UINT32_MAX不是无限等待 |
| `need_process` | 安排一次本地推进,不能阻塞等待新socket事件 |
| `pending_event_count` | 先通过NextEvent处理业务事件,再重新Prepare |
| `receive_paused` | 已受理I帧因通知容量不足暂留内部;消费普通通知后安排Process交付并恢复接收 |
存在客户端时,查询的协议等待上限最多为UINT32_MAX毫秒;没有更早期限仍可在该上限唤醒检查。接入或发送暂停尚未到期时,把各自剩余时间与协议等待上限取较小值。接入暂停即使没有客户端,也返回timer_active=1及接入重试剩余时间。没有客户端且没有尚未到期的接入暂停时,timer_active=0;到期后能否接入由容量和need_process表达。timeout_ms从本次查询时刻开始计算,处理其他任务较久后必须重新Prepare,不能用旧相对时间推迟期限。每次Process、Enqueue_Event、Send_Response、Close_Connection或事件消费改变状态后,下一次等待前都要重新查询。
接入暂停时,监听socket会暂时从Prepare的完整集合中消失,应用必须撤销旧注册;否则一直可读的监听socket仍可能使水平触发的外部等待空转。暂停结束后按最新快照恢复注册,监听socket和service_token的生命周期没有改变。发送暂停时同样须撤销客户端WRITE位,并保留仍需处理的READ位;客户端不再有任何关注位时将其移出集合。`ready.timer_expired`只表示定时唤醒,实际协议及接入/发送期限仍按当前单调时钟判断,提前或迟到的通知不会提前解除暂停。
应用循环的调用关系如下,其中“统一等待”由应用实现,可同时等待TCP、其他模块和业务定时器:
```text
NextEvent处理业务事件(可调用Send_Response或Enqueue_Event)
-> Prepare取得最新info
-> 更新完整socket注册集合和一次性定时器
-> need_process时安排本地唤醒,否则统一等待全部模块的事件
-> 合并本轮TCP socket就绪与定时通知,构造ready
-> Process(server, &ready, &error)
-> 处理其他模块任务,回到循环开头
```
本地唤醒时把ready清零、复制最近info.service_token即可;定时器触发再置timer_expired=1。socket通知每项复制注册时的socket/token,把events替换成本轮实际就绪位。同一socket只放一项,可读和可写合并;ERROR可表示平台报告的错误/挂断提示,Process通过实际I/O判定结果,不能把它直接当作某种协议故障。不要只把info原样复制成ready并把关注位当成实际就绪。即使需要立即推进,也应收集已经可用的socket通知,与定时提示一起交付。
socket只是借给事件循环注册,所有权仍属于TcpServer;应用不能对它recv/send/close或修改非阻塞属性。Windows事件循环适配代码可把`IEC104_TcpSocket_t`转换成SOCKET用于select等就绪机制,业务ASDU处理无需看到系统类型。TCP内部的Net后端仍负责所有真实I/O。此接口面向就绪驱动,不能直接把重叠I/O完成通知当作就绪位,或让异步I/O继续借用库内缓冲。
注册身份与业务generation分开:监听和客户端每次创建都获得新的非零token;计数跨Close/Init及Destroy/Create保留,不回绕。Process先检查service_token,旧服务整批忽略;当前服务中的旧socket/token逐项忽略,全部是旧socket通知且没有定时事件时不推进当前连接。不能为了处理旧通知而替换成最新token。旧定时器若属于同一次Init,最多触发一次按当前状态计算的提前检查,不能沿用旧时间差判定新连接超时。
Process/Send_Response/Close_Connection/Close可能关闭socket,应用须撤销旧注册;准备销毁服务时还须取消定时器和本地任务,避免继续使用已Destroy的句柄。边沿触发应保留need_process续跑;单次通知模式须在每轮按新快照重新布防。工作线程的结果由应用自己的唤醒机制送回事件循环线程,再调用Send_Response或Enqueue_Event并刷新等待条件。库不创建跨线程唤醒或注册回调。
接收路径:
```text
Net_Recv -> 固定接收缓冲 -> Connection_Feed(consumed_length)
-> I帧复制为事件,成功入队后Release;业务通过NextEvent取副本
-> S/U由Connection受理并释放
```
TCP层不解析APCI,也不假定一次recv对应一帧。Feed按实际消费量推进位置,剩余尾部跨Process/Poll保存;半帧由Receiver保留。WAIT不丢弃原文,发送和Tick继续驱动。即使旧S/U本轮刚释放、Feed消费0字节,也在预算内继续尝试尾部,不无限重试。
发送路径:
```text
Connection_Prepare_Next_Send == SEND_READY
-> Net_Send(pending_data, remaining_bytes)
-> Connection_Handle_Send_Progress(frame_id, 本次成功写入量)
```
每次Net_Send返回OK后立即回报实际增量,再处理后续接收事件;可读和可写同时就绪时,先处理已有接收字节,因为之前的同步send已全部记账,无须先发送新的帧才能处理旧帧的ACK。部分写入后重新Prepare取得同一APDU的剩余字节,不交错发送。`IEC104_NET_WOULD_BLOCK`保留当前帧,清零无进展重试计数并等待可写通知;`IEC104_NET_RETRY`及OK但写入0字节按下述有界策略重试,不提前Complete、不重置期限。最终发送失败调用Handle_Send_Failure并关闭客户端。发送完成回报即使因后续协议推进返回FATAL,也不重报已登记的增量。
发送准备及进度回报仅因本地发送和STOP期限直接报告超时,I帧ACK与TESTFR_CON的t1故障在接收阶段判定。Write_Output仍在Net_Send返回后读取真实时刻,供写入记录、活动时间和新TESTFR计时使用。若发送期间跨过旧确认的t1,快速应答已有process_pending;常规发送结束也只读查询协议期限,到期时登记立即续跑。下一轮Process先按既有预算和固定输入快照处理ACK/CON,再由Tick按原始起点判断;Prepare报告零等待,不依赖新的可读边沿。没有有效确认时仍超时,真正事件容量背压仍执行原期限,不新增1秒或其他固定宽限时间。Submit_Response入口发现期限已到时仍只入HIGH,不能靠连续提交应答推迟检查。
暂缓确认超时判定期间,旧I帧ACK或TESTFR_CON的t1已经到期时,Connection_Prepare_Next_Send暂停为HIGH/NORMAL创建、编号新I帧。已准备的当前I帧(含尚未写出字节的帧)及S/U仍按原顺序发送,以释放控制槽并继续受理接收报文;已有帧排空后返回WAIT,使接收解阻用的Flush_Output及时退出,不能顺带发出新的业务帧。有效确认解除所有已到期等待后自动恢复准入,未解除则由接收阶段按原期限断开。准入限制同时覆盖接收批次内、预算续收期间和常规发送,不改变未确认NORMAL在断线后的保留规则。
发送无进展采用跨轮预算:每次实际Net_Send返回OK+0或RETRY,累计一次`send_retry_count`,两种结果混合返回也共同计数。前3次安排本地续跑;第4次清零计数并保存`send_retry_at_ms = Now_Ms() + 10`,暂停发送。计数由Process普通发送、接收WAIT解阻发送和Send_Response快速入口共用,不能靠进入下一轮或换入口重置。写入正数字节、返回WOULD_BLOCK或已无待发帧时清零;断开及新连接初始化同时清除重试期限和计数。10毫秒为内部固定重试间隔,不新增业务配置,不改变正常有进展的发送路径。
发送暂停统一按`now_ms < send_retry_at_ms`判断。Prepare在同一次时钟快照中撤销客户端WRITE关注,并将剩余暂停时间与协议及接入期限取最小值;READ仍按接收背压规则保留。所有实际send都经过Write_Output的期限检查,因此接收就绪、NextEvent、业务提交、迟到的WRITE或提前的定时提示均不能提前写入,也不能延后原重试时刻。暂停不新增发送续跑,但保留其他工作已经登记的process_pending;这些工作可以推进一次,实际发送仍受期限限制。
等于或超过重试期限时,Prepare通过need_process主动安排发送,不依赖新的可写边沿。Write_Output在检查启停通知槽之前消费已到期的重试期限;若此时通知槽不足,转为等待NextEvent,不能保留已过期的期限反复零等待。已无待发帧也清除重试状态。重试后再次连续4次无进展,重新暂停10毫秒;Process和快速入口本身均不睡眠,等待由Poll或应用事件循环完成。
暂停期间接收及Tick继续运行,本地发送超时仍从原queued_at_ms计算,部分发送、零字节、RETRY及调度暂停都不续期。更早的发送或协议期限优先唤醒并按原规则收尾。因此修复消除持续无进展造成的忙等,不取消长时间无法完成发送时的超时断开;EOF后的待发内容也遵循相同规则。
Connection的Feed、Prepare_Next_Send、发送回报及Tick均可能推进保留帧;模块统一检查就绪I帧并复制事件,已确认记录也在复制事件后才释放。TcpServer_Prepare只查询等待条件,与内部Prepare_Next_Send不同。所有`now_ms`来自`Net_Now_Ms`,Windows后端内部使用`GetTickCount64`;日历时间/校时不影响协议期限。调用方长时间不调用Process/Poll或业务主循环阻塞,都会延迟收发和定时处理。
## 4. 业务接入
应用每轮Process/Poll后主动取事件,TCP不调用业务函数:
| 事件类型(均带`IEC104_TCP_EVENT_`前缀) | 有效载荷与契约 |
|---|---|
| `CONNECTED` | `data.connection`包含TCP建连状态及`peer`地址副本,不表示104已STARTED |
| `ACTIVATED` | `data.connection`保存STARTDT_ACT成功受理并激活后的快照;CON可能尚未写出,data_transfer_started=1 |
| `DEACTIVATED` | `data.connection`保存STOPDT_ACT成功受理并停用后的快照;ACK或CON可能仍待完成,data_transfer_started=0,TCP保持 |
| `I_FRAME` | `data.i_frame`保存完整APDU数组、长度、N(S)/N(R)及receive_serial |
| `RECORD` | `data.record.value`为发送记录;closing=0表示正常ACK回执,closing=1表示断线时剩余记录 |
| `DISCONNECTED` | `data.connection`为收尾前状态及原主站`peer`;status_valid仅控制status有效性,socket_error为后端诊断码 |
所有事件都有`generation`,同一代次以CONNECTED开始,以DISCONNECTED结束。连接建立、激活、停用和断开均使用`data.connection`,携带原主站的地址副本;启停事件的socket_error固定为0,不沿用此前网络操作的历史诊断。closing=1不等于发送失败或成功,仍须检查`local_send_completed`和`peer_acknowledged`。TCP有序关闭不新增协议fault,收到链路ACK也不表示对端业务已执行。
ACTIVATED/DEACTIVATED反映ACT受理时的实际状态变化;初始STOPPED、同状态重复ACT、CON发送完成及单纯断开不额外产生启停事件。每次变化立即入FIFO,保留激活、停用、再激活的顺序。后续发送失败不会撤销此前事件,DISCONNECTED最后交付。通知容量不足时延后ACT受理,不会先改变状态再丢弃通知。
STOP受理即产生停用变化并关闭新I帧接收,非法I帧不交付业务。后到START成功受理重新激活并开放I帧;已有STOP_CON继续按FIFO发送,旧完成不改变当前状态。取消前按序收到的非法I帧仍断链。
首次START_CON未完成时也能受理STOP:状态事件在受理时依次为ACTIVATED、DEACTIVATED,不等CON写完。随后再受理START产生新的ACTIVATED;已经生成的CON不撤回,尚未生成的旧STOP_CON可因重新激活而不再生成。默认4个启停通知槽,满时延后受理改变状态的ACT。
业务事件是历史事实副本,不保证当前仍连接或处于同一状态。首次ACTIVATED在START受理时生成,先于该次激活后合法I_FRAME的交付;应答是否接手仍由提交时的实际状态判断。下面函数由应用在读取NextEvent后自行调用,不向TcpServer注册:
```c
#include "IEC104_TcpServer.h"
#include <inttypes.h>
#include <stdio.h>
void App_Log_Connection_Event(const IEC104_TcpEvent_t *event)
{
const char *name;
switch (event->type) {
case IEC104_TCP_EVENT_CONNECTED: name = "connected"; break;
case IEC104_TCP_EVENT_ACTIVATED: name = "activated"; break;
case IEC104_TCP_EVENT_DEACTIVATED: name = "deactivated"; break;
case IEC104_TCP_EVENT_DISCONNECTED: name = "disconnected"; break;
default: return; /* I_FRAME和RECORD由原有业务分派处理。 */
}
printf("%s: generation=%" PRIu64 ", %s:%u\n", name, event->generation,
event->data.connection.peer.address, (unsigned)event->data.connection.peer.port);
}
```
处理I_FRAME时,ASDU首地址为`event.data.i_frame.apdu + IEC104_APCI_LEN`,长度为`event.data.i_frame.apdu_length - IEC104_APCI_LEN`。接收入口已保证6字节公共头完整,并对已知固定长度类型按VSQ数量和SQ位检查最低载荷长度;不足时按FRAME故障断连,不处理该帧的序号或ACK,也不上报I_FRAME事件。该检查不要求长度恰好相等,未知/变长类型、零对象和具体字段是否合法仍由业务检查,范围见[基础设计的ASDU长度检查](IEC104_设计架构.md#43-已知类型的最低载荷长度)。需要取得公共头字段时,显式包含 `IEC60870_Codec.h` 并调用 `IEC60870_Parse_ASDU_Header`。提交业务应答时保留事件中的generation:
```c
IEC104_TcpSubmitResult_t result = IEC104_TcpServer_Send_Response(
server, event.generation,
response_asdu, response_length);
```
返回类型为`IEC104_TcpSubmitResult_t`,结果须显式判断:
| 结果(均带`IEC104_TCP_SUBMIT_`前缀) | 含义 |
|---|---|
| `OK` | 已复制到发送缓冲或HIGH,可以复用输入原文;可能已写完、仅写出部分、暂不可写或仍在排队,不承诺对端已ACK;尚在HIGH中的应答会在受理新STOP时作废 |
| `WAIT` | HIGH当前容量不足,本次未接手,业务保留原文后重试 |
| `ERROR` | 参数、阶段、连接身份或总容量不符;无连接、旧代次、EOF后、未启动且无启动CON待发、停止排空及停止CON待发均拒绝应答 |
| `FATAL` | 服务队列异常,或会话失败并收尾;可能已经写出部分或整帧,不能直接重放,须处理RECORD/DISCONNECTED |
应答仅在STARTED/IDLE接手,其余状态在记录、窗口和HIGH容量判断前返回SUBMIT_ERROR,不入HIGH也不因此断链。普通路径先Drive再判断实际状态;期限已到时直接Enqueue(HIGH)仍使用同一准入函数,不能用此前Get_Status快照代替。
准入后,发送缓冲为空、窗口和记录有余量、HIGH无旧应答且公平配额允许时,直接准备I帧并尝试一次非阻塞send。已有CON或其他帧时暂存HIGH,不能越过FIFO;发送暂停及原期限保持有效。START受理即可接手,不再等待CON完整写出才激活。
一旦APDU已准备,部分写入或暂不可写都保留该帧,后续从剩余字节继续;不会把原文再次放入HIGH。快速路径和队列路径使用同一N(S)、完成回报和ACK处理逻辑,均不把旧连接应答交给新连接。OK后不可重复提交同一应答。调用后重新Prepare刷新socket、定时及本地续跑条件;发送失败可能已关闭当前socket。
SUBMIT_OK表示已接手,不保证HIGH积压最终发出;STOP受理时清理待发HIGH并产生停用事件,没有逐条作废回执。已有当前帧和记录继续完成,NORMAL保持原生命周期。从停用状态重新START会清理HIGH和配额;已启用时重复START保留HIGH,这是此前确定的项目队列策略。
NextEvent返回后副本归业务所有,业务处理失败时自行保存副本,事件FIFO不会自动重投。主站请求通过I_FRAME事件交给业务解析;HIGH缓存的是业务生成的应答ASDU。
主动上报使用服务级NORMAL,不需要先取得连接代次:
```c
IEC104_TcpSubmitResult_t result = IEC104_TcpServer_Enqueue_Event(
server, event_asdu, event_length);
```
Enqueue_Event只复制到服务级低优先级事件队列(内部NORMAL),不立即发送;OK表示已入队,WAIT表示本次未接手,ERROR表示输入/阶段非法,FATAL表示队列异常。Init成功后、首次连接前和断线期间均可缓存;尚未STARTDT也可入队。重连后按现存原文顺序重新构帧,STARTDT完成后才发送。NORMAL满时覆盖最旧原文,包括未ACK原文;未ACK数据重发可能重复,不提供掉电持久化。EOF后全部尚未编号的NORMAL及后来新增的NORMAL均留给下一连接,已经编号的当前帧继续完成。离线入队不设置need_process,避免无连接空转;有连接且未EOF时成功入队会要求本地推进。事件提交和应答发送都须在所属事件循环线程串行调用。
接收和发送接入同一个服务对象。以下示例使用Poll;应用事件循环使用第3.1节的Prepare/Process流程,初始化、事件读取、入队和收尾相同。下例中的`App_Handle_Event`由业务实现,按上述事件类型分派;它由应用主循环直接调用,可以调用Send_Response提交应答。传入的event在下一次NextEvent覆盖前有效,需稍后处理时按值复制整个事件:
```c
#include "IEC104_TcpServer.h"
#include <stddef.h>
static IEC104_TcpServer_t *server; /* 只保存句柄,实际对象由模块静态持有。 */
static IEC104_TcpServerStatus_t last_status; /* 应用留存端口和会话快照。 */
static IEC104_TcpError_t last_error; /* 本次服务操作的结果、失败阶段及网络诊断。 */
/* 应用自己的函数,不向TcpServer注册。 */
void App_Handle_Event(IEC104_TcpServer_t *server, const IEC104_TcpEvent_t *event);
static int App_Read_Events(void)
{
IEC104_TcpEvent_t event;
IEC104_TcpEventResult_t result;
while ((result = IEC104_TcpServer_NextEvent(server, &event)) == IEC104_TCP_EVENT_READY) {
App_Handle_Event(server, &event);
}
return result == IEC104_TCP_EVENT_EMPTY;
}
int App_Tcp_Start(void)
{
IEC104_TcpServerConfig_t config;
if (server != NULL) {
return 0; /* 先结束上一轮,不能覆盖仍持有的句柄。 */
}
server = IEC104_TcpServer_Create();
if (server == NULL) {
return 0;
}
IEC104_TcpServer_Config_Default(&config);
if (IEC104_TcpServer_Init(server, &config, &last_error) != IEC104_TCP_OK) {
/* 后续查询和清理传NULL,保留last_error中的初始化失败原因。 */
(void)IEC104_TcpServer_Get_Status(server, &last_status, NULL);
(void)IEC104_TcpServer_Destroy(server, NULL); /* 新建句柄初始化失败,没有资源或事件。 */
server = NULL;
return 0;
}
(void)IEC104_TcpServer_Get_Status(server, &last_status, NULL);
return 1;
}
/* 初始化成功后持续调用;共享业务主循环传0,专门的TCP循环可传50等正数。 */
int App_Tcp_Step(uint32_t max_wait_ms)
{
IEC104_TcpResult_t result = IEC104_TcpServer_Poll(server, max_wait_ms, &last_error);
if (result != IEC104_TCP_OK) {
(void)IEC104_TcpServer_Get_Status(server, &last_status, NULL);
(void)IEC104_TcpServer_Close(server, NULL);
}
if (!App_Read_Events()) {
return 0;
}
return result == IEC104_TCP_OK; /* 应用自己的0/1约定,不把TCP枚举直接当作布尔值。 */
}
int App_Tcp_Stop(void)
{
if (server == NULL) {
return 1;
}
if (IEC104_TcpServer_Close(server, &last_error) != IEC104_TCP_OK || !App_Read_Events()) {
return 0;
}
/* Close后先交付全部收尾事件,随后归还静态槽。 */
if (IEC104_TcpServer_Destroy(server, &last_error) != IEC104_TCP_OK) {
return 0;
}
server = NULL;
return 1;
}
```
App_Tcp_Start返回0时处理初始化失败;新建句柄上的Init失败会在示例中保存last_error并归还槽。生命周期错误返回明确分类,error.socket_error保持0;Create仍以NULL表示无可用槽,不产生网络诊断。示例中的App函数沿用应用自己的0/1约定,底层统一结果接口则必须比较IEC104_TCP_OK。成功后持续调用App_Tcp_Step(0)或App_Tcp_Step(50),按本轮业务调度决定是否等待;0模式下仍须由主循环持续调度Poll,协议期限不会由后台线程自动推进。Step失败时先记录last_error,随后调用App_Tcp_Stop,因为Stop自身的诊断会覆盖该变量。正常退出也调用Stop,保证归还句柄。实际端口和会话状态使用Get_Status输出,本次失败使用error,不能访问对象成员。事件与应答入口只接受ASDU原文(6..249字节),不包含APCI;不用手动构造I帧或调用socket的send。请求应答通过Send_Response在处理I_FRAME事件时提交,条件允许就立即尝试发送;主动上报通过Enqueue_Event进入服务队列。连接建立时尚未STARTED,实际业务发送受启停和k窗口约束。START尚未受理时,Send_Response返回ERROR,不能在CONNECTED事件中预存应答等待启动。START成功受理即开放准入,已有CON时应答入HIGH;已启用时重复START保留HIGH。
业务异步处理时可以复制整个事件交给工作线程,完成后由应用唤醒所属事件循环线程,再用保存的generation调用Send_Response并刷新Prepare结果;主动上报调用Enqueue_Event。不能从工作线程并发调用NextEvent、Enqueue_Event或Send_Response,也不能改用新连接的generation提交旧请求的应答。处理WAIT时自行保存应答并在后续调度间隙重试;对ERROR或FATAL应停止该次提交并按业务策略处理,不要无限重试。
### 4.1 对端查询与单连接关闭
对端地址查询与关闭连接是独立操作,Slave门面调用本节的TCP接口,不向业务交付Connection对象。查询使用接入时缓存的数值副本;关闭使用当前连接代次及统一结果分类。
`IEC104_TcpServer_Get_Remote_Address(server, &peer, error)`仅在OK时写入`IEC104_TcpPeerInfo_t`:
| 字段 | 含义 |
|---|---|
| `address[16]` | NUL结尾数字IPv4字符串,不含端口;当前未提供IPv6后端 |
| `port` | 主站TCP源端口,主机字节序,与子站监听端口bound_port不同 |
| `generation` | 当前主站非零代次,后续主动断开须携带原值 |
查询不执行I/O、不推进协议、不改服务状态;未Init或已Close返回INVALID_STATE,已Init但无客户端返回NOT_CONNECTED,其余参数/句柄/重入按统一结果处理,失败保持peer原值。EOF发送收尾期间仍持有客户端,查询可成功。CONNECTED、ACTIVATED、DEACTIVATED和DISCONNECTED均在`event.data.connection.peer`保留同一结构的副本,peer.generation等于外层event.generation;该地址不受协议status_valid影响。处理历史事件时直接使用副本,不查询当前新主站地址来标记旧连接。
主动断开当前主站的调用示例:
```c
#include "IEC104_TcpServer.h"
IEC104_TcpResult_t App_Close_Current_Connection(
IEC104_TcpServer_t *server, IEC104_TcpError_t *error)
{
IEC104_TcpPeerInfo_t peer;
IEC104_TcpResult_t result = IEC104_TcpServer_Get_Remote_Address(server, &peer, error);
if (result != IEC104_TCP_OK) {
return result;
}
/* 可先记录peer.address、peer.port及peer.generation,再结束此次查询对应的会话。 */
return IEC104_TcpServer_Close_Connection(server, peer.generation, error);
}
```
若是针对某个历史请求、事件或异步任务执行断开,直接传该任务保存的generation,不能重新查询最新代次来替换目标。generation为0返回INVALID_ARGUMENT;服务未Init返回INVALID_STATE;无客户端返回NOT_CONNECTED;当前存在其他代次返回STALE_GENERATION,阶段为GENERATION。这些拒绝分支都不关闭任何连接或追加收尾事件。两接口均须回到所属事件循环线程串行调用。
Close_Connection直接复用Drop_Client:关闭客户端,将剩余已受理I帧、发送记录及DISCONNECTED复制到事件FIFO,清理HIGH,恢复现存NORMAL的离线待发状态。它不发送STOPDT、不等待应答排空或ACK,不新增协议故障,不补造发送成功。重复断开已结束的连接只返回NOT_CONNECTED,不重复发事件;如果新主站已经接入,则旧代次返回STALE_GENERATION。若队列解除绑定失败,返回INTERNAL_ERROR/QUEUE_STATE,客户端已结束、监听仍在,应用须Close服务处理异常。
成功后监听地址、端口和service_token不变,后续Process按接入暂停与通知容量规则继续接入新主站;先消费事件并重新Prepare,移除旧客户端注册、更新定时和本地续跑条件。Close_Connection不限制主站再次连接。现存NORMAL可继续离线新增,重连并完成STARTDT后发送;未ACK原文恢复可能重复。Close仍负责关闭整个服务并清空所有ASDU缓存。
## 5. 启停、断线和重连
TCP连接后初始STOPPED,仅交付CONNECTED。START受理即激活并交付ACTIVATED,STOP受理即停用并交付DEACTIVATED;CON随后按FIFO完整写出,完成不再提交启停状态。后到START可结束尚未生成CON的停止等待;已生成的STOP_CON仍发送但不能覆盖新激活状态。停用不关闭TCP,可继续控制通信和重新启动。
EOF表示对端关闭发送方向:先调用AsduQueue_Limit_Normal_Send停止选取全部尚未编号的NORMAL,再记录`rx_eof`并结束当前接收批次。EOF前已入队及EOF后新增的未编号NORMAL都留给下一连接,避免在已无法取得新ACK的旧连接上继续新增上报帧。后续Process/Poll不再recv或关注该客户端的可读事件,继续通过发送调度处理当前已编号帧、此前已受理的HIGH及控制帧。已有当前I帧即使尚未写出字节也继续按原身份完成,不撤回N(S)。部分写入和`WSAEWOULDBLOCK`保留当前帧并关注可写;连续OK+0/RETRY仍执行发送暂停与定时恢复,发送预算耗尽安排本地续跑,均沿用原本的发送期限;不会仅因收到EOF而丢弃待发应答。Tick和其他协议期限仍持续推进,发送失败或超时按原故障路径收尾。
内部发送准备返回WAIT后,先按原有顺序和通知预算转移已确认记录;只要实际回收了记录槽,就重新准备发送,不用回收前的WAIT结果决定关闭。重试以实际回收为前提,受本轮通知预算约束。若仍WAIT,通过Connection.Get_Record_Wait确认是否仅受本地可回收记录容量限制:记录槽已满且队首已完整写出、已ACK,同时启停/k窗口允许新I帧、确认t1未到期。满足时保留连接及已接手的HIGH;只是本轮交付预算不足则安排下一轮Process,通知空间不足则由NextEvent腾出空间后唤醒。等待记录空间时不关注可写,也不持续为满FIFO安排本地续跑,原有协议及发送期限照常检查。
EMPTY表示当前帧、HIGH及控制发送均已排空,即使仍有未编号NORMAL也结束连接;其他WAIT表示仍需新的ACK/STARTDT等对端输入或已经受确认期限限制,也结束连接。不能仅因存在旧的已确认记录,就掩盖同时存在的窗口已满或停用状态。EOF后的等待只用于回收已经获得确认的记录,不等待新的对端报文,也不等待异步业务追加应答。业务应在取得I_FRAME事件后、下一次Process/Poll前入队,或在正常双向连接期间完成异步应答。协议错误、发送失败或期限到达仍可立即收尾,历史I帧事件不保证连接此刻仍可发送。
有序关闭本身不新增连接故障;接收错误调用Handle_Transport_Closed,发送错误先调用Handle_Send_Failure。协议FATAL保持原故障原因。收尾时结束实际I/O、交付剩余记录及关闭通知,最后Connection_Close并清空TCP接收尾部、EOF标记及发送重试期限/计数。监听socket继续等待新连接,新连接正常接收。正常TCP关闭不等于业务全部成功,未完成或未ACK的I帧仍通过`closing=1`的记录交付,不补造发送成功或对端确认;现存NORMAL在解除连接绑定后继续保留,等待新连接启动。
收尾按偏移只读复制内部发送记录,仅在RECORD成功入队后累计`records_saved`。生成DISCONNECTED时,查询关闭协议前的状态,并从内部记录总数中扣除`records_saved`,得到尚未转为事件的记录数;实际记录仍由最后的Connection_Close统一清理。读取记录返回EMPTY表示已读完,ERROR或事件入队失败则走现有收尾异常处理,快照仅扣除成功转移的部分,不能无条件清零。状态查询失败或成功转移数大于内部总数时,断开快照标记`status_valid=0`;计数不一致也按收尾异常处理。RECORD和DISCONNECTED的先后顺序及各记录中的发送、ACK事实保持不变。
每次接受主站都分配递增的非零generation,新连接重新进行STARTDT。代次到UINT64_MAX后拒绝继续分配,Poll返回GENERATION_EXHAUSTED且阶段为GENERATION,不回绕复用;该静态槽归还后也不再Create分配。同一槽Close/Init或Destroy/Create均沿用代次计数。句柄仅在一次Create到Destroy之间有效;业务在Destroy前须结束引用它的旧任务,也不能把旧事件交给另一个服务器句柄。
队列生命周期固定属于服务:Init先以内部代次0建立离线队列;客户端关闭时,在Connection_Close之后调用AsduQueue_Detach,立即清空HIGH、恢复现存NORMAL待发状态并回到代次0;断线期间新增NORMAL继续追加到同一字节环。新连接使用AsduQueue_Rebind绑定新的非零代次,再初始化Connection。绑定转换失败报告服务级INTERNAL_ERROR,不能重新Init队列而静默丢失缓存。主动Close整个服务才清空队列,下一次Init从空队列开始。
不再提供重连保留开关或旧通用入队接口。NORMAL用于面向同一业务接收方/冗余域的主动事件,业务须允许未ACK原文重发;模块不认证主站身份、不管理冗余组,也不实现应用去重。
## 6. 平台边界与接入约定
`Net.h`只包含标准C类型,不依赖Connection、Link或业务结构。后端不维护104状态,也不处理业务事件队列、记录消费、接收预算或NORMAL重连保留;这些职责留在TcpServer。后端使用以下统一结果:
| 结果 | TcpServer处理 |
|---|---|
| `OK` | 收发按实际字节数推进;Wait的就绪位为0表示未报告socket就绪;发送0字节不当作EOF,与send的RETRY合计连续4次后暂停发送10毫秒 |
| `WOULD_BLOCK` | 本次暂不可接受连接/读写,保留状态后续重试 |
| `RETRY` | accept在4次预算内重试,整轮均为RETRY时暂停100毫秒;send与OK+0合计连续4次后暂停发送10毫秒;recv结束本次尝试并交还调度;等待中断后仍推进接收和Tick |
| `RETRY_LATER` | 仅Accept使用:资源暂缺,立即暂停接入100毫秒后重试,保留监听和活动客户端 |
| `EOF` | 仅接收方向返回,停止继续接收,按现有规则排空发送后关闭客户端 |
| `ERROR` | 接收/发送错误收尾当前客户端;监听或等待错误返回服务级失败 |
Windows后端在内部把`WSAEWOULDBLOCK`转换为WOULD_BLOCK,把`WSAEINTR`以及accept的`WSAECONNRESET`/`WSAECONNABORTED`转换为RETRY。接入路径的`WSAENOBUFS`/`WSAEMFILE`转换为RETRY_LATER;原生错误码另外保留用于诊断。该分类不改变recv/send或监听初始化的错误处理,新的枚举值追加在EOF之后,已有值不变。Net_Accept(listener, &client, &peer, &native_error)成功时同时交付非阻塞且启用TCP_NODELAY的客户端和IEC104_NetPeer_t。Windows后端由accept取得sockaddr_in,先显式设置非阻塞及`TCP_NODELAY=1`,再用InetNtopA及ntohs转换IPv4和源端口;任一步骤失败先保存错误码并回收新句柄,再返回RETRY,若错误属于上述资源暂缺则返回RETRY_LATER。失败时client保持INVALID_SOCKET,peer保持原值。后端本身不循环重试或等待;监听句柄仍由调用方管理。Listen失败由后端回收其申请的句柄;TcpServer负责配对调用Net_Init/Net_Cleanup。
TCP_NODELAY设置在每个新接入的客户端socket上,关闭Nagle以减少S/U帧和短I帧的合并等待;重连时同样执行。该选项不改变104确认规则、发送顺序或非阻塞收发语义,send成功仍只表示字节交给本地TCP,不保证对端已经收到。
Net_Wait只接受通用事件位,系统的`fd_set`、`timeval`和等待参数差异留在平台文件中;只有Poll使用这个等待入口。应用自己的事件循环通过TcpServer_Prepare借出socket并传回就绪批次,Process仍经Net完成真实收发。所有I/O接口同步返回、无未完成I/O借用;后端须满足此契约,不能在返回后继续借用同一发送缓冲,也不能让业务绕过TcpServer驱动内部Connection。
2026-10-20增加内部接口`Net_Pending_Input(socket, &available, &error)`:只读取得当前内核接收队列字节数,不等待、不消费数据,失败返回ERROR。Windows使用`ioctlsocket(FIONREAD)`,未来其他平台或自定义Net后端必须补齐此接口。每份预算续收快照最多查询一次;快照期间不重新查询来扩大范围。该接口不属于业务公开API,零字节也不等于EOF,EOF仍由recv确认。真实Windows回环验证见`iec104_net_pending_input_test.c`。
Net_Wait允许interest为0,用于没有socket关注时的纯定时等待。Windows后端不把空集合传给select:wait_ms为0直接返回,正数调用一次有限Sleep,UINT32_MAX截为UINT32_MAX-1,避免被解释成INFINITE。Poll在进入该路径之前仍先合并max_wait_ms、协议/接入/发送重试期限、本地工作及未读事件;有事件背压时等待为0,立即交还业务。空集合等待返回后也照常计算timer_expired;Sleep可能提前结束,Process的实际接入及发送门控仍以当前单调时钟为准。Prepare/Process不执行睡眠,其他平台后端也须支持空集合的有限等待。
Slave是业务的统一子站入口,TcpServer是其内部的TCP服务。以下操作由门面代理,也可用于独立TCP接入。应用通过Create/Destroy管理句柄,使用Prepare/Process或Poll推进,并调用NextEvent/Enqueue_Event/Send_Response/Get_Remote_Address/Get_Status;Close_Connection只断开指定主站,Init/Close管理服务生命周期。Connection、SendManager及发送队列由TCP内部创建、驱动和回收。业务包含`IEC104_TcpServer.h`,其依赖的`IEC104_TcpTypes.h`和`IEC104_Types.h`提供公共值类型;Connection和SendManager头文件中的完整结构体定义用于内部静态存储,不属于业务接口。连接状态、发送记录和返回值在TCP实现中显式转换,业务不依赖内部结果或记录布局。
应用已有事件循环时通过Prepare/Process/NextEvent接入,socket注册的平台差异由应用的事件循环适配处理,库内真实I/O的平台差异由Net后端处理。Connection不反向调用Net,业务不直接驱动Connection或SendManager。ASDU内容可继续由业务使用Codec和公共时间工具解析、构造,这些无连接状态的工具不改变TCP接入边界。
新增后端时,实现`IEC104_Net.h`中的全部接口并替换链接文件;同时验证句柄无效值、非阻塞状态、部分写入、EOF、单调计时及失败资源回收。无需修改TcpServer或104协议模块。业务事件接口与平台选择无关。
## 7. Windows接口参考
- [Winsock服务端基本流程](https://learn.microsoft.com/en-us/windows/win32/winsock/complete-server-code)
- [非阻塞socket设置](https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-ioctlsocket)
- [select就绪等待](https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-select)
- [accept返回值与错误码](https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-accept)
- [Sleep与无限等待哨兵](https://learn.microsoft.com/en-us/windows/win32/api/synchapi/nf-synchapi-sleep)
- [send的部分写入与返回值](https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-send)
- [recv的EOF及暂不可读](https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-recv)
- [单调毫秒计时](https://learn.microsoft.com/en-us/windows/win32/api/sysinfoapi/nf-sysinfoapi-gettickcount64)
@@ -0,0 +1,728 @@
# IEC104 子站发送模块设计
同步日期:2026-10-20。本文对应 AsduQueue、SendBuffer、SendManager 当前实现,接口声明分别见 [AsduQueue.h](../../104/IEC104_AsduQueue.h)、[SendBuffer.h](../../104/IEC104_SendBuffer.h)、[SendManager.h](../../104/IEC104_SendManager.h)。
TCP接入边界:业务统一使用`IEC104_Slave.h`,Slave内部调用TcpServer;事件经`TcpServer_Enqueue_Event → AsduQueue_Enqueue`进入服务级NORMAL队列,应答经`TcpServer_Send_Response → Connection_Submit_Response → SendManager_Submit_Response`校验会话及启停准入后直接准备或缓存HIGH;协议期限已到时改走Manager.Enqueue(HIGH),使用同一准入检查。本文说明TCP内部发送模块的存储和调用契约,下文的模块调用方指Connection等内部实现。业务不直接包含或操作Manager、Buffer、Queue;应用主循环和事件用法见[TCP服务设计](IEC104_TcpServer_设计架构.md#4-业务接入)。
发送模块采用变长业务字节环、发送前编号、单当前I报文和独立确认记录。满时策略采用HIGH拒绝、NORMAL覆盖最旧原文,后者包含已提交未ACK条目且不提供逐条丢弃通知。保留静态内存、部分写入、本地发送期限、逐帧业务回执、代次隔离、公平配额及严格启停/TESTFR语义;不加入动态分配、线程或socket封装。
条目头按高低优先级职责拆分:HIGH仅有2字节长度,NORMAL保存编号、状态及长度,采用 `sizeof(IEC104_AsduNormalEntryHeader_t)` 作为头长,当前Windows 64位GCC下为16字节。两级队列及发送记录均移除user_tag;只有NORMAL分配条目编号,HIGH只消费当前队首。现有分段字节环、独立帧身份和帧回执继续使用,接口迁移见第6.2节。
- [整体数据生命周期](#overview)
- [SendBuffer:当前I帧与控制队列](#sendbuffer)
- [AsduQueue:变长业务队列](#asduqueue)
- [SendManager:准备、完成、ACK及回执](#sendmanager)
- [内部调度和恢复](#integration)
- [构建与接口迁移](#build)
<a id="overview"></a>
## 1. 整体数据生命周期
业务事件通过Enqueue_Event缓存NORMAL,入队时没有N(S),离线也可缓存。应答通过Send_Response提交:Connection核对会话及期限,Manager仅在STARTED+IDLE时接手,其他启停阶段返回ERROR且不入HIGH。准入后,在顺序、发送门控、窗口、记录和公平配额允许时直接准备I帧并分配N(S),暂不能准备时只复制到HIGH。TcpServer对直接应答最多尝试一次非阻塞send。
后续由Connection调用Manager.Prepare_Next_Send:续传已有当前帧;否则先取S/U控制队列;两者均空时,才在HIGH/NORMAL待发业务之间选择。队列发送和直接应答共用Prepare_I_Asdu完成预留、Link构帧和记录交接;实际socket写入统一由TcpServer经Net执行。
~~~mermaid
flowchart LR
B[业务] -->|Enqueue_Event / Send_Response / Poll / NextEvent| T[TcpServer]
T -->|内部连接调度| C[Connection]
T -->|实际网络收发| N[Net后端]
C -->|入队 / 准备 / 进度 / ACK| M[SendManager]
M -->|入队 / 选取 / 释放原文| Q[AsduQueue 两级字节环]
T -->|NORMAL服务缓存 / 绑定生命周期| Q
M -->|准备一帧并分配序号| L[Link]
M -->|报文存储与写入进度| S[SendBuffer 当前I帧 / 控制FIFO]
M -->|内部记录查询结果| C
C -->|内部帧和记录查询结果| T
T -->|NextEvent返回事件副本| B
~~~
| 阶段 | AsduQueue | SendBuffer | Manager记录 |
|---|---|---|---|
| 事件入队或应答暂存 | 保留未编号ASDU | 无变化 | 无记录 |
| 准备当前I帧 | HIGH原文出队;NORMAL标记已提交并保留原文 | 保存唯一当前I APDU | 建立帧身份、快照及NORMAL来源编号 |
| 直接准备应答 | 不入ASDU队列,不调用Mark_Submitted | 保存唯一当前I APDU | 建立HIGH记录,来源编号为0,纳入high_unacked_count |
| 部分写入/EAGAIN | HIGH没有队列原文,NORMAL可被后续入队覆盖 | 同帧原字节、原身份,续写剩余部分 | 未本地完成 |
| 整帧写完并提交 | HIGH没有队列原文,NORMAL可被后续入队覆盖 | I槽立即可复用 | 记录本地完成及实际写完时刻 |
| NORMAL空间不足时入队 | 覆盖最旧原文,记录已提交条目的待确认数量 | 已准备APDU保持原字节和进度 | 已编号记录保留,未编号条目无帧回执 |
| 对端有效累计ACK | HIGH不访问队列;NORMAL释放原文或核减覆盖待确认数 | 不访问旧I APDU | 标记已确认,等待TcpServer转为事件 |
| TcpServer复制RECORD事件并经Connection移除记录 | 无变化 | 无变化 | 释放记录槽 |
| 业务通过NextEvent读取事件副本 | 无变化 | 无变化 | 无变化;对应内部记录已移除 |
| 断线后Manager.Abort | 保留环内剩余原文;已覆盖原文不能恢复 | 清除发送状态 | 终止前须读取待回收记录 |
链路ACK表示对端协议接收确认,不表示遥控等应用操作已经执行成功。本地写完也不等于已ACK。
这些对象、字节数组、控制槽和记录数组均包含在TcpServer的私有存储中,Connection负责绑定和驱动发送模块;存储生命周期覆盖整个使用期。本模块不malloc、不释放借用内存、不内置锁。同一连接的入队、发送准备、写入结果、接收、查询和回收必须串行。Connection把事件交给Manager后,不得再调用底层Link、Buffer或Queue重复提交。业务只持有TcpServer句柄和公开值类型。
### 1.1 身份与时间
| 字段 | 用途 |
|---|---|
| connection_generation | 连接使用非零且不复用的代次;AsduQueue的0表示离线服务缓存,仅接受NORMAL,不能提交发送 |
| entry_serial | 仅NORMAL成功入队分配,1..UINT64_MAX循环,Rebind不重置;HIGH恒为0,无条目身份 |
| frame_serial | SendBuffer成功预留分配,取消后也不复用 |
| N(S)/N(R) | Link管理的15位协议序号,按模32768运算 |
| queued_at_ms | I帧准备或控制帧入队时刻,本地发送期限起点 |
| written_at_ms | 整帧实际写完时刻,I帧t1和主动TESTFR等待CON的起点 |
NORMAL的64位entry_serial在UINT64_MAX之后回到1,0对NORMAL是无效值;回绕不改变connection_generation。HIGH不分配条目编号,查询和发送记录的来源编号均为0,不能用0识别某条HIGH业务。活跃NORMAL编号按循环距离比较,不能按整数大小排序。SendBuffer的frame_serial仍采用耗尽时报错、不回绕的策略,两种编号独立。跨连接代次的全局不复用由调用方保障。is_initialized只表示对象初始化成功,不表示TCP存活。单调时刻允许0;部分写入、重复准备、重复ACK及WAIT均不续期。
<a id="sendbuffer"></a>
## 2. SendBuffer:当前I帧与控制队列
源码:[IEC104_SendBuffer.c](../../104/IEC104_SendBuffer.c)。
### 2.1 存储结构
SendBuffer结构内置一份255字节i_apdu和一份I帧快照;只允许一帧已准备但尚未提交本地完成的I报文。调用方另提供固定的IEC104_SendBufferControlFrame_t数组,容量1..65535,每槽仅保存6字节S/U APDU及元数据。
没有APDU节点池、空闲链、保留链、control_reserve_count,也不复制Link的三个序号边界。控制队列容量与k、ASDU字节容量、回执容量分别配置。S/U不占I帧k窗口或业务回执槽,控制队列自身仍可能满。
| 结构/字段组 | 含义 |
|---|---|
| FrameState | frame_serial、入队/写完时刻、长度、已写字节、encoded_nr、帧类型 |
| ControlFrame | FrameState + 6字节APDU |
| control_frames/capacity/head_index/count | 独立S/U环形FIFO;队尾由头和数量推导 |
| i_frame_state/i_frame_snapshot/i_apdu | 当前I帧元数据、不可变序号快照和字节 |
| has_i_frame | 当前I帧已提交,即使已写0字节也占用 |
| has_reservation/reservation_is_i_frame | 唯一预留是否存在及其类型 |
| generation/next_frame_serial | 本地身份及不复用编号 |
| Status | 代次、控制数量、当前I帧是否存在及其N(S)、预留标志、是否空闲 |
| HeadInfo | 当前身份、类型、快照、剩余字节借用指针、进度及时间 |
HeadInfo中的pending_data只借用当前存储,完整提交、Abort或Init后不能继续使用。发送异步进行时,同帧最多允许一个尚未回报的写操作。
<a id="sb-functions"></a>
### 2.2 初始化与验证
Init(buffer, control_frames, control_capacity, generation)只初始化控制结构,绑定调用方数组。Get_Status验证边界及要访问的端点并返回数值副本,不扫描整个控制队列。
Buffer_State_Valid检查索引、容量、0/1标志、身份及当前/控制端点元数据;Frame_State_Valid检查长度、快照、进度和完整写完时刻。Frame_Type_Matches结合Codec.Parse_APCI验证提交类型,子站仅接受I、S_ACK、STARTDT_CON、STOPDT_CON、TESTFR_ACT、TESTFR_CON。不能提交主站STARTDT_ACT或STOPDT_ACT。
<a id="sb-reserve"></a>
### 2.3 预留和提交
| 操作 | 成功及阻塞含义 |
|---|---|
| Reserve_I_Frame | 只有当前I帧和控制队列均空时成功;否则BUSY |
| Reserve_S_U_Frame | 预留控制队尾;控制队列满为FULL |
| 两种Reserve | 任一已有预留时BUSY;成功分配不复用frame_id |
| Commit_Frame | 校验身份、APCI、长度和I快照;I成为当前帧,S/U追加FIFO |
| Cancel_Reservation | 只归还尚未构帧成功的预留,已使用身份不复用 |
| Peek_Send_Head | 有当前I帧就返回它,否则返回控制队首;不选择业务 |
先预留存储,再调用会产生发送义务的Link构帧接口。Link.Prepare成功后N(S)或控制过程已提交,不能取消预留并继续旧连接;此后的提交异常必须结束连接。
控制帧优先于**尚未准备的业务**。已经准备的当前I帧,即使第一次写socket得到EAGAIN且尚未写出字节,也必须保持顺序先完成。此规则避免撤回已编号帧及已经冻结的N(R)快照。部分写出的任意APDU都不能被另一个APDU插入字节。
<a id="sb-completion"></a>
### 2.4 写入进度与释放
Record_Written_Bytes仅接受当前身份和实际写入增量。增量0不推进;未写完返回OK;恰好写完返回FRAME_WRITTEN并记录时刻;超出剩余长度、旧身份、重复完整提交返回ERROR。
Manager在整帧写完时连续执行:
1. 按保存的类型调用Link.Complete,I帧传回原始快照。
2. 登记I帧本地完成和实际写完时刻。
3. 调用Buffer.Commit_Send_Completion,释放当前I槽或控制队首。
只有第三步结束才可以复用报文字节。中间不得分派ACK事件,不得重入发送操作。该顺序由Manager内部维护,Connection按序提交发送结果和ACK;业务不调用SendBuffer完成接口。
<a id="sb-ack"></a>
### 2.5 ACK与超时的归属
SendBuffer不处理ACK,没有Apply_Peer_Ack。协议确认边界由Link独占;Manager记录ACK,核减HIGH未确认计数,并清理NORMAL仍保留的原文或已覆盖待确认计数。Buffer不再需要保留已发送APDU等ACK。
Head_Send_Expired从当前帧原queued_at_ms判断本地发送期限,返回1到期、0无帧或未到期、-1非法。控制帧等待前一帧期间也计入其原期限;进入队首后不会重新计时。I帧ACK的t1查询位于Manager。
Abort清除Buffer控制结构,不关闭TCP、不取消异步I/O;调用方先结束旧I/O再复用存储。
<a id="asduqueue"></a>
## 3. AsduQueue:变长业务队列
源码:[IEC104_AsduQueue.c](../../104/IEC104_AsduQueue.c)。
### 3.1 两级可跨尾部的字节环
HIGH和NORMAL各使用调用方提供的uint8_t数组,容量单位为**字节**。两级分别使用 `IEC104_ASDU_HIGH_ENTRY_HEADER_LEN` 和 `IEC104_ASDU_NORMAL_ENTRY_HEADER_LEN` 计算容量:
~~~text
HIGH:ASDU长度 uint16(2) | ASDU(6..249)
NORMAL:entry_serial uint64 | entry_state:2位 | asdu_length:8位 | ABI填充 | ASDU(6..249)
~~~
HIGH头固定2字节;NORMAL头是 `IEC104_AsduNormalEntryHeader_t` 的当前ABI布局,Windows 64位GCC下为16字节,其他平台以sizeof为准。NORMAL的entry_state为1表示未提交、2表示已提交待ACK,0/3无效;头内状态必须与已提交前缀/未提交后缀一致。两个头都通过memcpy读写,不要求环内地址对齐,不能将字节环强转成结构体指针。头不是协议字段或跨版本持久化格式;ASDU不含APCI、不含N(S)。Enqueue验证长度和容器条件,具体业务对象合法性由生产者负责。两级均不保存user_tag。
HIGH最小容量为2+6=8字节,NORMAL最小容量为NORMAL头长+6(当前ABI下22字节),只保证容纳最短ASDU。Enqueue先检查 `本级头长 + asdu_length <= 目标桶总容量`;不满足时返回ERROR,空队列也不能接纳该条目。100字节环最多容纳98字节HIGH ASDU,或当前ABI下84字节NORMAL ASDU;最大249字节ASDU分别需要251字节及NORMAL头长+249(当前ABI下265字节)。这种错误须调整容量或业务组帧,等待ACK释放空间无法解决。
条目能放入目标桶总容量后,才检查当前总空闲空间。条目头和ASDU都可以跨数组尾部:先使用尾部剩余字节,再从下标0继续,不插入额外回绕填充、不搬动在途原文。`used_bytes` 恰好等于所有保留条目的 `本级头长 + 实际长度` 之和,NORMAL结构体本身的ABI填充已计入头长。参数、状态合法时,只要总空闲不少于本条大小就有足够字节容量;HIGH总空闲不足时返回FULL,NORMAL总空闲不足时按队首顺序覆盖旧条目直到足够。NORMAL还检查编号窗口,HIGH不受该窗口限制。队列清空时索引归零。
例如当前ABI下100字节NORMAL环中,`head=40、tail=80、used=40`,尾部有20字节、开头有40字节可用。新的50字节条目(16字节头+34字节ASDU)直接使用尾部20字节及开头30字节,成功后 `tail=30、used=90`。其中ASDU原文分为尾部4字节和开头30字节,队列通过两段只读视图交给调用方。
NORMAL内部保持已登记交接、保留原文待ACK的前缀;HIGH只保存队列待发条目:
~~~text
NORMAL:队首 → 保留原文待ACK的前缀 → unsubmitted_index指向的待发后缀 → 队尾
HIGH:队首(也是unsubmitted_index)→ 全部待发条目 → 队尾
~~~
unsubmitted_index直接指向队列中下一条尚未登记发送交接的条目,发送选择不扫描保留待ACK前缀。NORMAL在入队时已经分配entry_serial,HIGH没有条目编号;刚入队时两级都没有I帧N(S),编号由后续发送流程分配,不能仅凭队列待发状态判断是否已编号。unsubmitted_count为0时,unsubmitted_index等于tail_index。HIGH在对应I帧已交给SendBuffer且Manager已登记记录后,通过Mark_Submitted消费队列原文;NORMAL的Mark_Submitted将头内状态设为保留原文待ACK,并推进待发游标。NORMAL空间不足时删除最旧条目,既可删除待发条目,也可删除保留待ACK原文,一次入队可能删除多条。新条目成功入队仍返回OK,不增加丢弃通知或回调。
原文删除不会撤销已编号的I帧:当前APDU在SendBuffer中有独立副本,Manager记录继续保留,k窗口、本地发送期限、t1和逐帧回执仍按真实发送及ACK推进。已覆盖但未ACK的已提交数量单独记录,不再占字节环容量。未编号条目被覆盖时尚未生成I帧,因此没有对应帧回执。
Enqueue先检查新条目本身能否放入总容量,再在控制副本中检查需要删除的全部旧条目;NORMAL另检查下一编号窗口,最后才写新字节并发布状态。条目过大或覆盖途中发现非法头时返回ERROR,原队列、字节和编号不变。NORMAL的UINT64_MAX仍可分配,下一编号回到1。正常覆盖复杂度为O(本次删除条目数);当前ABI下NORMAL条目为22..265字节,一次最多删除13条。其他ABI的上界为向上取整 `(NORMAL头长+249)/(NORMAL头长+6)`。
<a id="aq-fields"></a>
### 3.2 控制字段
| 字段 | 含义 |
|---|---|
| bytes/byte_capacity | 借用的字节数组及容量 |
| head_index/tail_index | 最旧保留条目和下一写入位置 |
| used_bytes | 所有保留条目的本级头长+ASDU实际长度之和,无额外回绕填充 |
| entry_count | 原文仍保留的ASDU总条目数;HIGH只保留待发区,NORMAL包含保留待ACK前缀和待发后缀 |
| unsubmitted_index/unsubmitted_count | 队列中下一条尚未登记发送交接的ASDU位置及条目数,不是SendBuffer中的帧数 |
| next_entry_serial | 下一个NORMAL成功入队身份;UINT64_MAX之后回到1;HIGH不消耗编号 |
| connection_generation | 队列当前绑定;0表示离线服务缓存,非零值绑定当前连接 |
| normal_send_limited | EOF收尾开关;为1时停止选取全部未提交NORMAL,原文留给下一连接,Detach/Rebind清零并解除限制 |
| overwritten_unacked_serial_begin | NORMAL原文已覆盖、仍待ACK的循环区间起始边界,含端点;ACK后推进,计数为0时为0 |
| overwritten_unacked_serial_end | 同一循环区间的结束边界,含端点;对应最后一个已覆盖待确认身份,计数为0时为0 |
| overwritten_unacked_count | NORMAL原文已覆盖、已提交且待确认的ASDU条目数,Queue和Status均提供 |
| Status.entry_count/retained_unacked_count | 各优先级原文仍保留的ASDU总条目数/其中已提交且待确认的ASDU条目数 |
| Status.is_storage_empty | 两级原文环均为空;HIGH或NORMAL仍可能有对应I帧等待ACK |
| HeadInfo.entry_id/priority/is_submitted | 条目身份、优先级及队列记账状态;is_submitted为0表示尚未登记交接,为1表示NORMAL保留原文待ACK;HIGH的entry_serial及is_submitted恒为0 |
| HeadInfo.asdu_first/asdu_first_length | 原文第一段及长度,指针非NULL |
| HeadInfo.asdu_second/asdu_length | 第二段或NULL,以及两段总长度;第二段长度=总长度-第一段长度 |
这些计数的单位都是ASDU条目。每一级的 `retained_unacked_count = entry_count - unsubmitted_count` 只统计原文仍保留、已提交且待确认的ASDU条目。HIGH提交后已经出队,其entry_count等于unsubmitted_count,retained_unacked_count恒为0。队列状态只能给出NORMAL保留及覆盖待确认数;全部已编号未ACK的I帧数还须加上Manager.high_unacked_count。
“未提交/已提交”在AsduQueue中描述队列记账状态。`Mark_Submitted` 的含义是登记已经完成的发送交接,调用顺序为:
```text
AsduQueue保存待发ASDU
→ SendBuffer接手组装好的完整I帧
→ Manager建立发送记录
→ Mark_Submitted完成队列记账
HIGH:消费队列原文,SendBuffer报文及Manager记录继续有效
NORMAL:登记为保留原文待ACK,将待发游标移到下一条
```
在最后一步执行前,队列仍保留待发旧状态,即使SendBuffer已经接手报文。因此HIGH在Mark_Submitted中核对待发旧状态后出队,出队依据是前面的交接已成功;不能把状态值0理解为“尚未交给发送模块就丢弃”。主动取消待发业务使用Discard_Unsubmitted_Head,且必须发生在发送交接之前。上述交接操作必须串行完成,中途不得插入队列修改。
公开视图 `is_submitted` 的0/1表示尚未登记交接/NORMAL保留待ACK;NORMAL条目头 `entry_state` 的1/2是对应的内部编码,两者不是同一组数值。HIGH条目头没有状态字段,完成交接后直接出队,不会留下is_submitted为1的条目。
待确认表示对应I帧尚未收到有效ACK,包含尚未写出、部分写出及整帧写完后等待ACK的阶段。当前实现中,一个已提交ASDU条目对应一个I帧,因此Manager的HIGH未确认数加NORMAL保留及覆盖待确认数,在数值上等于已编号未ACK的I帧数。AsduQueue保存条目头和ASDU原文;完整I帧的存储归SendBuffer管理,整帧写完并提交本地完成后即可复用,Manager的发送记录继续等待ACK。
`is_storage_empty` 只表示两级ASDU原文环为空,已经出队的HIGH或原文已覆盖的NORMAL仍可能有对应I帧待确认。这里的retained仅描述原文仍在缓冲区。只有NORMAL有条目编号;同一级内部提交及ACK处理始终FIFO。
overwritten_unacked统一表示“原文已覆盖、仍待有效ACK”。begin/end是包含两端的循环区间边界,实际数量以count为准。例如NORMAL已覆盖待确认编号为10、12,而11此前在未提交时被主动丢弃,则begin=10、end=12、count=2;确认10后begin推进到11、count减为1,实际下一待确认身份仍是12。区间起始边界不一定是某条现存记录的编号,也不能用普通整数大小比较跨UINT64_MAX回绕的边界。
<a id="aq-functions"></a>
### 3.3 公开操作
| 接口 | 行为 |
|---|---|
| Init | 服务启动时绑定两个字节数组;代次0可离线缓存NORMAL,非零值绑定连接,不分配内存 |
| Enqueue | 固定HIGH用于当前连接应答、NORMAL用于可跨连接恢复的事件;超过桶总容量为ERROR;HIGH当前空间不足为FULL,NORMAL覆盖最旧原文;NORMAL编号窗口受阻也返回FULL;OK复制ASDU,仅NORMAL分配身份;不接收user_tag,失败不改队列、字节或编号 |
| Get_Status | 常数时间查询代次、各优先级ASDU原文保留条目数、其中已提交待确认条目数、NORMAL原文已覆盖待确认条目数及原文是否为空 |
| Peek_Head | 查看最旧保留条目,可能已提交 |
| Peek_Unsubmitted | 常数时间查看当前允许交接的待发条目;EOF限制期间NORMAL返回EMPTY,即使仍有EOF前后入队的原文 |
| Copy_Asdu | 把仍有效的最多两段原文复制到调用方连续缓冲;容量不足或描述非法时ERROR且不改输出 |
| Mark_Submitted | 仅非零绑定代次可调用;SendBuffer接手I帧且Manager建立记录后核对状态及身份,HIGH消费原文,NORMAL保留待ACK;EOF后NORMAL禁止新交接,不影响此前已提交的帧;不执行I/O |
| Confirm_Next_Normal_Entry | 仅接受NORMAL:有原文时核对已提交队首并释放,已覆盖时核减待确认数;HIGH返回ERROR,其ACK由Manager记录处理 |
| Discard_Unsubmitted_Head | 仅允许主动移除未提交队首,拒绝撤回已编号业务 |
| Get_Entry_By_Offset | O(offset)查看保留条目,供故障检查及业务恢复 |
| Get_Free_Bytes | 返回未占用字节数;空闲不少于本级头长+ASDU长度即有足够容量;NORMAL另检查编号窗口 |
| Reset_High | 同代次清空HIGH待发条目;保留NORMAL及next_entry_serial,不影响已提交帧和Manager记录 |
| Limit_Normal_Send | EOF时停止选取全部未提交NORMAL,原文留给下一连接;不改已提交帧或HIGH,重复调用不解除限制 |
| Detach | 旧I/O及Manager结束后核对旧代次,清空HIGH并恢复现存NORMAL待发状态,切换到代次0;清除旧覆盖记账及发送限制 |
| Rebind | 完整检查两级,绑定新的非零代次,可从离线代次0接入;恢复现存NORMAL、清空HIGH及旧连接记账;ERROR不修改控制字段或字节 |
| Abort | 明确丢弃全部引用,调用方先完成业务回收 |
Peek操作成功才写输出;原文按 `asdu_first`、`asdu_second` 的顺序读取,后者为NULL表示全部位于第一段。本条目被覆盖、确认释放或Remove后两段借用失效;HIGH的Mark_Submitted释放当前队首,Reset_High使所有HIGH借用失效;Detach、Rebind、Abort或Init使所有借用失效。NORMAL的后续Enqueue可能覆盖旧原文,调用方不能跨可能覆盖它的操作继续使用借用。NORMAL的Remove/Mark及仍有原文的Confirm核对完整generation和entry_serial,不能用可回绕的N(S)代替身份。HIGH只核对generation及entry_serial==0,从Peek到Mark/Discard之间不得移除、清空或替换队首;不提供同代次的逐条身份保护,0编号不得长期保存为业务身份。
原文已覆盖时不另存一份完整身份列表;准确条目身份由Manager记录保存,Confirm_Next_Normal_Entry核对当前代次、计数及从overwritten_unacked_serial_begin到overwritten_unacked_serial_end的循环区间,要求按本优先级真实发送顺序调用。ACK后将区间下界推进到该编号的后继,拒绝重复/逆序确认;最后一个覆盖身份必须匹配区间终点,再允许释放仍保留的物理队首。覆盖计数归零时清除两个边界,避免无在途义务的历史确认长期占住编号窗口。普通业务不得构造身份调用Confirm_Next_Normal_Entry伪造ACK。
NORMAL编号环包含1..UINT64_MAX,前向距离为`to >= from ? to - from : UINT64_MAX - from + to`,因此UINT64_MAX到1的距离是1,而不是普通uint64溢出减法所得的2。非零距离不超过UINT64_MAX/2时才认为旧编号在新编号之前。NORMAL入队提交前检查其保留队首及覆盖待ACK区间下界到新next的距离,始终限制在半环内;只读至多一个队首,保持常数检查开销。若长期未处理的旧记录阻止窗口前进,NORMAL返回FULL,原队列及字节完全不变;处理旧条目或ACK后可重试。HIGH不分配编号,不受此窗口阻塞。NORMAL已经在控制副本中淘汰的未提交条目不再占用窗口。
该约束以仍保留的NORMAL条目和覆盖待ACK身份为准。HIGH的asdu_entry_serial恒为0,帧完成及ACK依据独立frame_id和N(S)匹配。释放后的NORMAL entry_id已经失效,调用方不得无限期保存并跨完整编号周期重新提交。回绕不会触发Rebind、清空业务或增加连接代次,也不增加内部条目头字段。
需要连续原文的业务恢复代码可使用以下接口。Copy_Asdu只检查描述和输出容量,不重新查询队列或验证身份;必须在借用有效期内串行调用,输出不得与原文或描述重叠。
~~~c
IEC104_AsduHeadInfo_t info;
uint8_t raw[IEC104_MAX_ASDU_LEN];
if (IEC104_AsduQueue_Peek_Head(&queue, IEC104_ASDU_PRIORITY_NORMAL,
&info) == IEC104_ASDU_QUEUE_OK &&
IEC104_AsduQueue_Copy_Asdu(&info, raw, sizeof raw) == IEC104_ASDU_QUEUE_OK) {
/* raw[0..info.asdu_length-1]是供内部处理使用的连续副本。 */
}
~~~
Bucket_Valid检查容器边界、数量和占用区与队尾/待发游标的关系,不遍历条目。Ring_Advance处理下标回绕并避免加法溢出,Ring_Read/Ring_Write最多分两次复制。Read_Entry_With_Expected_State先验证条目头位于已占用区,再读取可能跨尾部的长度和身份,核对预期队列状态,检查整条占用后返回原文视图。Mark/Remove会先验证需要访问的后继,再提交控制字段,避免错误返回时部分移动游标。
内部读取及删除函数的 `expected_queue_state` 参数只核对操作前的旧状态,使用 `QUEUE_ENTRY_PENDING`(尚未登记交接)或 `QUEUE_ENTRY_RETAINED_UNACKED`(NORMAL保留原文待ACK)表达。HIGH完成交接时调用 `Remove_Head_With_Expected_State(..., QUEUE_ENTRY_PENDING)`;该参数不是删除原因或要写入的新状态。NORMAL通过 `Mark_Normal_Entry_Retained_Unacked` 明确更新条目头,将内部编码写为2,不再用含义不清的0/1参数控制状态更新。
内部队列返回FULL时,NORMAL由TcpServer直接转换为WAIT,HIGH经Manager和Connection转换后返回给业务;业务保留原文和生产游标。HIGH需要等待字节空间,NORMAL可能需要等待占住编号窗口的旧条目/ACK处理完成。NORMAL成功可能伴随旧原文覆盖。ERROR须修正输入、容量配置或状态,不能进入等待空间的重试分支;库不会自动丢弃这条业务或推进游标。只有TcpServer提交接口返回OK才推进业务游标。静态数组的“释放”表示空间可复用,不是归还操作系统内存。
<a id="aq-reconnect-policy"></a>
### 3.4 固定的队列生命周期
优先级同时决定发送顺序和存储生命周期;不再提供逐条重连策略,也不根据TypeID或COT自动推断。同为遥测ASDU,自发事件与总召响应应按业务来源放入不同队列。
| 业务 | 队列 | 生命周期 |
|---|---|---|
| 总召激活确认、总召数据及结束确认 | HIGH | 属于发起总召的连接,提交后出队;连接初始化、启动应答及重连清空剩余待发业务 |
| 命令确认、读响应、时钟同步确认等请求应答 | HIGH | 同上,不向新连接重放旧请求结果 |
| 允许跨连接恢复的自发事件 | NORMAL | 随服务初始化,无连接也可入队;有效ACK释放原文,满时覆盖最旧原文;重连绑定现存原文,Close服务才清空 |
内部队列统一使用AsduQueue_Enqueue;NORMAL由TcpServer直接调用,需要缓存的HIGH经Connection/SendManager调用,直接应答不入队。业务分别使用Enqueue_Event和Send_Response,不接触队列指针。下面仅展示内部NORMAL入队接口,generation须匹配队列绑定,无连接时为0:
~~~c
/* 可跨连接恢复的事件使用NORMAL。
* 返回值仍须检查;仅OK推进生产者游标,FULL等待,ERROR明确处理。
*/
IEC104_AsduQueueResult_t result = IEC104_AsduQueue_Enqueue(
&queue, generation, IEC104_ASDU_PRIORITY_NORMAL,
event_asdu, event_length);
~~~
原先显式保留的HIGH事件应迁移到NORMAL;仅属于当前连接的NORMAL请求应答应迁移到HIGH。没有同一优先级内混合保留/丢弃策略的接口。NORMAL的保留不保证数据不丢失:空间不足时仍可能被覆盖;未ACK也不证明对端未收到。恢复只适用于业务认可的同一接收方或冗余域,本模块不识别远端主站身份,也不提供应用去重。
服务Init先以代次0初始化队列;离线状态下HIGH为空,NORMAL全部待发,覆盖待ACK记账及发送限制均为空。接入时Rebind到非零代次,再初始化Connection/Manager。EOF时Limit_Normal_Send将normal_send_limited置1,已有及后来新增的未提交NORMAL均不再交给旧连接。Peek_Unsubmitted对NORMAL返回EMPTY,原文及待发计数保持可查询;入队、覆盖、取消条目和重复调用均不解除限制,Detach/Rebind清零开关后全部现存NORMAL重新可选取。已提交的I帧由SendBuffer及Manager独立收尾:Manager先续写当前帧,再处理控制FIFO及已受理HIGH,不从NORMAL创建新帧,也不会因HIGH公平配额耗尽而选取被限制的NORMAL。EOF限制只用normal_send_limited表示,不维护剩余额度;它不改变接口签名及NORMAL容量覆盖策略。
高优先级队列用于连接应答,低优先级队列用于可跨连接保留的事件;高优先级原文出队后,由独立发送记录继续等待ACK。
Manager.Init清空HIGH;STOP受理立即作废待发HIGH,无逐条回执。从停用状态重新START仍清理HIGH及公平配额;已激活时重复START保留。WAIT尚未受理、不清理;排空中的重复STOP不重复清理。清理不撤回已提交I帧、不清除记录或ACK义务、不改变NORMAL;同一TCP启停不调用Rebind。
<a id="sendmanager"></a>
## 4. SendManager:发送准备、ACK及回执
源码:[IEC104_SendManager.c](../../104/IEC104_SendManager.c)。只绑定CONTROLLED子站;主站启停算法仍由独立Link角色模块提供,不在这里发送ACT。
### 4.1 记录与返回值
每个I帧占用一条 `IEC104_IFrameSendRecordStorage_t`:frame_serial、asdu_entry_serial、asdu_priority、原N(S)/N(R)/长度、准备和写完时刻、本地完成及对端确认标志;不保存user_tag。所有记录共用Manager保存的connection_generation,每条不再重复保存代次。查询接口仍返回 `IEC104_IFrameSendRecord_t`,将共享代次与该条frame_serial组合成完整frame_id,其他字段逐项复制;返回值是独立数值副本,Manager重建不会改变已经取出的快照。
NORMAL原文身份使用Manager的连接代次和该条非零asdu_entry_serial;HIGH原文提交时已出队,其asdu_entry_serial恒为0,没有入队业务身份。两种记录均以完整frame_id和N(S)处理完成及ACK,不借用原文指针,也不保存完整APDU。发送进度、失败、ACK和回执消费仍校验外部事件的连接代次;旧连接事件不能因新连接复用frame_serial而被接受。确认回执只报告帧级事实,不再返回调用方的业务标识。
Manager持有三个模块的指针及内部提供的记录环形数组,维护head/count、high_unacked_count、next_record_ns、k和高优先配额。high_unacked_count统计已登记且未ACK的HIGH记录,包括尚未完整写出的帧;登记HIGH记录时增加,有效ACK时减少,移除已ACK回执不再减少。next_record_ns表示下一条新登记I帧记录的N(S),在发布记录时推进,用于校验记录的连续编号;发送完成位置和ACK位置由Link另外维护。记录容量1..32767,k也为1..32767;它们可独立配置,记录容量包含已经ACK但尚未由TcpServer转为事件并移除的回执。已经复制到事件队列的回执由事件容量单独计数。
| 返回值 | 含义 |
|---|---|
| OK | 操作成功;Prepare_Next_Send得到可写字节,Handle_Send_Progress尚未整帧完成 |
| QUEUED | 控制帧已排队,不代表已写socket |
| EMPTY | 无待选业务/无记录/无对应待推进过程 |
| WAIT | 门控、窗口、容量或待完成义务阻塞;接收入口表示当前请求尚未受理 |
| FRAME_WRITTEN | 已连续提交Link完成、记录和Buffer释放,输出完成副本 |
| IGNORED | 排空中的重复STOP,或提前/无匹配等待的TESTFR_CON;不重启或撤销原有计时 |
| ERROR | 参数、身份或接入状态非法,需要修正;不能按容量不足盲目重试 |
| PROTOCOL_ERROR | I/S报文因接收阶段、序号或ACK违反协议而被Link拒绝,当前连接必须结束 |
| FATAL | 当前连接必须结束,先保留事实用于业务回收 |
所有枚举精确比较,不能用“非零为成功”。
<a id="manager-consistency"></a>
### 4.2 常数时间一致性检查
Manager_Storage_Valid校验自身容量、指针、代次、配额及HIGH未确认数不大于记录数,不依赖故障后的Link,供回执读取和恢复使用。运行会话的Manager_Session_Valid另外要求Link保持CONTROLLED角色;绑定后的角色变化属于本地状态非法。
`IEC104_SendManager_Get_Status`按同样的存储边界检查返回代次、记录容量、当前记录数及HIGH未ACK数;不暴露绑定指针,不消费记录,OK才写输出。该查询可在连接冻结后使用,Abort之后返回ERROR。
`IEC104_SendManager_Enqueue`先验证当前会话及代次,再调用绑定队列的Enqueue;返回OK、WAIT(队列FULL)或ERROR。它沿用HIGH/NORMAL的保留、覆盖和编号规则,不生成I帧或分配N(S),用于应答暂不能直接准备或Connection因期限已到而延后处理的路径。TcpServer把直接准备或暂存成功统一转换为公开的IEC104_TCP_SUBMIT_OK。服务级NORMAL由TcpServer直接写入所持队列,不要求Manager存在;实际发送仍统一由Manager处理,业务不依赖内部指针。
Manager_Session_Valid调用各模块公开查询,检查:
- 三模块绑定代次一致,无外部遗留预留。
- manager.next_record_ns等于Link下一分配序号。
- distance(next_completion_ns, next_frame_ns)为0或1,等于Buffer当前I帧数量;有当前帧时N(S)等于下一完成位置。
- HIGH原文环中已提交待确认数恒为0。
- 已编号未ACK的I帧数不超过k、不大于记录数,且等于Manager.high_unacked_count加NORMAL原文保留及覆盖待确认条目数。
所有距离按模32768计算,不以普通整数大小比较。Manager通过Link接口修改协议状态,角色也通过Get_Status读取。运行检查在完整事务的公开入口执行,不能插入Prepare/Commit、Complete/释放、ACK/原文释放之间;参数、身份、序号及模块计数校验不依赖构建模式。
记录通过N(S)与记录环偏移常数时间定位,再核对不复用frame_id及快照。ACK只访问本次新确认区间,不扫描全部历史回执。
故障回收允许Remove_Confirmed_Record在FAILED阶段调用,通过既有队首记录查询校验frame_id、本地完成及ACK标志,不要求Link或队列恢复正常会话状态。完整事务仍由Manager按顺序提交,不能在中间步骤插入其他队列操作或ACK处理。
<a id="manager-i-transfer"></a>
### 4.3 Prepare_Next_Send
签名:
~~~c
IEC104_SendManagerResult_t IEC104_SendManager_Prepare_Next_Send(
IEC104_SendManager_t *manager, uint64_t generation, uint64_t now_ms,
IEC104_SendBufferHeadInfo_t *head_info);
~~~
本接口由Connection在准备实际发送时调用,业务生产者只调用TcpServer_Enqueue_Event或TcpServer_Send_Response。内部也不能提前反复调用它来预建一批I帧。
1. 校验会话;已有当前I帧或控制队首时,直接返回该帧剩余字节。
2. 查看两级下一未编号条目,均空返回EMPTY。
3. 选择优先级;原文连续时直接借用,跨尾部时用Copy_Asdu拼成连续副本。调用共用Prepare_I_Asdu,记录满返回WAIT,否则保障当前I帧存储。
4. Link.Prepare检查k和链路门控,生成APDU并分配N(S)。未生成可取消预留,返回WAIT/ERROR。
5. 让SendBuffer接手完整I帧,登记Manager业务记录并在HIGH时增加high_unacked_count;再调用Mark_Submitted完成队列记账,HIGH消费队列原文,NORMAL登记为保留原文待ACK;最后更新配额。
6. 返回当前HeadInfo,结果为OK。
Prepare_Next_Send使用一个249字节的局部数组存放跨尾部ASDU;这是调用期间的自动存储,嵌入式接入需计入栈预算。只有原文确实分两段时才执行额外复制,连续原文仍直接交给Link。HIGH原文提交时已出队;NORMAL原文可被后续入队覆盖。SendBuffer对连接层始终提供独立、连续的APDU,原文覆盖不影响当前帧续写,实际I/O接口不变。
high_priority_burst_limit=0为严格高优先;非0时,NORMAL有待发条目才累积连续HIGH次数,达到上限让出一次NORMAL。普通桶仅有已提交未ACK条目不算待发,不积累配额欠账。每个新I帧重新选择,重复准备/WAIT不改变配额。
Link.Prepare成功后序号不可撤回,后续异常返回FATAL;保留尚存原文及已登记事实供恢复,已经出队的HIGH不恢复。最多一帧已编号但未完成,不能认为连这一帧也完全没有提前分配:编号发生在实际写调用前,EAGAIN时该帧仍持有序号。
### 4.3.1 Submit_Response
```c
IEC104_SendManagerResult_t IEC104_SendManager_Submit_Response(
IEC104_SendManager_t *manager, uint64_t generation,
const uint8_t *asdu, uint16_t asdu_length, uint64_t now_ms,
IEC104_SendBufferHeadInfo_t *head_info);
```
Connection在未到期路径先Drive处理保留接收和当前控制义务,再调用此接口。Manager的Submit_Response和Enqueue(HIGH)共用Response_Submit_Allowed,在记录容量、k窗口和HIGH容量判断之前按实际接手时的状态准入:
| 启停状态 | 应答准入 |
|---|---|
| STARTED + IDLE | 允许;满足发送条件时直接准备,否则暂存HIGH |
| STOPPED + IDLE | ERROR,不入HIGH |
| STOPPED + STOP_DRAINING | ERROR,不入HIGH |
子站START/STOP受理立即更新dt_state;应答准入仍集中检查STARTED/IDLE。协议期限已到路径直接Enqueue(HIGH),也经过同一检查。新的I帧须等待发送缓冲为空;已有CON时应答暂存HIGH,由FIFO保证先写控制帧,再发业务。
直接准备不虚构ASDU队列条目,也不调用Mark_Submitted;记录仍为HIGH、asdu_entry_serial为0,并增加high_unacked_count。之后与队列应答使用同一Handle_Send_Progress、Handle_I_S_Frame和回执逻辑。只有实际准备成功才消耗N(S)和配额,单纯入HIGH不会分配协议序号。
OK表示已准备APDU,只有此时写head_info;QUEUED表示已复制HIGH;WAIT表示HIGH暂满、本次未接手。ERROR表示参数/状态或HIGH总容量不符,包含启停准入拒绝,Connection及TcpServer原样映射为ERROR且不因此断连;编号后交接失败为FATAL,必须收尾。QUEUED及对外SUBMIT_OK不保证待发HIGH最终发出,受理新STOP时按4.7节作废。Manager不调用socket;TcpServer直接发送时最多一次非阻塞写入,部分写入或暂不可写由Process/Poll继续同一帧,不能重复入HIGH。
<a id="manager-send"></a>
### 4.4 Handle_Send_Progress / Failure
TcpServer经Connection取得HeadInfo后,通过Net实际写入,再由Connection向Manager提交该次成功写入增量。Manager按frame_id匹配当前帧;I帧还核对关联记录。整帧完成时按原类型分派:
| 原类型 | Link完成接口 |
|---|---|
| I | Complete_I_Send(原快照) |
| S_ACK | Complete_S_Ack_Send |
| STARTDT_CON | Complete_Startdt_Con_Send |
| STOPDT_CON | Complete_Stopdt_Con_Send |
| TESTFR_ACT | Complete_Testfr_Act_Send |
| TESTFR_CON | 无独立Link完成接口;仍提交Buffer进度与释放 |
FRAME_WRITTEN输出IEC104_LocalSendCompletion_t,只有数值副本,无已经释放的报文指针。里面的Link结果保留OK/IGNORED,主动TESTFR成功时可据written_at_ms建立等待CON的t1。
最终写入失败或本地发送超时用Handle_Send_Failure,匹配身份后分派失败完成并返回FATAL。EAGAIN不是最终失败,不调用该接口。不能重复报告写入增量或重复调用底层Complete。
<a id="manager-ack"></a>
### 4.5 Handle_I_S_Frame及记录消费
apci必须来自完整APDU的成功解析,只接受I/S:
1. 读取Link原位置,验证本次新ACK区间对应的记录已本地完成;越界网络N(R)交给Link拒绝,不用于记录寻址。
2. Link.Handle验证ACK、接收阶段及I帧N(S),成功后推进协议位置。
3. 先标记整个新确认区间的peer_acknowledged,并按本次新确认的HIGH记录数核减high_unacked_count。
4. HIGH不再访问ASDU队列;仅对NORMAL按真实记录的generation、entry_serial调用Queue.Confirm_Next_Normal_Entry:仍有原文就严格匹配队首并释放,原文已覆盖就核减待确认数,不访问或删除新队首。
Link只接受不越过本地完成位置的ACK。例如0、1还仅在ASDU队列时,ACK=2非法;当前I帧只写了一部分时,也不能由ACK代替本地完成。异步接入先提交真实发送结果,再按接收顺序处理相关ACK。
本地会话或记录预检失败返回ERROR;在本地状态合法时,Link拒绝I/S报文返回独立的`IEC104_SEND_MANAGER_PROTOCOL_ERROR`。Link已经受理后出现状态同步或原文释放失败仍返回FATAL。Connection将前者的协议拒绝归为PROTOCOL,将本地预检及后续交接失败归为INTERNAL,不再把所有非OK结果都归责于对端报文。原有返回值数值不变,新增结果仅用于I/S接收接口。
重复ACK不释放第二次,也不重复核减HIGH或覆盖待确认计数,不重置t1。原文覆盖本身不推进V(A)、不释放k窗口或业务回执槽;已有帧仍须真实完成和取得有效ACK。ACK处理复杂度为O(本次新确认条目数)。Link接受后释放原文失败为FATAL;所有已接受的ACK事实仍保留在记录中,恢复时不能把这些数据当成未确认重报。
| 记录接口 | 用途 |
|---|---|
| Peek_Oldest_Sent_Unacked_Record | 常数时间获取最早已本地完成未ACK记录,只有部分发送时EMPTY |
| T1_I_Ack_Expired | 使用该记录原written_at_ms,1到期/0未到期或无等待/-1非法 |
| Get_Deadlines | 当前队首身份、本地发送及I帧t1剩余时间、活动标志和控制容量;只读且不选择新业务 |
| Peek_Confirmed_Record | 查看已完成且已ACK的记录队首;未就绪WAIT,不自动释放 |
| Remove_Confirmed_Record | TcpServer成功复制RECORD事件后,经Connection按frame_id移除队首 |
| Get_Record_By_Offset | 不依赖运行中的Link读取记录,供故障恢复;ACK事实不丢失 |
回执未转为事件并移除时仍占records,容量满会阻止新I帧;已经ACK的原ASDU空间可复用,S/U仍可发送。业务处理RECORD副本失败时应自行保存副本,不调用内部Remove,也不会恢复已移除的记录槽。
<a id="manager-control"></a>
### 4.6 S、t2、TESTFR与t3
Queue_S_Ack按w门限、immediate或停止排空规则生成S。Queue_T2_Ack在原待确认接收数据达到t2时按相同门控生成S。Queue_Testfr_Act主动探测;Queue_T3_Testfr额外检查原空闲时长。Handle_Testfr_Act受理对端ACT并排队CON,不结束本端独立探测。
上述构帧入口先预留控制槽,再调用Link。无容量返回WAIT,不改变链路;未生成报文则取消预留,成功生成返回QUEUED。构帧成功后的提交异常、取消异常均为FATAL。时钟和定时器由连接层管理。
接收确认使用`Handle_Testfr_Con(manager, generation, apci)`。它校验会话后调用Link,不预留发送槽、不生成应答;CON_PENDING下接受确认返回OK,Connection此时才撤销探测t1。提前收到或没有匹配等待时返回IGNORED,不缓存、不撤销计时,控制槽满也不阻止确认受理。Connection不再直接修改Link的探测状态。
Connection分派的STARTDT_ACT、STOPDT_ACT和TESTFR_ACT已经通过格式与方向检查;合法重复请求沿用原受理规则,处理中的ERROR/FATAL归为INTERNAL,包括HIGH清理、控制槽提交或取消失败。TESTFR_CON没有匹配等待时仍忽略,内部状态非法归INTERNAL;子站收到格式合法的反向STARTDT_CON/STOPDT_CON由Connection消费并忽略,不交给Manager,不改变启停、确认期限或t3活动时刻。
Handle_Testfr_Act或Slave_Handle_Startdt_Act返回WAIT时请求尚未受理,调用方必须有界保留完整请求并维持接收顺序,不能静默丢弃或越过它分派后续帧。子站启停不再暂存相反ACT。
<a id="manager-slave"></a>
### 4.7 子站启停
| 入口 | 行为 |
|---|---|
| Slave_Handle_Startdt_Act | 先预留控制槽,成功受理即STARTED/IDLE并排CON;结束旧停止等待,不暂存START |
| Slave_Handle_Stopdt_Act | 无需控制槽,立即STOPPED/STOP_DRAINING并清理HIGH;不等待启动CON,不暂存STOP |
| Slave_Queue_Stopdt_Response | 先排S确认,再等已预留I帧获ACK;满足条件后排STOP_CON并回STOPPED/IDLE |
已在FIFO中的S完整覆盖接收数据时,STOP_CON可紧随排队,不必等S网络完成。队列容量不足返回WAIT,调用方保留义务;START的WAIT表示请求尚未受理,不能取消STOP。Link只控制协议状态,发送缓冲持有部分写入和帧身份。
从停用状态重新START时清理HIGH并重置公平配额;已启用时重复START保留HIGH。STOP清理不撤回当前I帧或记录,不影响NORMAL。
两个CON完成接口只检查发送结果,均不回写dt_state/dt_procedure。后到START可以在旧STOP_CON仍待发时激活,旧完成不能覆盖新状态。停止排空被START结束时尚未生成的STOP_CON不再生成;已经入队的CON必须按FIFO发送。
Slave_Queue_Stopdt_Response新增可空输出stop_con_id,仅STOP_CON成功入队时写入。Connection用它记录本轮最后一帧停止应答,匹配完整发送后才结束STOP期限;成功受理START也取消旧计时。重复STOP不刷新有效起点,旧CON完成不能误清新STOP的期限。
### 4.8 Init与Abort
Init要求Link为CONTROLLED初始状态、Buffer空闲、Queue与Buffer同代次且Queue没有已提交条目。允许Queue含预先排队或Rebind恢复的未编号业务;Init成功会清空HIGH、保留NORMAL,检查失败时不清理。HIGH出队后队列本身无法体现旧连接的在途帧,接入方仍须先结束旧I/O并Abort旧Manager,不能用Init接管运行中的连接。不分配存储。
Connection使用构造专用`Init_Connection`:在局部Link/Buffer/Manager完成上述校验,最后一次可失败操作为清理HIGH;随后只向指定的最终地址提交已校验对象,并在Manager内部建立绑定。ERROR时Manager、Link、Buffer及队列都不变,也不改控制槽和记录数组。Connection随后提交其余连接字段,无需访问或修补Manager内部指针。此入口不支持运行中重绑;对象成功初始化后仍不能复制或移动。原Init继续支持绑定已单独初始化的Link/Buffer。
Abort前,TcpServer先结束旧I/O并把剩余记录复制为事件;Connection_Close内部调用Manager.Abort清除Manager及Buffer,**保留AsduQueue**。TcpServer随后调用Queue.Detach,立即清空HIGH并恢复NORMAL离线缓存;仅关闭整个服务时调用Queue.Abort。新连接代次由TcpServer管理,Link重新初始化和发送模块绑定由Connection_Init完成。
<a id="integration"></a>
## 5. 内部调度、容量与恢复
### 5.1 静态存储与初始化
以下示例仅说明发送模块的内部绑定关系。实际对象由TcpServer及其内含Connection持有,业务通过TcpServer_Create/Init启动服务,无需复制这些声明或调用底层Init。
~~~c
#include "IEC104_SendManager.h"
static uint8_t high_bytes[1024];
static uint8_t normal_bytes[4096];
static IEC104_SendBufferControlFrame_t controls[4];
static IEC104_IFrameSendRecordStorage_t records[12];
static IEC104_AsduQueue_t queue;
static IEC104_SendBuffer_t buffer;
static IEC104_LinkState_t link;
static IEC104_SendManager_t manager;
/* 仅用于全新或明确丢弃旧业务后的队列,不用于保留业务的重连。 */
static int Init_Fresh(uint64_t generation)
{
if (!IEC104_Link_State_Init(&link, IEC104_ROLE_CONTROLLED) ||
IEC104_AsduQueue_Init(&queue, high_bytes, sizeof high_bytes,
normal_bytes, sizeof normal_bytes, generation) != IEC104_ASDU_QUEUE_OK ||
IEC104_SendBuffer_Init(&buffer, controls, 4, generation) != IEC104_SEND_BUFFER_OK) {
return 0;
}
return IEC104_SendManager_Init(&manager, &queue, &buffer, &link,
records, 12, 12, 4) == IEC104_SEND_MANAGER_OK;
}
~~~
直接使用AsduQueue时,HIGH至少 `IEC104_ASDU_HIGH_QUEUE_MIN_CAPACITY`(8)字节;NORMAL至少 `IEC104_ASDU_NORMAL_QUEUE_MIN_CAPACITY`(当前ABI下22)字节。保证同时保留N条、ASDU最长L字节(N≥1、6≤L≤249)时,HIGH配置 `N × (2 + L)`,NORMAL配置 `N × (IEC104_ASDU_NORMAL_ENTRY_HEADER_LEN + L)`,无需额外回绕空间。已知各条实际长度时,占用为 `Σ(本级头长 + Li)`。保留10条最大249字节ASDU,HIGH需2510字节,NORMAL在当前ABI下需2650字节。
HIGH的N只计算尚未提交的待发条目;NORMAL的N还包括原文仍保留的当前发送和已发未ACK条目,两级分别规划。需要支持任意合法ASDU长度时,对应桶至少本级头长+249字节。回执尚未转为事件的延迟计入records容量,业务读取事件的延迟计入TcpServer事件容量;事件区满也会阻止继续转移记录。仅NORMAL原文环采用覆盖;HIGH、控制FIFO、确认记录和k窗口各自保持拒绝或等待语义。已覆盖原文不再占字节容量,但对应的已编号帧仍占k窗口和records。
TcpServer公开接口支持全部合法ASDU长度,因此编译期要求HIGH和NORMAL各自至少容纳一条最大ASDU及本级条目头,即对应`ENTRY_HEADER_LEN + IEC104_MAX_ASDU_LEN`;当前ABI下分别为251和265字节。`Send_Response`的回退排队使用HIGH,`Enqueue_Event`使用NORMAL。底层AsduQueue仍允许上述较小容量;TcpServer不接受这种无法容纳最大ASDU的配置,避免应答在直接准备时成功、回退排队时却因总容量不足返回SUBMIT_ERROR。
Windows 64位GCC 16.1.0默认ABI下:AsduQueue控制结构120字节、SendBuffer结构336字节(含唯一255字节I APDU)、控制槽40字节、发送记录存储类型48字节、查询快照类型56字节、Manager结构64字节。共享连接代次曾将存储记录从64字节降为56字节;此次移除user_tag后从56字节降为48字节,12条记录数组由672字节降为576字节,再节省96字节。以上不是跨平台尺寸承诺,目标平台应以sizeof为准。
ASDU每条恰好占本级头长+实际长度,回绕不额外占容量。Manager有249字节的局部拼接数组;Init_Connection另有临时Link、Buffer和Manager用于预检,两条调用路径均须按目标编译结果计入栈预算;Rebind更新NORMAL头内状态和控制字段,不搬移ASDU,不使用整理数组。
相比之前每条固定272字节的业务槽,小ASDU可以共用更多容量;最大249字节ASDU在HIGH中占251字节,在NORMAL中占头长+249(当前ABI下265)字节。原文环容量和发送记录容量分别计算,实际RAM需求还取决于两者的配置。
### 5.2 业务入口与内部收发循环
~~~text
业务提交ASDU:
NORMAL:TcpServer_Enqueue_Event → AsduQueue_Enqueue(服务缓存)
应答:TcpServer_Send_Response → Connection_Submit_Response → Manager.Submit_Response
直接准备 → 共用Write_Output最多一次非阻塞写入
暂不能准备或协议期限已到 → Manager.Enqueue暂存HIGH
仅TCP_SUBMIT_OK后推进生产游标;NORMAL的OK可能已经覆盖旧原文
TCP_SUBMIT_WAIT保留原文,后续Poll间隙重试
TCP_SUBMIT_ERROR/FATAL → 按参数、连接身份或故障处理,不当作容量不足盲目重试
TCP内部准备发送:
先安排应生成的S/U
Connection_Prepare_Next_Send → Manager.Prepare_Next_Send
EMPTY/WAIT → 等待业务、ACK、记录转移或状态变化
Connection返回SEND_READY → 共用Write_Output经Net写socket(head.pending_data, head.remaining_bytes)
正字节数 → Connection_Handle_Send_Progress → Manager.Handle_Send_Progress
EAGAIN/EWOULDBLOCK → 等待再次可写,保持当前帧
EINTR → 按平台规则重试,不伪造进度
最终失败 → Connection_Handle_Send_Failure → 结束连接
FRAME_WRITTEN后才处理依赖这次完成的接收事件,再准备下一帧
TCP内部接收:
TcpServer经Net收到字节 → Connection.Feed → Receiver.Feed
TcpServer按consumed保留剩余输入
成帧后Connection经Receiver.Peek_Frame取得APDU及已解析APCI
Connection把I/S及需要处理的U帧交给Manager,对Link只作只读查询
WAIT → 保留当前接收帧,容量恢复后重试,不越过它处理后续帧
S/U已受理 → Connection释放内部接收帧
I帧已受理 → TcpServer复制I_FRAME事件 → 经Connection释放内部接收帧
确认回执就绪 → TcpServer复制RECORD事件 → 经Connection移除内部记录
业务处理事件:
TcpServer_NextEvent取出副本 → 解析ASDU或处理发送回执
需要应答时调用TcpServer_Send_Response,不调用底层Release或Remove
~~~
不要把Prepare成功当作已经发送;也不要把socket实际成功但尚未提交的写入长期滞留在异步完成队列。异步情况下同一帧最多一个未回报写操作;隔离代次不能代替结束旧I/O对数组的访问。
仅检查dt_state==STARTED不能代替Link完整门控。初始STOPPED时可以缓存NORMAL;HIGH应答须等STARTED/IDLE后再提交。被控站受理START立即开放Link的新I/S准备;Manager继续遵守SendBuffer顺序,已有当前I帧先完成、控制FIFO随后排空,再选择新I帧。HIGH在Manager初始化、受理新STOP以及从STOPPED受理START时清空;已启用时重复START保留HIGH。
<a id="timeouts"></a>
### 5.3 原始期限
| 期限 | 起点及接口 |
|---|---|
| 当前帧本地发送期限 | 原queued_at_ms;Connection经Manager.Get_Deadlines取得剩余时间和同一队首身份;Buffer.Head_Send_Expired保留为底层接口 |
| I帧等待ACK t1 | 最早已完成未ACK记录的原written_at_ms;Connection经Manager.Get_Deadlines查询,单项T1_I_Ack_Expired保留 |
| TESTFR等待CON t1 | ACT完整发送且Link完成成功的written_at_ms;Connection记录并通过Collect_Deadlines计算 |
| 接收确认t2 | 连续未确认接收区间的原起点;Collect_Deadlines判定到期后调用Queue_S_Ack(immediate=1),Queue_T2_Ack保留为底层接口 |
| 空闲t3 | 有效链路活动起点;Collect_Deadlines判定到期后调用Queue_Testfr_Act,Queue_T3_Testfr保留为底层接口 |
| 停止过程总期限 | 新STOP的received_at_ms;重复STOP不续期,成功受理START或本轮最后一帧STOP_CON匹配完成时结束 |
Connection的Check_Timeouts、Get_Wait_Time、发送准入及控制推进共用临时Collect_Deadlines视图。Manager的Get_Deadlines仅观察已存在的发送头和记录,OK才写输出;对应has_*为1且remaining_ms为0才表示到期。期限计算使用64位时间差,起点0合法,不计算可能溢出的绝对到期时刻。接收批次可以暂缓确认故障处理,实际到期事实及原始起点不改变。
定时器只负责唤醒,回调再次核对代次和当前有效起点。仅业务排队尚未编号不启动I帧t1。ACK推进后选下一最早未确认帧的原时间,不从当前时间重新开始。
<a id="failure"></a>
### 5.4 断线恢复
以下操作由TcpServer和Connection完成。NORMAL固定随服务保留,HIGH固定属于连接;业务使用事件提交与应答发送入口,并通过事件读取收尾结果。直接应答同样不跨连接恢复。
1. 停止分派旧连接事件,关闭TCP并结束/隔离旧I/O对存储的访问。
2. TcpServer经Connection_Get_Record_By_Offset读取剩余记录并复制为closing事件,区分已ACK、未ACK和未本地完成。NORMAL的记录可能仍在而原文已覆盖。
3. 核对记录中的ACK事实。只有NORMAL现存原文参与恢复,且业务须允许向同一接收方或冗余域重报;未ACK不证明对端未收到。HIGH请求应答不跨连接保留。
4. Connection_Close调用Manager.Abort,保留Queue。TcpServer随即调用Queue.Detach(old_generation),清空HIGH、恢复现存NORMAL待发状态并切换到代次0,继续接受离线NORMAL。新连接建立时调用Queue.Rebind(new_generation);任一步ERROR均停止本次恢复,不能重新Init而静默丢弃缓存。
5. Connection_Init经Manager.Init_Connection校验并提交初始CONTROLLED Link、空Buffer及Manager绑定,再提交其余连接字段;队列可含未编号业务,失败不覆盖原对象或队列。
6. 新连接STARTDT完成后,以新N(S)生成新的APDU和frame_id。
例如HIGH中有总召应答A、命令确认C,NORMAL中仍有事件B、D;断线Detach清空A、C,保留B、D原顺序并恢复未提交;离线新增E追加在后,下次Rebind绑定B、D、E。已提交的HIGH原文此前已出队,也不会重发。
Detach与Rebind共用绑定转换,先完整验证两级所有条目的长度、占用范围及待发分界,并验证NORMAL的编号顺序和头内状态。均通过后,将NORMAL已提交前缀的头内状态恢复为未提交;后续没有可失败分支,因此ERROR仍保证控制字段及字节不变。HIGH元数据清零,NORMAL将unsubmitted_index设为head_index、unsubmitted_count设为entry_count;只更新头,不搬移或清除ASDU原文。复杂度O(条目数),额外存储固定,不使用malloc。NORMAL保留条目的entry_serial和原文不变,next_entry_serial不重置;更换generation使所有旧entry_id和借用失效。
Detach/Rebind清除旧连接的覆盖待确认计数、确认边界及EOF发送限制,只能恢复NORMAL环中仍存在的原文。已覆盖的原文无法恢复。重连丢弃不产生回调或伪造ACK;未编号条目没有帧回执,已编号帧的旧回执应在Manager.Abort前读取。Rebind本身不发送,不提供冗余组管理;不要在同一TCP的普通STARTDT恢复中调用它。
如果FATAL发生在有效ACK后的原文释放阶段,部分已ACK条目可能仍保留在Queue。记录先登记了整个ACK区间,内部恢复逻辑不能把所有保留原文盲目当作未确认数据重报;业务根据公开记录判断发送事实,不直接修改内部队列。常规网络断线中,正常完成的ACK已释放对应原文。
### 5.5 满时背压
| 满的位置 | 行为及恢复条件 |
|---|---|
| HIGH字节环 | 当前空间不足返回FULL,释放后重试;不覆盖旧原文 |
| NORMAL字节环 | 从队首覆盖最旧原文直至足够,包含已提交未ACK条目;成功返回OK,无逐条丢弃通知 |
| 两级条目超过桶总容量 | ERROR,不覆盖、不修改队列或编号;须修正容量或组帧,不按背压重试 |
| 控制队列 | 控制接口WAIT,未受理接收请求须有界保存;控制发送完成后恢复 |
| 记录数组 | 准备新I返回WAIT;TcpServer复制RECORD事件并移除内部记录后恢复;控制帧仍可发 |
| k窗口 | Link不生成新I,Manager返回WAIT;有效ACK后恢复 |
| 当前帧部分写入 | 返回同帧剩余字节;保持FIFO字节顺序,不为后续业务编号 |
<a id="build"></a>
## 6. 构建和迁移
### 6.1 生产构建依赖
子站发送模块需要以下六个源文件:
~~~text
IEC104_Codec.c
IEC104_Link.c
IEC104_Link_Slave_StartStop.c
IEC104_AsduQueue.c
IEC104_SendBuffer.c
IEC104_SendManager.c
~~~
发送管理本身不需要主站启停实现或日志模块。独立流式接收另加入 `IEC104_Receiver.c` 和 `IEC60870_Codec.c`,分别完成104 APCI与公共ASDU头检查;旧 `IEC104.c/h`已原样恢复,但旧入口使用私有Link且不向Manager交付报文。Receiver完成APCI检查,连接层通过Peek取得视图并分派,受理后显式释放;Link公开协议接口签名不变。
2026-09-30共享连接代次历史验证:当时的5个专项场景覆盖完整身份及业务字段往返、混合优先级、部分写入、记录环复用、重连后旧代次拒绝、故障后读取ACK事实、NORMAL原文覆盖及查询失败不修改输出。GCC 16.1.0以 `-std=c11 -O2 -Wall -Wextra -Werror` 编译,专项 `5 passed, 0 failed`,原有全量 `119 passed, 0 failed`。该测试后因接口过期已于2026-10-19删除,不计入当前回归;历史命令和运行记录保存在`.build/shared-generation-check`。使用模拟I/O,未运行真实TCP。
2026-09-24编号回绕历史验证:当时新增独立的iec104_asdu_queue_test.c,以GCC 16.1.0、`-std=c11 -O2 -Wall -Wextra -Werror`编译,13个专项场景通过,其中包含3万次与独立FIFO模型逐步对照的随机操作。专项覆盖编号/字节环同时回绕、跨界覆盖ACK、重复及旧代次拒绝、重连保留顺序、失败不修改字节、半环窗口阻塞及恢复,以及Manager部分发送、EAGAIN和累计ACK。原有全部119个用例重新编译通过。64位边界测试在夹具中设置计数起点,窗口极限测试显式快进计数,其余队列及发送操作使用公开接口;未模拟真实TCP。当前目录未保留该专项源文件,这13个场景未计入2026-09-30的运行结果。
以下为此前字节环和重连策略改造的历史验证:严格警告编译、GCC静态分析和当时全部119个用例通过。临时校验从标准输入编译运行,覆盖1182组条目起点与长度组合、60万次队列随机操作、391组跨界位置构帧及7万帧协议序号回绕;重连策略另验证29760组满环起点、保留标记及提交分界组合。这些历史结果不代替本次编号回绕专项,真实TCP及嵌入式目标平台仍需接入验证。
<a id="migration"></a>
<a id="64-本次环形队列改造与接口迁移"></a>
### 6.2 接口迁移
此次高低优先级头拆分不提供旧条目格式兼容。所有调用方须按新头文件重新编译并初始化队列及Manager,不能把旧18字节头的缓冲内容交给新代码。NORMAL头采用本次构建的位域及对齐布局,不是跨ABI持久化格式。
| 原接口/约定 | 当前接口/约定 |
|---|---|
| `Enqueue(queue, generation, priority, asdu, length, user_tag)` | 删除最后一个参数,改为 `Enqueue(queue, generation, priority, asdu, length)` |
| `AsduHeadInfo.user_tag`、两种发送记录的 `user_tag` | 删除,不再保存或返回业务标识 |
| `IEC104_ASDU_ENTRY_HEADER_LEN` | 删除,按优先级改用 `IEC104_ASDU_HIGH_ENTRY_HEADER_LEN` / `IEC104_ASDU_NORMAL_ENTRY_HEADER_LEN` |
| `IEC104_ASDU_QUEUE_MIN_CAPACITY` | 删除,按优先级改用 `IEC104_ASDU_HIGH_QUEUE_MIN_CAPACITY` / `IEC104_ASDU_NORMAL_QUEUE_MIN_CAPACITY` |
| HIGH的非零entry_serial及按身份消费 | 查询的entry_serial和记录的asdu_entry_serial均为0;Mark/Discard消费当前队首,Peek至消费之间不得移除、清空或替换队首 |
| HIGH/NORMAL共用条目编号 | 仅NORMAL消耗next_entry_serial,HIGH不受NORMAL编号窗口阻塞 |
| NORMAL只用控制游标推导提交状态 | 条目头另存状态并与游标交叉校验;Mark写已提交,Rebind将已提交前缀恢复未提交 |
传给 `IEC104_SendManager_Init` 的记录数组继续使用 `IEC104_IFrameSendRecordStorage_t[]`,容量仍以条数计;查询输出继续使用 `IEC104_IFrameSendRecord_t`,两个类型均已删除user_tag,不能继续使用旧布局。发送结果和回执消费仍传完整frame_id,HIGH与NORMAL均有独立帧身份。结束旧I/O并回收记录后再Abort,随后重新绑定新代次。
发送状态命名按“未提交”“原文保留且未确认”“原文覆盖且未确认”区分。本次还改变HIGH存储生命周期、重连策略和结构布局;调用方需同步迁移,重新编译并初始化对象,不提供旧内存布局兼容。
| 旧名称 | 当前名称及含义 |
|---|---|
| AsduQueue.overwritten_serial_begin | overwritten_unacked_serial_begin,覆盖待ACK循环区间起点,含端点 |
| AsduQueue.last_overwritten_submitted_serial | overwritten_unacked_serial_end,同一区间终点,含端点 |
| AsduQueue/Status.overwritten_submitted_count | overwritten_unacked_count,原文已覆盖但仍待ACK的实际数量 |
| AsduPriorityQueue.waiting_index/waiting_count | unsubmitted_index/unsubmitted_count,队列中尚未登记发送交接的条目位置/数量 |
| AsduQueue.Peek_Waiting | Peek_Unsubmitted,直接查询队列中下一条尚未登记发送交接的条目 |
| AsduQueueStatus.submitted_count | retained_unacked_count,只统计原文仍保留的已提交未ACK条目 |
| AsduQueueStatus.is_empty | is_storage_empty,只说明原文存储为空 |
| SendBufferStatus.is_initial_state | is_idle,当前无I帧、控制帧及未结束的预留;发送结束后也可再次为1 |
| SendManager.next_commit_ns | next_record_ns,下一条新登记I帧记录的N(S) |
以下为此前存储和接口改造的迁移说明。
本次改变三个模块的结构布局和部分接口,需要更新外部调用方并重新编译,不提供旧布局兼容。
| 旧接口/结构 | 当前替换 |
|---|---|
| IEC104_AsduEntry_t固定条目数组 | 两个uint8_t字节数组,Init容量单位改为字节 |
| AsduQueue.Get_Free_Count | Get_Free_Bytes;容量计每条本级头长和ASDU实际长度 |
| AsduHeadInfo.asdu单一连续指针 | asdu_first/asdu_first_length及可选asdu_second;需要连续原文时调用Copy_Asdu |
| AsduPriorityQueue.padding_bytes | 已删除;头和原文可跨尾部,不再产生填充占用 |
| 两级Enqueue空间不足都返回FULL | 字节容量不足时HIGH返回FULL、NORMAL覆盖最旧原文;只有NORMAL可能被编号窗口阻塞;条目超过总容量仍为ERROR |
| AsduQueue.last_confirmed_normal_serial | 替换为overwritten_unacked_serial_begin,作为覆盖待ACK区间下界;该控制成员语义改变,版本迁移须重新初始化 |
| AsduQueue及Status只记录原文条目 | 增加overwritten_unacked_count;Queue另保存覆盖和确认身份边界,结构布局改变 |
| AsduHeadInfo借用可跨任意入队保留 | NORMAL后续入队可能覆盖该原文,覆盖后借用立即失效 |
| Peek_Head后构帧并立即移除队首 | Manager内部Peek_Unsubmitted、Mark_Submitted;HIGH提交时出队,NORMAL有效ACK才Confirm_Next_Normal_Entry |
| IEC104_SendBufferNode_t数组 | IEC104_SendBufferControlFrame_t数组;I APDU已内置Buffer |
| Buffer.Init(buffer,nodes,capacity,reserve,generation) | Init(buffer,controls,control_capacity,generation),删除reserve参数 |
| BufferStatus三个序号位置及未确认数 | Link.Get_Send_Progress;BufferStatus仅当前I、控制数和预留状态 |
| Buffer.Apply_Peer_Ack | 删除;统一Manager.Handle_I_S_Frame处理 |
| Manager.Queue_Next_I_Frame(...,record) | Prepare_Next_Send(...,head_info),成功返回OK,紧邻实际发送调用 |
| 发送前只Buffer.Peek_Send_Head | Manager.Prepare_Next_Send;Buffer.Peek仍仅查询已准备帧 |
| Manager.Init只允许空业务队列 | 允许非空未编号队列,成功绑定会清空HIGH、保留NORMAL;拒绝仍有NORMAL待确认条目的队列 |
| Manager.Abort同时丢弃业务队列 | 保留业务队列;显式Rebind清空HIGH、恢复NORMAL,或Queue.Abort全部丢弃 |
| Enqueue_Ex及逐条重连策略 | 删除Enqueue_Ex、IEC104_AsduReconnectPolicy_t和HeadInfo.reconnect_policy;HIGH固定清空,NORMAL固定保留,统一调用Enqueue |
| Rebind逐条筛选和原地整理 | 完整预检后清空HIGH、将NORMAL现存条目恢复未提交;不搬移原文,失败不改字节或控制状态 |
| HIGH原文留到ACK | Mark_Submitted成功时立即出队;HIGH未确认数量改由Manager.high_unacked_count维护,ACK不调用Queue.Confirm_Next_Normal_Entry |
| STARTDT只改变链路状态 | 从停用状态START时清理HIGH及配额;已启用时重复START保留,WAIT未受理不清理;启停立即生效、CON完成不回写状态 |
| 应答在任意启停阶段都可缓存HIGH | Submit_Response及Enqueue(HIGH)共用准入白名单;新STOP受理时清空待发HIGH,已提交I帧和记录继续排空 |
| 仅靠user_tag找恢复数据 | 已删除user_tag;NORMAL用generation和asdu_entry_serial关联保留原文,HIGH只提供frame_id标识的帧回执 |
Enqueue参数顺序为queue、generation、priority、asdu、length;旧Enqueue_Ex调用须删除策略和user_tag参数,并按业务生命周期选择HIGH或NORMAL。HIGH头为uint16长度,NORMAL头为编号、状态和长度结构,须分别按对应头长宏计算容量。跨尾部存储不改变Manager.Prepare_Next_Send及其返回的连续APDU视图,直接读取AsduHeadInfo原文的外部代码须按两段接口使用。Handle_Send_Progress、Handle_I_S_Frame、控制帧封装及记录消费的函数签名保持;结构布局和来源身份语义按本文更新。
### 6.3 当前边界
已经实现发送数据结构、编号调度、部分写入记账、ACK释放、回执、超时判定和显式恢复基础。Receiver提供每连接独立分帧、代次检查和完整APDU交付;旧全局接收入口作为历史代码保留,不参与TcpServer路径。Connection统一收发分派、U帧路由及期限推进;实际网络操作经Net后端执行,TCP连接管理和周期驱动由[TcpServer](IEC104_TcpServer_设计架构.md)负责。应用持续调用TcpServer_Poll/NextEvent,通过TcpServer_Enqueue_Event或TcpServer_Send_Response提交ASDU;底层发送模块由TCP内部驱动,没有后台自动同步。
File diff suppressed because it is too large Load Diff
@@ -0,0 +1,530 @@
# IEC104 编解码与独立接收器设计架构
> **用途**:说明 `IEC104_Codec.c` 的APCI解析与I/S/U帧构造、`IEC60870_Codec.c` 的101/104公共ASDU头解析,以及 `IEC104_Receiver.c` 的每连接流式成帧、完整报文交付和错误处理。
> **范围**:第一至九章描述基础模块现有实现;第十章说明后续集成设计,其中单当前I帧、独立S/U队列、两级ASDU字节环及发送调度接口已实现,其余能力以各项说明为准。`IEC104_Link.c` 的状态和算法见配套文档 [IEC104_Link 设计架构](IEC104_Link_设计架构.md)。本文不是 IEC 60870-5-104 标准全文,也不定义具体 Type ID 的信息对象业务。
> **实现依据**:`IEC104_Codec.c/h`、`IEC60870_Codec.c/h`、`IEC60870_Types.h`、`IEC104_Receiver.c/h`及旧 `IEC104.c/h`;历史验证记录按当时版本保留。
> **同步日期**:2026-09-23。发送模块已改为变长ASDU队列、发送前编号及单当前I帧。严格警告编译、原有119个用例及临时专项校验通过;测试源码、配置和测试文档保持原样。
> **当前接口同步**:2026-10-08。已新增 `IEC104_Receiver.c/h`,并从删除前备份原样恢复 `IEC104.c/h`及旧全局接口,两套接收实现共存。上面的2026-09-23同步说明为历史记录;本文主要描述Receiver,旧入口边界另行注明。
> **测试清理**:2026-10-19。接口过期的旧回归测试及专用辅助文件已删除,当前测试入口及覆盖范围见[测试说明](../test/IEC104测试文档.md)。
> **信息对象同步**:2026-10-21。`IEC60870_InformationObjects.c/h`提供12种监视、18种命令的独立对象编解码;`IEC60870_Asdu.c/h`统一维护公共头、VSQ/SQ、容量、对象分派及原文应答。编码经对象函数表,解码按Type ID分派;带时标类型复用基础值处理及公共CP56工具。该模块由业务显式调用,不改变Receiver准入或链路序号处理;实际总召、校时和遥控流程仍待业务接入。接口及示例见[README](README.md#asdu信息对象模块)。
> **TCP接入同步**:2026-10-15。`IEC104_Connection.c/h`负责子站连接调度;`IEC104_TcpServer.c/h`提供IPv4监听及非阻塞收发,Windows依赖在Net后端。业务通过Create取得静态池不透明句柄,使用Init、Prepare/Process或Poll、NextEvent、Enqueue_Event/Send_Response、Get_Status/Get_Remote_Address;Close_Connection只断开指定代次主站,Close整个服务后读空事件再Destroy。公开头文件只依赖`IEC104_Types.h`及标准类型。构建和业务接入见 [TCP服务设计](IEC104_TcpServer_设计架构.md)。
> **子站入口同步**:2026-10-23。`IEC104_Slave`统一管理服务、调度和应答,NextEvent自动提供ASDU视图及原连接接口;业务无需手动绑定generation。延迟任务通过Copy_Event复制原文并重建自引用,旧请求在重连、重新Init和服务槽复用后仍被隔离。共享TCP值类型已迁入`IEC104_TcpTypes.h`。
> **业务边界**:子站业务从Slave接入,Slave内部调用TcpServer。本文的Receiver、Connection、SendManager及链路调用说明面向内部实现;业务不创建或驱动这些对象,不持有内部借用视图。业务可使用Codec和公共时间工具处理NextEvent返回的ASDU副本。
> **连接事件**:NextEvent分别交付CONNECTED、ACTIVATED、DEACTIVATED和DISCONNECTED。子站激活/停用在START/STOP受理时产生,使用data.connection载荷并按序保存;CON完整写出不再改变状态。同状态重复ACT及单纯断开不补造启停事件。
> **通知容量**:按实际载荷长度存放于字节环;默认保证普通30条最长通知、启停4条、收尾32条记录加1个最长I帧和1个断开通知,均不覆盖。启停配额满时延后受理改变状态的ACT,已有CON继续发送,NextEvent消费后安排重试。普通I帧无处交付时保留原帧并暂停续收;回执因空间或预算不足可晚于启停通知交付,各类背压不延长协议期限。
> **队列监控同步**:2026-10-16。Get_Status新增high_queue/normal_queue数值快照,分别查询待发条目数、保留原文条目数及总容量/已用/空闲字节数。通过asdu_queue_status_valid判断统计有效性;Init成功后离线仍有效,Close后无效。待发数不含已交给发送模块的ASDU,NORMAL等待ACK的保留原文仍占用存储,字节数包含条目头。业务继续只使用TcpServer,公开状态结构扩展后须重新编译调用方;详见[ASDU队列积压查询](IEC104_TcpServer_设计架构.md#21-asdu队列积压查询)。
---
## 一、模块速览
### 1.1 总体职责
`IEC104_Codec.c` 负责104完整APDU的APCI检查及I/S/U编码;`IEC60870_Codec.c` 负责101/104共用的参数校验、ASDU公共头解析及最低载荷长度检查。两者均不保存连接状态,公共Codec不依赖104实现。
`IEC104_Receiver.c` 为每条连接提供独立的固定接收缓冲,接受任意长度的有序字节片段。每次Feed最多收齐一帧,通过consumed报告实际消费的输入,APCI检查成功后保留完整帧,供调用方读取和显式释放:
~~~text
IEC104_TcpServer.recv提供有序字节,经Connection.Feed递入接收器
→ Receiver.Feed:同步、长度检查、收集APDU、调用104 Parse_APCI和公共Parse_ASDU_Header
→ FRAME_READY:停止消费后续输入
→ Receiver.Peek_Frame:取得APDU及APCI只读视图
→ 连接层按类型分派:子站I/S交给SendManager,U交给对应控制入口
→ S/U受理后释放;I帧由TcpServer复制为事件后经Connection释放
→ 再递入剩余字节;业务通过TcpServer.NextEvent读取事件副本
~~~
Receiver已经提供多实例、半包/粘包处理、完整帧交付、代次检查及待处理帧保留。它不检查链路序号,不修改Link,不预设STARTED,仅检查ASDU公共头及最低载荷长度,不执行对象或业务校验,也不执行socket、系统定时器或业务回调。
同连接的接收、发送完成及ACK处理由`IEC104_Connection`串行组织。`IEC104_TcpServer`负责TCP监听调度、收发预算、断线收尾和事件队列,真实网络操作通过Net后端执行;Connection负责I/S/U统一分派及协议期限。业务通过`IEC104_Slave_NextEvent`取得ASDU及应答接口并校验具体Type ID;Slave内部经`IEC104_TcpServer_Send_Response`提交应答。
### 1.2 文件地图
| 文件 | 职责 |
|---|---|
| `IEC104_Codec.c/h` | 104专用APCI解析、I/S/U帧构造和帧类型 |
| `IEC60870_Codec.c/h` | 101/104共用ASDU公共头解析、参数及最低载荷长度检查 |
| `IEC60870_Types.h` | 公共应用层参数和ASDU存储上限,无传输状态 |
| `IEC60870_Asdu.c/h` | 通用ASDU容器、精确布局、VSQ/SQ、地址和容量检查、取对象及原文应答 |
| `IEC60870_InformationObjects.c/h` | 每类独立结构、Create与Get_From_Buffer;函数表编码、Type ID解码分派,复用基础类型和CP56 |
| `IEC104_Receiver.c/h` | 每连接独立流式成帧、完整APDU借用视图、消费数和显式释放;依赖104 Codec和公共Codec |
| `IEC104.c/h` | 已恢复的旧单路逐字节接收入口,持有全局接收器和私有Link,仅返回接收结果 |
| `IEC104_Link.c`、`IEC104_Link_Common.h` | 连接层持有的公共I/S、窗口、确认及TESTFR状态;角色启停分别在Master_StartStop、Slave_StartStop模块 |
| `IEC104_Link.h` | 兼容总头文件;角色接口和构建迁移见 `README.md` |
| `IEC104_SendBuffer.c/h` | 子站唯一当前I帧、紧凑S/U FIFO、部分写入与本地发送期限;协议序号由Link独占 |
| `IEC104_AsduQueue.c/h` | HIGH/NORMAL变长字节环,条目可跨尾部、无填充碎片;HIGH满时拒绝、提交后出队,NORMAL覆盖最旧原文;Rebind清空HIGH、恢复NORMAL现存原文 |
| `IEC104_SendManager.c/h` | 子站发送前选择及编号、I/S接收、完成分派、ACK释放原文、独立回执和I帧t1;由Connection统一驱动 |
| `IEC104_Connection.c/h` | 每连接持有Receiver、共享Link和发送模块,统一分派、超时推进及故障收尾 |
| `IEC104_Types.h` | 协议常量、ASDU优先级及公开协议配置,不包含运行对象 |
| `IEC104_TcpServer.c/h` | IPv4单主站监听调度、静态池不透明句柄、收发预算、事件/状态/对端地址查询及单连接关闭;通过Net适配平台 |
| `IEC104_TcpServer_Config.h` | 对象池及内部缓冲的编译期容量,不由业务头文件转发 |
| `IEC104_Log.c/h` | 日志级别、格式化、回调或标准流输出 |
| `iec104_tcp_event_ring_test.c` | 当前TCP事件字节环专项,覆盖容量、次序、跨环尾及背压恢复 |
| `iec104_tcp_scheduler_test.c` | ACK/TESTFR确认边界、固定输入快照、独立发送预算及真实超时 |
| `iec104_net_pending_input_test.c` | Windows回环验证内核输入字节数快照、部分读取及EOF |
| `IEC104测试文档.md` | 当前测试的构建方法、覆盖范围和验证记录 |
依赖方向为:
~~~text
IEC104_Receiver.c ──→ IEC104_Codec.c(APCI)/ IEC60870_Codec.c(ASDU公共头)
IEC104.c ──→ IEC104_Codec.c / IEC104_Link.c / IEC104_Log.c(旧单路入口)
IEC104_Link.c / Master_StartStop.c / Slave_StartStop.c
└──────→ IEC104_Codec.c(调用IEC104_Build_*编码函数)
IEC104_SendBuffer.c ──→ IEC104_Codec.c(提交报文时校验APCI)
IEC104_TcpServer.c ──→ IEC104_Connection.c ──→ Receiver / SendManager / Link
应用层 ──→ IEC104_Slave.h(不透明子站句柄、自动ASDU/应答接口)
IEC104_Slave.c ──→ IEC104_TcpServer.h(不透明TCP句柄、公开配置/事件/状态)
IEC104_TcpServer.h ──→ IEC104_Types.h(仅值类型,不包含Connection或Net)
Receiver / Link / AsduQueue的内部模块头文件 ──→ IEC104_Codec.h
IEC104_Codec.c / IEC60870_Codec.c ──→ C标准库
IEC60870_Asdu.c / IEC60870_InformationObjects.c ──→ IEC60870_Codec.c / IEC60870_Time.c
IEC60870_Codec.h / IEC60870_InformationObjects.h ──→ IEC60870_Types.h
IEC104_Log.c ──→ 平台时间与标准I/O,不依赖协议模块
~~~
独立成帧需编译 `IEC104_Receiver.c`、`IEC104_Codec.c` 和 `IEC60870_Codec.c`。仅检查104 APCI或构帧使用104 Codec,仅解析ASDU头使用公共Codec;Link及发送模块继续按README选择源文件。
旧 `IEC104.c/h`已原样恢复,原有调用方可继续包含 `IEC104.h`;该头文件仍包含Codec声明。旧入口保留全局接收器、私有Link和STARTED预设。独立流式接收使用 `IEC104_Receiver.h`及显式对象接口,由连接层管理共享Link;两套入口不互相转发报文或共享接收状态。
### 1.3 协议与缓存边界
```text
字节下标 0 1 2 3 4 5 6 ...
┌──────┬────────┬──────────────────────────────┬──────────┐
字段 │ 0x68 │ 长度 L │ 4字节控制域 │ ASDU │
└──────┴────────┴──────────────────────────────┴──────────┘
```
- 完整 APDU 长度的计算公式为 `2 + L`。
- I 帧 ASDU 长度的计算公式为 `L - 4`,其中4是控制域长度。
| 项 | 当前值 | 含义 |
|---|---:|---|
| 起始字节 | `0x68` | APDU 同步标志 |
| 长度域 L | 1 字节,数值为 `4..253` | 仅计算控制域和 ASDU,不包含起始字节及长度域自身 |
| 控制域 C0..C3 | 共 4 字节 | I/S 帧编码序号,U 帧编码功能码 |
| ASDU | 最大 249 字节 | I 帧携带;S/U 帧不携带 |
| ASDU 公共头 | 104为6字节 | Type ID、VSQ、COT、OA和CA;公共ASDU层按配置计算为4..6字节 |
| APDU 最大长度 | 255字节 | 2字节头部加253字节长度域内容 |
### 1.4 使用硬约束
1. 每条连接使用独立Receiver,先用非零代次Init;仅清零对象不等于完成初始化。同一对象的所有操作串行,保持输入顺序。
2. 输入字节、输出对象及Receiver存储不得重叠。Feed的consumed指针必须有效,length非0时data必须有效。
3. Feed每次最多交付一帧;未消费的输入尾部由调用方保留。FRAME_READY后未释放时再次Feed消费0字节。
4. Peek返回的apdu及apci.asdu借用Receiver内部缓冲。成功Release、Reset或Init后视图失效;持有视图期间不得搬移对象或修改原文。
5. 所有接口按枚举值判断。FRAME_READY说明APCI及ASDU最低长度检查通过,不说明具体对象、业务字段、N(S)/N(R)或连接启停状态合法。
6. 同一帧的I/S序号及ACK只交给同连接SendManager一次,不再另调底层Link重复提交。U帧由连接层按角色和功能码路由。
7. 返回WAIT时保留当前帧及接收顺序;已受理的QUEUED/IGNORED等结果按接口契约消费,不能重放。
8. 新连接复用对象前须结束旧I/O,再用未复用的非零代次Init;旧代次的输入、查询、释放和复位均被拒绝。
### 1.5 状态归属与数据生命周期
| 对象 | 所有者 | 内容及有效期 |
|---|---|---|
| `IEC104_Receiver_t` | 调用方,每连接一个实例 | 255字节缓冲、已收/预期长度、待帧标志及连接代次;跨调用保留半帧或完整帧 |
| `IEC104_LinkState_t` | 连接层,供SendManager和U帧处理共享 | 序号、窗口及启停状态;Receiver不持有副本、不修改它 |
| `IEC104_ReceivedFrame_t` | 调用方的输出对象 | 保存代次、APDU指针/长度及APCI结果;指针借用Receiver缓冲 |
| `IEC60870_AsduInfo_t` | 调用方 | 公共头字段及信息对象区视图,有效期不超过原ASDU |
| 构帧输出缓冲 | 调用方或SendBuffer | 保存已构造报文,由发送管理及传输层推进 |
Receiver不缓存指向自身缓冲的APCI指针;Feed完帧检查APCI,Peek重新解析到局部结果后一次性输出。因此移动对象不会留下内部悬空指针,但已经交付的借用视图仍要求原对象地址保持不变。
Init清零整个对象并绑定代次;Release和Reset只清除组帧进度,不擦除缓冲。即使物理字节仍在,释放后的旧视图也不可继续使用。
---
## 二、报文模型与 APCI(应用协议控制信息) 校验
### 2.1 APDU(应用协议数据单元) 布局
```text
偏移: 0 1 2 3 4 5 6 ...
+------+------+------+------+------+------+----------------+
| 0x68 | L | C0 | C1 | C2 | C3 | ASDU(可选) |
+------+------+------+------+------+------+----------------+
| APCI | ASDU |
| APDU |
完整 APDU 长度 = 2 + L
L = 4 字节控制域 + ASDU 长度
```
`IEC104_Parse_APCI()` 首先统一检查:
- `frame` 和输出参数 `apci` 非空;
- 总长度不少于 6 字节;
- 起始字节等于 `0x68`;
- `L` 位于 `4..253`;
- 调用方给出的 `frame_len` 严格等于 `2 + L`。
### 2.2 帧类型识别
`IEC104_Get_Frame_Type(C0)` 只按控制域首字节的低位分类:
| 分类条件 | 结果 |
|---|---|
| `(C0 & 0x01) == 0` | I 帧 |
| `(C0 & 0x03) == 0x01` | S 帧 |
| 其他 | U 帧候选 |
分类只是第一步。候选类型随后还必须通过对应的完整控制域校验,不能把任意“其他值”当作合法 U 帧。
### 2.3 三类控制域规则
| 类型 | 长度约束 | 控制域约束 | 解析结果 |
|---|---|---|---|
| I 帧 | `L >= IEC104_MIN_LENGTH_FIELD + IEC104_ASDU_HEADER_LEN`(当前为10) | `C0.bit0=0`、`C2.bit0=0` | `N(S)=(C1:C0)>>1`,`N(R)=(C3:C2)>>1`,ASDU 长度=`L-4` |
| S 帧 | `L == 4` | `C0=0x01`、`C1=0x00`、`C2.bit0=0` | `N(R)=(C3:C2)>>1`,无 ASDU |
| U 帧 | `L == 4` | `C0` 为六种允许功能码之一,`C1..C3=0` | 输出 U 功能码,无 ASDU |
允许的 U 帧功能码:
| 功能 | ACT | CON |
|---|---:|---:|
| STARTDT | `0x07` | `0x0B` |
| STOPDT | `0x13` | `0x23` |
| TESTFR | `0x43` | `0x83` |
> 当前模块只校验并报告 U 功能码,不改变数据传输启停状态,也不会自动生成对应 CON 帧。
### 2.4 I/S/U帧构造
`IEC104_Build_Iframe()`执行APCI解析的反向操作:调用方传入`N(S)`、`N(R)`和完整ASDU,函数将起始字节、长度域、四字节控制域及ASDU写入输出缓冲区,并返回完整APDU长度。
该函数是无状态编码接口:不读取或修改`IEC104_LinkState_t`,不检查发送窗口,也不调用网络发送函数。调用方必须提供至少`IEC104_APCI_LEN + asdu_len`字节的输出空间。实际连接通过下述链路 Prepare/Complete 配对管理序号,不能单独构帧后伪造一个完成快照。
`IEC104_Build_Sframe()`根据调用方提供的`N(R)`构造固定6字节S帧:
```text
encoded_receive = (uint16_t)(recv_seq << 1)
68 04 01 00 encoded_receive低字节 encoded_receive高字节
```
写入控制域前,`N(R)`先左移1位。`buf`为空或`N(R)>32767`时返回`-1`,成功时返回`IEC104_APCI_LEN`。
`IEC104_Build_Uframe()`接收`int function`,使用`IEC104_UFrameFunction_t`定义的六种功能码构造固定6字节U帧:
```text
68 04 功能码 00 00 00
```
功能码仅允许`STARTDT_ACT/CON`、`STOPDT_ACT/CON`和`TESTFR_ACT/CON`。`buf`为空或功能码非法时返回`-1`且不写入缓冲区,成功时返回`IEC104_APCI_LEN`。
链路模块内部已检查非空缓冲及至少 6 字节容量,并传入固定合法功能码,因此这些调用使用 `(void)IEC104_Build_Uframe(...)` 显式忽略固定返回值。编码仍执行,公开函数仍返回 `int`;构造成功只代表缓冲已写入,不代表网络发送成功。对外部传入的未验证参数仍须按返回值处理。
基础构造函数只生成字节数组,不决定何时发送,也不调用网络接口。连接发送 I 帧应使用 `IEC104_Link_Prepare_I_Frame()`,由它在构帧成功时预留 `N(S)`;完整发送后把原 `IEC104_IFrameTx_t` 快照和最终发送长度传给 `IEC104_Link_Complete_I_Send()`。普通 S 确认则使用 `IEC104_Link_Prepare_S_Ack()` 与 `IEC104_Link_Complete_S_Ack_Send()` 配对。S/U帧调用方必须提供至少6字节输出空间。
构帧参数与返回值汇总:
| 接口 | 输入边界 | 成功返回 | 失败返回 |
|---|---|---|---|
| `IEC104_Build_Iframe()` | `buf/asdu` 非空,`N(S)/N(R)` 为 `0..32767`,`asdu_len` 为 `6..249` | APDU 长度 `6 + asdu_len`,范围 `12..255` | `-1` |
| `IEC104_Build_Sframe()` | `buf` 非空,`N(R)` 为 `0..32767` | `6` | `-1` |
| `IEC104_Build_Uframe()` | `buf` 非空,`int function` 的原值等于六种U帧功能码之一 | `6` | `-1` |
I 帧的序号先左移一位,再按低字节、高字节顺序写入控制域;ASDU 使用 `memcpy()` 原样复制,不验证其公共头或信息对象语义。输入 ASDU 与输出报文应使用不重叠的存储区域。所有构造接口都没有输出容量参数,无法检查调用方实际分配的空间。
例如,`N(S)=1`、`N(R)=2`、ASDU 为 `01 01 03 00 01 00` 时,I 帧构造结果为:
```text
68 0A 02 00 04 00 01 01 03 00 01 00
```
其中 `02 00` 编码 `N(S)=1`,`04 00` 编码 `N(R)=2`。该例仅用于验证字节编码,六字节 ASDU 只有公共头,不代表包含完整业务对象。APCI解析与I帧构造的ASDU长度范围一致,均为`IEC104_ASDU_HEADER_LEN..IEC104_MAX_ASDU_LEN`,当前为`6..249`字节。
U帧编码入口及内部功能码校验函数均使用`int`参数,先按完整整数值检查六种合法功能码,再转换为`uint8_t`写入控制域。启用短枚举时也会拒绝`0x107`等非法值,避免误生成`STARTDT_ACT`。调用方应直接传入待校验整数或合法枚举常量;若提前转换为短枚举或`uint8_t`,已丢失的高位无法由编码函数恢复。公开参数类型已调整,调用方及依赖该签名的函数指针须使用新声明并重新编译。
---
## 三、流式接收状态机
### 3.1 状态定义
阶段由received_length及is_frame_ready推导,不另存一份stage枚举。
| 状态 | 不变量 | 输入处理 |
|---|---|---|
| 等待帧头 | received=0、expected=0、ready=0 | 首字节必须为0x68;否则消费该字节并返回FRAME_ERROR |
| 等待长度 | received=1、expected=0、ready=0 | 长度必须4..253;合法后expected=2+L、received=2 |
| 收集报文体 | 2≤received<expected≤255、ready=0 | 批量复制当前帧所需字节,不消费下一帧 |
| 完整帧待处理 | received=expected、ready=1 | Feed返回FRAME_READY且consumed=0,等待显式释放 |
### 3.2 完帧处理
Feed收齐APDU后调用Parse_APCI,I帧再调用Parse_ASDU_Header检查公共头及已知固定长度对象的最低载荷长度。任一步失败都清空当前进度并返回FRAME_ERROR;全部通过后才设置待帧标志并返回FRAME_READY,保持APDU原文。
Peek只在待帧状态下输出 `IEC104_ReceivedFrame_t`。它复用相同的格式及最低长度检查并重建APCI视图,失败或EMPTY时不修改调用方输出。接收器不调用Link、SendManager或业务代码,不提交任何序号或ACK。
### 3.3 错误恢复边界
- 每个APDU边界的首字节必须为0x68;遇到其他值立即消费该字节、清除进度并返回FRAME_ERROR,不扫描后续字节重新同步。Connection登记FRAME故障,TcpServer随后断开连接。
- 长度非法时消费该长度字节,丢弃当前候选帧,停止本次Feed;剩余输入不被消费。
- 完整APCI非法、ASDU公共头不足或已知固定长度对象被截短时,消费到声明的候选帧末尾,丢弃候选帧,停止本次Feed;不处理该帧的序号或累计ACK。
- 报文体按已声明长度收集,内部0x68属于数据;不会在半帧中搜索新帧头。半帧超时由连接层处理。
- 参数、代次或内部进度非法返回ERROR,不修改接收器;有效的consumed输出被置0。
- Receiver_Reset只核对初始化及代次,允许显式丢弃异常组帧进度。是否继续格式错误后的连接由接入方决定;链路FATAL不能靠复位接收器继续旧会话。
### 3.4 接收结果与调用方责任
| 结果 | 值 | 含义及处理 |
|---|---:|---|
| ERROR | -2 | 参数、代次或状态错误;consumed=0,修正调用或结束故障连接 |
| FRAME_ERROR | -1 | 起始字节、长度/APCI或ASDU最低长度错误;候选帧已清除,consumed标明停止位置 |
| IN_PROGRESS | 0 | 全部输入已消费,尚无完整帧;继续输入后续字节 |
| OK | 1 | Init、Reset、Release_Frame或Get_Status成功 |
| FRAME_READY | 2 | 有完整帧,通过APCI及ASDU最低长度检查;Peek、分派、受理后Release |
| EMPTY | 3 | Peek/Release时没有完整帧;半帧保留,查询输出不变 |
表中省略 `IEC104_RECEIVER_` 前缀,不能按布尔值判断。data=NULL、length=0是合法的Feed查询;其他情况下data必须指向length字节有效输入。
### 3.5 状态校验与复位
Receiver_Valid在读写前核对初始化、代次、待帧标志,以及帧头、长度域、expected_length和received_length的一致性。报文体复制长度取“本帧剩余长度”和“本次剩余输入”的较小值,因此不会将粘包中的后续帧写入当前缓冲。
| 操作 | 当前半帧/完整帧 | 连接代次 | Link状态 |
|---|---|---|---|
| Init | 全部清空并使旧视图失效 | 绑定非零参数 | 不操作 |
| Release_Frame | 有完整帧才清空进度;半帧返回EMPTY | 保留 | 不操作 |
| Reset | 丢弃当前进度和待处理帧,保留缓冲字节 | 必须匹配并保留 | 不操作 |
| Get_Status | 只读返回已收长度、期望长度及完整帧标志 | 必须匹配并保留 | 不操作 |
| Abort | 清空全部状态及缓冲,使旧视图失效 | 解除绑定,须重新Init | 不操作 |
| 旧代次调用 | 不修改 | 不修改 | 不操作 |
`Get_Status`复用完整进度校验,OK时才写数值快照,不重新解析或分派报文。Connection据此区分本次新成帧和此前保留的帧。`Abort`用于已结束旧I/O及所有原文借用后的收尾,允许NULL;它不核对代次,Connection在调用前负责检查身份,不能拿旧事件直接清理新接收器。
### 3.6 分段输入与待帧保留
调用方为当前网络输入保存offset;每次Feed后只增加consumed,不丢弃尾部。FRAME_READY时先Peek并分派,即使offset已经到输入末尾,也必须处理这帧。
如果分派暂时返回WAIT,保留当前Receiver帧及尚未消费的输入尾部,并暂停该连接的后续分派。条件满足后重试当前帧;一旦受理,Release后从原offset继续递入。禁止在待帧状态下仅重复Feed形成空转。
Receiver只提供一个待处理帧槽。未消费输入的容量和网络读取背压由连接层负责;无额外接收FIFO、动态分配或后台任务。
---
## 四、ASDU 公共头解析
### 4.1 当前实际调用关系
Receiver.Feed调用Parse_APCI校验帧格式,I帧还调用Parse_ASDU_Header检查最低载荷长度;Peek_Frame返回完整APDU、已解析APCI和ASDU视图。两次检查都在Link/Manager受理之前完成。ASDU公共头解析结果不缓存在接收器中,业务仍按需解析事件副本。
~~~text
Receiver.Feed → Parse_APCI → I帧调用Parse_ASDU_Header → FRAME_READY → Peek_Frame
→ 连接层:I/S交给SendManager,U交给对应控制接口
→ I帧受理后:TcpServer复制I_FRAME事件 → 经Connection调用Release_Frame
业务:TcpServer_NextEvent取得副本 → Parse_ASDU_Header → Type ID业务处理
~~~
Parse_APCI要求I帧ASDU长度至少为IEC104_ASDU_HEADER_LEN,当前为6字节;接收器随后通过Parse_ASDU_Header检查已知固定长度类型的载荷。任一步失败都报告FRAME_ERROR,不进入链路序号及累计ACK处理,也不交付I_FRAME。apci.asdu指向APDU偏移6,asdu_len为长度域减4。业务仍须检查具体字段和对象内容;业务检查失败不能回滚已经由链路接受的传输序号。Parse_APCI也用于发送缓冲,仍只承担APCI及公共头最小空间检查;发送构帧不调用ASDU载荷检查。
### 4.2 可配置公共头与104默认布局
公共头解析现在必须显式传入`IEC60870_AppLayerParameters_t`,不保留原三参数签名。COT和CA分别支持1/2字节,IOA支持1/2/3字节,头长为`2+sizeOfCOT+sizeOfCA`。以下图表描述本工程Receiver显式使用的104标准配置(COT/CA/IOA=2/2/3、最大249);通用ASDU解析也可使用其他合法配置。
```text
偏移: 0 1 2 3 4 5 6 ... 末尾
+------+------+------+------+------+------+----------------+
| TI | VSQ | COT | ORG | CA | 信息对象区 |
+------+------+------+------+------+------+----------------+
| ASDU |
```
| ASDU 偏移 | 字段 | 当前解析规则 |
|---:|---|---|
| 0 | Type ID | 原值输出;已知固定长度类型参与最低载荷检查,未知类型不因此被拒绝 |
| 1 | VSQ | bit7 → `is_sequence`;bit0..6 → `object_count` |
| 2 | COT | bit7 → `is_test`;bit6 → `is_negative_confirm`;bit0..5 →传送原因 |
| 3 | ORG | 源发地址原值输出 |
| 4..5 | CA | 小端组合为 16 位公共地址 |
| 6..末尾 | 信息对象区 | 输出首地址视图和剩余长度 |
函数接受所选头长至`maxSizeOfASDU`字节的ASDU(通用上限254),并在写输出前检查已知固定长度对象所需的最低载荷长度。COT为1字节时没有OA,结果OA为0;CA从偏移`2+sizeOfCOT`开始,信息对象区从所选头长开始。参数或长度失败返回0,输出保持不变。它不判断是否支持该Type ID,也不验证传送原因、公共地址或信息对象内容是否合法。参数与原报文均为借用,视图使用期间必须有效且不变。104传输层仍只接受标准配置及6..249字节ASDU。
`is_sequence`、`is_negative_confirm`、`is_test` 输出为 `0/1`,不是保留原掩码值。SQ参与最低长度计算,但不会自动展开连续信息对象地址。信息对象区长度为零时,其指针位于公共头之后,不得解引用。
### 4.3 已知类型的最低载荷长度
设IOA宽度为L=`parameters->sizeOfIOA`(104接收器传入3)、VSQ对象数量为N、单个对象除IOA以外的数据长度为D,公共头后的最低载荷为:
- SQ=0:`N × (L + D)`;
- SQ=1:`L + N × D`。
固定长度表覆盖Type ID `1..21`、`30..41`、`45..51`、`58..64`、`70`、`100..107`、`110..113`、`120..124`和`126..127`。例如104配置下单点命令45、N=1时,6字节公共头后至少还须有3字节IOA和1字节命令;只有公共头的声明长度在链路受理前被拒绝。读命令102的数据部分为零字节,但仍按配置检查IOA是否完整。
这是最低长度检查:未知/变长类型(包括文件段125)及N=0不通过该表限制;额外尾字节、某类型是否允许SQ或多个对象、字段取值和业务支持范围继续由业务检查。长度字段仍决定APDU边界,不根据后续字节猜测或补齐被截短的命令。
ASDU长度检查接入Receiver,保证格式错误在序号和累计ACK受理之前被发现。
---
## 五、与链路模块的接口边界
Receiver与Link独立,连接层持有一份LinkState供发送和接收共同使用,不存在接收器私有序号状态。链路必须显式初始化角色并通过既有启停流程推进;接收器不会将其预设为STARTED。
| 帧类型 | 子站连接层的处理位置 | 释放接收帧的时机 |
|---|---|---|
| I | `SendManager_Handle_I_S_Frame` | 成功受理且TcpServer已复制I_FRAME事件后,由Connection释放 |
| S | `SendManager_Handle_I_S_Frame` | 成功受理后,由Connection释放 |
| STARTDT_ACT / STOPDT_ACT / TESTFR_ACT | 对应Manager入口 | 根据各接口返回值确认已受理后 |
| TESTFR_CON | `Link_Handle_Testfr_Con` | 当前事件已处理或按契约忽略后 |
| 角色不接受的U功能 | 连接层按角色策略处理 | 处理完成或连接终止 |
控制入口WAIT表示尚未受理,必须保留当前帧;成功受理后释放控制帧。对端ACK必须晚于对应本地发送完成的提交;Receiver仅保留接收顺序,不代替发送完成记账。
旧 `IEC104_Legacy_Link_Reset`及其私有Link已恢复,该接口只复位旧入口的I/S状态并恢复STARTED预设,不改变旧接收进度。独立Receiver的接收复位调用Receiver_Reset;指定连接的Link初始化/复位继续使用Link公共接口。链路状态、超时及错误收尾约定见 [链路设计](IEC104_Link_设计架构.md)。
---
## 六、公开接口契约
104帧接口位于 `IEC104_Codec.h/.c`,公共ASDU头与参数检查位于 `IEC60870_Codec.h/.c`,独立接收接口位于 `IEC104_Receiver.h/.c`。旧 `IEC104.h/.c` 提供原有逐字节接口;下表合并列出两个Codec和Receiver。
| 接口 | 状态性 | 成功结果 | 主要注意事项 |
|---|---|---|---|
| `IEC104_Get_Frame_Type(control)` | 无状态 | 返回 I/S/U 候选类型 | 只分类,不代表控制域合法 |
| `IEC104_Parse_APCI(frame,frame_len,apci)` | 无状态 | 返回 `1`,填充类型、序号、U 功能或 ASDU 视图 | 失败返回 `0`;基础参数检查失败不写输出,分类后的控制域检查失败可能已改写部分输出;不校验链路序号和 ASDU 语义 |
| `IEC104_Build_Iframe(buf,send_seq,recv_seq,asdu,asdu_len)` | 无状态 | 写入完整 I 帧,返回 `12..255` | 参数非法返回 `-1`;调用方保证输出空间;不修改链路状态 |
| `IEC104_Build_Sframe(buf,recv_seq)` | 无状态 | 写入固定 6 字节 S 帧,返回 `6` | 参数非法返回 `-1`;`N(R)` 范围为 `0..32767`;不标记接收已确认 |
| `IEC104_Build_Uframe(buf,function)` | 无状态 | 写入固定 6 字节 U 帧,返回 `6` | 按`int`原值校验功能码,失败返回`-1`且不写入缓冲区;不执行状态转换或自动应答 |
| `IEC60870_AppLayerParameters_Valid(parameters)` | 无状态 | 合法参数返回 `1` | NULL、非法字段宽度/OA/最大长度返回 `0` |
| `IEC60870_Parse_ASDU_Header(parameters,asdu,asdu_len,asdu_info)` | 无状态 | 返回 `1`,填充公共头、信息对象区及参数借用视图 | 参数或最低载荷长度检查失败返回 `0`,不修改输出;长度限制由配置决定 |
| `IEC104_Receiver_Init(receiver,generation)` | 初始化指定实例 | OK | 非零代次;新连接复用前先结束旧I/O |
| `IEC104_Receiver_Feed(receiver,generation,data,length,consumed)` | 更新指定实例 | FRAME_READY或IN_PROGRESS | 每次最多一帧;所有返回都按consumed推进输入;ERROR消费0 |
| `IEC104_Receiver_Peek_Frame(receiver,generation,frame)` | 只读 | FRAME_READY | 输出借用视图;EMPTY/ERROR不改输出 |
| `IEC104_Receiver_Release_Frame(receiver,generation)` | 释放待处理帧 | OK | 无完整帧返回EMPTY,保留半帧 |
| `IEC104_Receiver_Reset(receiver,generation)` | 丢弃接收进度 | OK | 保留代次,不操作Link;所有旧视图失效 |
| `IEC104_Receiver_Get_Status(receiver,generation,status)` | 只读 | OK | 数值快照不借用原文;参数、旧代次或进度非法返回ERROR且不改输出 |
| `IEC104_Receiver_Abort(receiver)` | 清除状态及绑定 | 无返回值 | 先结束I/O和借用;允许NULL,再使用须Init |
`IEC104_Link.c` 自身的公开接口不属于本文接口定义,详见 `IEC104_Link_设计架构.md`。
---
## 七、设计决策与考量
### 7.1 分段输入与显式释放
Feed兼容单字节和批量输入,报文体批量复制,每次停在一帧边界。显式Release将报文有效期与下一次输入分开,便于连接层处理控制队列满等暂时无法受理的情况,并保持同连接的严格分派顺序。
### 7.2 固定缓冲、零动态分配
每个Receiver内置255字节APDU缓冲,另有少量长度、代次和标志字段。无堆分配、接收FIFO或独立ASDU副本。Peek输出只读借用视图;需要长期保存的调用方自行复制数据。
### 7.3 先检查、后更新
参数、代次和内部进度在处理输入前检查,ERROR不修改接收器。FRAME_ERROR属于已经消费的输入格式错误,会丢弃候选帧并报告消费位置。Peek在局部结果完成APCI解析后才写调用方输出。Receiver不提前或重复提交Link状态。
### 7.4 接收复位与链路复位分离
Reset只丢弃指定Receiver的接收进度并保留连接代次;Link序号、启停和发送记录由各模块独立管理。重建连接用新代次Init,且必须先结束旧I/O。实例初始化不使链路进入STARTED。
### 7.5 日志独立
Receiver和Codec不依赖日志模块。连接层根据返回值决定日志级别和断连策略;现有 `IEC104_Log.c/h`可按应用需要继续使用,无需随接收器一并链接。
### 7.6 旧接口迁移
`IEC104.c/h`、`IEC104_Rx_Feed_Byte`、`IEC104_Rx_Reset`、`IEC104_Legacy_Link_Reset`及旧接收枚举/结构已从删除前备份原样恢复。旧入口仍编译IEC104.c、Codec.c、Link.c和Log.c;独立Receiver需要Receiver.c、IEC104_Codec.c和IEC60870_Codec.c。恢复旧文件不改变新接收器或发送模块。
内部接收实现迁移到独立Receiver时,由Connection持有Receiver并处理consumed、Peek及Release,TcpServer负责保留输入尾部和复制业务事件。应用的子站接入统一使用IEC104_Slave.h,门面内部使用TcpServer.h;只处理公共ASDU头的业务包含IEC60870_Codec.h,104帧工具包含IEC104_Codec.h。旧入口在成帧成功前包含I/S链路检查;新路径由Connection交给SendManager执行,不能仅重命名函数后继续假设序号已被校验。
接口过期的旧测试入口已删除;当前测试直接使用现有TcpServer实现,不提供测试兼容层。
## 八、变更记录
| 日期 | 变更 |
|---|---|
| 2026-09-03 | 初始版本:依据当前源码建立成帧、APCI/ASDU 解析、链路序号、接口契约、测试基线和已知边界设计说明 |
| 2026-09-03 | 拆分 `IEC104_Link.c` 设计:本文只保留调用边界和全局状态集成限制,链路状态、算法及测试迁移至独立文档 |
| 2026-09-03 | 更正 ASDU 调用关系:明确当前接收链路只调用 APCI 解析,`IEC60870_Parse_ASDU_Header()` 尚未接入且仅由测试直接调用 |
| 2026-09-04 | 增加I、S、U帧无状态构造接口及其参数、输出格式和职责边界说明 |
| 2026-09-07 | 链路模块增加普通S帧的 `w` 门限、立即确认、N(R)快照和发送完成接口;全局接收器与发送调度仍未接入该流程 |
| 2026-09-08 | 同步固定连接角色模型:全局旧入口默认被控站;连接故障只由外部 TCP 上下文管理,不在链路状态重复锁存;详细状态与接口契约见链路设计文档 |
| 2026-09-10 | 同步IEC104_Legacy_Link_Reset命名及两类复位边界,纠正I/S链路结果类型,补充U帧编码返回约定与当前测试状态;区分已有算法和待实现的连接调度 |
| 2026-09-17 | 将无状态编解码、协议常量和报文类型提取到IEC104_Codec.c/h;旧单路接收入口及其行为保留,IEC104.h继续提供原有声明,生产构建新增Codec源文件 |
## 九、当前验证与使用边界
本文描述当前源码行为,不等于已经完成端到端协议验证。当前保留的字节环专项、编译命令和覆盖范围集中维护在[测试说明](../test/IEC104测试文档.md);旧回归套件已删除,其历史通过数不计入当前验证。
链路层已提供 `sent_vs`、不可变 I 帧快照、固定角色启停、按受理顺序立即启停和独立 TESTFR。独立 `IEC104_SendBuffer` 已提供 唯一当前I帧、独立紧凑S/U FIFO、部分写入及本地发送期限;`IEC104_AsduQueue` 和 `IEC104_SendManager` 已提供变长业务排队、发送前编号、未ACK原文保留、I/S接收、完成分派、独立回执、I帧t1及显式重连恢复。Receiver已提供独立接收上下文、完整APDU交付和代次隔离;Connection已统一收发事件分派、U帧路由及协议期限,Windows TcpServer已提供实际I/O,并用Poll周期调用Tick,无须业务另建协议定时器。基础编码器只校验可见参数,U枚举截断边界见2.4节,不能宣称已经全面校验所有整数输入。
## 十、集成设计与接入边界
### 10.1 当前能力与职责分配
Receiver已实现每连接成帧和完整APDU交付;独立发送队列、业务队列及发送调度接口见 [发送模块统一设计](IEC104_发送模块_设计架构.md)。当前Windows子站接入由Connection、TcpServer和Net_Windows组成,业务持续Poll、通过NextEvent主动读取事件并按需排入ASDU;具体业务对象仍由上层实现。
| 能力 | 当前负责层 | 与现有实现的衔接 |
|---|---|---|
| TCP建连、读写、断连和重连 | TcpServer(已实现) | 将recv字节交给Connection;回报send实际写入量;断线后保留监听并接受新主站 |
| 每连接独立状态、统一错误收尾 | Connection(已实现) | 持有接收器、链路状态、发送模块及配置,统一串行调度 |
| 完整帧的有序分派 | Connection(已实现) | 使用Receiver.Feed/Peek/Release;I帧由TcpServer复制为事件后释放,S/U受理后释放,WAIT保留 |
| STARTDT/STOPDT/TESTFR事件分派 | Connection(已实现) | 按子站角色路由U功能码,由Manager统一提交Link修改;Connection仅作只读Link查询 |
| `t1/t2/t3`、`k`和`w`调用时机 | Connection + TcpServer(已实现) | Poll使用单调时间推进Tick,执行确认、探测和超时收尾;被动监听不发起TCP连接,未实现主站`t0`建连流程 |
| I/S/U实际发送 | TcpServer + Connection(已实现) | Prepare取得待发字节,send后立即回报增量;部分发送下轮续传,业务不再直接调用底层完成接口 |
| 总召、计数量召唤与Type 103校时 | 独立业务模块(已实现) | 通过Slave事件及共用站点表分派,总召/计数量使用业务事件;校时由Execute_Next显式执行,确认回显原时标,见[时钟同步设计](IEC104_ClockSynchronization_设计架构.md) |
| 实际遥信/遥测数据源、遥控及设备设时 | 应用接入层 | 按业务模块请求读取点表或执行设备动作;示例提供模拟点表和模拟时钟,协议库不自动操作硬件 |
### 10.2 统一连接上下文
独立Receiver由Connection持有,接收和发送使用同一份LinkState;已恢复的旧入口仍保留原有接收/Link私有全局对象,不参与TcpServer路径。当前归属如下:
```mermaid
flowchart TD
App[业务层] -->|Poll / NextEvent / Enqueue| Transport
Transport["IEC104_TcpServer:监听 / 收发 / 断连事件"] --> Context["IEC104_Connection:统一串行调度"]
Transport --> Net[Net网络后端]
Transport -->|NextEvent返回事件副本| App
App --> Asdu[ASDU公共头与业务对象处理]
Context --> Rx["接收器:IEC104_Receiver_t"]
Context --> Link["共享序号:IEC104_LinkState_t"]
Context --> Manager[SendManager发送管理]
Manager --> Link
Manager --> Tx[SendBuffer报文与写入进度]
Manager --> Queue[AsduQueue原文队列]
```
Receiver各入口已经显式接收实例和连接代次;Connection按序调用SendManager及控制接口,统一处理错误收尾。TcpServer为每次接受的主站分配新代次,旧单路入口及其私有Link不参与此路径。
Receiver的内部Peek视图持续有效到Release、Reset或重新Init。TcpServer先复制完整APDU到事件FIFO,再经Connection释放内部帧;业务通过NextEvent取得无借用指针的独立副本,可以跨下一轮Poll或断线保留,无需调用底层Release。普通通知满仍可处理排在前面的S/U;遇到无处交付的I帧时保留原帧、暂停续收,NextEvent腾出空间后由Process恢复。启停和收尾分别预留容量;启停变化逐条保留,启停槽满时延后受理改变状态的ACT,消费对应通知后重试。通知积压不主动断连,但原有协议期限继续生效;持续积压的I帧会挡住后续S/U,等待启停槽会延迟ACT受理及其应答,应用必须及时消费事件。Close后仍能取出全部请求、回执和连接收尾事件。同连接业务需要应答时,携带事件generation通过TcpServer_Send_Response提交ASDU;通过启停准入后,条件允许时立即尝试一次非阻塞发送,暂不能发送时缓存HIGH。主动上报通过TcpServer_Enqueue_Event缓存,不要求存在连接,帧头、序号及实际socket写入由协议和TCP层完成。
### 10.3 收发与状态提交顺序
以下说明底层顺序。SendManager.Prepare_Next_Send在实际发送前选择并准备当前帧,Handle_Send_Progress执行完整发送后的Complete/Commit_Send_Completion,Handle_I_S_Frame执行I/S校验、记录ACK并释放对应ASDU原文;调用方不再重复执行其中的底层步骤。S/TESTFR及子站启停构帧入队使用Manager封装,TESTFR_CON也经Manager.Handle_Testfr_Con提交,只有受理成功才由Connection撤销探测t1。Connection安排调用时机及U帧路由,TcpServer执行I/O。Manager仅绑定CONTROLLED链路,不参与主站启停流程。
Connection的Link/Buffer运行期修改入口统一为Manager;初始化经Manager.Init_Connection预检后直接绑定最终地址,失败保留原对象和队列。发送期限及队首身份由Manager.Get_Deadlines提供,Connection以临时Collect_Deadlines视图统一超时检查、发送准入、控制推进和等待计算,原始帧时间戳仍保存在所属模块。运行期参数、身份、序号及模块计数校验继续保留。
接收流程为:严格检查帧头并按长度成帧 → APCI校验 → I帧公共头及已知类型最低载荷检查 → 连接控制状态与I/S序号校验 → 提交链路接收状态 → 按帧类型分派。成帧及最低长度失败统一登记FRAME;I帧通过后仍由业务检查对象内容,S帧进入发送确认处理,U帧进入启停或心跳控制。后续ASDU业务校验失败应单独报告,不能自行回滚已经接受的传输序号。
发送侧必须区分“已构造并预留”“已排队”“完整写入传输层”“对端已确认”四个阶段。`IEC104_Link_Prepare_I_Frame()` 成功构帧时立即分配 `N(S)`、保存 `N(R)` 快照并推进 `V(S)`,使预编码和排队中的帧也占用 k 窗口;`V(A)` 仍只能由对端合法 `N(R)` 推进。
子站连接层在准备实际写socket时调用 `IEC104_SendManager_Prepare_Next_Send()`。已有当前I帧时续传,否则先发控制FIFO;两者均空才从ASDU字节环选择未编号业务。ASDU头和原文均可跨数组尾部,队列提供最多两段视图;Manager在原文跨界时先用249字节局部数组拼接,再交给Link,传输层仍取得连续APDU。Manager保障记录和当前APDU存储后调用Link.Prepare,让SendBuffer接手完整I帧并建立Manager记录,再通过Mark_Submitted完成队列交接记账:HIGH消费原文,NORMAL登记为保留原文待ACK。队列记账前仍保留待发旧状态,该状态不能用来判断发送缓冲是否已经接手。最多一帧已编号I帧等待本地完成,其余业务仍可按优先级选择。S/U使用独立6字节报文槽;当前帧不可被截断交错。Prepare成功后的序号不可撤回,后续提交或发送失败须结束连接。
应答入口经Manager的共享准入函数,仅在STARTED+IDLE时接手;其他启停阶段在记录容量、k窗口及HIGH容量检查前返回ERROR且不入HIGH、不因该拒绝断连。普通路径先由Connection.Drive处理保留接收和控制义务,再调用SendManager.Submit_Response检查实际接手时的状态;期限已到时直接走SendManager.Enqueue(HIGH),同样受准入限制。准入后,没有当前帧和旧HIGH且发送门控、窗口、记录容量、公平配额允许时直接准备一帧,再由TcpServer尝试一次非阻塞写入;暂不能准备或协议期限已到时先缓存HIGH。直接路径与队列路径共用Prepare_I_Asdu、SendBuffer及HIGH发送记录,仅跳过ASDU入队和Mark_Submitted;不会重复实现序号、完成或ACK逻辑。部分写入或暂不可写保留当前帧,由Process/Poll续发。公开OK只表示已接手原文,FATAL可能发生在实际写入之后。
I帧完成接口要求快照的 `N(S)==sent_vs`,只推进本地完成边界和实际捎带确认位置。Manager提交完成记录后立即释放当前I帧APDU;HIGH原文在I帧提交并建立发送记录时已出队,NORMAL原文保留到ACK或被后续入队覆盖,发送记录独立保留。对端ACK限制在 `va..sent_vs` 内;Link接受后Manager先登记所有新增ACK事实,核减high_unacked_count,再仅对NORMAL按记录身份释放原文或核减覆盖待确认计数,不能删除后来入队的新条目。原文出队或覆盖不推进ACK、不释放k窗口或回执槽。SendBuffer不保存确认边界,不再提供Apply_Peer_Ack。TcpServer把就绪回执复制为RECORD事件后,经Connection移除内部记录,业务通过NextEvent读取副本。Manager按最早已完成未确认记录的原始写完时刻判断t1;异步传输适配必须先提交对应发送结果,再分派相关接收事件。
发送准备和写入回报保留真实单调时间,仅因本地发送及STOP期限直接报告超时;对端ACK/TESTFR确认超时故障由接收阶段判定。旧确认t1已到时,Connection暂停为HIGH/NORMAL创建、编号新I帧;已有帧及控制发送仍可推进,以解除接收阻塞。有效确认解除所有已到期等待后自动恢复准入,不改变任何期限起点。快速应答或常规发送跨过确认期限后安排立即Process,先按有界输入快照处理确认,再按原始t1检查;Prepare报告零等待。不增加恢复期限或固定宽限时间,事件容量背压下仍按既有期限处理。
断线时TcpServer先复制剩余记录和断开通知,再由Connection_Close调用Manager.Abort;服务队列继续存在。TcpServer在关闭旧Connection后调用Detach:清空HIGH,将NORMAL现存原文恢复未提交,清除旧覆盖记账并切换到代次0;离线期间继续缓存NORMAL。新连接建立时Rebind到新代次,再Init连接。业务只使用公开提交及事件接口,不直接操作队列。HIGH固定用于当前连接的请求应答,NORMAL用于业务允许跨连接恢复的事件,业务分别调用Send_Response和Enqueue_Event;不提供通用入队兼容入口或重连保留开关,Close服务才清空NORMAL。已覆盖原文无法恢复,新连接从新序号开始,不能复用旧APDU。同一TCP上的启停不执行Rebind。Manager初始化成功、受理新STOPDT_ACT及每轮首次生成STARTDT_CON时清空待发HIGH;已启用时重复START保留HIGH及公平配额,WAIT尚未受理不清理;STOP成功受理立即清理HIGH。STOP受理时仍在HIGH的应答即使已返回OK也按约定作废,不产生逐条回执;已提交的当前帧和发送记录不受清理影响,继续完成及等待ACK。
需要纳入链路状态管理的 I/S 帧不能只调用基础 `IEC104_Build_*` 构造函数:I 帧必须通过 `IEC104_Link_Prepare_I_Frame()` 与 `IEC104_Link_Complete_I_Send()` 配对,普通 S 帧必须通过 `IEC104_Link_Prepare_S_Ack()` 与 `IEC104_Link_Complete_S_Ack_Send()` 配对。两个完成接口内部只把 `acked_nr` 推进到对应报文实际携带的位置,因此排队后新收到的 I 帧仍保留在 `acked_nr..V(R)`。同一连接仍须按上线顺序串行提交;较新的确认已经发送后,旧 S 帧不得再上线。
被控站受理START时立即激活,受理STOP时立即停用并等待确认;相反ACT不暂存。后到START结束尚未生成CON的停止等待,已有CON按FIFO写出,完成不回写状态。S确认覆盖接收数据且I帧全部获ACK时可排STOP_CON;Connection最多依次推进S与CON两项。STOP总期限从received_at_ms起算,按本轮最后一帧STOP_CON身份结束,成功受理START也取消旧计时。状态事件由Connection内部适配器在ACT受理时交给TcpServer,通知容量不足则WAIT保留原请求。发送完成仍准确记录字节、序号及ACK事实,见[发送缓冲设计](IEC104_发送模块_设计架构.md#sendbuffer)。
### 10.4 建议实施顺序与验收点
| 顺序 | 实施内容 | 可检查的完成条件 |
|---:|---|---|
| 1(已实现接收基础) | Receiver独立实例、完整帧视图、消费数和显式释放;Link由连接层共享 | 两个接收实例可交错输入;待处理帧不被后续Feed覆盖,旧代次调用被拒绝 |
| 2(已实现) | 接入发送前准备、部分写入续传及独立确认记录,补齐实际I/O和收发串行调度 | 发出 `N(S)=0` 后收到 `N(R)=1` 能正确确认并释放原ASDU;发送失败不重复推进状态,旧确认不清除新增待确认数据 |
| 3(已实现) | 连接生命周期、U 控制、定时器及窗口策略 | 受控传输与时间事件下可验证启动、停止、心跳、超时和窗口边界;序号错误停止当前批次并关闭连接 |
| 4(对象及三类业务已实现) | 公共对象编解码、总召/计数量、校时校验及显式执行;继续接入真实数据源和遥控 | 自动回归覆盖地址路由、召唤进度、校时原文确认及时间边界;模拟模式不设系统时间,硬件设时和实际主站联调须另行验收 |
---
@@ -0,0 +1,431 @@
# IEC104 链路模块
当前子站业务统一包含`IEC104_Slave.h`:Slave内部持有不透明TcpServer,提供生命周期、事件循环、主动上报和状态查询,并在NextEvent交付I帧时自动建立ASDU视图及原连接的共用应答接口。业务不再手动创建TcpServer、绑定generation或安装函数指针。入口和延迟任务示例见[子站统一入口](#子站统一入口)。
Slave提供[共用站点表](IEC104_API接口汇总.md#station-registry):应用提供固定地址节点,动态注册多个CA和业务context,重复CA拒绝。删除立即退出路由,已有引用和遍历结束后才回收;Is_Reusable为true后应用才能释放存储。总召设置config.use_station_registry=true后按请求CA选站;多目标广播配置每站状态区,以一个任务执行“全部确认、逐站数据、全部终止”。其他业务可复用相同的查找、引用及快照遍历接口。
总召由独立库模块[IEC104_Interrogation.c/h](../../104/business/IEC104_Interrogation.h)实现,支持QOI=20站总召、21..36分组总召及多类型无时标监视数据,负责批次校验、发送等待、主站撤销、业务超时及停用/断线取消。应用通过BEGIN/NEED_DATA/FINISHED事件和显式应答管理IOA、分组、遍历、逐批取值及终结;[子站示例](../../examples/iec104_slave_example.c)提供模拟点表、事件分派和main,构建运行见[示例说明](../examples/IEC104子站示例.md)。
内部调用关系为`Slave → TcpServer → Connection → SendManager/Receiver/Link`,网络I/O仍经Net执行,当前提供Windows后端。现有单主站、静态内存、HIGH/NORMAL队列、事件FIFO、Prepare/Process或Poll调度策略保持不变。共用ASDU及Slave发送接口继续使用IEC60870前缀;公共层不依赖104传输实现。下文的底层接口说明供维护和独立TCP接入使用,业务默认通过Slave操作服务。
`Get_Status`同时提供`high_queue`和`normal_queue`的待发条目数、保留原文条目数及总容量/已用/空闲字节数,先检查`asdu_queue_status_valid`。待发数不包含已交给发送模块的ASDU;NORMAL保留到ACK前的原文仍计入存储量,字节统计包含条目头。Init成功后离线也可查询,Close后统计无效;队列为空不代表发送或确认全部完成。公开状态结构已扩展,库与调用方须一起重新编译,字段含义见[ASDU队列积压查询](IEC104_TcpServer_设计架构.md#21-asdu队列积压查询)。
`NextEvent`区分连接建立(CONNECTED)、数据传输激活(ACTIVATED)、停用(DEACTIVATED)和连接断开(DISCONNECTED),四者共用`event.transport.data.connection`快照及对端地址。启停事件在对应ACT成功受理并提交状态变化后产生,CON可能仍待发送;同状态重复ACT不重复通知,直接断开不补造停用事件。业务可按事件类型处理启停,无需通过查询状态比较变化。
`Get_Status`的`pending_state_event_count`报告尚未消费的ACTIVATED/DEACTIVATED数量,不能追溯已消费的启停历史。当前请求的错误应答可在同步分派中调用`IEC104_Slave_Reject_Request`,支持COT=44..47,复用HIGH且不改输入事件;不新增示例应答队列。调用时机、WAIT丢新策略与FATAL不可重试约定见[同步拒绝当前请求](IEC104_API接口汇总.md#reject-request)。
发送队列NORMAL与`NextEvent`业务通知FIFO是两份独立存储:NORMAL满时可覆盖旧ASDU原文;已入队业务通知逐条保留,不覆盖、不合并启停变化。通知按有效载荷长度存放于字节环,配置宏仍表示保证条数:默认普通30条最长通知、启停4条及收尾32条记录加1个最长I帧和1个断开通知。当前x64 ABI下环占11243字节,接收暂存默认2048字节,两块合计13291字节,比原来减少43.9%;16字节APDU可在普通区缓存185条。普通通知不能占用启停及收尾预留;启停配额满时暂缓受理后续改变状态的ACT,已有CON继续发送。详细公式见[TCP服务设计](IEC104_TcpServer_设计架构.md)。
新I帧无普通空间可交付时保留原帧并暂停续收,`Prepare`及`Get_Status`的`receive_paused`为1;NextEvent腾出空间后安排Process恢复,等待中的I帧先于回执交付。已确认回执因普通空间或本轮预算不足暂留内部时,可能晚于随后发生的启停通知交付,保持不因回执积压而暂缓启停CON的行为。通知积压不直接断连,但保留I帧会阻挡后续S/U;长期不消费仍可能触发原有协议超时。应用应在每轮Process/Poll后及时取出事件。此次存储调整保持公开API及事件结构不变。
`IEC104_TcpServer_Prepare(server, &info, error)`只读导出socket关注集合、最近协议等待上限及本地续跑标志;应用统一等待其他模块和TCP事件后,用`IEC104_TcpServer_Process(server, &ready, error)`有界推进,Process不执行等待。socket只借给事件循环注册,关闭/重连后的旧通知按注册token过滤;真实I/O与Connection调度仍由TCP内部处理。活动连接未EOF时入队成功、背压解除和预算耗尽后按need_process安排续跑,不能只等待新的socket边沿;离线或EOF后新增NORMAL只缓存,不因此触发空转。EOF后也停止为此前入队但尚未编号的NORMAL创建新I帧,将这些原文留给下一连接;当前已编号帧、已受理HIGH及控制帧继续按原规则收尾。接入约定见[TCP事件循环说明](IEC104_TcpServer_设计架构.md#31-接入应用自己的事件循环)。
`IEC104_TcpServer_Poll(server, max_wait_ms, error)`组合相同的准备和推进核心,中间至多等待一次:0只查询就绪,正数允许等待并按最近协议期限缩短。原poll_interval_ms配置项已移除,业务无需分别驱动内部收发和Tick。
当前实现支持控制方向提前发送:控制站可在ACT成功入队后预留命令I帧,并在ACT之后发送,不必等待CON;被控站成功受理STARTDT_ACT即进入STARTED/IDLE,开放I/S处理与发送准备,已生成的CON按FIFO先于随后准备的I帧和S确认发送。初始STOPPED/IDLE仍禁止I/S接收及新I帧发送。标准适用条件与连接组管理边界集中说明于 [链路设计第3.2节](IEC104_Link_设计架构.md#32-接收-i-帧)。
| 阅读入口 | 负责内容 |
|---|---|
| `IEC60870_Types.h` | 101/104共用的应用层参数、ASDU存储上限;不包含传输状态 |
| `IEC104_Types.h` | 104尺寸常量、标准104应用层初始化值、ASDU优先级及链路配置 |
| `IEC60870_Codec.c/h` | 101/104共用的参数校验、ASDU公共头解析及已知类型最低载荷长度检查 |
| `IEC104_Codec.c/h` | 104专用APCI检查、I/S/U帧编码和帧类型 |
| `IEC60870_Asdu.c/h` | 通用ASDU容器、布局校验、对象分派与原文应答;使用说明见下文“ASDU信息对象模块” |
| `IEC60870_Slave.c/h` | 101/104共用的主站连接接口,分派ASDU发送、激活确认和激活终止 |
| `IEC104_Slave.c/h` | 子站统一入口:TCP服务、ASDU/应答接口、原连接隔离及各业务共用的CA站点表 |
| `business/IEC104_Interrogation.c/h` | 共用召唤引擎:任务、广播、期限、事件、取消与发送等待;接入见[总召流程](IEC104_完整调用流程.md#flow-interrogation) |
| `business/IEC104_GeneralInterrogation.c/h` | Type100规则及兼容的Interrogation_Create入口 |
| `business/IEC104_CounterInterrogation.c/h` | Type101规则、创建及一次动作执行入口;见[计数量设计](IEC104_CounterInterrogation_设计架构.md) |
| `IEC104_TcpTypes.h` | Slave与TcpServer共用的配置、调度、事件和状态值类型,无服务操作接口 |
| `IEC60870_InformationObjects.c/h` | 67种独立信息对象,覆盖监视、命令、初始化、参数和文件;编码通过只读函数表分派,支持变长文件段 |
| `IEC60870_Time.c/h` | 101/104共用时间工具:CP16/CP24/CP56Time2a编解码、本地标准时间转换、SU修正、日历/星期和纪元秒数工具;使用约定见[时间工具设计](../common/IEC60870_Time_设计架构.md) |
| `IEC60870_Clock.c/h` | 101/104共用时间源接口:直接读取和设置固定UTC+8日历;Clock.c内置Windows读写,Clock.h预留RTC接口,由编译选项二选一 |
| `IEC104_Receiver.c/h` | 每连接严格帧头检查、成帧、APCI及ASDU最低长度检查、完整APDU借用视图和显式释放;不处理链路序号 |
| `IEC104_Connection.c/h` | TCP内部连接协调:I/S/U分派、接收保留与释放、部分发送、超时推进及旧代次隔离;内部设计见[连接层设计](IEC104_Connection_设计架构.md) |
| `IEC104_TcpServer.c/h` | 底层TCP服务:IPv4单主站、静态池句柄、事件FIFO;Prepare/Process或Poll推进,Get_Remote_Address查询对端,Close_Connection按代次断开单连接 |
| `IEC104_TcpServer_Config.h` | 实现的编译期容量配置;默认一个服务器静态槽,可调整池及缓冲容量 |
| `IEC104_Net.h` / `IEC104_Net_Windows.c` | 通用网络接口及当前Windows实现:非阻塞监听/接入/收发、就绪等待、关闭及单调计时 |
| `IEC104.c/h` | 已恢复的旧单路逐字节接收入口,保留原有全局接收器及私有Link状态 |
| `IEC104_SendBuffer.c/h` | 唯一当前I帧、独立紧凑S/U队列、部分写入续传及本地发送期限 |
| `IEC104_AsduQueue.c/h` | 调用方字节缓冲的两级变长队列,HIGH满时拒绝、NORMAL覆盖最旧原文,支持显式重连恢复 |
| `IEC104_SendManager.c/h` | Connection内部的Link/SendBuffer修改入口:会话初始化、发送调度、控制收发、完成分派、ACK和回执,以及发送期限查询 |
| `IEC104_Link.c`、`IEC104_Link_Common.h` | 初始化、完整状态校验、I/S序号、k/w窗口、S确认、公共超时判定和TESTFR |
| `IEC104_Link_Master_StartStop.c/h` | 主站发STARTDT/STOPDT_ACT,收CON,处理等待超时 |
| `IEC104_Link_Slave_StartStop.c/h` | 子站收STARTDT/STOPDT_ACT,受理时更新启停状态,生成CON并处理停止排空及交错启停 |
| `IEC104_Link_Internal.h` | 三个实现文件共用的私有声明,不供业务调用 |
| `IEC104_Link.h` | 兼容总头文件,汇总公共、主站、子站接口 |
维护内部链路实现时,可按本端角色包含 `IEC104_Link_Master_StartStop.h` 或 `IEC104_Link_Slave_StartStop.h`,两者都包含公共接口。只处理I/S或TESTFR时包含 `IEC104_Link_Common.h`。旧内部代码可继续包含 `IEC104_Link.h`;模块发送完成接口统一以 `_Send` 结尾,该命名调整本身不改变参数和处理行为。改名不保留旧名兼容入口,内部调用方须同步更新名称并重新编译。
公共ASDU基础解析由 `IEC60870_Codec.c/h` 提供,业务需要解析公共头时包含 `IEC60870_Codec.h`;104的APCI检查和I/S/U编码由 `IEC104_Codec.c/h` 提供。Receiver分别调用两层:先检查APCI,再显式传入104参数调用 `IEC60870_Parse_ASDU_Header`。遇到非法帧头或截短的已知固定长度对象时返回FRAME错误,不推进序号或ACK,也不生成I_FRAME。未知/变长类型及具体字段继续由完整ASDU解析器和应用检查,边界见[基础设计](IEC104_设计架构.md#43-已知类型的最低载荷长度)。旧 `IEC104.c/h` 的全局接收入口保留原行为,不参与TcpServer路径。两个Codec均只依赖标准库及值类型,公共Codec不依赖104实现。
| 模块及构建依赖范围 | 生产源文件 |
|---|---|
| 101/104公共ASDU头解析 | `IEC60870_Codec.c` |
| 104 APCI与I/S/U编解码 | `IEC104_Codec.c` |
| ASDU信息对象编解码 | `IEC60870_Asdu.c`、`IEC60870_InformationObjects.c`、`IEC60870_Codec.c`、`IEC60870_Time.c`;C11及IEEE 754 binary32,不依赖TcpServer或Clock |
| 子站统一入口 | 在ASDU及TCP依赖之外增加`IEC60870_Slave.c`、`IEC104_Slave.c`;共用接口本身不依赖TCP或串口实现 |
| 104站/分组总召 | 在Slave及其依赖之外加入`104/business/IEC104_Interrogation.c`和`104/business/IEC104_GeneralInterrogation.c`,头文件搜索路径增加`104/business/`;应用按QOI选点表,响应NEED_DATA提交数据 |
| 104计数量召唤 | 引擎加`104/business/IEC104_CounterInterrogation.c`,头文件搜索路径增加`104/business/`;与总召分别创建,状态通知交付两边,动作通过Execute_Begin执行 |
| 104时钟同步 | Slave依赖加`104/business/IEC104_ClockSynchronization.c`,独立实例及静态池;只由Execute_Next执行同步action,模块不依赖Clock设备适配 |
| 101/104公共时间工具 | `IEC60870_Time.c`,对已有时间值进行日历校验、时间转换及编解码 |
| 101/104时间源:Windows系统时钟 | `IEC60870_Clock.c`、`IEC60870_Time.c`;`IEC60870_CLOCK_USE_RTC=0`(默认),Clock.c直接使用Windows的Kernel32接口 |
| 101/104时间源:RTC预留接口 | 上述两个源文件,定义`IEC60870_CLOCK_USE_RTC=1`,另需板级驱动实现`IEC60870_Clock_RTC_Read/Set`;具体芯片驱动暂不提供 |
| 独立子站发送缓冲 | `IEC104_Codec.c`、`IEC104_SendBuffer.c`;公共发送类型仍由Link公共头文件提供,无需链接Link实现 |
| 链路处理 | `IEC104_Codec.c`、`IEC104_Link.c`,再按所需启停接口加入主站/子站实现 |
| 子站发送管理 | `IEC104_SendManager.c`、`IEC104_AsduQueue.c`、`IEC104_SendBuffer.c`、`IEC104_Codec.c`、`IEC104_Link.c`、`IEC104_Link_Slave_StartStop.c` |
| 子站连接协调 | 上述子站发送管理源文件,加 `IEC104_Receiver.c`、`IEC104_Connection.c` 和 `IEC60870_Codec.c`;无需主站启停或日志实现 |
| Windows TCP子站模块 | 上述子站连接协调源文件,加 `IEC104_TcpServer.c`和`IEC104_Net_Windows.c`,应用工程链接`Ws2_32`;构建与接入见[TCP服务设计](IEC104_TcpServer_设计架构.md) |
| 独立流式接收 | `IEC104_Receiver.c`、`IEC104_Codec.c`、`IEC60870_Codec.c`;不依赖Link、SendManager或日志 |
| 旧单路逐字节接收 | `IEC104.c`、`IEC104_Codec.c`、`IEC104_Link.c`、`IEC104_Log.c` |
时间工具以`IEC60870_Time`作为公共入口,供101和104的ASDU业务层及平台接入层按需调用,不在Connection中自动执行校时。`IEC60870_InformationObjects.c`复用CP56Time2a处理带时标信息对象和命令;Type 103校验及确认使用独立ClockSynchronization模块,实际设时由应用显式执行。**新生成业务时标使用本地标准时间日历并设置SU=0;Type 103确认回显原CP56及SU。** 公共编解码继续支持SU=0和1,按输入保留标志,不强制或自动清零。生成新时标前须保证日历本身已是本地标准时间,不能只清除夏令时标志而保留原小时值。
时间源提供UTC纪元秒数时,直接调用`IEC60870_Time_Seconds_To_Local(utc_seconds, ms, &local_time)`即可取得固定UTC+8的本地年月日、时分秒、毫秒和星期,调用前后都无需手动加八小时。接口内部统一处理跨日/月/年及范围检查;原始UTC秒数上限为4102415999,超过时返回0并保留输出。RTC已直接提供本地标准时间日历时,可直接构造CP56解析值并编码。
当前时间直接通过`IEC60870_Clock_Read(&value)`取得,设置实际时钟调用`IEC60870_Clock_Set(&local_time)`,均使用固定UTC+8日历。**时间源范围仅限Windows系统时钟和RTC;`IEC60870_CLOCK_USE_RTC=0`默认使用Clock.c内置的Windows实现,`=1`调用Clock.h声明的`IEC60870_Clock_RTC_Read/Set`接口。RTC具体芯片驱动暂不实现。** 编译选项须作用于`IEC60870_Clock.c`,不规划其他操作系统适配。公共入口无需时钟对象或绑定初始化;以后接RTC时,硬件仍按驱动要求初始化,已有本地标准时间日历可直接填入,无需转换成时间戳再还原。读取结果分别表示日历和`is_invalid`,读取成功不等于时间有效;失败不修改输出。RTC的BCD格式、时间基准、毫秒来源及掉电状态由具体驱动处理。接入示例见[统一时间源读写](../common/IEC60870_Time_设计架构.md#统一时间源读写),业务待接入项见[当前接入状态](../common/IEC60870_Time_设计架构.md#当前接入状态与待补齐项)。
时间戳转日期保留两种实现:Windows默认调用CRT的64位`_gmtime64_s`;编译`IEC60870_Time.c`时定义`IEC60870_TIME_USE_PLATFORM=0`即可使用原有整数算法,其他平台默认采用此配置。配置在编译时生效,业务接口、UTC含义及1970..2099年的范围一致。此选项只决定如何转换传入的时间戳,与是否接入RTC无关;应用使用RTC作为时间源时,仍需通过相应驱动读取时间,再按返回值的格式和时间基准调用转换或编码接口。详见[实现选择](../common/IEC60870_Time_设计架构.md#时间戳转日期的实现选择)。
业务接收按`From_CP56 → CP56_To_Local`调用:原始解码保留源日历及IV/SU,转换接口返回本地标准时间年月日、时分秒、毫秒和星期。双方使用本地标准时间基准时,源标准时区参数传`IEC60870_LOCAL_UTC_OFFSET_MINUTES`(480):SU=0保持原时间,SU=1减一小时并处理跨日/月/年,IV=1则转换失败。其他源时区须传入其标准偏移,输出仍为本地标准时间;调用方无需再加八小时或重复扣除夏令时。接收SU=1的兼容处理与本地发送SU=0的约定分别生效。
日历范围为1970..2099年,CP56Time2a采用2000..2099年的世纪约定;接口以1/0表示成功/失败,失败保留输出。通用纪元秒数接口保留UTC语义,不能将本地标准时间日历直接当UTC使用。RTC读写仍由平台实现,Link和Connection的`now_ms`继续使用单调计时,不受校时影响。当前提供CP16经过时间、CP24短时标、CP56及日历工具。CP24仅含分钟、分钟内毫秒及IV,不能单独恢复小时和日期,需由业务结合已有时间基准解释。完整范围、星期和保留位策略见[时间工具设计](../common/IEC60870_Time_设计架构.md)。
Connection内部持有独立 `IEC104_Receiver_t`,先用非零连接代次调用 `IEC104_Receiver_Init`,再调用 `Feed(receiver, generation, data, length, &consumed)`。Feed最多收齐一帧,TcpServer保留未消费的输入尾部;`FRAME_READY`后由Connection通过 `Peek_Frame`取得APDU和APCI并分派。S/U受理后释放,I帧在TcpServer成功复制为事件后经Connection释放。帧未释放时Feed消费0字节,不覆盖原文;`Reset`丢弃当前半帧或完整帧,但不改变连接代次或Link状态。内部接口和迁移说明见 [编解码与接收器设计](IEC104_设计架构.md)。
接收器校验APCI格式和ASDU最低长度。Connection将I/S帧交给同连接的SendManager处理序号及ACK,并按功能分派U帧;WAIT时保留接收帧。Slave内部通过TcpServer_NextEvent读取I_FRAME副本,无需释放底层帧。连接重建由TcpServer先结束旧I/O并Close,随即Detach队列回到离线状态;新连接以新代次Rebind队列并Init连接;旧代次事件返回ERROR。
I 帧本地发送结果通过 `IEC104_Link_Complete_I_Send()` 提交,`Send` 明确限定为本地发送,成功不表示对端已经确认。同一次发送结果只提交一次。具体契约见 [链路设计第3.4.4节](IEC104_Link_设计架构.md#344-complete_i_send-的本地发送完成提交)。
发送完成接口如下,表中省略统一前缀 `IEC104_Link_`。它们报告最终发送结果,包括失败;返回 OK 表示本地发送结果已成功提交,是否仍需等待对端确认由对应状态决定。
| 接口 | 对应的本地发送结果 |
|---|---|
| `Complete_I_Send` | I 帧 |
| `Complete_S_Ack_Send` | S 确认帧 |
| `Complete_Startdt_Act_Send` | 本端主动发送的 STARTDT_ACT |
| `Complete_Startdt_Con_Send` | 本端应答的 STARTDT_CON;完成不回写启停状态 |
| `Complete_Stopdt_Act_Send` | 本端主动发送的 STOPDT_ACT |
| `Complete_Stopdt_Con_Send` | 本端应答的 STOPDT_CON;完成不回写启停状态 |
| `Complete_Testfr_Act_Send` | 本端主动发送的 TESTFR_ACT |
`Prepare_*` 负责准备报文或推进准备流程,`Handle_*` 负责处理接收事件;二者名称保持原有职责划分。收到 TESTFR_CON 使用 `Handle_Testfr_Con()`,不能用本地发送完成替代对端确认。
主动 TESTFR 使用 `IDLE → ACT_SEND_PENDING → CON_PENDING → IDLE` 三态,与控制站主动发起的 STARTDT/STOPDT 一致:ACT 完整发送后先调用 Complete,再处理对应 CON。ACT 尚未 Complete 时处理到的合法 TESTFR_CON 返回 IGNORED,不缓存;只有 CON_PENDING 接受确认。被动 TESTFR_ACT 仍独立生成 CON,应答对端请求不结束本端探测。
完整状态校验集中在 `IEC104_Link.c`,主站、子站的状态组合规则由该文件内的 `static` 函数检查。角色实现通过 `IEC104_Link_Internal.h` 调用公共辅助函数,公共链路模块不再反向调用角色实现。构建时包含公共链路及基础编解码实现,再按实际使用的启停接口加入对应角色 `.c`;同时使用两端接口时加入两个角色实现。
I/S的启停准入和停止阶段立即确认规则集中在 `IEC104_Link.c` 的私有判断函数中;I/S处理与规划通过这些判断继续执行序号、窗口及确认检查。I帧接收、I帧预留、S帧接收和普通S确认分别判断,保留各自的方向与阶段差异。子站在ACT受理时提交启停状态,S确认与CON发送完成分别维护各自的完成事实。具体规则见 [I/S与启停的内部边界](IEC104_Link_设计架构.md#16-is与启停的内部边界)。
启停和TESTFR在对应入口中直接检查状态、编码并提交;I/S帧保留序号规划。内部确认提交复用公开入口的状态校验,STOPDT直接返回各等待原因,不再经过私有计划对象和结果转换。
## ASDU信息对象模块
信息对象、ASDU容器、公共头解析及参数类型统一使用 `IEC60870_` 前缀,供101/104共用。旧信息对象/ASDU文件和符号直接迁移,不提供兼容头、宏或类型别名;调用方须更新包含路径、函数/类型名称和构建源文件并重新编译。104的APCI、链路、TCP及发送队列仍使用 `IEC104_` 前缀。
公共层仅需 `IEC60870_Asdu.c`、`IEC60870_InformationObjects.c`、`IEC60870_Codec.c`、`IEC60870_Time.c`;头文件依赖也不包含任何104模块。101接入提供约定的字段宽度和容量,104接入提供标准2/2/3及249字节上限。两种接入共用同一套对象构造和解析接口。
业务包含`IEC104_Slave.h`,取得`Slave_NextEvent`交付的I帧后可直接使用ASDU视图并解析具体对象,或先构造ASDU再交给发送接口。ASDU编解码层不分配内存、不操作连接、不读取或设置系统时钟;共用连接接口可构造并提交确认/终止应答。站/分组总召可交给IEC104_Interrogation管理校验、分批、撤销、期限和重试,应用响应业务事件提交数据,自行维护IOA、分组及遍历状态;其他命令的选择/执行、校时权限及业务任务由应用接入。
| 层次 | 职责 |
|---|---|
| `IEC60870_Codec.c/h` | 101/104共用的参数校验、ASDU公共头解析及已知类型最低载荷长度检查 |
| `IEC104_Codec.c/h` | 104专用APCI检查、I/S/U帧编码和帧类型 |
| `IEC60870_Asdu.c/h` | ASDU创建/添加/解析/取对象,维护Type ID、VSQ/SQ、IOA布局和容量,构造原文应答 |
| `IEC60870_InformationObjects.c/h` | 每种类型独立结构、Create和Get_From_Buffer;通过对象函数表编码,按Type ID选择具体解析器 |
| `IEC60870_Time.c/h` | CP16经过时间、CP24短时标及CP56日历的编解码、范围和保留位校验 |
| 能力 | 当前范围 |
|---|---|
| 监视对象编解码 | 1–21、30–40,共32种;含步位置、比特串、成组单点、CP24及保护事件;支持SQ=0/1 |
| 命令对象编解码 | 45–51、58–64、100–107,共22种;SQ=0、一个对象、精确长度 |
| 初始化结束 | 70;COI保留原因与本地参数改变标志;SQ=0、一个对象 |
| 参数对象编解码 | 110–113;QPM/QPA按独立限定词处理;允许多个对象但SQ必须为0 |
| 文件对象编解码 | 120–127;含变长文件段125与归档查询127;126文件目录支持多个对象及SQ,其余只允许一个非SQ对象 |
| 应答构造 | COT=7激活确认、9停止激活确认、10激活终止和44–47错误应答;P/N显式传入,否定激活确认使用7和1 |
上述共67种类型都有独立结构、构造和解析接口。安全扩展、厂家私有类型不在当前范围内。本层提供无状态报文编解码;站总召状态机由IEC104_Interrogation提供,参数生效、文件传输、文件读写及归档检索仍由业务接入。类型编号可在公共对象头文件的`IEC60870_AsduType_t`中查到。
应用层参数`IEC60870_AppLayerParameters_t`定义在`IEC60870_Types.h`:
| 字段 | 合法范围及含义 |
|---|---|
| `sizeOfTypeId`、`sizeOfVSQ` | 固定为1 |
| `sizeOfCOT` | 1或2;1字节时省略OA,解析OA为0 |
| `originatorAddress` | 0..255,供业务作为默认OA;构造以header中的显式OA为准 |
| `sizeOfCA` | 1或2;1字节配置拒绝大于255的公共地址 |
| `sizeOfIOA` | 1、2或3;IOA及SQ连续地址上限随宽度变化 |
| `maxSizeOfASDU` | 至少容纳公共头、最多254字节;104传输不得超过249字节 |
标准104包含 `IEC104_Types.h` 后使用`IEC104_APP_LAYER_PARAMETERS_DEFAULT`,即`{1,1,2,0,2,3,249}`。所有ASDU创建/解析入口必须显式传入非空参数。容器和解析视图借用参数,使用期间参数必须有效且不变。通用ASDU可复用到采用其他宽度的101接入,但本工程尚未提供101串口链路;Receiver、APCI、TcpServer和发送队列继续使用104布局及249字节上限。
每类对象通过自己的`Create`写入调用方提供的结构体,并绑定类型及只读编码函数表。例如单点用`IEC60870_SinglePointInformation_t`,双命令用`IEC60870_DoubleCommand_t`。普通监视和控制的带CP24/CP56对象用`base`保存基础对象、`time`保存时标,并复用基础值处理;保护事件则显式保存事件、QDP、CP16经过时间和时标。对象可按值复制,不需要销毁;业务可修改值或IOA,重新编码时仍会校验,类型和函数表不得手工修改。
容器调用顺序为`IEC60870_Asdu_Create → IEC60870_Asdu_Add_InformationObject → IEC60870_Asdu_Get_Data`。Create固定参数、SQ和公共头,首个成功添加的对象确定Type ID;后续对象必须同类型。SQ=1要求IOA连续且不越过所选宽度上限,SQ=0逐对象携带地址。Add成功后已经复制对象字节,可以立即复用对象存储。
容量取实际缓冲区与`maxSizeOfASDU`的较小值。空间不足、对象达到127个或单对象类型已加入一个对象时返回`IEC60870_ASDU_FULL`;业务提交当前非空ASDU后另起一条重试。空容器放不下首对象时须调整容量;文件数据须按可用长度分成更小的段。类型不匹配、SQ地址不连续或字段非法返回ERROR。所有失败保留容器、原文和输出参数,首对象失败不会提前设置Type ID。结果必须显式比较`IEC60870_ASDU_OK`,不可按布尔值判断。
业务包含 `IEC60870_Asdu.h`;本例使用104默认配置,还需包含 `IEC104_Types.h`。以下代码放入业务函数,`data`在原缓冲区未修改期间有效:
```c
uint8_t buffer[IEC104_MAX_ASDU_LEN];
const IEC60870_AppLayerParameters_t parameters = IEC104_APP_LAYER_PARAMETERS_DEFAULT;
IEC60870_Asdu_t asdu;
IEC60870_AsduHeader_t header = {
.cause_of_transmission = IEC60870_ASDU_COT_SPONTANEOUS,
.common_address = 1
};
IEC60870_SinglePointInformation_t point;
const uint8_t *data = NULL;
uint16_t length = 0;
IEC60870_AsduResult_t result =
IEC60870_SinglePointInformation_Create(&point, 100, 1, 0);
if (result == IEC60870_ASDU_OK) {
result = IEC60870_Asdu_Create(
&asdu, &parameters, buffer, sizeof(buffer), &header, 0);
}
if (result == IEC60870_ASDU_OK) {
result = IEC60870_Asdu_Add_InformationObject(&asdu, &point.object);
}
if (result == IEC60870_ASDU_OK) {
result = IEC60870_Asdu_Get_Data(&asdu, &data, &length);
}
/* OK时可将data/length交给Enqueue_Event;提交返回WAIT时保留原文重试。 */
```
监视和命令统一使用`IEC60870_Asdu_Parse`校验整条报文,再通过`IEC60870_Asdu_Get_Element`取得独立类型的对象。例如处理单命令:
```c
/* parameters、data、length对应收到的ASDU;处理期间原文保持有效。 */
IEC60870_AsduInfo_t info;
IEC60870_AsduResult_t status =
IEC60870_Asdu_Parse(&parameters, data, length, &info);
if (status == IEC60870_ASDU_OK && info.type_id == IEC60870_ASDU_C_SC_NA_1) {
IEC60870_SingleCommand_t command;
status = IEC60870_Asdu_Get_Element(&info, 0, &command, sizeof(command));
if (status == IEC60870_ASDU_OK) {
/* info保存COT/CA/OA;command.object.ioa、state、is_select、
* qualifier供业务判断地址、限定词、选择/执行及权限。 */
}
}
```
Get_Element输出无需预先Create,必须按`info.type_id`选择匹配的具体结构体并传入其尺寸;尺寸检查不能替代C类型匹配。解析视图借用原文和参数,取出的具体对象按值保存。只处理单个载荷时,可直接调用对应类型的`Get_From_Buffer`,传入已解析IOA及不含IOA的精确载荷;读命令载荷为0字节,允许NULL。
归一化值使用原始`int16_t`(实际值为原值/32768),标度值使用`int16_t`,短浮点保留IEEE 754 binary32位模式。累计量用`IEC60870_BinaryCounterReading_t`保存32位计数、5位序号及CY/CA/IV。对象层校验品质保留位、SCO、DCO/RCO状态、VTI有符号范围、保护事件QDP和CP24/CP56;COT、CA、IOA及限定词的业务适用性由应用判断。
`Build_Response(&parameters, request, length, cause, is_negative, out, capacity, &out_length)`仍以`IEC60870_Asdu_`为前缀。它复制请求,只替换COT/P/N,保留TEST、存在时的OA、CA、VSQ及全部对象原文,支持原地和部分重叠。它仅作公共头及最低长度检查,可回显未知类型。生成后携带原请求generation调用Send_Response,并处理WAIT/ERROR/FATAL。
`IEC60870_Asdu_Create_From_Buffer(&asdu, &parameters, buffer, length)`直接借用可写原文,建立可修改的ASDU对象。它只做公共头及最低长度检查,未知类型也能建立对象,用于COT=44等错误应答;执行业务前仍须使用完整Parse和业务规则校验。借用对象不能Add,`Set_COT`、`Set_Negative`、`Set_CA`原地修改相应字段;Get_Data可以导出原文。Create创建的构造容器也可使用这三个设置接口,空构造容器仍不能导出。Set_CA按COT宽度定位、CA宽度写入,1字节仅允许0..255,2字节允许0..65535;非法容器或地址溢出返回ERROR且不修改原文,业务地址限制仍由业务层判断。ASDU结构新增来源标志,调用方须一起重新编译。
### 文件段和新增时间格式
`IEC60870_FileSegment_t`含255字节的数据数组。Create和Get_From_Buffer把有效数据复制进对象,调用结束后即可复用输入;对象无需销毁。它的线上载荷为`NOF(2)+NOS(1)+LOS(1)+数据(LOS)`,解析精确检查LOS与报文长度,不接受截短和多余尾字节。
先用`IEC60870_FileSegment_Get_Max_Data_Size(parameters)`计算当前配置允许的数据长度。默认104配置返回236;最短101头、1字节IOA、254字节上限时返回245。返回0表示只能容纳空段,-1表示配置非法或连空段都装不下。Create允许0..255字节,实际加入ASDU时仍检查总长;超过容量返回FULL,调用方负责分段。
`IEC60870_Time_To_CP16/From_CP16`处理0..65535毫秒的经过时间。`IEC60870_Time_To_CP24/From_CP24`处理分钟0..59、分钟内毫秒0..59999和IV;bit6是保留位,CP24没有SU、小时或日期。CP24编解码保留IV,不自动推断完整日历。所有接口均沿用成功1、失败0且保留输出的约定。
### 子站统一入口
业务包含`IEC104_Slave.h`,持有一个不透明的`IEC104_Slave_t *`。Slave内部创建、驱动和销毁TcpServer;配置、调度、状态和结果仍复用`IEC104_TcpTypes.h`中的值类型,业务头文件不引入TcpServer操作接口或内部布局。
生命周期为`IEC104_Slave_Create → Config_Default/Init → Prepare/Process或Poll → Close → NextEvent读空 → Destroy`。所有操作在同一事件循环线程串行执行。静态池容量沿用`IEC104_TCP_SERVER_CAPACITY`,与直接使用TcpServer共享底层名额,无动态分配。创建失败返回NULL;其他生命周期接口显式比较`IEC104_TCP_OK`。
`IEC104_Slave_NextEvent(slave, &event)`按原FIFO交付`IEC104_SlaveEvent_t`:`event.transport`是TCP事件副本;I_FRAME且`event.asdu_result == IEC60870_ASDU_OK`时,`event.asdu`已经借用事件自身的ASDU字节,`event.connection`已经绑定原服务实例及原连接代次。业务不再传入server/generation,也不再手工Create_From_Buffer。字段/地址/命令权限仍由业务校验,未知类型可以原文交付,视图创建成功不等于允许执行命令。
普通循环使用以下顺序;Application_Handle_Event为应用自己的同步处理函数,其中可以提交应答或复制事件到延迟任务:
```c
IEC104_TcpResult_t result = IEC104_Slave_Poll(slave, 10, NULL);
if (result == IEC104_TCP_OK) {
IEC104_SlaveEvent_t event;
IEC104_TcpEventResult_t next;
while ((next = IEC104_Slave_NextEvent(slave, &event)) == IEC104_TCP_EVENT_READY) {
Application_Handle_Event(slave, &event);
}
/* next为ERROR时处理内部读取错误;EMPTY表示本轮事件已读空。 */
}
```
外部事件循环使用Slave_Prepare/Process,继续保留原service_token和socket token;pending_event_count或need_process非零时先处理本地工作。主动上报通过`IEC104_Slave_Get_Application_Layer_Parameters`取得参数构造ASDU,再调用`IEC104_Slave_Enqueue_Event(slave, &asdu)`进入NORMAL。关闭单连接传原事件给`IEC104_Slave_Close_Connection(slave, &event, error)`,库内部使用该事件的原代次。
### 共用连接上的激活确认和激活终止
共用接口`IEC60870_MasterConnection_t`继续供101/104业务复用;当前104的接口由Slave_NextEvent自动安装,101串口后端仍未提供。下例放在业务已验证请求并决定肯定确认的分支,event为地址稳定的Slave事件:
```c
if (event.transport.type == IEC104_TCP_EVENT_I_FRAME &&
event.asdu_result == IEC60870_ASDU_OK) {
bool accepted = IEC60870_MasterConnection_Send_ACT_CON(
&event.connection, &event.asdu, false);
if (!accepted) {
IEC104_TcpSubmitResult_t submit =
IEC104_Slave_Get_Last_Submit_Result(&event.connection);
/* 按下表处理submit;WAIT需要保留事件及原文,不能忽略或盲目重发。 */
(void)submit;
}
}
```
| 共用操作 | 行为 |
|---|---|
| Send_ASDU | 提交给定ASDU对象的当前原文,也可提交业务另外构造的数据ASDU |
| Send_ACT_CON | 原地设置COT=7及指定P/N,然后提交 |
| Send_ACT_TERM | 原地设置COT=10、P/N=0,然后提交 |
| Get_Application_Layer_Parameters | 返回该连接的标准104只读参数,最大249字节 |
确认及终止先修改事件副本的字节再发送,失败也不回滚;TEST/OA/CA/VSQ和对象原文保留。需要原请求内容时,在修改前保存副本。
| 详细结果 | 布尔返回 | 业务处理 |
|---|---|---|
| OK | true | 已复制到发送缓冲或HIGH,可复用发送原文;不代表已写完或已ACK,不重复提交 |
| WAIT | false | 本次未接手;保留已修改的ASDU及原事件,待容量恢复后重试 |
| ERROR | false | 参数、布局、旧代次或调用阶段非法,不能按容量等待盲目重试 |
| FATAL | false | 发送路径故障,可能已写出字节;结合RECORD/DISCONNECTED处理 |
事件含有指向自身的ASDU视图和连接上下文,不能用赋值或memcpy搬到另一地址。延迟任务可让NextEvent直接写入自身稳定存储,或调用`IEC104_Slave_Copy_Event(&task.event, &event)`;复制时同时保存字节、重建自引用,并保留原服务实例和原连接代次。源事件随后可被下一次NextEvent覆盖,任务副本仍独立可用;复制不代表需要重发已经OK的报文。多个任务的事件存储由应用提供,库不额外引入待办任务池。
总召内部使用紧凑存储:只保留`Get_Event_Identity`取得的原身份及10字节请求ASDU,按需建立视图,通过`Slave_Send_Response / Slave_Try_Send_Response`应答,关闭原连接用`Slave_Close_Connection_By_Identity`。任务槽、事件队列和发送容量保持不变,内存测量见[固定存储](IEC104_Interrogation_设计架构.md#2-对象身份与固定存储)。其他需要完整事件的业务仍可用Copy_Event。
NextEvent返回EMPTY/ERROR时保持输出不变。Close、重连、重新Init或Destroy后复用服务槽,都不会把旧任务改绑到新连接;发送继续检查原身份。Destroy成功后旧服务句柄失效,但旧事件的字节仍由任务自身保存。所有延迟任务也在所属事件循环串行提交。
多帧总召的数据和终止应经同一事件的connection依次提交,逐帧处理WAIT;把数据放NORMAL而终止放HIGH会造成优先级越序。门面不实现点表、总召状态机、遥控选择/执行或系统校时。
[子站示例](../../examples/iec104_slave_example.c)通过BEGIN/NEED_DATA/FINISHED事件与显式应答接入独立的[总召模块](../../104/business/IEC104_Interrogation.h)推进业务;Slave和TcpServer继续负责服务、连接及传输。总召接入顺序见[完整调用流程](IEC104_完整调用流程.md#flow-interrogation)。
调用`IEC104_Interrogation_Process(gi)`自动推进当前就绪任务,无需传入预算。每个实例至多一个未终结总召,包含等待生成BEGIN的请求;忙时相同和不同QOI的新激活均否定,不保存后续总召。4个任务槽共用于这个总召和待发短应答。Handle_Event在原会话有效、Slave通知已读空且无更早REPLY时尝试立即提交短应答,未接手再保存。满槽时尝试否定确认;不能安全提交/保存则仅丢新请求并累计dropped_requests,保留当前任务及TCP。Process在空闲、等待应用/事件空位、发送WAIT或Slave通知未读空时返回。对象、状态、调度及接入约定见[总召模块设计](IEC104_Interrogation_设计架构.md)。
总召Get_Status的`need_process`用于决定是否立即续跑,不能从`waiting`取反推断。应答或读取业务事件后重新查询;发送WAIT后等待网络推进再重试。每次Slave_Poll/Process及Slave通知处理结束仍须推进总召,即使need_process为false。外部事件循环同时合并Slave_Prepare的调度条件;新增状态字段后调用方须重新编译。
BEGIN由调用者判断是否接受,遍历状态可延至首个NEED_DATA建立;NEED_DATA由调用者选择本批IOA并读取当前值和品质,协议库不登记或冻结点表。Submit_Batch立即尝试不排队提交,WAIT不保存数据、不推进游标,应用在网络推进后重新取当前值重试;OK才固定帧顺序并推进批次。点值更新及突发发布须与总召读值及提交串行化,持续突发可能推迟总召,详见[数据批次与发送路径](IEC104_Interrogation_设计架构.md#6-数据批次与发送路径)。
BEGIN携带实际CA、station_id和QOI=20..36;应用检查数据源并决定接受,首个NEED_DATA才需建立取数游标。多目标广播先完成全部BEGIN/ACT_CON,再逐站取数,最后全部ACT_TERM;每站状态区保证FINISHED无损交付。Submit_Batch只接受事件目标CA。新增/替代站下轮参加,尚未选入BEGIN便删除的站跳过;已经选中尤其已确认的原站必须完成或明确终结。各站独立计时,总期限默认关闭;FINISHING的终结事件读完前仍忙拒绝新激活。详见[总召设计](IEC104_Interrogation_设计架构.md#33-广播地址与本站地址)。
主站COT=8按原连接、目标CA/OA/TEST/QOI匹配总召,包括已确认但尚未取数或等终止的站。定向撤销匹配站,其他站继续;广播撤销停止整轮,对各仍活动的站回肯定COT=9。FINISHED(DEACTIVATED)通知应用清理,匹配站旧批次失效。已被发送层接手的帧仍按顺序发送,撤销不补发成功ACT_TERM。
业务接受和每批取数期限默认各15秒,执行整体期限默认0(禁用),各项均可单独配置;这些是业务默认策略,不是标准规定的总召时限。关闭整体期限允许慢链路累计传输超过原60秒上限,底层单帧发送、确认和链路探测期限仍有效。BEGIN生成时启动已启用的业务期限,此前等待业务事件空位没有独立超时,但已占用总召资格,应及时读取FINISHED。总期限显式设为非零后仍按固定整体耗时计算,不因新批次或发送重试而延长。START/CONFIRM超时及BEGIN阶段Fail_Request复用原槽发送否定ACT_CON,保留TCP及其他短应答;肯定ACT_CON被发送层接手后,取数超时、总超时和数据源失败仍关闭原连接。终结事件保留具体原因,BEGIN未取出则只移除工作事件。接受BEGIN前检查数据源及必要业务资源,仍可逐批取值并编码。等待前查询timer_active/timeout_remaining_ms并持续驱动Process。此次失败处理修复不新增接口或配置开关;先前已移除queue_timeout_ms及多总召排队状态/统计,保留negative_submitted和dropped_requests,使用旧字段的调用方须调整并重新编译。
原`IEC104_SlaveConnection_Init`和手动接入对象已移除,调用方改用Slave服务及其事件接口并重新编译。TCP底层接口仍供独立通信接入和维护测试使用,业务的默认入口统一为Slave。
本次接口直接替换为独立对象与统一ASDU入口,删除旧通用监视/命令联合体及分类解析、Builder接口,不提供兼容包装;调用方须按上述示例迁移并重新编译。构建须新增`IEC60870_InformationObjects.c`。
时标保留IV/SU;IV=1可解码但不代表可校时。业务新上报应提供本地标准时间且SU=0,应答回显保留请求时标。验证命令和覆盖范围见[测试说明](../test/IEC104测试文档.md)。
### 时钟同步业务
[ClockSynchronization](../../104/business/IEC104_ClockSynchronization.h)处理Type 103、COT=6、IOA=0,按共用站点表路由;COT=5读时和COT=8撤销回45。独立静态池默认与TCP服务容量相同,每实例4个任务槽,与总召/计数量分别创建、分别取消。Handle_Event校验保存,Process处理期限及FIFO应答,只有应用显式Execute_Next会调用本次传入的同步action,不保存函数指针。
默认源标准时区480分钟、执行期限15000ms,0禁用期限;IV/SU及时区由公共时间工具处理,64位毫秒计算只补偿受理后的站内滞留。action收到的local_time已经是固定UTC+8,base_ms为执行检查时刻。肯定/否定确认保留原CP56字节,不回读时钟或提供自定义确认时标。
调用过action的确认走Try,错误校验应答走普通HIGH;WAIT只重试确认,STOP取消未交接任务但不回滚时钟。广播动作一次,快照目标分别确认;满槽丢新并计数,不断链。同内容的新请求仍执行,可能再次回拨。持续NORMAL发布可能推迟Try确认,应用通过包含回调执行期的confirm_pending串行协调新的带时标上报。默认示例只设模拟时钟,`--clock system`才调用Windows时间源。完整契约见[时钟同步设计](IEC104_ClockSynchronization_设计架构.md)和[调用流程](IEC104_完整调用流程.md#flow-clock-synchronization)。
## 启停主流程
| 角色与过程 | 调用顺序 |
|---|---|
| 主站启动 | `Prepare_Startdt_Act` → 实际发送 → `Complete_Startdt_Act_Send` → 收CON → `Handle_Startdt_Con` |
| 主站停止 | `Request_Stopdt` → `Prepare_Stopdt_Request` → 依次发送S/ACT并提交完成 → 收CON → `Handle_Stopdt_Con` |
| 子站启动 | 收ACT → `Handle_Startdt_Act`(立即STARTED/IDLE)→ 发送CON → `Complete_Startdt_Con_Send` |
| 子站停止 | 收ACT → `Handle_Stopdt_Act`(立即STOPPED/STOP_DRAINING)→ `Prepare_Stopdt_Response` → 按需发送S、等待I帧确认 → 发送CON → `Complete_Stopdt_Con_Send` |
上表省略统一前缀 `IEC104_Link_`。只有具体接口返回值表明已生成报文时,才将本次输出交给发送层;生成不等于已发送。部分 Handle 只受理请求或提交对端确认,例如 `Handle_Stopdt_Act` 不生成应答,后续由 `Prepare_Stopdt_Response` 推进。S帧完成交给 `Complete_S_Ack_Send`。被控站不暂存相反方向ACT;停止等待期间成功受理START即恢复STARTED/IDLE,结束尚未生成STOPDT_CON的停止等待。
正常控制流程应串行执行启停,例如 `STOPDT_ACT → STOPDT_CON → STARTDT_ACT → STARTDT_CON`。主站的忙或重复请求结果不表示可以再次发送ACT。子站交错请求按实际受理顺序改变状态:START激活,STOP停用。已经生成的CON始终按FIFO发送,后到请求不撤回旧CON,旧CON完成也不覆盖后到ACT已经提交的状态。具体语义见 [链路设计第4.2节](IEC104_Link_设计架构.md#42-被控站受理启动)。
被控站成功受理STARTDT_ACT时立即进入STARTED/IDLE,并生成STARTDT_CON。首个CON尚未Complete时,后续每个成功受理的重复START也生成一帧CON;同状态重复请求不再次产生激活通知。所有CON按FIFO发送,Complete只确认对应发送结果,不重新提交启停状态。首个STARTDT_CON尚未完成也能受理STOP,立即停用并进入STOP_DRAINING。具体分支见 [链路设计第4.2节](IEC104_Link_设计架构.md#42-被控站受理启动)。
## 子站发送模块(已实现)
三个模块采用变长业务队列、发送前编号和独立确认记录组织,HIGH满时拒绝、NORMAL覆盖最旧原文,同时支持无malloc、部分写入续传、本地发送期限、严格启停/TESTFR、逐帧回执及可配置防饿死配额。
ASDU队列的状态以业务条目为单位:`unsubmitted_*` 表示队列尚未登记发送交接的待发条目。操作顺序是 **SendBuffer接手完整I帧 → Manager建立发送记录 → Mark_Submitted完成队列记账**。最后一步执行前,队列仍保留待发旧状态,不能据此判断SendBuffer是否已经接手。这里的“已提交”不表示整帧已写完或对端已ACK。
HIGH在完成交接记账时消费队列原文,SendBuffer中的完整I帧及Manager记录继续有效;NORMAL则保留原文等待ACK。`retained_unacked_count` 统计原文仍保留、已完成交接记账且待确认的ASDU条目,HIGH恒为0;`overwritten_unacked_count` 统计NORMAL原文已覆盖、仍待确认的条目。全部已编号未ACK的I帧数等于Manager的 `high_unacked_count` 加NORMAL保留及覆盖待确认数。`is_storage_empty` 只表示ASDU原文环为空,HIGH和NORMAL仍可能有对应I帧待确认;SendBuffer的 `is_idle` 表示当前无帧和预留。接口和行为变化见 [发送模块接口迁移](IEC104_发送模块_设计架构.md#migration),调用方须同步迁移、重新编译并初始化。
- **AsduQueue**:HIGH/NORMAL各用一个调用方提供的字节数组。两级使用不同条目头:HIGH仅存2字节长度;NORMAL存条目编号、状态及长度,头大小为 `sizeof(IEC104_AsduNormalEntryHeader_t)`,当前Windows 64位GCC下为16字节。条目恰好占本级头长加ASDU实际长度,头和原文均可跨尾部回绕,无额外回绕填充。两级都不保存user_tag,只有NORMAL分配条目编号。未提交条目通过待发游标直接定位。HIGH空间不足返回FULL,提交后立即释放原文;NORMAL保留原文到有效ACK,空间不足时覆盖最旧原文,包括已提交未ACK条目,成功返回OK且无逐条丢弃通知。条目超过目标桶总容量返回ERROR,须修正容量或组帧,不清空旧数据。
- **SendBuffer**:结构内只存一份255字节当前I帧,另用调用方提供的 `IEC104_SendBufferControlFrame_t[]` 保存S/U,每槽APDU仅6字节。当前帧连续写完;控制队列排在下一未编号业务之前。取消了APDU节点池、控制预留量和重复的协议序号边界。
- **SendManager**:Connection在准备实际写socket时调用 `Prepare_Next_Send`,无当前帧才重新选业务并分配N(S)。重复调用只返回当前帧剩余部分,最多一帧I尚未本地完成。实际写入后用 `Handle_Send_Progress`;解析后的I/S用 `Handle_I_S_Frame`。有效ACK更新所有对应发送记录;HIGH只核减Manager的未确认计数,NORMAL释放仍保留的原文或核减覆盖待确认数。确认记录由TcpServer复制为RECORD事件后经Connection移除,业务稍后处理事件副本。原文出队或覆盖不撤回当前帧、不释放k窗口,也不重置期限。
业务入口为Slave;其下的TCP及发送内部调用主线为:
```text
主动上报:TcpServer_Enqueue_Event → 服务ASDU队列(首次连接前、断线期间均可缓存)
连接应答:TcpServer_Send_Response → Connection_Submit_Response → Manager.Submit_Response(直接准备或缓存HIGH)
总召数据:TcpServer_Try_Send_Response → Connection_Try_Submit_Response → Manager.Try_Submit_Response(只能直接准备,不能排队则WAIT)
内部发送:Connection经Manager准备字节 → TcpServer经Net写socket → Connection回报Manager进度
内部接收:TcpServer经Net收字节 → Connection经Receiver成帧、由Manager统一提交链路事件
事件交付:TcpServer复制I帧/回执到事件队列并释放内部资源 → 业务通过NextEvent取副本
```
内部模块读取AsduQueue时,`AsduHeadInfo` 通过 `asdu_first/asdu_first_length` 和可选的 `asdu_second` 返回原文,`asdu_length` 是总长度;需要连续副本可用 `Copy_Asdu`。HIGH的 `entry_id.entry_serial` 恒为0,仅核对当前代次;从Peek到Mark/Discard之间不得移除、清空或替换队首,0编号不能当作可长期保存的条目身份。HIGH提交或清空后、NORMAL原文被覆盖或ACK释放后,对应借用立即失效。Manager已处理跨界原文,传输层取得的APDU仍连续。每级需同时保留N条、ASDU最长L字节时,HIGH配置 `N × (2 + L)`,NORMAL配置 `N × (IEC104_ASDU_NORMAL_ENTRY_HEADER_LEN + L)`,无需另留回绕空隙;HIGH的N只计待发条目,NORMAL的N还包括原文仍保留的未ACK条目。Manager的构帧函数另使用249字节局部拼接数组,需计入栈预算。
仅NORMAL使用64位非零循环条目编号:`UINT64_MAX → 1`,回绕不改变连接代次,也不清空队列。先后顺序按编号环距离判断;NORMAL保留条目及覆盖待ACK区间不能跨越半个编号环,旧记录阻止窗口前进时NORMAL入队返回FULL,处理旧条目或ACK后可重试,HIGH不受该编号窗口阻塞。NORMAL条目释放后身份失效,调用方不得保存旧身份跨完整编号周期再次使用。NORMAL头内状态在Mark时改为已提交,Rebind时恢复未提交;接口说明见[发送模块设计](IEC104_发送模块_设计架构.md#aq-functions)。
`Prepare_Next_Send` 的成功值是 **OK**;`Submit_Response`以OK表示直接准备、QUEUED表示已缓存HIGH;控制帧入队成功仍为QUEUED,不能按布尔值判断。两条I帧路径共用组帧和发送记录,直接应答不经过ASDU队列,也不绕过旧HIGH、当前帧、窗口或公平配额。TcpServer的`Send_Response`最多尝试一次非阻塞写入;EAGAIN保留当前帧和期限,部分写入不能交错其他APDU。当前I帧已经准备后,即使暂时写出0字节,也要先完成,再发后来排队的控制帧。
`Try_Submit_Response`还要求NORMAL没有未提交条目;无发送机会时只返回WAIT,不降级为HIGH排队。Slave提供事件连接入口`Try_Send_ASDU`和纯值身份入口`Try_Send_Response`;总召使用后者,WAIT后重读数据。它们仍通过原SendBuffer、发送记录、k窗口和链路期限,不要求等待所有已提交帧的ACK。已有普通应答和主动上报接口的排队语义不变。
业务提交统一返回`IEC104_TcpSubmitResult_t`:`IEC104_TCP_SUBMIT_OK`表示已接手ASDU,不保证已写完或已ACK;WAIT表示未接手,业务保留重试;FATAL可能发生在已写出字节后,须处理收尾事件。`Enqueue_Event`只缓存服务事件,`Send_Response`尝试直接发送或缓存连接应答;调用后重新Prepare刷新调度条件。旧Enqueue_Normal/Enqueue_High入口与TCP_ENQUEUE结果名已移除,不保留兼容包装。
子站受理STARTDT_ACT即进入STARTED,STARTDT_CON作为发送任务按FIFO完成。STOPDT受理即停用并停止选取新业务,最多完成一帧此前已编号的当前I帧,等待已发帧确认后返回CON;未提交的NORMAL保留未编号,HIGH按下述规则清理。公共S、t2、TESTFR、t3及子站启停继续由Manager封装。接收接口的WAIT表示请求尚未受理,接入方须有界保留原帧并按接收顺序重试。
Manager初始化成功会清空HIGH待发原文并重置高优先配额;新STOP受理时清空HIGH。从停用状态受理START时,生成本轮首个STARTDT_CON并清空HIGH、重置高优先配额;已激活状态下的重复START仅追加CON,保留HIGH和配额。WAIT时请求尚未受理,不清理HIGH。以上清理均不影响NORMAL,也不撤销已提交的当前I帧及其发送记录。
初始化使用字节容量和控制槽数组。此次移除 `Enqueue` 的最后一个user_tag参数,以及条目查询、发送存储记录和记录查询中的user_tag字段;旧调用方须迁移、重新编译并初始化。HIGH发送记录的 `asdu_entry_serial` 恒为0,NORMAL继续保存条目编号,两级都用独立frame_id处理发送完成和帧回执。发送记录数组使用 `IEC104_IFrameSendRecordStorage_t`,连接代次由Manager统一保存;查询输出用 `IEC104_IFrameSendRecord_t`,返回完整 `frame_id`。当前Windows 64位GCC下,移除user_tag后每条存储记录由56字节降为48字节,查询快照由64字节降为56字节:
```c
static IEC104_IFrameSendRecordStorage_t records[12];
IEC104_AsduQueue_Init(&queue, high_bytes, sizeof high_bytes,
normal_bytes, sizeof normal_bytes, generation);
IEC104_SendBuffer_Init(&buffer, control_frames, control_count, generation);
IEC104_SendManager_Init(&manager, &queue, &buffer, &link,
records, 12, k, high_burst_limit);
```
以上省略返回值检查,完整示例、接口替换及容量单位见 [发送模块设计](IEC104_发送模块_设计架构.md#integration) 和 [接口迁移](IEC104_发送模块_设计架构.md#migration)。Link须先按CONTROLLED初始化。Manager允许绑定有未编号业务的队列,绑定成功会清空HIGH、保留NORMAL,不接管运行中的旧连接。
`Manager.Abort` 保留AsduQueue;结束旧I/O并核对记录中的ACK事实后,TcpServer调用 `AsduQueue.Detach` 解除绑定,清空HIGH并恢复NORMAL离线缓存;新连接再 `AsduQueue.Rebind` 到新代次并初始化。**HIGH固定用于当前连接的请求应答,重连清空;NORMAL固定用于允许跨连接恢复的事件,保留现存原文并恢复未提交。** 内部队列不提供逐条重连策略,使用 `Enqueue(queue, generation, priority, asdu, length)`;业务只调用TcpServer的Enqueue_Event/Send_Response。Rebind先完整检查两级条目,再将NORMAL头内已提交状态恢复为未提交并更新控制字段,不搬移ASDU原文,不使用整理数组。NORMAL头含编译器位域及对齐,必须按对应头长宏配置容量,不能沿用旧18字节头的缓冲内容或跨ABI解释。使用约定见 [队列生命周期](IEC104_发送模块_设计架构.md#aq-reconnect-policy)。
Rebind清除旧覆盖待确认计数,所有旧身份和借用失效;已覆盖原文不能恢复。它本身不发送,新连接仍须完成STARTDT;同一TCP上的STOPDT/STARTDT恢复不调用Rebind。未ACK不证明对端未收到,NORMAL只用于业务允许向同一接收方或冗余域恢复的事件;旧请求应答应放HIGH。关闭整个服务时由TcpServer调用Queue.Abort清空缓存,不提供掉电持久化。未编号条目被覆盖或重连丢弃时没有帧回执,旧帧回执须在Manager.Abort前读取;尚不提供冗余组切换或应用业务去重。
Connection通过`SendManager_Get_Deadlines`一次取得当前队首身份、本地发送及I帧t1剩余时间、控制槽容量;对应活动标志为1且剩余时间为0表示到期。原始queued_at_ms仍保存在SendBuffer,written_at_ms仍保存在Manager记录,部分ACK后选下一条的原始时刻。Connection的`Collect_Deadlines`汇合TESTFR、STOP、t2及t3,供超时检查、发送准入、控制推进和等待查询共用;不创建系统定时器,也不缓存第二份计时起点。原有底层单项超时接口保留。TcpServer在Process中执行TCP读写并驱动Connection,Poll复用该推进核心。
发送准备和写入回报仅因本地发送及STOP期限直接报告超时;ACK/TESTFR的t1故障交给接收阶段判定。旧确认t1已到时,统一发送准备入口暂停为HIGH/NORMAL创建、编号新I帧;已有帧及控制发送仍可推进,避免控制槽解阻后继续新增业务帧。有效确认解除所有已到期等待后自动恢复准入。Send_Response和常规发送仍按send后的真实时刻登记完成,发送期间跨过确认期限时安排立即Process,先有界处理已到达的确认,再按原始t1检查。Prepare对到期协议期限返回零等待;不增加恢复期限或固定宽限时间,也不改变真实容量背压下的超时策略。
## 子站连接协调层(已实现)
TcpServer内部的`IEC104_Connection_t`内含一个Receiver、一个Link、一个SendBuffer和一个SendManager,借用TcpServer提供的ASDU队列、控制槽数组及发送记录数组。初始化后保持对象地址不变,同一连接的所有调用串行执行。内部接口、时间规则及重连顺序见[连接层设计](IEC104_Connection_设计架构.md)。
Connection_Init先准备Receiver及配置,再由`SendManager_Init_Connection`校验并向最终地址提交Link、SendBuffer和绑定关系,最后提交其余连接字段;失败保留原Connection和队列。
控制帧是否可准备由Link的`Can_Prepare_*`只读接口判断,并与实际构帧共用规则。Connection对Link保留只读访问,运行期修改统一经SendManager,TESTFR_CON也经`SendManager_Handle_Testfr_Con`提交;只有返回OK才撤销本端探测t1,IGNORED不取消计时。Connection不直接查询SendBuffer,也不操作Manager的内部指针。Connection及SendManager的完整结构体供内部静态嵌入;TcpServer公开头文件隐藏这些布局,业务只使用TCP句柄、公开值类型及事件接口。
以下步骤均在TcpServer及Connection内部执行:
1. `Connection_Init`以CONTROLLED角色初始化STOPPED链路。成功受理STARTDT_ACT即进入STARTED/IDLE并开放I帧准入,发送队列保证已有CON先于随后准备的本端I帧写出。
2. 收到TCP字节后调用`Connection_Feed`,按`consumed_length`推进输入。一次最多处理一帧;未消费尾部由TcpServer保留。半帧留在Receiver中;S/U受理后自动释放;I帧返回FRAME_READY后由TcpServer经Peek复制为事件,再按`receive_serial`显式Release。
3. WAIT表示当前接收请求尚未受理,Connection保留原文并在后续驱动中重试。成功受理的START/STOP按控制帧路径自动释放原帧;重复驱动不会再次提交同一I帧的序号或ACK。
4. `Connection_Prepare_Next_Send == SEND_READY`时取剩余字节实际写入,再用`Handle_Send_Progress`回报增量;0字节和部分写入保留当前帧及原期限。整帧完成自动提交对应Link完成和Manager记录,不能另调底层Complete。本地已知发送完成必须先回报,再Feed覆盖该帧的ACK。
5. 定期调用`Connection_Tick`推进本地发送期限、I帧/TESTFR的t1、w/t2确认、t3探测和STOP总期限。停止过程中的重复STOP和WAIT不延长原期限;START成功受理取消旧STOP总计时。TESTFR等待CON的t1不因其他链路活动续期。t2保留连续未确认接收区间的最早起点,前缀被确认时不续期。
6. FATAL后连接冻结,TcpServer停止真实I/O,把剩余记录和断开通知复制为事件,再调用Connection_Close。Connection_Close保留内部ASDU队列;TcpServer随后Queue.Detach清空HIGH并保留NORMAL,离线期间继续接受NORMAL;重连时Queue.Rebind到新代次,再Connection.Init。仅Close服务清空全部ASDU。所有旧代次事件返回ERROR,不修改新连接。业务只处理TcpServer交付的事件并执行ASDU业务逻辑。
旧 `IEC104_Rx_Feed_Byte`、`IEC104_Rx_Reset`、`IEC104_Legacy_Link_Reset`及相关类型保持原样;旧入口继续使用全局单路状态、预设STARTED,并在成帧后检查I/S序号,只返回接收结果。Connection使用新Receiver并共享自身Link与SendManager,不调用旧全局接收入口。同一条连接不能同时交给这两条接收路径。
因接口过期而无法编译的旧回归测试及专用辅助文件已删除。当前有`iec104_tcp_event_ring_test.c`的13个字节环场景、`iec104_tcp_scheduler_test.c`的25个调度场景,以及`iec104_net_pending_input_test.c`的Windows回环检查;构建和运行见[测试说明](../test/IEC104测试文档.md#2-编译与运行)。
2026-10-20调度修复:预算让出时固定已到达输入范围并立即续跑,处理完后再判定ACK/TESTFR超时;后续新输入不能扩大旧批次。发送使用独立预算,持续接收不再跳过发送阶段。业务API及配置宏不变,内部Connection和Net新增续收/输入快照支持,自定义Net后端需实现`IEC104_Net_Pending_Input`。真正容量背压仍遵守原有严格期限;回执与启停通知的顺序继续按B方案。
以下为历史变更与验证记录,不代表当前保留的测试范围:
2026-09-23:NORMAL空间不足时改为覆盖最旧原文(含已提交未ACK条目),HIGH继续满时拒绝;当前APDU和发送记录独立保留,ACK兼容原文已覆盖。条目支持跨尾部存放,无填充碎片。仅更新代码和设计文档,测试文件保持原样。
2026-09-23:三发送模块改为变长ASDU字节环、单当前I帧和紧凑控制队列,发送前编号,有效ACK释放原文,业务回执独立消费,支持显式Rebind。保留ACK不得越过本地完成位置的修复。原有全部119个用例通过;本次补充校验从标准输入编译执行,未修改或新增测试源码、测试配置和测试文档。
2026-09-18:LINK测试改为报文回放用例,当时默认LINK套件68个、全部套件119个场景通过。该套件已随过期测试清理移除,历史记录保存在`.build`中。
2026-09-16:TESTFR改为三态,取消提前CON的缓存;当时旧用例因状态枚举变化而无法编译,未计为该次变更的验证结果。
2026-09-14:完善STARTDT期间的收发方向门控,当时新增LINK 36至40。算法契约见[链路设计](IEC104_Link_设计架构.md)。