///|
/// Android 二进制 XML(AXML)解析库:类型、错误模型与公开接口。
///
/// 本文件包含全部公开类型与 5 个导出函数的真实实现;字节读取、UTF-8/UTF-16
/// 解码与字符串池解析等内部实现在 `decode.mbt`(不导出)。
/// 规范依据:AOSP frameworks/base/include/androidfw/ResourceTypes.h(Apache-2.0)。
///|
/// AXML chunk 类型(AOSP RES_STRING_POOL_TYPE / RES_XML_*_TYPE)。
/// 仅作节点来源标注,暂不参与解析决策。
pub(all) enum ChunkType {
StringPool
XmlTree
StartNamespace
EndNamespace
StartElement
EndElement
CData
ResourceMap
}
///|
/// 字符串池编码;UTF8_FLAG(0x100) 置位为 Utf8,否则 Utf16。
pub(all) enum StringEncoding {
Utf8
Utf16
}
///|
/// `Res_value.dataType` 的枚举化子集;`Unknown` 保留原始字节以便上层降级。
pub(all) enum ValueType {
Null
Reference
Attribute
String
Float
Dimension
Fraction
IntDec
IntHex
IntBoolean
Unknown(Int32)
}
///|
/// 单个 typed attribute。
/// `raw_data` 保留 32 位原始 data;本库不解释 `@ref` / `?attr` 等资源引用语义。
pub(all) struct XmlAttribute {
ns : String?
name : String
raw_value : String?
value_type : ValueType
res0 : Byte
raw_data : UInt32
line : Int32
}
///|
/// 文档树节点。`children` / `parent` 使用 `AxmlDoc::nodes()` 的索引,
/// 避免递归结构带来的所有权与生命周期歧义。
pub(all) struct XmlNode {
line : Int32
ns : String?
name : String
attributes : Array[XmlAttribute]
children : Array[Int32]
parent : Int32?
chunk : ChunkType
}
///|
/// 字符串池视图;`strings` 下标与 chunk 内 string index 一一对应。
/// `styles` 保留原始字节,暂不做样式解析。
pub(all) struct StringPool {
encoding : StringEncoding
strings : Array[String]
styles : Bytes
}
///|
/// AXML 解析结果:已解码字符串池 + 线性节点表 + 根索引 + 原始 resource map。
pub(all) struct AxmlDoc {
pool : StringPool
nodes : Array[XmlNode]
roots : Array[Int32]
resource_map : Array[UInt32]
}
///|
/// AXML 错误模型:全部为可恢复、可定位到字节偏移的显式错误,禁止 panic。
#derive(Debug)
pub suberror AxmlError {
UnexpectedEof(Int32)
BadChunkType(Int32, UInt32)
BadHeaderSize(Int32, Int32)
BadStringPool(Int32, String)
InvalidStringIndex(Int32)
InvalidNodeIndex(Int32)
UnsupportedEncoding(String)
VendorVariant(String)
}
///|
pub extend AxmlError with Debug::{to_repr}
///|
/// 字符串池索引。
pub type StringIndex = Int32
///|
/// 节点表索引。
pub type NodeIndex = Int32
///|
/// 解析一段完整 AXML 字节流(含 RES_XML_TYPE 头,不含 ZIP 封装)为文档树。
///
/// - 参数:`data` 为只读字节切片,调用方持有所有权,本函数不转移、不缓存;
/// `styles` 原始字节在返回值中是独立拷贝。
/// - 返回:`AxmlDoc` 纯值,无句柄、无需释放。
/// - 错误:越界 / 非法 headerSize / 非法字符串索引均以 `AxmlError` 传播并带
/// 字节偏移。偏移语义:`UnexpectedEof(offset)` 指被截断项的起始偏移;
/// `BadChunkType` / `BadHeaderSize` 的 offset 指 chunk 起始(外层头部为 0)。
/// - 线程:无可变全局状态,可并发调用;返回值为只读,可跨线程共享。
/// - 降级策略(见 docs/API.md §1):未知 chunk 类型按 headerSize/size 跳过;
/// 厂商变体布局(attributeStart/attributeSize < 20)以 `VendorVariant` 报告;
/// 未知字符串池标志位以 `UnsupportedEncoding` 报告。
/// - 非目标:不解析资源引用、不提供 manifest 语义、不处理 resources.arsc
/// (格式级回编见 `encode`,不做 XML 文本编译与打包)。
/// - TODO:`res0`/`data` 的语义解释(当前按 docs/API.md 保留原值,语义确定后再实现)。
pub fn parse(data : Bytes) -> AxmlDoc raise AxmlError {
let limit = data.length()
let doc_type = read_u16(data, 0, limit)
if doc_type != 0x0003 {
raise BadChunkType(0, doc_type.reinterpret_as_uint())
}
let header_size = read_u16(data, 2, limit)
if header_size != 8 {
raise BadHeaderSize(0, header_size)
}
let size = read_u32(data, 4, limit)
if size < limit {
// RES_CHUNK_header.size 必须覆盖整个输入;更短意味着尾随垃圾。
raise BadHeaderSize(4, size)
}
if size > limit {
// 外层 size 超出实际输入:文件在 `limit` 处被截断;必须先拒绝,
// 否则后续 chunk 的 limit 会越过输入末尾并触发越界读取。
raise UnexpectedEof(limit)
}
let mut pool : StringPool? = None
let nodes : Array[XmlNode] = []
let roots : Array[Int32] = []
let resource_map : Array[UInt32] = []
let stack : Array[Int32] = []
let mut off = 8
while off < size {
let chunk_type = read_u16(data, off, limit)
let chunk_header_size = read_u16(data, off + 2, limit)
let chunk_size = read_u32(data, off + 4, limit)
if chunk_size < 8 {
raise BadHeaderSize(off, chunk_size)
}
if chunk_header_size < 8 || chunk_header_size > chunk_size {
raise BadHeaderSize(off, chunk_header_size)
}
if off + chunk_size > size {
raise UnexpectedEof(off)
}
if chunk_type == 0x0001 {
if pool is Some(_) {
raise BadChunkType(off, 0x0001U)
}
if chunk_header_size != 28 {
raise BadHeaderSize(off, chunk_header_size)
}
pool = Some(parse_string_pool(data, off, chunk_size))
} else if chunk_type == 0x0180 {
if chunk_header_size != 8 {
raise BadHeaderSize(off, chunk_header_size)
}
if (chunk_size - 8) % 4 != 0 {
raise BadHeaderSize(off, chunk_size)
}
let mut p = off + 8
while p < off + chunk_size {
resource_map.push(read_u32u(data, p, off + chunk_size))
p = p + 4
}
} else if chunk_type >= 0x0100 && chunk_type <= 0x0104 {
// RES_XML_* 节点 chunk:必须位于字符串池之后,node 头固定 16 字节。
let pool = require_pool(pool, off, chunk_type)
if chunk_header_size != 16 {
raise BadHeaderSize(off, chunk_header_size)
}
if chunk_type == 0x0102 {
parse_start_element(data, off, chunk_size, pool, nodes, roots, stack)
} else if chunk_type == 0x0103 {
parse_end_element(data, off, chunk_size, pool, nodes, stack)
} else if chunk_type == 0x0104 {
parse_cdata(data, off, chunk_size, pool, nodes, roots, stack)
} else {
// 0x0100 / 0x0101:命名空间声明仅校验字符串引用后跳过
// (docs/API.md 非目标:不做命名空间解析)。
let chunk_end = off + chunk_size
ignore(string_opt(pool, read_u32(data, off + 16, chunk_end)))
ignore(string_opt(pool, read_u32(data, off + 20, chunk_end)))
}
} else {
// RES_NULL_TYPE(0x0000) 与未知 chunk 类型按 headerSize/size 跳过。
()
}
off = off + chunk_size
}
if !stack.is_empty() {
// 文档在元素未闭合处结束。
raise UnexpectedEof(off)
}
let pool = match pool {
Some(p) => p
None => raise BadStringPool(8, "missing RES_STRING_POOL_TYPE chunk")
}
{ pool, nodes, roots, resource_map, }
}
///|
/// 取出已解析的字符串池;XML 节点 chunk 不允许出现在字符串池之前。
fn require_pool(
pool : StringPool?,
off : Int32,
chunk_type : Int32,
) -> StringPool raise AxmlError {
match pool {
Some(p) => p
None => raise BadChunkType(off, chunk_type.reinterpret_as_uint())
}
}
///|
/// 把节点挂到父节点的 children 或 roots 上。
fn attach(
nodes : Array[XmlNode],
roots : Array[Int32],
parent : Int32?,
index : Int32,
) -> Unit {
match parent {
Some(p) => nodes.at(p).children.push(index)
None => roots.push(index)
}
}
///|
/// 解析 RES_XML_START_ELEMENT_TYPE chunk(起始于 `off`,长度 `csize`)。
/// 厂商变体降级:attributeStart/attributeSize 允许大于 20(跳过多余字节),
/// 小于 20 无法安全解析,以 `VendorVariant` 报告。
fn parse_start_element(
data : Bytes,
off : Int32,
csize : Int32,
pool : StringPool,
nodes : Array[XmlNode],
roots : Array[Int32],
stack : Array[Int32],
) -> Unit raise AxmlError {
let limit = off + csize
let line = read_u32(data, off + 8, limit)
let ns_index = read_u32(data, off + 16, limit)
let name_index = read_u32(data, off + 20, limit)
let attribute_start = read_u16(data, off + 24, limit)
let attribute_size = read_u16(data, off + 26, limit)
let attribute_count = read_u16(data, off + 28, limit)
if attribute_start < 20 || attribute_size < 20 {
raise VendorVariant(
"start element at offset \{off}: attributeStart=\{attribute_start}, attributeSize=\{attribute_size}",
)
}
let attr_base = off + 16 + attribute_start
if attribute_count > (csize - 16 - attribute_start) / attribute_size {
raise UnexpectedEof(attr_base)
}
let attributes : Array[XmlAttribute] = []
let mut i = 0
while i < attribute_count {
let a = attr_base + i * attribute_size
let attr_ns = read_u32(data, a, limit)
let attr_name = read_u32(data, a + 4, limit)
let attr_raw = read_u32(data, a + 8, limit)
let value_size = read_u16(data, a + 12, limit)
let res0 = read_u8(data, a + 14, limit)
let data_type = read_u8(data, a + 15, limit)
let raw_data = read_u32u(data, a + 16, limit)
if value_size != 8 {
// Res_value.size 恒为 8;其他取值属于厂商变体布局。
raise BadHeaderSize(a + 12, value_size)
}
attributes.push({
ns: string_opt(pool, attr_ns),
name: string_req(pool, attr_name),
raw_value: string_opt(pool, attr_raw),
value_type: value_type_of(data_type),
res0: res0.to_byte(),
raw_data,
line,
})
i = i + 1
}
let parent : Int32? = if stack.is_empty() {
None
} else {
Some(stack.at(stack.length() - 1))
}
let index = nodes.length()
nodes.push({
line,
ns: string_opt(pool, ns_index),
name: string_req(pool, name_index),
attributes,
children: [],
parent,
chunk: StartElement,
})
attach(nodes, roots, parent, index)
stack.push(index)
}
///|
/// 解析 RES_XML_END_ELEMENT_TYPE chunk:弹出元素栈,并校验结束标签与栈顶
/// 元素的名称/命名空间一致;不匹配以 `BadChunkType` 报告。
fn parse_end_element(
data : Bytes,
off : Int32,
csize : Int32,
pool : StringPool,
nodes : Array[XmlNode],
stack : Array[Int32],
) -> Unit raise AxmlError {
let limit = off + csize
let ns_index = read_u32(data, off + 16, limit)
let name_index = read_u32(data, off + 20, limit)
if stack.is_empty() {
raise BadChunkType(off, 0x0103U)
}
let top = stack.at(stack.length() - 1)
let node = nodes.at(top)
if node.name != string_req(pool, name_index) ||
node.ns != string_opt(pool, ns_index) {
raise BadChunkType(off, 0x0103U)
}
ignore(stack.pop())
}
///|
/// 解析 RES_XML_CDATA_TYPE chunk:文本作为 `chunk = CData` 的节点进入节点表,
/// 挂在当前打开元素之下;`elements()` 会将其过滤掉。
fn parse_cdata(
data : Bytes,
off : Int32,
csize : Int32,
pool : StringPool,
nodes : Array[XmlNode],
roots : Array[Int32],
stack : Array[Int32],
) -> Unit raise AxmlError {
let limit = off + csize
let line = read_u32(data, off + 8, limit)
let text_index = read_u32(data, off + 16, limit)
let value_size = read_u16(data, off + 20, limit)
ignore(read_u8(data, off + 22, limit))
ignore(read_u8(data, off + 23, limit))
ignore(read_u32u(data, off + 24, limit))
if value_size != 8 {
raise BadHeaderSize(off + 20, value_size)
}
let parent : Int32? = if stack.is_empty() {
None
} else {
Some(stack.at(stack.length() - 1))
}
let index = nodes.length()
nodes.push({
line,
ns: None,
name: string_req(pool, text_index),
attributes: [],
children: [],
parent,
chunk: CData,
})
attach(nodes, roots, parent, index)
}
///|
/// 按 chunk 顺序返回全部元素节点。`XmlTree` / `CData` 等非元素节点不在此列表中。
/// 先校验 roots / parent / children 索引,越界返回 `InvalidNodeIndex`。
pub fn AxmlDoc::elements(self : AxmlDoc) -> Array[XmlNode] raise AxmlError {
let count = self.nodes.length()
for root in self.roots {
if root < 0 || root >= count {
raise InvalidNodeIndex(root)
}
}
for i in 0..
if parent < 0 || parent >= count {
raise InvalidNodeIndex(parent)
}
None => ()
}
for child in node.children {
if child < 0 || child >= count {
raise InvalidNodeIndex(child)
}
}
}
self.nodes.filter(fn(node) { node.chunk is StartElement })
}
///|
/// 读取字符串池第 `index` 项;越界返回 `InvalidStringIndex`。
pub fn AxmlDoc::string_at(
self : AxmlDoc,
index : StringIndex,
) -> String raise AxmlError {
if index < 0 || index >= self.pool.strings.length() {
raise InvalidStringIndex(index)
}
self.pool.strings.at(index)
}
///|
/// 读取节点表第 `index` 项;越界返回 `InvalidNodeIndex`。
pub fn AxmlDoc::node_at(
self : AxmlDoc,
index : NodeIndex,
) -> XmlNode raise AxmlError {
if index < 0 || index >= self.nodes.length() {
raise InvalidNodeIndex(index)
}
self.nodes.at(index)
}
///|
/// 返回某节点的属性列表(保持 chunk 内原始顺序,不做去重、不做命名空间解析)。
pub fn XmlNode::attrs(self : XmlNode) -> Array[XmlAttribute] {
self.attributes
}