#ifndef __DRV_BTN_H__
#define __DRV_BTN_H__

#ifdef __cplusplus
extern "C" {
#endif

#include "rtthread.h"
#include "stdint.h"
#include "string.h"
#include "stdlib.h"
#include "stdbool.h"
#include "drv_btn_interface.h"


/**
 * @brief 按键驱动状态枚举
 *
 * @details 该枚举定义了按键操作中的不同状态，用于状态机管理按键事件。
 */
typedef enum {
    BTN_DRV_STATE_PRESS_DOWN = 0,   /**< 按键按下状态 */
    BTN_DRV_STATE_PRESS_UP,         /**< 按键释放状态 */
    BTN_DRV_STATE_REPEAT_DOWN,      /**< 按键连按中（如双击过程中的第二次按下） */
    BTN_DRV_STATE_REPEAT_UP,        /**< 按键连按完成（所有连击结束） */
    BTN_DRV_STATE_LONG_PRESS_UP,    /**< 长按释放事件 */
} btn_drv_state_e;

/**
 * @brief 按键驱动电平枚举
 *
 * @details 该枚举定义了按键操作中的不同电平状态，用于表示按键是否被按下。
 */
typedef enum {
    BTN_DRV_LEVEL_INACTIVE = 0,     /**< 按键未激活（释放）状态 */
    BTN_DRV_LEVEL_ACTIVE,           /**< 按键激活（按下）状态 */
} btn_drv_level_e;

/**
 * @brief 按键驱动事件枚举
 *
 * @details 该枚举定义了按键驱动操作中可能触发的事件类型。
 */
typedef enum {
    BTN_DRV_EVENT_PRESS_DOWN = 0,   /**< 按键按下事件 */
    BTN_DRV_EVENT_PRESS_UP,         /**< 按键释放（弹起）事件 */
    BTN_DRV_EVENT_PRESS_REPEAT,     /**< 按键连按中（如双击过程中的第二次按下） */
    BTN_DRV_EVENT_PRESS_REPEAT_DONE,/**< 按键连按完成（所有连击结束） */
    BTN_DRV_EVENT_SINGLE_CLICK,     /**< 单击事件 */
    BTN_DRV_EVENT_DOUBLE_CLICK,     /**< 双击事件 */
    BTN_DRV_EVENT_MULTIPLE_CLICK,   /**< 多次点击事件（需配置次数） */
    BTN_DRV_EVENT_LONG_PRESS_START, /**< 长按开始事件（达到长按时间阈值） */
    BTN_DRV_EVENT_LONG_PRESS_HOLD,  /**< 长按保持事件（长按期间周期性触发） */
    BTN_DRV_EVENT_LONG_PRESS_UP,    /**< 长按释放事件 */
    BTN_DRV_EVENT_PRESS_END,        /**< 按键操作结束事件（一次完整的按下释放流程结束） */
    BTN_DRV_EVENT_MAX,              /**< 事件总数 */
    BTN_DRV_EVENT_NONE_PRESS = 0xFF,/**< 无按键按下状态 */
} btn_drv_event_e;

/**
 * @brief 按键驱动事件回调函数类型定义
 *
 * @param handle 触发事件的按键驱动句柄
 * @details 该类型定义了按键驱动事件的回调函数指针，用于处理按键事件。
 */
typedef void (*btn_drv_cb_t)(void *handle);

/**
 * @brief 按键驱动配置结构体
 *
 * @details 该结构体定义了按键驱动设备的属性和状态。
 */
typedef struct btn_drv_config {
    uint32_t ticks;                     /**< 当前状态已持续的扫描 tick 数（用于计时/阈值判断） */
    uint32_t long_press_ticks;          /**< 长按阈值（单位：tick） */
    uint32_t short_press_ticks;         /**< “连击等待窗口”阈值（单位：tick） */
    uint32_t long_press_hold_cnt;       /**< 长按保持（HOLD）已触发次数计数 */
    uint8_t repeat;                     /**< 已检测到的连续按下次数（1=单击，2=双击...） */
    uint8_t state: 3;                   /**< 状态机当前状态（见上方 PRESS_*） */
    uint8_t debounce_cnt: 4;            /**< 去抖计数器：采样与稳定电平不一致时累加，达到阈值后翻转稳定电平 */
    uint8_t button_level: 1;            /**< 去抖后的稳定电平：DRV_BTN_LEVEL_ACTIVE/DRV_BTN_LEVEL_INACTIVE */
    btn_drv_event_e event;              /**< 最近一次产生的事件（供 get_event/回调内读取） */
    btn_drv_interface_t *interface;     /**< 具体硬件驱动（GPIO/ADC/矩阵/自定义） */
    btn_drv_cb_t cb[BTN_DRV_EVENT_MAX]; /**< 每个事件的回调数组（可注册多个） */
    struct btn_drv_config *next;        /**< 全局链表指针：把所有按键配置串起来被统一扫描 */
} btn_drv_config_t;

/**
 * @brief 按键驱动句柄类型定义
 *
 * @details 该类型定义了按键驱动设备的句柄，用于操作和管理按键实例。
 */
typedef struct btn_drv_config_t *btn_drv_handle_t;

/**
 * @brief 按键事件处理回调函数
 *
 * @param args 按键驱动实例指针
 * @details 该函数作为按键驱动的回调，用于处理按键事件。
 */
void btn_drv_event_callback(void *args);

/**
 * @brief 注册按键事件回调函数
 * 
 * @param handle 按键句柄
 * @param event 要注册的事件类型
 * @param cb 事件回调函数指针
 * @return bool true 成功，false 失败
 * @details 该函数用于注册指定按键实例上的某个事件回调。
 */
bool btn_drv_event_register(btn_drv_handle_t handle, btn_drv_event_e event, btn_drv_cb_t cb);

/** 
 * @brief 注销按键事件回调
 * 
 * @param handle 按键句柄
 * @param event 要注销的事件类型
 * @return bool true 成功，false 失败
 * @details 该函数用于注销指定按键实例上的某个事件回调。
 */
bool btn_drv_event_unregister(btn_drv_handle_t handle, btn_drv_event_e event);

/**
 * @brief 创建一个按键驱动实例
 *
 * @param config 按键驱动配置参数
 * @param driver 按键驱动接口
 * @param button 输出的按键驱动句柄指针
 * @return bool true 成功，false 失败
 * @details 该函数根据配置参数和驱动接口创建一个按键驱动实例，并将其插入到全局按键链表中。
 */
bool btn_drv_create(const btn_drv_params_t *params, const btn_drv_interface_t *interface, btn_drv_handle_t *handle);

/**
 * @brief 删除一个按键驱动实例
 *
 * @param handle 按键驱动句柄
 * @return bool true 成功，false 失败
 * @details 该函数根据按键驱动句柄删除指定按键驱动实例，释放其占用的资源。 
 */ 
bool btn_drv_delete(btn_drv_handle_t handle);


#ifdef __cplusplus
}
#endif

#endif  /* __DRV_BTN_H__ */


