/******************************************************************************

                  版权所有 (C), 2018-2099, Radkil

 ******************************************************************************
  文 件 名   : ATParser.h
  版 本 号   : 初稿
  作    者   : Radkil
  生成日期   : 2026年3月14日星期六
  最近修改   :
  功能描述   : ATParser.c 的头文件
  
  修改历史   :
  1.日    期   : 2026年3月14日星期六
    作    者   : Radkil
    修改内容   : 创建文件

******************************************************************************/

/*----------------------------------------------*
 * 外部变量说明                                 *
 *----------------------------------------------*/

/*----------------------------------------------*
 * 外部函数原型说明                             *
 *----------------------------------------------*/

/*----------------------------------------------*
 * 内部函数原型说明                             *
 *----------------------------------------------*/

/*----------------------------------------------*
 * 全局变量                                     *
 *----------------------------------------------*/

/*----------------------------------------------*
 * 模块级变量                                   *
 *----------------------------------------------*/

/*----------------------------------------------*
 * 常量定义                                     *
 *----------------------------------------------*/

/*----------------------------------------------*
 * 宏定义                                       *
 *----------------------------------------------*/

#ifndef __ATPARSER_H__
#define __ATPARSER_H__


#ifdef __cplusplus
#if __cplusplus
extern "C"{
#endif
#endif /* __cplusplus */


/*==============================================*
 *      include header files                    *
 *----------------------------------------------*/
#include <stdint.h>
#include <string.h>
#include <stdbool.h>
#include <stdlib.h>

/*==============================================*
 *      constants or macros define              *
 *----------------------------------------------*/
#define AT_RX_BUFFER_SIZE   256       // 接收缓冲区大小
#define AT_CMD_MAX_LEN      64        // 单条命令最大长度
#define AT_MAX_RESPONSES    8         // 支持的最大响应回调数量

/**
 * @brief AT 命令执行结果状态
 */
typedef enum {
    AT_OK,              // 成功
    AT_ERROR,           // 失败 (ERROR)
    AT_TIMEOUT,         // 超时
    AT_BUSY,            // 模块忙
    AT_UNKNOWN          // 未知响应
} at_status_t;

/**
 * @brief 响应结构体
 */
typedef struct {
    const char *prefix;             // 响应前缀，例如 "+CSQ:" 或 "OK"
    void (*callback)(const char *data, int len); // 匹配到该前缀时的回调
} at_response_item_t;

/**
 * @brief AT 解析器主结构体
 */
typedef struct {
    uint8_t rx_buffer[AT_RX_BUFFER_SIZE]; // 环形缓冲区
    uint16_t head;                        // 写指针
    uint16_t tail;                        // 读指针
    
    char cmd_buffer[AT_CMD_MAX_LEN];      // 当前正在解析的命令缓冲
    uint16_t cmd_len;                     // 当前命令长度
    
    bool is_waiting_response;             // 是否正在等待响应
    uint32_t wait_start_time;             // 等待开始的时间戳 (ms)
    uint32_t timeout_ms;                  // 超时时间设置
    
    at_status_t last_status;              // 最后一次执行状态
    
    // 注册的响应列表
    at_response_item_t responses[AT_MAX_RESPONSES];
    uint8_t response_count;

    // 硬件抽象层回调 (用户需实现)
    void (*hw_send)(const uint8_t *data, uint16_t len);
    uint32_t (*hw_get_tick)(void); // 获取系统毫秒时间
} at_parser_t;

/*==============================================*
 *      project-wide global variables           *
 *----------------------------------------------*/



/*==============================================*
 *      routines' or functions' implementations *
 *----------------------------------------------*/
/**
 * @brief 初始化解析器
 * @param parser 解析器实例指针
 * @param send_cb 发送数据回调 (必须实现)
 * @param tick_cb 获取时间戳回调 (必须实现)
 */
void at_parser_init(at_parser_t *parser, 
                    void (*send_cb)(const uint8_t*, uint16_t), 
                    uint32_t (*tick_cb)(void));

/**
 * @brief 注册响应前缀和回调
 * @param parser 解析器实例
 * @param prefix 前缀字符串 (如 "+CSQ:")
 * @param cb 回调函数，当收到该前缀时触发
 * @return true 成功，false 列表已满
 */
bool at_parser_register_response(at_parser_t *parser, const char *prefix, void (*cb)(const char*, int));

/**
 * @brief 将串口接收到的字节喂给解析器 (需在中断或轮询中调用)
 * @param parser 解析器实例
 * @param data 接收到的字节
 */
void at_parser_feed(at_parser_t *parser, uint8_t data);

/**
 * @brief 发送 AT 命令并等待响应 (阻塞式)
 * @param parser 解析器实例
 * @param cmd 命令字符串 (不含 \r\n，函数会自动添加)
 * @param timeout_ms 超时时间
 * @return AT_OK, AT_ERROR, AT_TIMEOUT 等
 */
at_status_t at_parser_send_cmd(at_parser_t *parser, const char *cmd, uint32_t timeout_ms);

/**
 * @brief 发送原始数据 (不等待响应，用于发送透传数据)
 * @param parser 解析器实例
 * @param data 数据
 * @param len 长度
 */
void at_parser_send_raw(at_parser_t *parser, const uint8_t *data, uint16_t len);

/**
 * @brief 后台处理函数 (需在主循环中调用，处理超时逻辑)
 * @param parser 解析器实例
 */
void at_parser_process(at_parser_t *parser);

#ifdef __cplusplus
#if __cplusplus
}
#endif
#endif /* __cplusplus */


#endif /* __ATPARSER_H__ */