Files
STM32F4-Base/IEC60870-Slave/104/IEC104_SendBuffer.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

236 lines
15 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.
/* 子站发送字节存储:一帧当前I报文 + 独立紧凑S/U队列,不执行TCP I/O。 */
#ifndef IEC104_SENDBUFFER_H
#define IEC104_SENDBUFFER_H
#include "IEC104_Link_Common.h"
#ifdef __cplusplus
extern "C" {
#endif
/* 本地发送描述;子站启停只发送CON,TESTFR支持ACT和CON。 */
typedef enum {
IEC104_SEND_BUFFER_FRAME_INVALID = 0,
IEC104_SEND_BUFFER_FRAME_I,
IEC104_SEND_BUFFER_FRAME_S_ACK,
IEC104_SEND_BUFFER_FRAME_STARTDT_CON,
IEC104_SEND_BUFFER_FRAME_STOPDT_CON,
IEC104_SEND_BUFFER_FRAME_TESTFR_ACT,
IEC104_SEND_BUFFER_FRAME_TESTFR_CON
} IEC104_SendBufferFrameType_t;
/* 必须精确比较枚举值;正数不统一表示存在报文或发送完成。 */
typedef enum {
IEC104_SEND_BUFFER_ERROR = -1, /* 参数、身份、状态或报文描述非法 */
IEC104_SEND_BUFFER_FULL = 0, /* S/U控制队列无空槽 */
IEC104_SEND_BUFFER_OK = 1, /* 操作成功;记账时表示尚未整帧写完 */
IEC104_SEND_BUFFER_EMPTY = 2, /* 没有已提交帧;未Commit的预留不算已提交帧 */
IEC104_SEND_BUFFER_BUSY = 3, /* 已有预留,或I帧不能取得当前发送位置 */
IEC104_SEND_BUFFER_FRAME_WRITTEN = 4 /* 字节已全部写完,尚需适用的链路完成处理及缓冲释放 */
} IEC104_SendBufferResult_t;
typedef struct {
uint64_t connection_generation; /* 非零且跨连接不复用 */
uint64_t frame_serial; /* 每次预留分配;取消后也不复用 */
} IEC104_SendFrameId_t;
/* apdu只在本次预留有效时可写,Commit/Cancel后不可继续修改。 */
typedef struct {
IEC104_SendFrameId_t frame_id; /* 预留身份,Commit/Cancel必须原样传回 */
uint8_t *apdu; /* Link直接构帧的可写地址 */
uint16_t apdu_capacity; /* I槽255字节,S/U槽6字节 */
} IEC104_SendBufferReservation_t;
/* 数值可以复制;pending_data借用队首存储,Commit_Send_Completion/Abort/Init后失效。 */
typedef struct {
IEC104_SendFrameId_t frame_id; /* 当前发送身份,用于每次增量及完成匹配 */
const uint8_t *pending_data; /* APDU起点+written_bytes,供实际I/O借用 */
uint16_t remaining_bytes; /* 本次最多可写的剩余字节数 */
uint16_t apdu_length; /* 完整报文长度,不随部分写入改变 */
uint16_t written_bytes; /* 累计成功写入字节数 */
IEC104_SendBufferFrameType_t frame_type; /* 完成分派类型,不按当前Link状态推断 */
IEC104_IFrameTx_t i_frame_snapshot; /* I帧原始快照;S/U查询时为0 */
uint16_t encoded_nr; /* I/S中实际编码的N(R),U帧为0 */
uint64_t queued_at_ms; /* 本地发送期限的原始起点 */
uint64_t written_at_ms; /* 仅整帧写完时有效,允许时刻0 */
} IEC104_SendBufferHeadInfo_t;
/* 共用写入元数据;frame_type保存上面的枚举值。 */
typedef struct {
uint64_t frame_serial; /* 本次预留分配的编号,不随槽位复用而复用 */
uint64_t queued_at_ms; /* Commit时保存的原始单调时刻 */
uint64_t written_at_ms; /* 最后一段成功写入的实际时刻,允许0 */
uint16_t apdu_length; /* 完整长度;尚未提交的预留为0 */
uint16_t written_bytes; /* 累计已写长度,不可超过apdu_length */
uint16_t encoded_nr; /* Commit从APCI读取的确认快照 */
uint8_t frame_type; /* 已提交枚举类型;尚未提交为INVALID */
} IEC104_SendBufferFrameState_t;
/* 调用方仅为控制帧分配数组,每槽只有6字节APDU,不再为S/U预留255字节。 */
typedef struct {
IEC104_SendBufferFrameState_t state; /* 本槽身份、类型、写入进度及时间 */
uint8_t apdu[IEC104_APCI_LEN]; /* S/U固定6字节报文 */
} IEC104_SendBufferControlFrame_t;
typedef struct {
IEC104_SendBufferControlFrame_t *control_frames; /* 调用方提供的S/U槽数组 */
uint16_t control_capacity; /* S/U槽总数,1..65535 */
uint16_t control_head_index; /* 控制队首下标;空队列由control_count=0表示 */
uint16_t control_count; /* 已提交S/U数量,不含正在预留的槽 */
IEC104_SendBufferFrameState_t i_frame_state; /* 唯一当前I槽的元数据 */
IEC104_IFrameTx_t i_frame_snapshot; /* 原Prepare快照,交回Link.Complete使用 */
uint8_t i_apdu[IEC104_MAX_APDU_LEN]; /* 唯一当前I帧,Commit_Send_Completion成功后可复用 */
uint8_t has_i_frame; /* 0/1:I槽已提交,包括尚未写出字节的当前帧 */
uint8_t has_reservation; /* 0/1:当前是否存在尚未Commit/Cancel的预留 */
uint8_t reservation_is_i_frame; /* 0/1:预留是否为I槽;无预留时必须为0 */
uint8_t is_initialized; /* 1表示Init成功,不表示TCP存活 */
uint64_t connection_generation; /* 本次连接的非零、不复用代次 */
uint64_t next_frame_serial; /* 下一个预留身份,耗尽时报错而不回绕 */
} IEC104_SendBuffer_t;
/* 不复制协议序号边界;Link管序号,AsduQueue保留原文,Manager保存确认记录。 */
typedef struct {
uint64_t connection_generation; /* 查询时的绑定代次 */
uint16_t control_count; /* 已提交控制帧数 */
uint16_t i_frame_ns; /* 仅has_i_frame=1时有效 */
uint8_t has_i_frame; /* 当前是否有已提交I帧 */
uint8_t has_reservation; /* 当前是否还有未结束的预留 */
uint8_t is_idle; /* 当前无I帧、S/U或预留;完成发送后也可重新空闲 */
uint8_t control_has_room; /* 无预留且控制槽未满;只表示容量,不保证编号可分配 */
} IEC104_SendBufferStatus_t;
/**
* 功能:初始化新连接;control_capacity>=1,generation非零且跨连接不复用。
* 输入参数:control_frames——持续有效的调用方数组;control_capacity——1..65535个槽;
* connection_generation——非零且跨连接不复用的代次。
* 输出参数:buffer——非NULL,仅成功时写入空闲状态。
* 返回值:OK或ERROR,失败不改buffer。
* 说明:control_frames由调用方持有;无malloc、无锁,全部操作串行,存储/参数不得重叠。
* 控制帧有独立容量,不再设置control_reserve_count或APDU节点池。
*/
extern IEC104_SendBufferResult_t IEC104_SendBuffer_Init(
IEC104_SendBuffer_t *buffer, IEC104_SendBufferControlFrame_t *control_frames,
uint16_t control_capacity, uint64_t connection_generation);
/**
* 功能:查询只返回数值副本,OK写status;失败不改输出,不提供已完成/ACK协议边界。
* 输入参数:buffer——有效发送缓冲。
* 输出参数:status——非NULL,仅OK时写入数值副本。
* 返回值:OK或ERROR,失败不改输出。
* 说明:i_frame_ns仅在has_i_frame=1时有效;is_idle表示当前为空闲,
* 不证明TCP为新连接,也不报告Link的完成或ACK边界。
*/
extern IEC104_SendBufferResult_t IEC104_SendBuffer_Get_Status(
const IEC104_SendBuffer_t *buffer, IEC104_SendBufferStatus_t *status);
/**
* 功能:S/U预留队尾,容量不足FULL;I只能在无当前帧且控制队列为空时预留,否则BUSY。
* 输入参数:buffer——有效发送缓冲。
* 输出参数:reservation——仅OK时返回frame_id和6字节可写APDU存储。
* 返回值:OK、FULL、BUSY或ERROR,含义见Reserve_Frame。
* 说明:任一时刻只有一个预留;OK写输出,非OK不改对象或输出。编号耗尽ERROR。
* 先取得存储,再调用会产生发送义务的Link构帧接口。
*/
extern IEC104_SendBufferResult_t IEC104_SendBuffer_Reserve_S_U_Frame(
IEC104_SendBuffer_t *buffer, IEC104_SendBufferReservation_t *reservation);
/**
* 功能:预留唯一当前I帧的APDU存储。
* 输入参数:buffer——有效发送缓冲。
* 输出参数:reservation——仅OK时返回frame_id和最大255字节可写存储。
* 返回值:OK、BUSY或ERROR,含义见Reserve_Frame。
* 说明:此处尚未分配协议N(S);后续由Link.Prepare_I_Frame在实际发送准备时分配。
*/
extern IEC104_SendBufferResult_t IEC104_SendBuffer_Reserve_I_Frame(
IEC104_SendBuffer_t *buffer, IEC104_SendBufferReservation_t *reservation);
/**
* 功能:I提交为唯一当前帧,S/U追加到独立控制FIFO;校验APCI、身份和原始快照。
* 输入参数:buffer/frame_id——本次预留及身份;frame_type/apdu_length——实际报文描述;
* i_frame_snapshot——I帧必须传原Prepare快照,S/U必须为NULL;
* queued_at_ms——原始本地发送期限起点,使用单调毫秒,允许0。
* 输出参数:buffer及对应槽元数据——成功时保存描述、时间、快照并解除预留。
* 返回值:OK或ERROR;ERROR不修改缓冲状态,调用前存在的合法预留仍保留。
* 说明:已准备的当前I帧(包括EAGAIN后尚未写出字节)先完成,再发后来的控制帧。
* 禁止交错写两个APDU,禁止撤回已编号的帧;Prepare后Commit失败须结束连接。
* Commit成功后借用的构帧指针不可再写;queued_at_ms是原始本地发送期限起点。
*/
extern IEC104_SendBufferResult_t IEC104_SendBuffer_Commit_Frame(
IEC104_SendBuffer_t *buffer, IEC104_SendFrameId_t frame_id,
IEC104_SendBufferFrameType_t frame_type, uint16_t apdu_length,
const IEC104_IFrameTx_t *i_frame_snapshot, uint64_t queued_at_ms);
/**
* 功能:核对唯一预留身份后归还存储;仅限Link尚未构帧成功时使用,不回滚协议状态。
* 输入参数:buffer——有效缓冲;frame_id——Reserve返回的完整身份。
* 输出参数:buffer——成功时清除预留标志,不推进控制队列或发布当前I帧。
* 返回值:OK或ERROR,身份不符或没有预留时不修改状态。
* 说明:调用方保证Link尚未成功构帧;这里只归还存储,不回滚Link,不复用frame_serial。
*/
extern IEC104_SendBufferResult_t IEC104_SendBuffer_Cancel_Reservation(
IEC104_SendBuffer_t *buffer, IEC104_SendFrameId_t frame_id);
/**
* 功能:查看已提交帧,不挑选业务;已写完但未提交完成时仍返回OK且remaining_bytes为0。上层入口为Manager.Prepare_Next_Send。
* 输入参数:buffer——有效发送缓冲。
* 输出参数:head_info——非NULL,仅OK时写入身份、元数据及剩余字节借用指针。
* 返回值:OK有当前帧,EMPTY没有已提交报文,ERROR表示参数或状态非法。
* 说明:优先续传当前I帧,否则取控制队首;不选择ASDU、不重新编号。
* 已写完但尚未Commit_Send_Completion的帧仍返回OK,此时remaining_bytes为0。
* 原始帧即使因EAGAIN尚未写出字节也保持当前位置,借用在完成释放前结束。
*/
extern IEC104_SendBufferResult_t IEC104_SendBuffer_Peek_Send_Head(
const IEC104_SendBuffer_t *buffer, IEC104_SendBufferHeadInfo_t *head_info);
/**
* 功能:匹配当前帧,记录实际成功写入的增量;0不推进,部分写入OK,整帧FRAME_WRITTEN。
* 输入参数:buffer/frame_id——当前缓冲及帧身份;bytes_written_now——不超过剩余长度的增量;
* written_at_ms——本次实际写入时刻;仅整帧写完时校验不早于queued_at_ms并保存。
* 输出参数:buffer——推进written_bytes;整帧写完时登记written_at_ms。
* 返回值:OK尚未完整;FRAME_WRITTEN恰好整帧写完;ERROR表示身份、长度、时间或状态非法。
* 说明:最后一次时间不得早于入队时刻;已写完不能重报,输出缓冲借用须在完成前结束。
* 同帧最多一个未回报写操作;不执行I/O、不调用Link.Complete。
*/
extern IEC104_SendBufferResult_t IEC104_SendBuffer_Record_Written_Bytes(
IEC104_SendBuffer_t *buffer, IEC104_SendFrameId_t frame_id,
uint16_t bytes_written_now, uint64_t written_at_ms);
/**
* 功能:对应Link.Complete及I帧本地完成记录提交后调用;TESTFR_CON无Link.Complete。成功释放当前槽,不等待ACK。
* 输入参数:buffer——有效缓冲;frame_id——本次已经完成的当前帧身份。
* 输出参数:buffer——清除has_i_frame,或推进控制队首并减少数量。
* 返回值:OK或ERROR;未写完、身份不符或新队首非法时不释放。
* 说明:调用方须先提交该帧适用的Link完成结果;I帧还须登记本地完成事实。
* I槽不等待ACK;Manager继续保留发送记录,NORMAL原文可能仍在Queue或已被覆盖。
* TESTFR_CON没有Link完成接口;本接口本身不分派Link完成或解释ACK。
*/
extern IEC104_SendBufferResult_t IEC104_SendBuffer_Commit_Send_Completion(
IEC104_SendBuffer_t *buffer, IEC104_SendFrameId_t frame_id);
/**
* 功能:1到期、0无帧/未到期、-1非法;部分写入不续期,已写完未释放的帧也参与检查。I帧ACK的t1由Manager查询。
* 输入参数:buffer/connection_generation——有效缓冲及匹配代次;
* now_ms——当前单调毫秒;timeout_ms——非零期限。
* 输出参数:无,不修改进度或关闭连接。
* 返回值:1到期,0无当前帧或未到期,-1参数/状态非法或当前时刻早于起点。
* 说明:从原queued_at_ms作差,等于期限即到期;部分写入和重复查询不续期。
* 尚未提交到本缓冲区的ASDU排队时间不在此计算;I帧等待ACK的t1由Manager检查。
* 已整帧写完但尚未提交完成释放的帧仍在检查范围内。
*/
extern int IEC104_SendBuffer_Head_Send_Expired(
const IEC104_SendBuffer_t *buffer, uint64_t connection_generation,
uint64_t now_ms, uint32_t timeout_ms);
/**
* 功能:旧I/O结束后清除引用;不关闭TCP,不释放调用方数组。
* 输入参数:buffer——待终止对象,允许NULL。
* 输出参数:buffer——非NULL时清零;调用方控制数组不清零、不释放。
* 返回值:无。
* 说明:不关闭socket、不取消异步I/O,调用方必须先结束旧I/O及报文字节借用。
*/
extern void IEC104_SendBuffer_Abort(IEC104_SendBuffer_t *buffer);
#ifdef __cplusplus
}
#endif
#endif /* IEC104_SENDBUFFER_H */