/**
 * 主站启停公开接口：本端为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 */