/*
 * 模块名称：SNTP 配置（[sntp] 段）
 * 模块功能：板端 SNTP 客户端配置——RAM 副本 + 工厂默认 + 读写出口
 *           （[sntp] 段：enable / server1 / server2 / poll_min）；段描述符
 *           由 net_cfg.c 在 net_cfg_load 里组好交引擎（分层门禁 layer-deps：
 *           本模块不 include 引擎头）；消费者（App/sync/time_sntp.c）与 UI 页
 *           经 sntp_cfg_get() 只读访问，配置引擎属主仍为 defaultTask
 * 适用平台：STM32F407ZGTx / PC 模拟器（两端共用）
 * 作者：王建锋
 * 创建日期：2026-11-04
 * 修改记录：
 *     v1.0  2026-11-04  王建锋  创建初始版本（SNTP 客户端接入，#57 调研结论）
 *     v1.1  2026-11-04  王建锋  分层门禁口径：sntp_cfg_register 改为
 *                               sntp_cfg_data/sntp_cfg_defaults 数据口，
 *                               段描述符编排移 net_cfg.c（本模块不再依赖引擎头）
 */

#ifndef SNTP_CFG_H
#define SNTP_CFG_H

#ifdef __cplusplus
extern "C" {
#endif

#include <stdint.h>

/* 轮询周期合法范围（分钟）；范围外的存储值读取时回落工厂默认（同 [comm]
 * 频段自愈口径，见 iec104_comm.c 带外值自愈） */
#define SNTP_CFG_POLL_MIN_MIN  1u
#define SNTP_CFG_POLL_MIN_MAX  1440u

/* 工厂默认：enable=0（出厂不启用，调研 §6 产品口径）、服务器留空
 * （0.0.0.0 = 未配置，客户端跳过该服务器）、poll_min=60（1 小时） */
#define SNTP_CFG_DEF_ENABLE   0u
#define SNTP_CFG_DEF_SERVER   { 0u, 0u, 0u, 0u }
#define SNTP_CFG_DEF_POLL_MIN 60u

typedef struct {
    uint8_t enable;          /* 1 = 启用 SNTP 客户端；0 = 停用（默认） */
    uint8_t server_pri[4];   /* 主 SNTP 服务器 IPv4（全零 = 未配置） */
    uint8_t server_bak[4];   /* 备 SNTP 服务器 IPv4（全零 = 无备） */
    uint16_t poll_min;       /* 成功后的轮询周期（分钟，1~1440） */
} sntp_cfg_t;

/*
 * 函数功能：取 [sntp] 段 RAM 副本（引擎注册专用写入口）
 * 入口参数：无
 * 返回值：RAM 配置副本指针（恒非空，静态常驻）  sntp_cfg_t *
 * 限定条件：仅供 net_cfg.c 组 [sntp] 段描述符交配置引擎（net_cfg_load 编排）；
 *          分层门禁 layer-deps：本模块不 include cfg_file.h，段注册集中在
 *          net_cfg.c（同层基线文件）完成
 */
sntp_cfg_t *sntp_cfg_data(void);

/*
 * 函数功能：取工厂默认值（引擎注册 p_defaults 指向）
 * 入口参数：无
 * 返回值：工厂默认结构指针（只读，恒非空）  const sntp_cfg_t *
 * 限定条件：同上，net_cfg.c 组段描述符专用
 */
const sntp_cfg_t *sntp_cfg_defaults(void);

/*
 * 函数功能：取 [sntp] 段 RAM 副本（只读）
 * 入口参数：无
 * 返回值：恒非 NULL（静态常驻，load 前初值 = 工厂默认）  const sntp_cfg_t *
 * 限定条件：无
 * 函数说明：defaultTask poll 重载瞬间可能读到撕裂值——IPv4 4 字节 / uint16
 *          在本平台是单条 LDR 指令天然原子，enable 单字节同理；即便撕裂，
 *          SNTP 客户端最坏多用一次旧值，下一轮自愈（配置变更本就罕见）
 */
const sntp_cfg_t *sntp_cfg_get(void);

/*
 * 函数功能：更新 RAM 副本（不写盘）
 * 入口参数：p_new - 新配置（NULL 忽略）  const sntp_cfg_t *
 * 返回值：无
 * 限定条件：UI 编辑路径专用（net_cfg_set 同口径）；写盘须走
 *          net_cfg_save_request 整档链（属主 defaultTask）
 */
void sntp_cfg_set(const sntp_cfg_t *p_new);

/*
 * 函数功能：取轮询周期（带外自愈读出口）
 * 入口参数：无
 * 返回值：合法范围内 = 存储值；0 或 >1440 = 工厂默认 60  uint16_t
 * 限定条件：无
 * 函数说明：不改写 RAM 副本（UI 显示的仍是用户写的原值，避免"保存后
 *          数字自己变了"的困惑）；消费方（time_sntp）用本口而非裸字段
 */
uint16_t sntp_cfg_poll_min(void);

#ifdef __cplusplus
}
#endif

#endif /* SNTP_CFG_H */