175 lines
11 KiB
C
175 lines
11 KiB
C
/**
|
||
* 主站启停公开接口：本端为CONTROLLING，主动发送STARTDT/STOPDT_ACT并接收CON。
|
||
* START：Prepare -> 实际发送 -> Complete -> Handle CON；
|
||
* STOP：Request -> Prepare（S/ACT）-> 按tx类型发送并Complete -> Handle CON。
|
||
* 主站的两个CON处理接口都只接受CON_WAITING过程，不缓存ACT完成前的CON；
|
||
* 调用方必须先提交已知的ACT完整发送结果。I/S与TESTFR使用Common.h的公共接口。
|
||
* 主动启停须等本次CON成功处理后再发起下一过程；忙或重复请求不得重发ACT或重启计时。
|
||
* 实现见Master_StartStop.c；Internal.h仅供实现协作，不供业务调用。
|
||
*/
|
||
#ifndef IEC104_LINK_MASTER_STARTSTOP_H
|
||
#define IEC104_LINK_MASTER_STARTSTOP_H
|
||
|
||
#include "IEC104_Link_Common.h"
|
||
|
||
#ifdef __cplusplus
|
||
extern "C" {
|
||
#endif
|
||
|
||
/**
|
||
* 适用端：仅控制站。
|
||
* 功能：生成主动启动请求STARTDT_ACT，并记录等待最终发送结果的状态。
|
||
* 输入参数：state——链路状态；request——输出缓冲；capacity——实际容量，至少6字节。
|
||
* 输出参数：request——写入68 04 07 00 00 00；state——主动请求转ACT_SEND_PENDING。
|
||
* 返回值：6表示生成新请求；0表示已有启停过程或链路已启动；
|
||
* -1表示参数或状态非法。返回0或-1时不修改状态和输出缓冲。
|
||
* 说明：仅控制站可调用，只允许从STOPPED且过程IDLE时开始；不执行网络发送，不修改序号。
|
||
* 返回6后必须提交最终发送结果；同一连接的三个主动启动接口须串行调用。
|
||
* ACT成功入队后，控制站可预留命令I帧，不必等待CON；ACT必须在
|
||
* 同一FIFO中先于这些I帧发送和提交Complete。未受理STARTDT前仍禁止I帧。
|
||
*/
|
||
extern int IEC104_Link_Prepare_Startdt_Act(IEC104_LinkState_t *state,
|
||
uint8_t *request,
|
||
uint16_t capacity);
|
||
|
||
/**
|
||
* 适用端：仅控制站。
|
||
* 功能：记录主动STARTDT_ACT的最终发送结果。
|
||
* 输入参数：state——链路状态；sent_len——最终累计成功发送字节数，恰好6表示成功。
|
||
* 输出参数：有匹配ACT时，完整成功转START_CON_WAITING，发送失败回IDLE；
|
||
* 无匹配过程或状态/角色非法时不修改状态。所有分支均不改变稳定状态。
|
||
* 返回值：OK表示完整发送并开始等待CON；IGNORED表示没有ACT等待完成；
|
||
* FATAL表示状态/角色非法或发送失败。
|
||
* 说明：失败后上层须断连。部分写入未结束时不要调用；调用方必须与具体枚举值比较。
|
||
* 状态合法但无匹配ACT时先返回IGNORED，不检查sent_len；成功提交后才处理CON。
|
||
* ACT失败后不得继续发送其后已预留的I帧，也不得回滚vs后复用当前连接。
|
||
*/
|
||
extern IEC104_LinkResult_t IEC104_Link_Complete_Startdt_Act_Send(
|
||
IEC104_LinkState_t *state, int sent_len);
|
||
|
||
/**
|
||
* 适用端：仅控制站。
|
||
* 功能：接受正在等待的STARTDT_CON，完成本端主动启动。
|
||
* 输入参数：state——链路状态；apci——已通过APCI解析的STARTDT_CON。
|
||
* 输出参数：过程回IDLE，dt_state进入STARTED。
|
||
* 返回值：OK表示接受并提交；IGNORED表示当前未等待CON；
|
||
* FATAL表示参数、角色、报文或状态非法。
|
||
* 说明：仅控制站可调用；不修改序号、确认位置及TESTFR状态。
|
||
* START_ACT_SEND_PENDING时返回IGNORED，不保存提前CON；须先完成本ACT的Complete。
|
||
* 报文/角色/状态检查先于等待过程检查，非法输入不会因当前未等待而被忽略。
|
||
*/
|
||
extern IEC104_LinkResult_t IEC104_Link_Handle_Startdt_Con(
|
||
IEC104_LinkState_t *state, const IEC104_ApciInfo_t *apci);
|
||
|
||
/**
|
||
* 适用端：控制站与被控站；实际超时只适用于控制站等待CON的过程。
|
||
* 功能：判断主动STARTDT_ACT发送成功后等待STARTDT_CON是否达到t1超时。
|
||
* 输入参数：state——链路状态；elapsed_ms——等待STARTDT_CON的毫秒数；
|
||
* t1_ms——t1配置值，必须大于0。
|
||
* 输出参数：无，不修改链路状态。
|
||
* 返回值：1表示正在等待STARTDT_CON且已经超时；0表示未等待或尚未超时；
|
||
* -1表示参数或链路状态非法。
|
||
* 说明：调用方在Complete_Startdt_Act_Send()成功后，以ACT实际完整发送时刻为单调计时起点，
|
||
* Handle_Startdt_Con()成功时取消计时；返回1后的断连由调用方执行。
|
||
* 同一次ACT的计时起点只记录一次；重复调用、业务收发或无匹配的完成事件不重置起点。
|
||
* 合法被控站没有对应等待过程，返回0；角色与过程组合非法仍返回-1。
|
||
*/
|
||
extern int IEC104_Link_T1_Startdt_Con_Expired(
|
||
const IEC104_LinkState_t *state,
|
||
uint32_t elapsed_ms, uint32_t t1_ms);
|
||
|
||
/**
|
||
* 适用端：仅控制站。
|
||
* 功能：受理主动停止意图，进入STOP_REQUESTED，立即禁止新的业务I帧预留。
|
||
* 输入参数：state——控制站链路状态。
|
||
* 输出参数：ACCEPTED时dt_procedure转为STOP_REQUESTED，保留稳定状态和序号。
|
||
* 返回值：ACCEPTED表示新受理；ALREADY_STOPPED表示已经停止；IN_PROGRESS表示
|
||
* 停止已在进行；BUSY表示存在其他启停过程；REQUEST_ERROR表示参数、角色
|
||
* 或状态非法。除ACCEPTED外均不修改状态。
|
||
* 说明：不构帧；重复请求不重置进度。受理后调用Prepare_Stopdt_Request推进，
|
||
* 接收数据和发送完成事件到达后继续推进；等待期间停止意图始终保留。
|
||
* 只有ACCEPTED代表新过程；其余结果不得重启已有的准备/排队或CON等待计时。
|
||
* 等待CON的t1须等ACT完整发送成功后开始，不能从本接口受理时刻开始计算。
|
||
*/
|
||
extern IEC104_StopdtRequestResult_t IEC104_Link_Request_Stopdt(
|
||
IEC104_LinkState_t *state);
|
||
|
||
/**
|
||
* 适用端：仅控制站。
|
||
* 功能：推进已受理的主动停止，按需生成S确认或STOPDT_ACT。
|
||
* 输入参数：state——控制站链路状态；request——输出缓冲；capacity——至少6字节；
|
||
* tx——本次报文类型和长度的输出地址，须随报文保存在FIFO节点中。
|
||
* 输出参数：FRAME_READY时写入request和tx，并提交S确认或STOPDT_ACT待发送状态。
|
||
* 返回值：FRAME_READY表示生成报文；NOT_ACTIVE表示没有对应停止过程；
|
||
* WAIT_SEND表示等待已有S/ACT发送完成；WAIT_PEER_CON表示等待STOPDT_CON；
|
||
* PREPARE_ERROR表示参数、角色、状态或编码结果非法。
|
||
* 非FRAME_READY时不修改状态和输出；NOT_ACTIVE不会隐式受理停止请求。
|
||
* 说明：在途S帧覆盖当前V(R)时可生成ACT，否则等待S完成后补确认。
|
||
* 本端未获确认的I帧不阻止生成ACT；收到CON时检查V(A)==V(S)及接收确认覆盖。
|
||
* 调用方须先取得有界FIFO节点，再构帧并按生成顺序排队；无法入队须断连。
|
||
* 将tx与报文共同保存：S_ACK完成调用Complete_S_Ack_Send，ACT完成调用
|
||
* Complete_Stopdt_Act_Send。
|
||
* 同一连接按FIFO提交完成事件，不能因当前状态改变而重新猜测报文类型。
|
||
* 等待CON的t1仍从ACT完整发送成功开始；准备/排队超时由连接层管理。
|
||
*/
|
||
extern IEC104_StopdtPrepareResult_t IEC104_Link_Prepare_Stopdt_Request(
|
||
IEC104_LinkState_t *state, uint8_t *request, uint16_t capacity,
|
||
IEC104_StopdtTx_t *tx);
|
||
|
||
/**
|
||
* 适用端：仅控制站。
|
||
* 功能：记录主动STOPDT_ACT的最终发送结果。
|
||
* 输入参数：state——链路状态；sent_len——最终累计成功发送字节数，恰好6表示成功。
|
||
* 输出参数：有匹配ACT时，完整成功转STOP_CON_WAITING，发送失败回IDLE；
|
||
* 无匹配过程或状态/角色非法时不修改状态。
|
||
* 返回值：OK表示完整发送并开始等待CON；IGNORED表示没有ACT等待完成；
|
||
* FATAL表示状态/角色非法或发送失败。
|
||
* 说明：失败后上层须断连。部分写入未结束时不要调用；调用方必须与具体枚举值比较。
|
||
* 状态合法但无匹配ACT时先返回IGNORED，不检查sent_len；匹配ACT发送失败时
|
||
* dt_state仍为STARTED，不能因过程回IDLE而继续业务发送。
|
||
* 成功提交后才处理STOPDT_CON；本接口不能代替前序S帧的Complete_S_Ack_Send。
|
||
*/
|
||
extern IEC104_LinkResult_t IEC104_Link_Complete_Stopdt_Act_Send(
|
||
IEC104_LinkState_t *state, int sent_len);
|
||
|
||
/**
|
||
* 适用端：仅控制站。
|
||
* 功能：接受正在等待的STOPDT_CON，完成本端主动停止。
|
||
* 输入参数：state——链路状态；apci——已通过APCI解析的STOPDT_CON。
|
||
* 输出参数：过程回IDLE，dt_state进入STOPPED。
|
||
* 返回值：OK表示接受并提交；IGNORED表示当前未等待CON；FATAL表示参数、角色、
|
||
* 报文或状态非法、发送方向未排空，或接收数据未确认且无完整覆盖的在途S帧。
|
||
* 说明：要求V(A)==V(S)，并且acked_nr==V(R)或在途S帧s_ack_nr==V(R)。
|
||
* 覆盖完整时允许CON早于本地S完成回调；保留S待完成状态和确认快照，
|
||
* 后续Complete_S_Ack_Send成功才推进确认位置，发送失败仍要求上层断连。
|
||
* 非OK结果不修改状态；始终不修改序号、确认位置及TESTFR状态。
|
||
* STOP_ACT_SEND_PENDING时返回IGNORED且不缓存CON；允许S完成回调晚到，
|
||
* 不代表允许本ACT完成回调晚到。V(A)==V(S)时，公共序号约束保证
|
||
* sent_vs也已经到达vs；这些I帧的本地发送完成必须先于ACK提交。
|
||
*/
|
||
extern IEC104_LinkResult_t IEC104_Link_Handle_Stopdt_Con(
|
||
IEC104_LinkState_t *state, const IEC104_ApciInfo_t *apci);
|
||
|
||
/**
|
||
* 适用端：控制站与被控站；实际超时只适用于控制站等待CON的过程。
|
||
* 功能：判断主动STOPDT_ACT发送成功后等待STOPDT_CON是否达到t1超时。
|
||
* 输入参数：state——链路状态；elapsed_ms——等待STOPDT_CON的毫秒数；
|
||
* t1_ms——t1配置值，必须大于0。
|
||
* 输出参数：无，不修改链路状态。
|
||
* 返回值：1表示正在等待STOPDT_CON且已经超时；0表示未等待或尚未超时；
|
||
* -1表示参数或链路状态非法。
|
||
* 说明：调用方在Complete_Stopdt_Act_Send()成功后，以ACT实际完整发送时刻为单调计时起点，
|
||
* Handle_Stopdt_Con()成功时取消计时；返回1后的断连由调用方执行。
|
||
* 同一次ACT的计时起点只记录一次；重复请求、I/S收发及WAIT_*结果均不重置起点。
|
||
* 合法被控站没有对应等待过程，返回0；角色与过程组合非法仍返回-1。
|
||
*/
|
||
extern int IEC104_Link_T1_Stopdt_Con_Expired(
|
||
const IEC104_LinkState_t *state,
|
||
uint32_t elapsed_ms, uint32_t t1_ms);
|
||
|
||
#ifdef __cplusplus
|
||
}
|
||
#endif
|
||
|
||
#endif /* IEC104_LINK_MASTER_STARTSTOP_H */
|