/******************************************************************************
 
                  版权所有 (C), 2018-2099, Radkil
 
 ******************************************************************************
  文 件 名   : rd_udp.h
  版 本 号   : 初稿
  作    者   : Radkil
  生成日期   : 2026年11月3日
  最近修改   :
  功能描述   : 跨平台 UDP 传输抽象层公共头文件 (TComCtrl 集成)
              与 rd_serial 同构: 创建 TComCtrl + 内部接收线程,
              平台差异在 peripheral/rd_udp.c 内通过宏处理:
                USE_LWIP              → lwip/sockets.h (STM32 固件, 需 tcpip 栈已启动)
                BUILD_PLATFORM_LINUX  → POSIX socket
                BUILD_PLATFORM_WIN32  → winsock2
  
  修改历史   :
  1.日    期   : 2026年11月3日
    作    者   : Radkil
    修改内容   : 创建文件
 
******************************************************************************/
 
#ifndef __RD_UDP_H__
#define __RD_UDP_H__
 
#ifdef __cplusplus
#if __cplusplus
extern "C"{
#endif
#endif /* __cplusplus */
 
/*==============================================*
 *      include header files                    *
 *----------------------------------------------*/
#include <stdint.h>
#include "common.h"
#include "com.h"
 
/*==============================================*
 *      constants or macros define              *
 *----------------------------------------------*/
#define RD_UDP_IP_MAX   16      /* 点分十进制 IP 最大长度("255.255.255.255"+0) */

/* ── UDP 广播设备发现 (beacon) 参数 ──
 * 机制: 各实例按 RD_UDP_BEACON_INTERVAL_MS 周期向
 * 255.255.255.255:RD_UDP_DISCOVERY_PORT 广播 22B beacon,
 * 收到方校验 magic 后记录 (源IP, data_port) 进 peer 表,
 * 数据帧扇出给所有 RD_UDP_PEER_TIMEOUT_MS 内活跃的 peer */
#define RD_UDP_DISCOVERY_PORT     9005   /* 发现通道端口 (beacon 收发, 两端一致) */
#define RD_UDP_PEER_MAX           8      /* peer 表容量 (满时覆盖最旧) */
#define RD_UDP_PEER_TIMEOUT_MS    5000   /* peer 存活超时 (beacon 周期整数倍, 防误剔) */
#define RD_UDP_BEACON_INTERVAL_MS 1000   /* beacon 广播周期 */
 
/* UDP 链路配置 */
typedef struct
{
    const char *m_psRemoteIp;   /* 对端 IP (发送目的), 点分十进制;
                                 * NULL/"" = 纯发现模式 (数据帧扇出给 beacon 发现的活 peer) */
    int         m_iRemotePort;  /* 对端端口 (仅固定 IP 模式使用; 纯发现模式忽略, 可 0) */
    int         m_iLocalPort;   /* 本地绑定端口 (接收), 0 = 只发不收 (beacon data_port 同源) */
    int         m_iTxSrcPort;   /* 发送源端口 (对齐固件 7006 双 PCB 语义),
                                 * 0 = 复用接收 socket (源端口 = 本地端口) */
    uint32_t    m_uiBufSize;    /* TComCtrl 环形缓冲区大小 */
    const char *m_psName;       /* 设备名 (beacon 携带, 对端日志可见), NULL = 不填 */
    cbk_ComCheck m_pfCheck;
    cbk_ComDecode m_pfDecode;
} TRdUdpCfg;
 
/*==============================================*
 *      routines' or functions' implementations *
 *----------------------------------------------*/
 
/**
 * @brief  创建 UDP 链路 TComCtrl (内部启动接收线程 + beacon 发现线程)
 * @param  _ptCfg  UDP 配置 (不可为空; m_psRemoteIp 可为 NULL/"")
 * @return TComCtrl* 成功, NULL 失败
 * @note   m_psRemoteIp 为 NULL/"" 时进入纯发现模式: 不再要求配置对端,
 *         数据帧自动扇出给 beacon 发现的活 peer (rd_udp.h 宏可调);
 *         非空时固定直连与发现并存 (扇出 = 固定对端 + 全部活 peer)。
 *         发现 socket 绑定失败仅降级关闭发现 (log_w), 链路创建不受影响。
 *         USE_LWIP 平台需先完成 tcpip 栈/netif 初始化再调用
 *         (SO_REUSEADDR 需 LWIP_SO_REUSE);
 *         发送回调经模块级静态上下文解析, 每进程仅支持一条 UDP 链路
 *         (与 rd_serial 的单实例约束同模式, 不改 com.c)
 */
TComCtrl *Rd_UdpCreate(const TRdUdpCfg *_ptCfg);
 
/**
 * @brief  关闭并销毁 UDP 链路 TComCtrl
 * @param  _ptComCtrl  TComCtrl 控制块
 */
void Rd_UdpClose(TComCtrl *_ptComCtrl);
 
#ifdef __cplusplus
#if __cplusplus
}
#endif
#endif /* __cplusplus */
 
#endif /* __RD_UDP_H__ */