# MinizExtension.hpp 说明文档
## 文件概述
对miniz压缩库的C++封装扩展，提供ZIP文件读写的高级接口。主要特性包括：
- 面向对象的ZIP存档管理
- UTF-8文件名支持
- 错误状态追踪机制
- 安全的资源生命周期管理
## 核心组件
### 全局函数
```cpp
bool open_zip_reader(mz_zip_archive*, const std::string& fname_utf8); // 打开ZIP读取器
bool open_zip_writer(mz_zip_archive*, const std::string& fname_utf8); // 打开ZIP写入器
bool close_zip_reader(mz_zip_archive*); // 关闭读取器
bool close_zip_writer(mz_zip_archive*); // 关闭写入器
MZ_Archive类
class MZ_Archive {
public:
mz_zip_archive arch;
MZ_Archive();
static std::string get_errorstr(mz_zip_error mz_err);
std::string get_errorstr() const;
bool is_alive() const;
};
方法详解
文件操作函数
| 方法 | 参数说明 | 返回值 | 注意事项 |
|---|
open_zip_reader | fname_utf8: UTF-8编码文件路径 | 成功返回true | 需确保文件存在且可读 |
open_zip_writer | fname_utf8: UTF-8编码文件路径 | 成功返回true | 自动创建不存在的目录 |
close_zip_reader | - | 成功返回true | 必须显式调用释放资源 |
close_zip_writer | - | 成功返回true | 确保所有数据已写入 |
MZ_Archive成员方法
| 方法 | 功能描述 | 典型返回值示例 |
|---|
get_errorstr() | 获取最后操作的错误描述 | “MZ_ZIP_FILE_OPEN_FAILED!” |
is_alive() | 检查存档是否可用 | 写入模式返回true直到调用close |
使用示例
基础读操作
Slic3r::MZ_Archive reader;
if (Slic3r::open_zip_reader(&reader.arch, "input.zip")) {
Slic3r::close_zip_reader(&reader.arch);
} else {
std::cerr << "打开失败: " << reader.get_errorstr();
}
安全写操作
Slic3r::MZ_Archive writer;
if (Slic3r::open_zip_writer(&writer.arch, "output.zip")) {
if (!Slic3r::close_zip_writer(&writer.arch)) {
std::cerr << "写入失败: " << writer.get_errorstr();
}
} else {
std::cerr << "创建失败: " << writer.get_errorstr();
}
错误代码处理
miniz错误类型到字符串的转换示例：
mz_zip_error err = MZ_ZIP_FILE_OPEN_FAILED;
std::string msg = MZ_Archive::get_errorstr(err);
设计特点
- 资源管理：要求显式调用关闭函数，避免资源泄漏
- 跨平台支持：通过UTF-8路径处理Windows/Linux兼容性
- 状态追踪：
is_alive()实时反映存档操作状态 - 错误追溯：自动记录最后一次操作的错误代码
典型应用场景
- 3D打印模型文件(G-code)的压缩存储
- 插件系统的模块打包
- 大型工程文件的版本存档
- 跨平台应用的资源打包
注意事项
- 线程安全：单个MZ_Archive实例不应跨线程使用
- 异常处理：所有函数返回bool状态，需手动检查
- 内存管理：
mz_zip_archive结构体由miniz库内部管理 - 性能建议：批量文件操作时保持存档开启状态
