/*
 * 模块名称：Time SNTP — 板端 SNTP 客户端（UDP 48 字节报文）
 * 模块功能：按 [sntp] 段配置向主/备 SNTP 服务器发送 RFC 4330 请求、校验应答
 *           （originate 精确匹配 + 源地址 + mode/stratum/LI/KoD）、计算钟差并
 *           按阈值步进本地墙钟（sys_clock_set_unix，钟面 = 本地时间 UTC+8），
 *           首次成功后置 SYS_EVT_TIMESYNC_READY；报文编解码用 vendor 的
 *           coreSNTP serializer（Lib/coreSNTP，MIT）
 * 适用平台：STM32F407ZGTx + CH395F（timeSyncTask 内运行，模拟器不编）
 * 作者：王建锋
 * 创建日期：2026-11-04
 */

#ifndef TIME_SNTP_H
#define TIME_SNTP_H

#ifdef __cplusplus
extern "C" {
#endif

#include <stdint.h>

/*
 * 函数功能：SNTP 客户端节拍入口（幂等、非阻塞——除等待应答期一次 ≤50ms 收片）
 * 入口参数：net_gen - 调用方本轮读取的网络代次（net_get_generation()）  uint32_t
 * 返回值：无
 * 限定条件：**仅 timeSyncTask 上下文**调用（看门狗心跳由调用方在片间喂，
 *          本模块单次调用最长驻留 = 一个 50ms 收片，满足 100ms 抽样窗约束）
 * 函数说明：内部状态机 停用 → 到期 → 发送 → 等应答 → 步进/退避；配置
 *          （sntp_cfg_get()）每轮现读，代次变化自动弃旧 Socket 重开
 */
void time_sntp_run(uint32_t net_gen);

/*
 * 函数功能：取累计成功同步次数（诊断/测试锚点）
 * 入口参数：无
 * 返回值：成功次数（含死区内的"未步进但校验通过"）  uint32_t
 * 限定条件：无
 */
uint32_t time_sntp_sync_count(void);

/*
 * 函数功能：取最近一次校验通过应答的钟差（诊断锚点）
 * 入口参数：无
 * 返回值：钟差毫秒，截断到 int32；正 = 本地钟落后服务器；从未成功 = 0  int32_t
 * 限定条件：无
 */
int32_t time_sntp_last_offset_ms(void);

#ifdef __cplusplus
}
#endif

#endif /* TIME_SNTP_H */