初始提交卡包 USB 工程

纳入固件源码、屏幕组件、nand_xfer 工具和文档。忽略本机构建产物、sdkconfig，以及含本机路径的依赖锁。 Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-13 21:54:50 +08:00
commit 851e347cf5
260 changed files with 269349 additions and 0 deletions
@@ -0,0 +1,147 @@
+#ifndef ZIP_EXTRACTOR_H
+#define ZIP_EXTRACTOR_H
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#include <stdbool.h>
+#include "esp_err.h"
+
+/**
+ * @brief ZIP解压器配置参数
+ */
+typedef struct {
+    const char *zip_path;           ///< ZIP文件路径
+    const char *extract_dir;        ///< 解压目标目录
+    bool overwrite_existing;       ///< 是否覆盖已存在的文件
+    bool create_directories;        ///< 是否自动创建目录
+    bool skip_directories;          ///< 是否跳过ZIP中的目录条目
+} zip_extractor_config_t;
+
+/**
+ * @brief 默认配置参数
+ */
+#define ZIP_EXTRACTOR_CONFIG_DEFAULT() { \
+    .zip_path = NULL, \
+    .extract_dir = NULL, \
+    .overwrite_existing = true, \
+    .create_directories = true, \
+    .skip_directories = true \
+}
+
+/**
+ * @brief 解压结果结构体
+ */
+typedef struct {
+    int total_files;        ///< ZIP中总文件数
+    int extracted_files;    ///< 成功解压的文件数
+    int skipped_files;      ///< 跳过的文件数（目录或已存在且不覆盖）
+    int failed_files;       ///< 解压失败的文件数
+    size_t total_size;      ///< 解压的总字节数
+} zip_extractor_result_t;
+
+/**
+ * @brief 解压进度回调函数类型
+ * @param filename 当前正在处理的文件名
+ * @param current 当前处理的文件索引
+ * @param total 总文件数
+ * @param user_data 用户数据
+ */
+typedef void (*zip_extractor_progress_cb_t)(const char *filename, int current, int total, void *user_data);
+
+/**
+ * @brief 初始化ZIP解压器
+ * 
+ * @note 在使用其他函数前必须先调用此函数进行初始化
+ * 
+ * @return esp_err_t ESP_OK表示成功，其他表示错误
+ */
+esp_err_t zip_extractor_init(void);
+
+/**
+ * @brief 解压ZIP文件（使用配置结构体）
+ * 
+ * @param config 解压配置参数
+ * @param result 解压结果（可选，可为NULL）
+ * @param progress_cb 进度回调函数（可选，可为NULL）
+ * @param user_data 传递给进度回调的用户数据（可选）
+ * @return esp_err_t ESP_OK表示成功，其他表示错误
+ */
+esp_err_t zip_extractor_extract(const zip_extractor_config_t *config, 
+                               zip_extractor_result_t *result,
+                               zip_extractor_progress_cb_t progress_cb,
+                               void *user_data);
+
+/**
+ * @brief 解压ZIP文件（简化版本）
+ * 
+ * @param zip_path ZIP文件路径
+ * @param extract_dir 解压目标目录
+ * @return esp_err_t ESP_OK表示成功，其他表示错误
+ */
+esp_err_t zip_extractor_extract_simple(const char *zip_path, const char *extract_dir);
+
+/**
+ * @brief 获取ZIP文件信息
+ * 
+ * @param zip_path ZIP文件路径
+ * @param file_count 返回文件数量（可选，可为NULL）
+ * @param total_size 返回总大小（字节，可选，可为NULL）
+ * @return esp_err_t ESP_OK表示成功，其他表示错误
+ */
+esp_err_t zip_extractor_get_info(const char *zip_path, int *file_count, size_t *total_size);
+
+/**
+ * @brief 列出ZIP文件内容
+ * 
+ * @param zip_path ZIP文件路径
+ * @param file_list 文件列表缓冲区（二维数组）
+ * @param max_files 最大文件数量
+ * @return int 实际列出的文件数量，负数表示错误
+ */
+int zip_extractor_list_files(const char *zip_path, char **file_list, int max_files);
+
+/**
+ * @brief 检查ZIP文件是否有效
+ * 
+ * @param zip_path ZIP文件路径
+ * @return bool true表示有效，false表示无效
+ */
+bool zip_extractor_is_valid(const char *zip_path);
+
+/**
+ * @brief 释放ZIP解压器资源
+ * 
+ * @note 在应用程序结束时调用
+ */
+void zip_extractor_cleanup(void);
+
+// 特定于您需求的便捷函数
+
+/**
+ * @brief 解压/extflash/json.zip到/extflash目录
+ * 
+ * @return esp_err_t ESP_OK表示成功，其他表示错误
+ */
+void extract_json_zip(char* filename);
+
+/**
+ * @brief 检查JSON ZIP文件是否存在且有效
+ * 
+ * @return bool true表示存在且有效
+ */
+bool is_json_zip_available(void);
+
+/**
+ * @brief 获取最近一次解压成功对应的表情包 ID（如 'A'/'B'/'C'/'D'）
+ *        解压成功时在 extract_zip_file 内设置，供 main 识别下载成功并按路径播放动画
+ * @return char 表情包 ID，'0' 表示无效或未下载
+ */
+char zip_extractor_get_last_downloaded_pack(void);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif // ZIP_EXTRACTOR_H