/**
 * @file sd_card.h
 * @brief SD 卡驱动 (SDMMC 4-bit 模式 + FATFS)
 *
 * 硬件接口: SDMMC1, 4-bit 模式
 * 引脚定义: 见 hw_config.h (SDMMC_CLK/CMD/D0-D3/CD_GPIO)
 * 框架: ESP-IDF 5.1.x
 */

#ifndef SD_CARD_H
#define SD_CARD_H

#include <stdint.h>
#include <stdbool.h>
#include <stddef.h>
#include "esp_err.h"

#ifdef __cplusplus
extern "C" {
#endif

/* ================================================================
 * 类型定义
 * ================================================================ */

/** SD 卡文件系统类型 */
typedef enum {
    SD_FS_NONE = 0,   /* 未挂载 / 无卡 */
    SD_FS_FAT32,       /* FAT32 格式 */
    SD_FS_OTHER,       /* 其他文件系统（需要格式化） */
} sd_fs_type_t;

/** SD 卡文件信息 */
typedef struct {
    char    name[64];
    size_t  size;
    bool    is_dir;
} sd_file_info_t;

/* ================================================================
 * 挂载 / 卸载 / 格式化
 * ================================================================ */

/** 初始化 SDMMC 主机并尝试挂载 FAT 文件系统到 /sdcard */
esp_err_t sd_card_init(void);

/** 卸载文件系统并释放 SDMMC 资源 */
esp_err_t sd_card_deinit(void);

/** 获取当前 SD 卡的文件系统类型 */
sd_fs_type_t sd_card_get_fs_type(void);

/** 检测 SD 卡是否物理插入 (读取 CD 引脚) */
bool sd_card_is_inserted(void);

/** 将 SD 卡格式化为 FAT32 并重新挂载 */
esp_err_t sd_card_format(void);

/* ================================================================
 * 文件枚举
 * ================================================================ */

/** 枚举 SD 卡根目录下的文件和目录
 * @param list      输出缓冲区
 * @param max_files 最多返回的文件数
 * @return 实际枚举到的文件数量 (≤ max_files)
 */
int sd_card_list_files(sd_file_info_t *list, int max_files);

/* ================================================================
 * 文件读取
 * ================================================================ */

/** 读取文本文件全部内容到字符串缓冲区
 * @param path    文件路径 (相对于 /sdcard, 如 "readme.txt")
 * @param buf     输出缓冲区 (会以 '\0' 结尾)
 * @param max_len 缓冲区最大字节数 (含结尾 '\0')
 * @return ESP_OK 成功, 否则失败
 *
 * 注意: 文件超过 max_len-1 时会被截断。
 */
esp_err_t sd_card_read_text(const char *path, char *buf, size_t max_len);

/** 读取图片文件到内存缓冲区 (二进制原始数据)
 * @param path    文件路径 (相对于 /sdcard, 如 "photo.bmp")
 * @param buf     输出缓冲区 (调用者负责分配)
 * @param max_len 缓冲区最大字节数
 * @param out_len [输出] 实际读取的字节数
 * @return ESP_OK 成功, 否则失败
 *
 * 注意: 此函数只负责读取原始二进制数据,
 *       图片解析和显示由上层实现。
 */
esp_err_t sd_card_read_image(const char *path,
                             uint8_t *buf, size_t max_len,
                             size_t *out_len);

#ifdef __cplusplus
}
#endif

#endif /* SD_CARD_H */