Lib.rs

Simple Rust 绑定到 ZArchive。

概述

ZArchive 是另一种文件归档格式。类似于 zip、tar、7z 等，但要求支持随机访问读取和压缩。

特性 / 规范

• 支持在存储的文件内进行随机访问读取
• 使用 zstd 压缩（64KiB 块大小）
• 合理地扩展到多太字节，支持数百万个文件
• 每个文件的理论大小限制为 2^48-1（256 太字节）
• 归档内路径的编码为 Windows-1252（不区分大小写）
• 包含整个归档的 SHA256 哈希值，用于完整性检查
• 端序无关。该格式始终在内部使用大端序
• 无状态的文件和目录迭代器句柄，不需要内存分配（对于 Rust 绑定并非完全如此）

Rust 绑定

zarchive 包提供了对 C++ 库的 Rust 绑定。API 故意进行了限制。尽管实现了大部分的读取器 API，但出于安全考虑，仅公开了基本的归档打包函数以供写入。Rust 绑定在读取器的目录迭代 API 上增加了一些轻微的 overhead，但希望带来足够的便利性。

示例 - 打包和提取归档

use zarchive::{pack, extract};
pack("/path/to/stuff/to/pack", "/path/to/archive.zar")?;
extract("/path/to/archive.zar", "/path/to/extract")?;

限制

• 未设计用于在创建归档后添加、删除或修改文件

无查找创建

在创建新归档时仅使用字节追加操作。无需进行文件查找。这使得在只能写入一次的存储上创建归档成为可能。这也简化了通过网络流式传输创建 ZArchive。

UTF8 路径

理论上支持 UTF8 文件和文件夹路径，因为路径只是二进制数据块。但大小写不敏感的比较仅适用于拉丁字母（a-z）。Rust 绑定使用原始的 &str 类型，这意味着通过此 API 传递的所有路径都是 UTF8。

Wii U 特定

最初，此格式是为了存储 Wii U 游戏存档而创建的。这些使用文件扩展名 .wua（Wii U 归档），但其他方面是常规的 ZArchive 文件。为了允许将多个 Wii U 标题存储在单个归档中，每个标题必须放置在按以下命名方案创建的子文件夹中：16 位标题 ID 后跟 _v，然后是作为十进制表示的版本。例如：0005000e10102000_v32

许可协议

zarchive 库受 GPL 3+ 许可协议的许可。原始的 ZArchive 库受 MIT No Attribution 许可协议的许可，但 sha_256.c 和 sha_256.h 除外，它们属于公有领域，详见：https://github.com/amosnier/sha-2。