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

575 lines
43 KiB
C
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
/* 子站两类生命周期的变长ASDU字节环:借用调用方存储,不动态分配;HIGH满时拒绝,NORMAL覆盖最旧原文。
* 严格业务调度在这两个字节环中记录等级,不为每个等级另建载荷缓冲。
* 队列只接受HIGH/NORMAL;IDLE仅标记空闲直发的发送记录,不是第三级队列,也不能用作队列数组下标。 */
#ifndef IEC104_ASDUQUEUE_H
#define IEC104_ASDUQUEUE_H
#include "IEC104_Codec.h"
#include <stdbool.h>
#ifdef __cplusplus
extern "C" {
#endif
/* 区分条目头:兼容HIGH只有uint16长度,严格HIGH另存票据、受理顺序和业务等级。
* NORMAL通过memcpy存取,可跨尾部且不要求环内地址对齐;布局仅供本次构建使用,不能持久化。
* 此类型公开用于容量计算,调用方不得把字节环强转为结构体指针。 */
typedef struct {
uint64_t entry_serial;
unsigned int entry_state : 2; /* 1待发,2已交接待ACK;严格模式3为已覆盖原文的身份头,0无效。 */
unsigned int asdu_length : 8; /* 原文为6..249;严格模式已覆盖身份头为0。 */
unsigned int business_priority : 4; /* 严格模式为1..12,兼容模式为0;不增加原NORMAL头的对齐长度。 */
} IEC104_AsduNormalEntryHeader_t;
#define IEC104_ASDU_HIGH_ENTRY_HEADER_LEN ((uint32_t)sizeof(uint16_t))
#define IEC104_ASDU_NORMAL_ENTRY_HEADER_LEN ((uint32_t)sizeof(IEC104_AsduNormalEntryHeader_t))
#define IEC104_ASDU_HIGH_QUEUE_MIN_CAPACITY (IEC104_ASDU_HIGH_ENTRY_HEADER_LEN + IEC104_ASDU_HEADER_LEN)
#define IEC104_ASDU_NORMAL_QUEUE_MIN_CAPACITY (IEC104_ASDU_NORMAL_ENTRY_HEADER_LEN + IEC104_ASDU_HEADER_LEN)
#define IEC104_ASDU_STRICT_HIGH_ENTRY_HEADER_LEN 19U /* 票号8、受理顺序8、长度2、等级1,逐字段memcpy。 */
#define IEC104_ASDU_SOE_SLOT_LEN 26U /* serial8、state/rank1、完整单对象ASDU17;逐字节存储,无ABI填充。 */
#define IEC104_ASDU_SOE_ASDU_LEN 17U
#define IEC104_ASDU_SOE_MAX_CAPACITY 256U
/* SOE统计以单对象事件为单位;pending_count不含仍待应用决定的deferred_count。 */
typedef struct {
uint16_t capacity, retired_capacity;
uint16_t stored_count, pending_count, retained_unacked_count, deferred_count, retired_count;
uint64_t dropped_pending_count; /* 容量覆盖待发事件或占位的累计数。 */
uint64_t overwritten_unacked_count; /* 容量覆盖已交接原文的累计数,不代表确定未送达。 */
uint64_t discarded_count; /* 显式撤销或筛选清除的累计数,不含ACK或容量覆盖。 */
} IEC104_AsduSoeStatus_t;
/* 仅借用存储,控制副本不复制256个槽;retired中0为空,非零为精确的已覆盖待ACK身份。 */
typedef struct {
uint8_t *slots;
uint64_t *retired;
uint16_t capacity, retired_capacity;
uint64_t dropped_pending_count, overwritten_unacked_count, discarded_count;
} IEC104_AsduSoeStorage_t;
typedef enum {
IEC104_ASDU_QUEUE_ERROR = -1, /* 条目超过桶总容量,或参数、代次、状态非法 */
IEC104_ASDU_QUEUE_FULL = 0, /* 字节空间/编号不足;严格NORMAL须计入不可丢的待ACK身份头。 */
IEC104_ASDU_QUEUE_OK = 1, /* 本次操作成功,查询输出有效 */
IEC104_ASDU_QUEUE_EMPTY = 2 /* 无匹配条目,不代表操作成功 */
} IEC104_AsduQueueResult_t;
typedef struct {
uint64_t connection_generation; /* 队列绑定代次;0表示离线NORMAL,Detach/Rebind后旧身份失效 */
uint64_t entry_serial; /* NORMAL仅未绑定SOE的兼容模式循环;绑定SOE或严格模式不回绕;HIGH固定0。 */
} IEC104_AsduEntryId_t;
/* NORMAL筛选按104固定布局读取Type(字节0)和CA(字节4..5,小端),不解析业务对象。
* 位图全0合法,表示不匹配任何类型;common_address只接受1..65534。
* 筛选没有站点注册编号,同CA旧站和新站留下的原文均可匹配;站点授权由上层检查。 */
typedef struct {
uint16_t common_address;
uint8_t type_bitmap[32]; /* type_bitmap[type / 8]的type % 8位匹配该Type。 */
} IEC104_AsduNormalFilter_t;
/* 条目逻辑连续,头和原文均可跨数组尾部。
* 队列待发区是尚未完成Mark_Submitted记账的条目;unsubmitted_*沿用此接口命名。
* HIGH在发送模块接手后直接出队;NORMAL在兼容模式分为待ACK前缀和待发后缀,严格模式两种状态可交错。 */
typedef struct {
uint8_t *bytes; /* 调用方持有的字节数组,模块只借用 */
uint32_t byte_capacity; /* 数组字节容量,至少对应优先级的MIN_CAPACITY */
uint32_t head_index; /* 最旧物理头的下标;严格模式仅剩覆盖身份头时entry_count可为0。 */
uint32_t tail_index; /* 下一次追加位置,直接从这里跨尾部写入 */
uint32_t used_bytes; /* 头与原文的实际占用;包含严格NORMAL已覆盖原文后留下的身份头。 */
uint32_t entry_count; /* 原文仍保留的ASDU条目数;NORMAL含待ACK原文,不含覆盖身份头。 */
uint32_t unsubmitted_index; /* 物理顺序中第一条待发头;不一定是严格模式下一候选,无待发时等于tail_index。 */
uint32_t unsubmitted_count; /* 尚未完成队列交接记账的条目数,不表示SendBuffer中的待发帧数 */
} IEC104_AsduPriorityQueue_t;
/* 每级独立FIFO票据进度;低4位为等级、同级步长16,高水位仍汇总到high_next_sequence。
* 不同等级可乱序交接,不能用全局最大已交接票号推断较小票号已HANDED;查询必须回到所属等级。
* 状态由调用方提供并持续到Queue.Abort,独立于Queue控制副本,避免入队预检把480B复制到深层栈。 */
typedef struct {
uint64_t head_sequence, next_sequence, known_from, cancel_begin, cancel_end;
} IEC104_AsduPriorityTicketState_t;
typedef struct {
IEC104_AsduPriorityTicketState_t lanes[IEC104_BUSINESS_PRIORITY_COUNT - 1];
} IEC104_AsduQueuePriorityState_t;
/*
* overwritten_unacked表示NORMAL原文已覆盖、对应I帧仍未被有效ACK确认;具体发送身份由Manager记录。
* 兼容模式以begin/end包含两端的区间表示普通NORMAL身份,丢弃未提交条目可造成间隔;ACK后的下界未必对应实际条目。
* 该模式待ACK计数为0时两端均为0;仅未绑定SOE时区间循环且受半环编号窗口约束,绑定SOE后编号不回绕。
* 严格模式不用区间推断ACK身份;每份已覆盖原文在NORMAL环内保留精确身份头,计数单独汇总。
*/
typedef struct {
IEC104_AsduPriorityQueue_t priority_queues[IEC104_ASDU_PRIORITY_COUNT]; /* HIGH/NORMAL两个独立字节环 */
uint64_t connection_generation; /* 当前绑定代次;0为服务离线缓存,只允许NORMAL待发原文 */
uint64_t next_entry_serial; /* 未绑定SOE时兼容NORMAL循环;绑定后单调分配SOE奇数/OTHER偶数,严格HIGH共用受理时序。 */
uint64_t high_head_sequence, high_next_sequence; /* 兼容HIGH隐式区间;严格模式next汇总各级高水位,跨Init避免票号复用。 */
uint64_t high_known_from; /* 更早票据的取消历史已遗忘,保守返回CANCELLED。 */
uint64_t high_cancel_begin, high_cancel_end; /* 最近一次非空取消区间,[begin,end)。 */
uint64_t overwritten_unacked_serial_end; /* 普通NORMAL待确认区间的结束边界,含端点;仅未绑定SOE时循环,计数为0时为0。 */
uint64_t overwritten_unacked_serial_begin; /* 普通NORMAL待确认区间的起始边界,含端点;仅未绑定SOE时循环,ACK后推进,计数为0时为0。 */
uint64_t discarded_asdu_count; /* 筛选清除及显式取消SOE的累计条目数;Init清零,Detach/Rebind保留。 */
uint32_t overwritten_unacked_count; /* NORMAL原文已覆盖、已提交且待确认的ASDU条目数 */
uint8_t normal_send_limited; /* 0/1:EOF后停止选取全部未提交NORMAL;Detach/Rebind解除 */
uint8_t startup_pending; /* 0/1:启动流程暂停NORMAL/IDLE;独立于EOF,绑定转换不解除。 */
uint8_t is_initialized; /* 1表示已初始化,不表示TCP存活或可发送 */
uint8_t strict_business_priority; /* 0兼容双FIFO;1按业务等级选择,绑定转换保留。 */
IEC104_AsduQueuePriorityState_t *priority_state; /* 严格模式借用的固定票据元数据;不拥有原文缓冲。 */
IEC104_AsduSoeStorage_t soe; /* 独立SOE保留区;普通NORMAL覆盖不能触及此区。 */
} IEC104_AsduQueue_t;
/**
* 功能:为空SOE区绑定调用方持有的固定字节槽和覆盖待ACK身份表。
* 输入参数:queue——已初始化队列;slots——capacity×26字节;capacity——1..256;retired——retired_capacity个uint64_t;retired_capacity——非零,至少覆盖实际发送记录容量。
* 输出参数:queue——保存借用指针;slots/retired——成功时清零。
* 返回值:OK成功;ERROR参数、状态或旧SOE区非空,失败不修改存储。
* 说明:存储须互不重叠且活到Abort;不分配内存,不能在保留原文或覆盖身份期间重绑。
*/
extern IEC104_AsduQueueResult_t IEC104_AsduQueue_Bind_Soe_Storage(IEC104_AsduQueue_t *queue,
uint8_t *slots, uint16_t capacity, uint64_t *retired, uint16_t retired_capacity);
/**
* 功能:复制单对象Type30/31、COT3原文到独立SOE区,满时只覆盖最旧SOE。
* 输入参数:queue/generation——有效队列及当前代次,离线可为0;bytes/length——完整17字节ASDU,单对象SQ0、PN0、合法CA/非零IOA;rank——1..12;deferred——true建立待应用决定的占位。
* 输出参数:queue及外借SOE存储——成功时更新;serial——非NULL,成功返回不复用的受理身份。
* 返回值:OK已复制;FULL编号窗口或覆盖身份表不足;ERROR参数、未绑定或状态非法。失败不改输出或原文。
* 说明:保留TEST、OA、值、品质及原CP56,业务字段由生产者校验;同点重复事件不去重,未ACK覆盖不撤回已交接I帧。
* serial是不可解释的身份,调用方不得按连续差值计事件数;绑定后内部奇偶分类且全局不回绕。
*/
extern IEC104_AsduQueueResult_t IEC104_AsduQueue_Enqueue_Soe(IEC104_AsduQueue_t *queue,
uint64_t generation, const uint8_t *bytes, uint16_t length, IEC104_BusinessPriority_t rank,
bool deferred, uint64_t *serial);
/**
* 功能:将仍存在的SOE占位发布为待发事件,或明确丢弃该占位。
* 输入参数:queue——有效队列;serial——占位受理身份;publish——true发布,false删除。
* 输出参数:queue及SOE槽——成功时更新状态或删除并累计显式丢弃。
* 返回值:OK已决定;EMPTY身份已覆盖、删除或已决定;ERROR参数或队列状态非法。
* 说明:占位阻止其后同级SOE交接,不能以普通重试重建已丢失身份;跨Detach/Rebind仍保留尚未决定的占位。
* Abort/Init后调用方须丢弃旧serial;本层裸编号可能重新使用,跨服务期隔离由上层票据校验。
*/
extern IEC104_AsduQueueResult_t IEC104_AsduQueue_Resolve_Soe(IEC104_AsduQueue_t *queue,
uint64_t serial, bool publish);
/**
* 功能:读取独立SOE原文、占位、覆盖身份及累计丢弃统计。
* 输入参数:queue——已初始化队列,可未绑定SOE存储。
* 输出参数:status——非NULL,仅成功时写入完整快照。
* 返回值:OK成功;ERROR参数或状态非法,失败保持输出。
* 说明:未绑定时容量与计数均为0;Get_Status的NORMAL计数汇总两区,Get_Free_Bytes仍只查询普通字节环。
*/
extern IEC104_AsduQueueResult_t IEC104_AsduQueue_Get_Soe_Status(const IEC104_AsduQueue_t *queue,
IEC104_AsduSoeStatus_t *status);
/*
* 只读ASDU条目状态快照,各count均以ASDU条目为单位;本队列保存原文,SendBuffer仅保存当前待完成的I帧APDU。
* 队列“已提交”表示发送模块接手后又完成了Mark_Submitted记账,不表示整帧已写完。
* 顺序是:SendBuffer持有完整I帧 -> Manager建立记录 -> Mark_Submitted更新队列。
* 最后一步执行前,队列仍保留旧的待发状态;所有步骤串行,不得插入其他队列修改。
* 待确认表示对应I帧尚未收到有效ACK,涵盖尚未写出、部分写出及整帧写完后的等待阶段。
* HIGH在交接记账时消费原文,其retained_unacked_count恒为0;未确认HIGH数量由Manager发送记录维护。
* NORMAL的retained_unacked_count加overwritten_unacked_count等于NORMAL已提交待确认条目数。
* NORMAL计数包含普通环及SOE区,尚未决定的SOE占位计入保留原文;退休身份另计overwritten_unacked_count。
* is_storage_empty只说明原文存储为空,HIGH或NORMAL仍可能有对应I帧等待ACK。
* 严格模式仅剩覆盖身份头时is_storage_empty仍可为1,但used_bytes不为0,不能据此断言字节环已清空。
*/
typedef struct {
uint64_t connection_generation; /* 查询时的绑定代次;0为未绑定连接的服务队列 */
uint64_t discarded_asdu_count; /* 筛选清除及显式取消SOE的累计条目数,不含容量覆盖、ACK释放或Abort。 */
uint32_t entry_count[IEC104_ASDU_PRIORITY_COUNT]; /* 各优先级仍保留原文的ASDU总条目数,包含未提交条目 */
uint32_t retained_unacked_count[IEC104_ASDU_PRIORITY_COUNT]; /* 原文仍保留的已提交待确认ASDU条目数;HIGH恒为0 */
uint32_t overwritten_unacked_count; /* NORMAL原文已覆盖、已提交且待确认的ASDU条目数 */
uint8_t is_storage_empty; /* 两级ASDU原文环均为空,不表示所有对应I帧均已确认 */
} IEC104_AsduQueueStatus_t;
/*
* ASDU原文最多分两段借用,先first后second;总长度为asdu_length。
* asdu_second==NULL时全部位于第一段;否则第二段长度=asdu_length-asdu_first_length。
* 本条目被覆盖、确认释放、Remove或HIGH提交后借用失效;Reset_High使HIGH借用失效。
* Detach/Rebind/Abort/Init及按筛选Discard_Unsubmitted_Normal使所有借用失效。
* NORMAL再次Enqueue可能覆盖旧借用;需要连续副本时,在借用仍有效期间使用Copy_Asdu。
* 严格模式任意位置出队/ACK/覆盖会压紧对应字节环,该环此前全部原文借用随之失效。
*/
typedef struct {
IEC104_AsduEntryId_t entry_id; /* NORMAL核对完整身份;HIGH仅有当前代次,entry_serial为0 */
IEC104_AsduPriority_t priority; /* 条目所属字节环 */
const uint8_t *asdu_first; /* 原文第一段,非NULL,不包含APCI */
const uint8_t *asdu_second; /* 跨尾部时指向数组起点,否则NULL */
uint16_t asdu_first_length; /* 第一段长度,1..asdu_length */
uint16_t asdu_length; /* ASDU实际长度,6..249字节 */
uint8_t is_submitted; /* 0队列尚未登记交接;1 NORMAL已登记交接、保留待ACK;HIGH出队前恒0 */
uint16_t entry_header_length; /* 本条实际头长:兼容HIGH为2、严格HIGH为19,NORMAL为其结构头长。 */
IEC104_BusinessPriority_t business_priority; /* 严格模式的业务等级;兼容模式提供默认分类。 */
uint64_t response_ticket; /* HIGH的真实交接票据;NORMAL为0。票据仅供查询交接事实,不是协议N(S)。 */
uint64_t admission_order; /* 严格模式两环共享的受理顺序,Manager用它打破同等级平局;与票据、N(S)独立。 */
} IEC104_AsduHeadInfo_t;
/**
* 功能:两个缓冲区容量单位均为字节,至少各自MIN_CAPACITY;不分配内存,不清空字节数组。
* 输入参数:high_bytes/normal_bytes——持续有效且互不重叠的数组;
* high_capacity/normal_capacity——字节容量,分别至少对应优先级的MIN_CAPACITY;
* connection_generation——0建立服务离线队列;非零值表示绑定到不复用的连接代次。
* 输出参数:queue——非NULL,仅成功时整体写入初始化结果。
* 返回值:OK表示成功,ERROR表示参数非法;失败不修改queue或字节数组。
* 说明:Init默认兼容模式,HIGH占2+asdu_length;启用严格模式后HIGH头为19字节,NORMAL头长不变。
* 头和原文均可跨尾部;最大HIGH ASDU兼容模式需要251字节、严格模式需要268字节。
* high_next_sequence须非零,作为本次HIGH起点;重建队列时传入旧高水位,不能重用已发放票号。
* Enqueue中条目超过桶总容量返回ERROR;空间不足时HIGH返回FULL,NORMAL覆盖最旧原文。
* NORMAL覆盖包括已提交未ACK条目,不产生丢弃通知;发送记录及ACK义务由Manager独立保留。
* 结构、数组、输入、输出不得重叠;所有操作串行。generation为0时只缓存NORMAL,不能提交发送。
* 绑定连接须使用非零且跨连接不复用的generation;服务可先Init(0),接入后再Rebind。
* 仅未绑定SOE的兼容模式NORMAL编号在1..UINT64_MAX循环,活跃身份受半环约束;绑定SOE或严格模式共用受理序号耗尽后拒绝新增。
* NORMAL的entry_id只在原文条目或覆盖待ACK记录存活期间有效;释放后不得跨编号复用再次提交。
* HIGH的entry_id不含逐条身份;从Peek到Mark/Discard之间不得改变选择结果,不能异步保存0编号当作身份。
* 两级后续发送完成和ACK均由Manager的frame_id及协议序号处理,不保存业务user_tag。
*/
extern IEC104_AsduQueueResult_t IEC104_AsduQueue_Init(
IEC104_AsduQueue_t *queue,
uint8_t *high_bytes, uint32_t high_capacity,
uint8_t *normal_bytes, uint32_t normal_capacity,
uint64_t connection_generation, uint64_t high_next_sequence);
/**
* 功能:仅空队列且未启用严格模式时绑定固定元数据,失败不改状态;不分配任何原文容量。
* 输入参数:queue——ASDU队列。
* state——当前状态。
* 输出参数:queue——ASDU队列的更新结果。
* 返回值:按处理分支返回IEC104_ASDU_QUEUE_ERROR、IEC104_ASDU_QUEUE_OK。
* 说明:仅空队列的兼容状态允许绑定,切换严格模式时才初始化各等级,失败不替换已有绑定。
*/
extern IEC104_AsduQueueResult_t IEC104_AsduQueue_Bind_Priority_State(
IEC104_AsduQueue_t *queue, IEC104_AsduQueuePriorityState_t *state);
/**
* 功能:只允许空队列切换;enabled为0/1,启用须先绑定state且HIGH至少容纳严格头+最短ASDU。
* 输入参数:queue——ASDU队列。
* enabled——使能标志。
* 输出参数:queue——ASDU队列的更新结果。
* 返回值:按处理分支返回IEC104_ASDU_QUEUE_ERROR、IEC104_ASDU_QUEUE_OK。
* 说明:严格NORMAL覆盖已交接原文时保留头作为ACK身份墓碑,必要头空间不足返回FULL而不丢失身份。
* 严格模式HIGH/NORMAL共享受理序号,耗尽后两者均拒绝新增,不回绕;仅未绑定SOE的兼容模式沿用循环编号。
*/
extern IEC104_AsduQueueResult_t IEC104_AsduQueue_Set_Strict_Priority(
IEC104_AsduQueue_t *queue, uint8_t enabled);
/**
* 功能:只读数值快照;仅OK写status,查询不预留容量,也不证明TCP或链路状态。
* 输入参数:queue——已初始化的业务队列。
* 输出参数:status——非NULL,仅OK时写入数值副本。
* 返回值:OK或ERROR;失败不修改输出。
* 说明:兼容模式校验控制字段;严格模式有界扫描两个字节环,含覆盖身份头,复杂度随保留条目数增长。
*/
extern IEC104_AsduQueueResult_t IEC104_AsduQueue_Get_Status(
const IEC104_AsduQueue_t *queue, IEC104_AsduQueueStatus_t *status);
/**
* 功能:HIGH用于连接请求应答,提交后出队;Manager初始化成功、受理新STOP或从STOPPED受理START时清空待发条目。
* 输入参数:queue/connection_generation——队列及当前绑定代次;priority——生命周期。
* asdu/asdu_length——待复制的ASDU原文及字节数。
* 输出参数:无。
* 返回值:OK已复制接手;FULL暂时无法入队;ERROR为参数、代次或存储状态非法。
* 说明:重复START的CON不清理HIGH;HIGH重连不保留,启停准入由Manager控制,本队列不读取链路状态。
* NORMAL用于允许向同一业务接收方恢复的事件,离线时以generation=0入队;HIGH必须绑定非零代次。
* Detach/Rebind保留仍存在的NORMAL原文并恢复未提交;EOF后全部未提交NORMAL均留给下一连接。
* 长度6..249;条目头加ASDU超过目标桶总容量时ERROR,不为装不下的条目清空队列。
* HIGH空间不足时FULL,等待释放后重试;NORMAL按队首顺序计划移除旧条目,全部检查通过后才覆盖并返回OK。
* 兼容NORMAL旧身份阻止编号窗口前进时也返回FULL;严格NORMAL不可回收的ACK身份头仍占空间。
* 兼容HIGH使用隐式单调序号,next达到UINT64_MAX后入队ERROR;严格HIGH逐级编号也不允许回绕。
* 兼容NORMAL的UINT64_MAX仍可分配,下一编号为1;严格模式预留next哨兵,受理序号耗尽返回FULL。
* 覆盖包括已提交原文,但不撤回已经编号的帧、不伪造ACK、不产生逐条丢弃通知。
* 启动暂停不改变以上入队和覆盖规则;同样不阻止Manager继续按有效ACK回收已提交原文。
* 仅OK后生产者推进游标;FULL/ERROR不修改队列、字节或编号。ERROR不能按背压盲目重试。
*/
extern IEC104_AsduQueueResult_t IEC104_AsduQueue_Enqueue(
IEC104_AsduQueue_t *queue, uint64_t connection_generation,
IEC104_AsduPriority_t priority, const uint8_t *asdu,
uint16_t asdu_length);
/**
* 功能:将应答复制到HIGH并返回非零交接凭证;ticket可传NULL。失败不改队列或输出。
* 输入参数:queue/connection_generation——队列及当前绑定代次;asdu/asdu_length——应答原文及长度。
* 输出参数:ticket——可为NULL,仅入队成功时写入票据。
* 返回值:OK已接手;FULL表示HIGH暂无空间;ERROR表示输入或队列状态非法。
* 说明:兼容模式HIGH按FIFO与Manager配额发送;严格模式按业务等级与共同受理顺序参与两个环的候选比较。
*/
extern IEC104_AsduQueueResult_t IEC104_AsduQueue_Enqueue_Response(
IEC104_AsduQueue_t *queue, uint64_t connection_generation,
const uint8_t *asdu, uint16_t asdu_length, uint64_t *ticket);
/**
* 功能:显式业务等级入口;1..12有效,兼容模式仅校验等级并沿用双FIFO调度。
* 输入参数:queue/connection_generation——队列及代次;priority——HIGH或NORMAL生命周期。
* asdu/asdu_length——原文及长度;business_priority——NONE与COUNT之间的业务等级。
* 输出参数:无。
* 返回值:OK已接手;FULL暂时无法入队;ERROR为业务等级、输入或队列状态非法。
* 说明:旧Enqueue在严格模式将NORMAL映射为事件4、HIGH映射为应答5,Enqueue_Response同样使用应答5。
* 默认映射只维持旧入口可用;业务应使用显式入口继承事务等级,不可仅凭ASDU类型猜测所属流程。
*/
extern IEC104_AsduQueueResult_t IEC104_AsduQueue_Enqueue_Priority(
IEC104_AsduQueue_t *queue, uint64_t connection_generation,
IEC104_AsduPriority_t priority, const uint8_t *asdu, uint16_t asdu_length,
IEC104_BusinessPriority_t business_priority);
/**
* 功能:按指定业务等级将应答复制到HIGH队列,并按需返回交接票据。
* 输入参数:queue/connection_generation——队列及代次;asdu/asdu_length——应答原文及长度。
* business_priority——NONE与COUNT之间的有效等级。
* 输出参数:ticket——可为NULL,仅成功时写入票据。
* 返回值:OK已接手;FULL暂无入队空间;ERROR为等级、输入或队列状态非法。
* 说明:生命周期始终为HIGH;兼容模式校验等级但不按等级重新排序。
*/
extern IEC104_AsduQueueResult_t IEC104_AsduQueue_Enqueue_Response_Priority(
IEC104_AsduQueue_t *queue, uint64_t connection_generation,
const uint8_t *asdu, uint16_t asdu_length, uint64_t *ticket,
IEC104_BusinessPriority_t business_priority);
/**
* 功能:严格模式直接应答的非零票据:该等级无排队前驱才能分配;不占原文字节。
* 输入参数:queue——ASDU队列。
* generation——连接代次。
* priority——优先级。
* 输出参数:无。
* 返回值:按处理分支返回IEC104_ASDU_QUEUE_ERROR、lane->head_sequence == lane->next_sequence ? IEC104_ASDU_QUEUE_OK : IEC104_ASDU_QUEUE_FULL。
* 说明:Can为只读预检,FULL表示同级仍有前驱,ERROR表示身份/等级/编号非法;Record仅OK写票据。
* Record必须在SendBuffer实际接手后调用;成功立即HANDED,不代表写出或ACK。
* 本接口只保护同级票据连续性;当前业务阶段、其他等级候选及链路容量须由Manager先行检查。
* Can不预留票号,准备帧与Record必须串行完成;不得用本接口越过仍排队的同级应答。
*/
extern IEC104_AsduQueueResult_t IEC104_AsduQueue_Can_Record_Direct_Response(
const IEC104_AsduQueue_t *queue, uint64_t generation, IEC104_BusinessPriority_t priority);
/**
* 功能:调用前SendBuffer必须已接手本帧;仅OK写非零ticket,失败保持输出原值。
* 输入参数:queue——ASDU队列。
* generation——连接代次。
* priority——优先级。
* ticket——应答交接票据。
* 输出参数:queue——ASDU队列的更新结果。
* ticket——应答交接票据的更新结果。
* 返回值:按处理分支返回IEC104_ASDU_QUEUE_ERROR、checked、IEC104_ASDU_QUEUE_OK。
* 说明:不保存原文且不触发发送,已交接帧不能因登记失败按WAIT重新提交,调用方须按致命故障收尾。
*/
extern IEC104_AsduQueueResult_t IEC104_AsduQueue_Record_Direct_Response(
IEC104_AsduQueue_t *queue, uint64_t generation, IEC104_BusinessPriority_t priority, uint64_t *ticket);
/**
* 功能:0为直接交接的哨兵。只描述离开HIGH的交接事实,不表示本地写完或主站ACK。
* 输入参数:queue——保留票据历史的队列;ticket——应答提交时取得的票据。
* 输出参数:无,不修改队列。
* 返回值:PENDING尚未交接;HANDED已交接;CANCELLED已取消或历史不可判定;ERROR为非法票据/状态。
* 说明:兼容模式统一、严格模式逐级仅保留最近非空取消区间;更早未知历史保守CANCELLED。
* CANCELLED可能表示历史已遗忘,不能据此断言从未交接。Abort后非零票也保守CANCELLED,
* TcpServer须用其保存的next另行拒绝未分配票号;新Init的known_from等于传入起点。
*/
extern IEC104_ResponseState_t IEC104_AsduQueue_Get_Response_State(
const IEC104_AsduQueue_t *queue, uint64_t ticket);
/**
* 功能:Peek_Head查看最旧保留原文;Peek_Unsubmitted在兼容模式查看待发区首条,严格模式选最小业务等级、同级FIFO。
* 输入参数:queue——有效队列;priority——HIGH或NORMAL。
* 输出参数:head_info——非NULL,仅OK时提供身份、原文借用及是否已提交。
* 返回值:OK有条目,EMPTY为空,ERROR表示参数、状态或条目非法。
* 说明:两者均只读;严格模式跳过已覆盖原文的身份头,不向应用发布长度为0的伪ASDU。
* Peek_Unsubmitted返回EMPTY表示当前没有可交接条目;启动暂停或EOF可隐藏待发NORMAL,不代表队列为空。
* 离线时仍可查看NORMAL待发原文,但必须Rebind到非零代次后才能Mark_Submitted。
* 查询只描述队列记账状态,不检查SendBuffer;is_submitted为0不证明发送模块尚未接手。
*/
extern IEC104_AsduQueueResult_t IEC104_AsduQueue_Peek_Head(
const IEC104_AsduQueue_t *queue, IEC104_AsduPriority_t priority,
IEC104_AsduHeadInfo_t *head_info);
/**
* 功能:只读查看指定生命周期中当前允许交接的下一条ASDU。
* 输入参数:queue——有效队列;priority——HIGH或NORMAL。
* 输出参数:head_info——调用方提供的非NULL指针;仅返回OK时写入,is_submitted为0。
* 返回值:OK表示找到当前允许交接的未提交条目;EMPTY表示没有可交接条目,不代表整个队列为空;
* ERROR表示参数、状态或条目非法。
* 说明:兼容模式通过unsubmitted_index定位;严格模式在校验后扫描全环,挑最高业务等级的最早待发项。
* 不移除条目,不改变记账状态;Manager交接过程中的内部复核也使用本接口。
* 本队列不查询SendBuffer,调用方不能把is_submitted为0当作发送模块尚未接手的证明。
* NORMAL全部已提交、启动暂停或EOF停止选取时返回EMPTY,Peek_Head仍可查看实际保留原文。
* 把暂停落实在共用选帧入口,Manager的排队调度和直发准入都看到同一可发送集合。
* 离线查询可返回代次0的NORMAL原文视图,真正提交发送须先Rebind到非零代次。
*/
extern IEC104_AsduQueueResult_t IEC104_AsduQueue_Peek_Unsubmitted(
const IEC104_AsduQueue_t *queue, IEC104_AsduPriority_t priority,
IEC104_AsduHeadInfo_t *head_info);
/**
* 功能:将仍有效的两段原文复制到destination;capacity至少asdu_length,且不得与原文或描述重叠。
* 输入参数:head_info——借用仍有效的条目描述;capacity——输出缓冲实际字节容量。
* 输出参数:destination——非NULL、与两段原文及描述不重叠的可写数组,仅OK时写入。
* 返回值:OK复制了asdu_length字节;ERROR表示描述或容量非法,此时不改输出。
* 说明:OK写完整ASDU,ERROR不改输出;不重新验证条目身份,调用方须保证借用仍有效。
*/
extern IEC104_AsduQueueResult_t IEC104_AsduQueue_Copy_Asdu(
const IEC104_AsduHeadInfo_t *head_info, uint8_t *destination, uint16_t capacity);
/**
* 功能:登记发送交接的队列结果;调用前完整I帧须已交给SendBuffer且Manager已建立记录。
* 输入参数:queue/priority——目标队列与优先级;entry_id——NORMAL完整身份,HIGH为当前代次及0编号。
* 输出参数:queue——HIGH释放所选条目;NORMAL更新头内状态、unsubmitted_count和unsubmitted_index。
* 返回值:OK或ERROR;失败不修改队列。
* 说明:必须绑定非零代次;本函数入口处,队列仍保留待发旧状态。
* HIGH直接消费原文,NORMAL改为保留待ACK并推进待发游标;EOF后NORMAL不允许新的发送交接。
* 出队或修改状态均在发送模块接手之后,不表示报文已写完或已收到ACK。
* 本队列无法验证发送缓冲是否接手,调用方须保证上述顺序,不能提前调用本函数取消待发业务。
* HIGH要求当前代次及0编号,不提供同代次逐条身份保护;NORMAL另核对条目编号。
* 从Peek到本次记账之间不得移除、清空或替换所选条目;成功前的原文借用须持续有效。
*/
extern IEC104_AsduQueueResult_t IEC104_AsduQueue_Mark_Submitted(
IEC104_AsduQueue_t *queue, IEC104_AsduPriority_t priority, IEC104_AsduEntryId_t entry_id);
/**
* 功能:仅接受NORMAL的有效ACK路径,按发送顺序提交Manager记录中的真实身份;HIGH的ACK只由Manager处理。
* 输入参数:queue——有效队列;priority——只允许NORMAL;entry_id——有效ACK对应Manager记录的真实身份。
* 输出参数:queue——仍有原文时释放匹配队首;已覆盖时更新待确认计数和区间边界,不移除当前队首。
* 返回值:OK或ERROR;ERROR表示代次、编号区间、覆盖计数或已提交队首身份不符合约束。
* 说明:兼容模式仍有原文时必须匹配已提交队首;原文已覆盖时核减待确认计数,不删除新队首。
* 兼容模式普通NORMAL已覆盖身份以计数和编号区间检查,仅未绑定SOE时区间循环;严格模式精确查找保留头或覆盖身份头,允许跨等级回收。
* 两种模式均只供Manager提交Link验证后的真实ACK身份,不能由业务调用来伪造确认。
*/
extern IEC104_AsduQueueResult_t IEC104_AsduQueue_Confirm_Next_Normal_Entry(
IEC104_AsduQueue_t *queue, IEC104_AsduPriority_t priority, IEC104_AsduEntryId_t entry_id);
/**
* 功能:主动丢弃只允许最旧的保留原文尚未登记交接时执行,不能越过待ACK原文删除后面的待发条目。
* 输入参数:queue/priority——目标字节环;entry_id——NORMAL完整身份,HIGH为当前代次及0编号。
* 输出参数:queue——成功时释放队首并推进待发游标;不清零原文字节,被丢弃条目的借用失效。
* 返回值:OK或ERROR;队首为空、身份不符或已登记交接时ERROR且不修改队列。
* 说明:严格模式跳过没有原文的覆盖身份头,但保留其ACK义务;本接口不按业务等级挑选丢弃对象。
* HIGH只核对代次及0编号,NORMAL另核对条目编号;成功使该条目的原文借用失效。
* 本函数无法检查SendBuffer是否已接手,调用方须在发送交接开始前使用,不得插入Manager交接过程。
* 不能用它撤回已编号I帧;ERROR不修改队列。
*/
extern IEC104_AsduQueueResult_t IEC104_AsduQueue_Discard_Unsubmitted_Head(
IEC104_AsduQueue_t *queue, IEC104_AsduPriority_t priority, IEC104_AsduEntryId_t entry_id);
/**
* 功能:按CA和Type筛选NORMAL待发条目;已登记交接的原文及覆盖待ACK记账不变。
* 输入参数:queue——ASDU队列。
* connection_generation——连接代次。
* filter——筛选条件。
* count——条目数量。
* 输出参数:count——条目数量的更新结果。
* 返回值:按处理分支返回IEC104_ASDU_QUEUE_ERROR、IEC104_ASDU_QUEUE_OK。
* 说明:在线须匹配当前代次,离线使用0;EOF限制时也可查询/清除,操作不解除限制。
* 两入口均先验证NORMAL完整布局、条目身份及状态;严格模式没有单一提交分界,不校验ASDU业务内容。
* Count只读,不预留条目或冻结队列;Discard仍独立完成一次完整验证后才修改。
* Discard稳定压缩待发区,保留条目头、entry_serial和顺序,不回收编号。
* Rebind恢复为待发的旧连接原文也在筛选范围内;删除不能撤回主站可能已经收到的副本。
* ERROR不改队列、字节或输出;无匹配时OK且输出0。count/removed以ASDU条目为单位。
* 成功清除使此前原文借用失效;不能插入Manager的Peek至Mark_Submitted之间,也不能撤回已编号I帧。
* 输入筛选、输出与队列及内部字节数组不得重叠;所有操作与Manager串行。
*/
extern IEC104_AsduQueueResult_t IEC104_AsduQueue_Count_Unsubmitted_Normal(
const IEC104_AsduQueue_t *queue, uint64_t connection_generation,
const IEC104_AsduNormalFilter_t *filter, uint32_t *count);
/**
* 功能:先完成全部可失败检查,再稳定压缩删除匹配的待发条目;已交接原文及覆盖身份头均保留。
* 输入参数:queue——ASDU队列。
* connection_generation——连接代次。
* filter——筛选条件。
* removed——删除数量。
* 输出参数:queue——ASDU队列的更新结果。
* removed——删除数量的更新结果。
* 返回值:开始移动后没有返回ERROR的分支。
* 说明:兼容模式仅压缩未提交后缀;严格模式状态交错,可能移动已交接条目,但不会改变其身份与ACK义务。
* 清除不涉及发送记录,不修改next_entry_serial、覆盖待ACK记账、HIGH或EOF发送限制。
* 串行调用契约保证预检与移动之间无人改队列;开始移动后没有返回ERROR的分支。
*/
extern IEC104_AsduQueueResult_t IEC104_AsduQueue_Discard_Unsubmitted_Normal(
IEC104_AsduQueue_t *queue, uint64_t connection_generation,
const IEC104_AsduNormalFilter_t *filter, uint32_t *removed);
/**
* 功能:故障检查/业务恢复使用,offset为保留原文序位,0表示最旧原文,单位不是字节。
* 输入参数:queue/priority——目标字节环;offset——从最旧保留条目起的条目序位,0为队首,单位不是字节。
* 输出参数:head_info——非NULL,仅OK时写入对应条目及其已提交状态。
* 返回值:OK找到条目,EMPTY表示偏移超出已有条目,ERROR表示参数或经过的条目非法。
* 说明:严格模式校验全环并跳过覆盖身份头,复杂度随物理条目数增长;不能用offset推断业务发送顺序。
*/
extern IEC104_AsduQueueResult_t IEC104_AsduQueue_Get_Entry_By_Offset(
const IEC104_AsduQueue_t *queue, IEC104_AsduPriority_t priority,
uint32_t offset, IEC104_AsduHeadInfo_t *head_info);
/**
* 功能:返回未占用字节数;所需空间按实际头长(HIGH兼容2/严格19)加ASDU长度核算,身份头也占预算。
* 输入参数:queue/priority——目标字节环。
* 输出参数:free_bytes——非NULL,仅OK时写入容量减used_bytes。
* 返回值:OK或ERROR,失败不改输出。
* 说明:NORMAL空闲不足时仍可能覆盖旧原文入队;查询不预留空间,最终以Enqueue返回值为准。
*/
extern IEC104_AsduQueueResult_t IEC104_AsduQueue_Get_Free_Bytes(
const IEC104_AsduQueue_t *queue, IEC104_AsduPriority_t priority, uint32_t *free_bytes);
/**
* 功能:清空HIGH未提交条目,保留缓冲区、代次及编号进度;不影响NORMAL、已提交I帧和Manager发送记录。
* 输入参数:queue——有效队列;connection_generation——匹配当前绑定的连接代次。
* 输出参数:仅HIGH桶的条目计数、字节占用及游标清零;所有HIGH原文借用失效。
* 返回值:OK或ERROR;非法状态或旧代次不修改队列。
* 说明:HIGH已提交原文已经出队,因此不影响当前I帧、发送记录、ACK义务和NORMAL数据。
* 不影响NORMAL的next_entry_serial;HIGH只有代次,没有可跨队首变化保存的条目身份。
* 这是同一代次内的清理,不执行重连,也不会把NORMAL待ACK条目重新变成待发。
*/
extern IEC104_AsduQueueResult_t IEC104_AsduQueue_Reset_High(
IEC104_AsduQueue_t *queue, uint64_t connection_generation);
/**
* 功能:EOF收尾前停止选取全部未提交NORMAL;已有及后来新增的未提交原文均留给下一连接,仍按正常容量策略缓存。
* 输入参数:queue——ASDU队列。
* connection_generation——连接代次。
* 输出参数:queue——ASDU队列的更新结果。
* 返回值:按处理分支返回IEC104_ASDU_QUEUE_ERROR、IEC104_ASDU_QUEUE_OK。
* 说明:必须匹配当前非零代次;重复调用不解除限制,已提交I帧继续由SendBuffer/Manager收尾。
* 不影响HIGH,不修改ASDU原文或已有交接记账;Detach/Rebind解除限制。
*/
extern IEC104_AsduQueueResult_t IEC104_AsduQueue_Limit_Normal_Send(
IEC104_AsduQueue_t *queue, uint64_t connection_generation);
/**
* 功能:设置启动暂停,允许匹配的离线代次0;只影响后续NORMAL选择及Manager的IDLE准入。
* 输入参数:queue——ASDU队列。
* connection_generation——连接代次。
* pending——待处理状态。
* 输出参数:queue——ASDU队列的更新结果。
* 返回值:按处理分支返回IEC104_ASDU_QUEUE_ERROR、IEC104_ASDU_QUEUE_OK。
* 说明:pending仅接受0/1;OK已更新,ERROR参数/代次/状态非法且不修改队列,不执行网络推进。
* 不改变原文、ACK、覆盖、HIGH及EOF限制;Detach/Rebind也不隐式解除本标志。
* 本层只认识连接generation,不保存业务或activation_id;服务层须核对实际START轮次后才解除。
*/
extern IEC104_AsduQueueResult_t IEC104_AsduQueue_Set_Startup_Pending(
IEC104_AsduQueue_t *queue, uint64_t connection_generation, uint8_t pending);
/**
* 功能:旧I/O结束、旧Manager已Abort且已知ACK事实已处理后,解除与当前非零代次的绑定。
* 输入参数:queue——有效队列;connection_generation——要解除的当前非零代次。
* 输出参数:queue——ASDU队列的更新结果。
* 返回值:OK保留现存NORMAL并切换到代次0;ERROR不修改队列。
* 说明:清空HIGH,保留NORMAL全部现存原文并恢复待发,清除旧ACK记账及EOF限制;启动暂停和编号进度不变。
* 成功后generation为0,可继续缓存离线NORMAL;所有旧身份及借用失效,ERROR不改变队列。
*/
extern IEC104_AsduQueueResult_t IEC104_AsduQueue_Detach(
IEC104_AsduQueue_t *queue, uint64_t connection_generation);
/**
* 功能:旧连接及所有旧I/O结束、Manager已Abort后显式调用;要求新的非零代次,也可从离线代次0绑定。
* 输入参数:queue——有效队列,可以尚未绑定;connection_generation——未使用过的非零新代次。
* 输出参数:queue——ASDU队列的更新结果。
* 返回值:OK或ERROR;先完整验证两个环,ERROR不修改控制字段或字节。
* 说明:清空HIGH,保留NORMAL全部现存原文并恢复未提交;清除旧代次覆盖待确认记账及EOF限制,保留启动暂停。
* 先验证两个环的全部条目,再把NORMAL头内状态恢复未提交;严格模式移除覆盖身份头并稳定压紧原文。
* ERROR不改控制字段或字节,成功使所有旧借用失效。
* 已覆盖原文无法恢复;不自动发报,允许新Manager绑定恢复后的非空队列。
* 调用前先处理已知ACK事实;NORMAL只能恢复到业务认可的接收方或冗余域,未确认不等于对端未收到。
* Rebind后旧entry_id失效,保留NORMAL条目的serial和原文不变;新连接使用新N(S)。
* next_entry_serial继续沿用;本接口只检查新代次非零且不同于当前值,历史代次不复用由调用方保证。
*/
extern IEC104_AsduQueueResult_t IEC104_AsduQueue_Rebind(
IEC104_AsduQueue_t *queue, uint64_t connection_generation);
/**
* 功能:明确丢弃全部引用;先完成业务回收。Manager.Abort不会隐式调用本接口。
* 输入参数:queue——待终止对象,允许NULL。
* 输出参数:queue——非NULL时清零;调用方提供的字节数组不清零、不释放。
* 返回值:无。
* 说明:不清零或释放调用方数组;队列随后须Init才能重新使用。需要保留NORMAL恢复时应使用Rebind。
*/
extern void IEC104_AsduQueue_Abort(IEC104_AsduQueue_t *queue);
#ifdef __cplusplus
}
#endif
#endif