/**
 * @file menu_port.h
 * @brief 菜单组件硬件端口层接口定义（用户需要实现的硬件相关接口）
 * @note 工业级嵌入式菜单组件 - 硬件端口层
 */
#ifndef MENU_PORT_H
#define MENU_PORT_H

#include <stdarg.h>
#include <stdint.h>

// 包含菜单核心类型定义
#include "menu.h"

/************************** 硬件端口层接口声明 **************************/
/**
 * @brief 硬件端口驱动结构体（模块化设计，支持运行时配置）
 */
typedef struct {
    /**
     * @brief 硬件打印接口（可变参数版本）
     * @param fmt 格式化字符串
     * @param args 可变参数列表
     * @note 用户需要实现此接口，用于调试信息输出
     */
    void (*printf)(const char* fmt, va_list args);
    
    /**
     * @brief 获取系统滴答时间（毫秒级）
     * @return 当前系统滴答时间（ms）
     * @note 用户需要实现此接口，用于菜单的定时和超时处理
     */
    uint32_t (*get_tick)(void);
    
    /**
     * @brief 硬件延迟函数（毫秒级）
     * @param ms 延迟时间（ms）
     * @note 用户需要实现此接口，用于必要的延迟操作
     */
    void (*delay_ms)(uint32_t ms);
    
    /**
     * @brief 菜单显示接口
     * @param menu_name 菜单名称字符串
     * @param menu_id 菜单ID
     * @note 用户需要实现此接口，用于在硬件上显示菜单内容
     */
    void (*display)(const char* menu_name, uint16_t menu_id);
    
    /**
     * @brief 按键扫描接口（可选）
     * @return 当前按键事件（MenuEventType类型）
     * @note 用户可以实现此接口，也可以在自己的主循环中调用menu_post_event发送按键事件
     */
    MenuEventType (*key_scan)(void);
    
    /**
     * @brief 中断管理接口（可选）
     * @param enable 中断使能标志
     * @note 用户需要实现此接口，用于管理全局中断
     */
    void (*irq_ctrl)(bool enable);
    
    /**
     * @brief 错误处理接口（可选）
     * @param err_code 错误码
     * @note 用户可以实现此接口，用于处理硬件错误
     */
    void (*error_handler)(MenuErrCode err_code);
    
    #if MENU_CONFIG_ENABLE_MODBUS_MAP
    /**
     * @brief Modbus硬件发送数据接口（可选，如RS485发送）
     * @param reg_type 寄存器类型
     * @param reg_addr 寄存器地址
     * @param reg_buf 数据缓冲区
     * @param buf_len 数据长度
     * @return 错误码
     */
    MenuErrCode (*modbus_send)(ModbusRegType reg_type, uint16_t reg_addr, const uint8_t* reg_buf, uint8_t buf_len);
    
    /**
     * @brief Modbus硬件接收数据接口（可选，如RS485接收）
     * @param reg_type 寄存器类型
     * @param reg_addr 寄存器地址
     * @param reg_buf 数据缓冲区
     * @param buf_len 数据长度
     * @return 错误码
     */
    MenuErrCode (*modbus_receive)(ModbusRegType reg_type, uint16_t reg_addr, uint8_t* reg_buf, uint8_t buf_len);
    #endif // MENU_CONFIG_ENABLE_MODBUS_MAP
} MenuPortDriver;

/**
 * @brief 硬件端口初始化接口
 * @param driver 硬件驱动结构体指针
 * @return 错误码
 * @note 用户需要实现此接口，用于初始化硬件设备
 */
MenuErrCode menu_port_init(const MenuPortDriver* driver);

/**
 * @brief 硬件端口反初始化接口
 * @return 错误码
 * @note 用户需要实现此接口，用于释放硬件资源
 */
MenuErrCode menu_port_deinit(void);

/**
 * @brief 获取当前硬件驱动
 * @return 当前硬件驱动结构体指针
 * @note 内部使用，获取当前配置的硬件驱动
 */
const MenuPortDriver* menu_port_get_driver(void);

/**
 * @brief 硬件打印接口（兼容旧接口）
 * @param fmt 格式化字符串
 * @param args 可变参数列表
 */
void menu_port_printf(const char* fmt, va_list args);

/**
 * @brief 获取系统滴答时间（兼容旧接口）
 * @return 当前系统滴答时间（ms）
 */
uint32_t menu_port_get_tick(void);

/**
 * @brief 硬件延迟函数（兼容旧接口）
 * @param ms 延迟时间（ms）
 */
void menu_port_delay_ms(uint32_t ms);

/**
 * @brief 菜单显示接口（兼容旧接口）
 * @param menu_name 菜单名称字符串
 * @param menu_id 菜单ID
 */
void menu_port_display(const char* menu_name, uint16_t menu_id);

/**
 * @brief 默认硬件驱动结构体（提供基本实现，减少用户工作量）
 */
extern const MenuPortDriver g_menu_default_driver;

#endif // MENU_PORT_H