/* 子站发送字节存储:一帧当前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 */