dex

    把 DEX 字节解析成六表结构、指令序列、注解与交叉引用,输出可读清单与 smali 风格反汇编。

    dex
    android
    parser
    disassembly
    smali
    reverse-engineering
    Download zip
    Version
    0.1.0
    License
    Apache-2.0
    Last updated
    4 hours ago
    Downloads
    4

    No dependencies

    #hnlyxiaobing/dex

    把 DEX 字节解析成六表结构、指令序列、注解与交叉引用,输出可读清单与 smali 风格反汇编。

    #安装

    moon add hnlyxiaobing/dex

    #最小可用示例

    // 已 `moon add hnlyxiaobing/dex` 后,包名为 dex
    fn analyze(dex_bytes : Bytes) -> Unit {
    let dex = @dex.parse(dex_bytes)?
    println("string count: \(dex.strings().length())")
    println("class count: \(dex.classes().length())")
    let ok = @dex.signature_ok(dex_bytes)?
    println("signature ok: \(ok)")
    }

    #能力概览

    • 六表解析:header / string / type / proto / field / method / class_def,含索引越界与长度校验
    • 指令解码:code_item 全 opcode 序列与结构化操作数(含 DEX 038+ 指令组)
    • 反汇编:disasm 输出 smali 风格文本
    • 注解与静态值:annotations_index / static_values / encoded_array
    • 交叉引用:build_xref 九种 kind 的调用点与字段访问点双向索引
    • 完整性校验:signature_ok 校验 DEX header 的 SHA-1 signature(仅格式完整性,非 APK 签名验签)

    公开 API 以 pkg.generated.mbti 为准;索引入口包括 parse / disasm / build_xref / signature_ok / annotations_index 等。

    #命令行(可选)

    本模块附带 cmd/main 二进制(默认 preferred_target = wasm,可切 native 运行):

    moon run cmd/main --target native -- dump <apk|dex> [--view summary|norm|xref] [--json] moon run cmd/main --target native -- disasm <apk|dex> [--method <ref>]

    APK 输入条目 CRC-32 不符或解压失败时整体拒绝(fail-closed),无部分输出,退出码 1。

    #依赖与许可

    零第三方依赖;preferred_target = "wasm";Apache-2.0。

    MethodHandle

    type MethodHandle = Int

    方法句柄:在 DexFile 内定位一个方法,作为 code / disasm 的输入。

    Disassembler

    pub trait Disassembler {
    fn disasm(Self, Int) -> String raise DexError
    }

    只读反汇编输出契约,便于后续替换为不同文本后端。

    DexError

    pub suberror DexError {
    UnexpectedEof(Int)
    BadMagic(String)
    UnsupportedVersion(String)
    BadTableOffset(TableKind, Int)
    InvalidIndex(TableKind, Int)
    InvalidInstruction(Int, Int)
    BadCodeItem(Int, String)
    BadDebugInfo(Int, String)
    MultiDexNotMerged(String)
    } derive(
    Debug
    )

    DEX 错误模型:全部带偏移或索引,便于黄金样本差分定位。

    DexError::to_repr

    Annotation

    pub(all) struct Annotation {
    visibility : AnnotationVisibility
    annotation : EncodedAnnotation
    }

    annotation_item:可见性 + encoded_annotation。

    AnnotationElement

    pub(all) struct AnnotationElement {
    name : String
    value : EncodedValue
    }

    注解元素:元素名(name_idx 已解析)与值。

    AnnotationSet

    pub(all) struct AnnotationSet {
    annotations : Array[Annotation]
    }

    annotation_set_item:一个成员的注解集合(合法 DEX 中按类型描述符升序)。

    AnnotationVisibility

    pub(all) enum AnnotationVisibility {
    VisibilityBuild
    VisibilityRuntime
    VisibilitySystem
    }

    annotation_item.visibility:0=BUILD(编译期可见)、1=RUNTIME、2=SYSTEM(VM 注解)。

    AnnotationsDirectory

    pub(all) struct AnnotationsDirectory {
    class_annotations : AnnotationSet
    field_annotations : Array[FieldAnnotations]
    method_annotations : Array[MethodAnnotations]
    parameter_annotations : Array[ParameterAnnotations]
    }

    annotation_directory_item 解码结果:class / field / method / parameter 四类注解目录。字段/方法索引为 field_ids / method_ids 表索引。

    AnnotationsIndex

    pub struct AnnotationsIndex {
    data : Bytes
    strings : Array[String]
    types : Array[String]
    protos : Array[ProtoId]
    fields : Array[FieldDef]
    methods : Array[MethodDef]
    handles : Array[MethodHandleItem]
    call_sites : Array[CallSiteItem]
    }

    注解 / 静态初值索引(加法性新增,2026-11-09):一次 read_ctx 建立解析上下文, 之后按 class_defs 位置 O(1) 局部解码,避免批量查询时逐类重建六张表。

    • 构建:annotations_index(data) 执行与 parse 相同的头部校验与六表读取;
    • 查询:AnnotationsIndex::class_annotations / ::static_values 与同名全局 入口语义逐字一致(含 InvalidIndex(ClassDef, ...)、BadTableOffset 等错误);
    • 复杂度:构建 O(表规模) 一次,每次查询只解码该类自身的注解目录 / encoded_array;
    • 逐 dex 使用,不缓存、不跨 dex 合并(MultiDexNotMerged 口径维持);
    • 不透明 pub struct、私有字段,构建后视为只读;纯函数,无全局状态,可并发。
    • 实现注记:Ctx 为包内私有类型,公开结构不得直接依赖它;此处平铺保存其 公开类型的表字段,查询时在包内重组 Ctx(只搬表引用,不复制表内容)。

    AnnotationsIndex::class_annotations

    fn AnnotationsIndex::class_annotations(self : AnnotationsIndex, class_index : Int) -> AnnotationsDirectory? raise DexError

    索引视图:解析指定类的注解目录;annotations_off == 0 直接返回 None, 不重复解码任何索引表。错误同全局 class_annotations。

    AnnotationsIndex::static_values

    fn AnnotationsIndex::static_values(self : AnnotationsIndex, class_index : Int) -> Array[EncodedValue] raise DexError

    索引视图:解析指定类的静态字段初值;static_values_off == 0 返回空数组。 错误同全局 static_values。

    ArrayPayloadView

    pub(all) struct ArrayPayloadView {
    element_width : Int
    elements : Array[Bytes]
    }

    fill-array-data-payload 的结构化视图:element_width 与逐元素原始字节。

    CallSiteItem

    pub(all) struct CallSiteItem {
    call_site_off : Int
    values : Array[EncodedValue]
    }

    call_site_id_item → call_site_item(encoded_array)的解析结果。
    • call_site_off:call_site_item 的文件内偏移(call_site_id_item 原值)。
    • values:call_site_item 的 encoded_array 值序列;DEX 规范布局为 [bootstrap MethodHandle, 链接名 String, 链接类型 MethodType, 静态参数…], 其中 MethodHandle/MethodType 为 DEX 038+ 新增 encoded_value 类型。

    CatchHandlerView

    pub(all) struct CatchHandlerView {
    pairs : Array[(Int, Int)]
    catch_all_offset : Int?
    }

    单个 encoded_catch_handler 的多类型展开视图。

    ClassDef

    pub(all) struct ClassDef {
    class_index : Int
    type_descriptor : String
    superclass_index : Int?
    interfaces : Array[Int]
    source_file : String?
    access_flags : UInt
    class_data_off : Int
    static_fields : Array[FieldDef]
    instance_fields : Array[FieldDef]
    direct_methods : Array[MethodDef]
    virtual_methods : Array[MethodDef]
    }

    class_def 的结构化表示;class_data_off = 0 表示无 class_data。

    CodeItem

    pub(all) struct CodeItem {
    registers_size : Int
    ins_size : Int
    outs_size : Int
    tries_size : Int
    debug_info_off : Int
    insns : Array[Instruction]
    tries : Array[TryItem]
    debug_info : Bytes
    }

    code_item 的结构化表示;debug_info 保留原始字节,暂不展开。

    DebugEvent

    pub(all) enum DebugEvent {
    AdvancePc(Int)
    AdvanceLine(Int)
    StartLocal(Int, String, String)
    StartLocalExtended(Int, String, String, String)
    EndLocal(Int)
    RestartLocal(Int)
    SetPrologueEnd
    SetEpilogueBegin
    SetFile(String)
    }

    状态机事件。

    DebugInfoView

    pub(all) struct DebugInfoView {
    line_start : Int
    parameter_names : Array[String?]
    events : Array[DebugEvent]
    }

    debug_info_item 展开视图。

    DexFile

    pub(all) struct DexFile {
    version : DexVersion
    checksum : UInt
    signature : Bytes
    file_size : Int
    header_size : Int
    endian_tag : UInt
    strings : Array[String]
    type_descriptors : Array[String]
    protos : Array[ProtoId]
    fields : Array[FieldDef]
    methods : Array[MethodDef]
    classes : Array[ClassDef]
    handles : Array[MethodHandleItem]
    call_sites : Array[CallSiteItem]
    map_list : Bytes
    }

    单 DEX 文件的解析结果(纯值,无句柄)。

    DexFile::classes

    fn DexFile::classes(self : DexFile) -> Array[ClassDef]

    返回全部 class_def(保持文件内顺序)。

    DexFile::code

    fn DexFile::code(self : DexFile, method_ref : Int) -> CodeItem? raise DexError

    返回指定方法(method_ids 表索引)的 code_item;abstract / native 方法返回 None。 method_ref 越界抛 InvalidIndex(MethodId, method_ref)。

    DexFile::methods

    fn DexFile::methods(self : DexFile, class_index : Int) -> Array[MethodDef] raise DexError

    返回指定类(class_defs 表索引)下的全部方法(direct + virtual)。 class_index 越界抛 InvalidIndex(ClassDef, class_index)。

    DexFile::strings

    fn DexFile::strings(self : DexFile) -> Array[String]

    返回字符串表(string_id 顺序)。

    DexVersion

    pub(all) enum DexVersion {
    Dex035
    Dex037
    Dex038
    Dex039
    Dex040
    Dex041
    Unknown(Int)
    }

    DEX 版本 / magic 前缀。多 dex(classes2.dex…)由上层合并,本库只管单个 DEX。

    EncodedAnnotation

    pub(all) struct EncodedAnnotation {
    type_descriptor : String
    elements : Array[AnnotationElement]
    }

    encoded_annotation:注解类型描述符 + 元素序列(保持文件内顺序, 合法 DEX 中按元素名升序)。

    EncodedValue

    pub(all) enum EncodedValue {
    ValueByte(Int)
    ValueShort(Int)
    ValueChar(Int)
    ValueInt(Int)
    ValueLong(Int64)
    ValueFloat(Float)
    ValueDouble(Double)
    ValueString(String)
    ValueType(String)
    ValueField(String)
    ValueMethod(String)
    ValueEnum(String)
    ValueMethodType(String)
    ValueMethodHandle(String)
    ValueArray(Array[EncodedValue])
    ValueAnnotation(EncodedAnnotation)
    ValueNull
    ValueBoolean(Bool)
    }

    encoded_value 全 18 种 value_type 的结构化解码结果。 引用类值(string/type/field/method/enum)在解码时按表解析为名字 (字段/方法/枚举沿用 smali 风格 Lcls;->name:type / Lcls;->name(sig)ret); 整型/字符为扩展后的数值;float/double 为 IEEE-754 位模式还原值。

    FieldAnnotations

    pub(all) struct FieldAnnotations {
    field_index : Int
    annotations : AnnotationSet
    }

    字段注解目录项(annotation_directory_item.field_annotations)。

    FieldDef

    pub(all) struct FieldDef {
    class_index : Int
    type_index : Int
    name_index : Int
    access_flags : UInt
    }

    字段定义。

    IndexKind

    pub(all) enum IndexKind {
    IndexNone
    IndexString
    IndexType
    IndexField
    IndexMethod
    IndexCallSite
    IndexMethodHandle
    IndexProto
    }

    操作数中常量池引用的类别(结构化视图用)。

    InsnOperands

    pub(all) struct InsnOperands {
    regs : Array[Int]
    literal : Int64?
    branch : Int?
    index_kind : IndexKind
    index : Int
    }

    单条指令的结构化操作数视图。
    • regs:寄存器序列(invoke 列表 / range 形式已展开为连续寄存器)。
    • literal:整型字面量(const/4…const-wide、lit8/lit16;None 表示无)。
    • branch:相对跳转偏移(以指令起始 code unit 计;None 表示无)。
    • index_kind / index:常量池引用类别与索引(IndexNone 时索引无意义)。 switch / 数组 payload 伪指令返回空视图(其摘要保留在文本 operands 中)。

    Instruction

    pub(all) struct Instruction {
    offset : Int
    opcode : Int
    mnemonic : String
    operands : Array[String]
    raw : Bytes
    }

    单条 Dalvik 指令解码结果。opcode 为 0x00–0xFF 原值,operands 为已解码的字面量。

    MapItem

    pub(all) struct MapItem {
    type_code : Int
    size : Int
    offset : Int
    }

    单条 map_item 的结构化视图。

    MethodAnnotations

    pub(all) struct MethodAnnotations {
    method_index : Int
    annotations : AnnotationSet
    }

    方法注解目录项(annotation_directory_item.method_annotations)。

    MethodDef

    pub(all) struct MethodDef {
    class_index : Int
    name_index : Int
    proto_index : Int
    access_flags : UInt
    code_off : Int
    code : CodeItem?
    }

    方法定义。code 为 None 表示 abstract / native 方法。

    MethodHandleItem

    pub(all) struct MethodHandleItem {
    handle_type : MethodHandleKind
    field_or_method_index : Int
    }

    method_handle_item 结构化解析结果。
    • handle_type:句柄类型(见 MethodHandleKind)。
    • field_or_method_index:按 kind 语义解释——字段句柄(is_field_ref)为 field_ids 表索引,方法句柄(is_method_ref)为 method_ids 表索引。

    MethodHandleItem::is_field_ref

    fn MethodHandleItem::is_field_ref(self : MethodHandleItem) -> Bool

    字段句柄(0x00–0x03)判定:索引语义为 field_ids 表索引。

    MethodHandleItem::is_method_ref

    fn MethodHandleItem::is_method_ref(self : MethodHandleItem) -> Bool

    方法句柄(0x04–0x08)判定:索引语义为 method_ids 表索引。

    MethodHandleKind

    pub(all) enum MethodHandleKind {
    StaticPut
    StaticGet
    InstancePut
    InstanceGet
    InvokeStatic
    InvokeInstance
    InvokeConstructor
    InvokeDirect
    InvokeInterface
    }

    method_handle_item.method_handle_type:MethodHandle 句柄类型(Dex 038+ 标注)。 0x00–0x03 为字段读写句柄(field_or_method_index 是 field_ids 索引), 0x04–0x08 为方法调用句柄(field_or_method_index 是 method_ids 索引)。

    ParameterAnnotations

    pub(all) struct ParameterAnnotations {
    method_index : Int
    parameters : Array[AnnotationSet]
    }

    方法参数注解目录项(annotation_directory_item.parameter_annotations → annotation_set_ref_list)。parameters 与形参一一对应,空 AnnotationSet 表示该参数无注解(ref 列表中偏移为 0)。

    ProtoId

    pub(all) struct ProtoId {
    shorty : String
    return_type : String
    parameters : Array[String]
    }

    原型(proto_id)的结构化表示。

    TableKind

    pub(all) enum TableKind {
    StringId
    TypeId
    ProtoId
    FieldId
    MethodId
    ClassDef
    CallSiteId
    MethodHandle
    MapList
    } derive(
    Debug
    )

    六张索引表之一的类别标识,用于错误定位与诊断输出。

    TryItem

    pub(all) struct TryItem {
    start_addr : Int
    insn_count : Int
    handler_off : Int
    catch_type_index : Int?
    }

    try/catch 异常处理项;handler_pc 为 code_item 内以 code unit 计的偏移。

    XrefIndex

    pub struct XrefIndex {
    all_sites : Array[XrefSite]
    method_count : Int
    field_count : Int
    }

    逐 dex 的访问点索引(不透明 pub struct、私有字段;逐 dex,不跨 dex 合并)。 构建后视为只读;各查询返回新数组,sites() 返回副本。

    XrefIndex::callees

    fn XrefIndex::callees(self : XrefIndex, method_ref : Int) -> Array[XrefSite] raise DexError

    调用方侧查询:method_ref 发出的调用点(Call* 点、method_ref == 入参)。 排序(冻结):offset 升序。abstract/native 与外部方法(code==None) 返回空数组。method_ref 越界抛 InvalidIndex(MethodId, method_ref); 空结果=空数组。

    XrefIndex::callers

    fn XrefIndex::callers(self : XrefIndex, method_ref : Int) -> Array[XrefSite] raise DexError

    目标侧查询:谁调用了 method_ref(Call* 点、target_ref == method_ref)。 排序(冻结):caller 的 method_ref 升序、同 caller 内 offset 升序。 method_ref 越界抛 InvalidIndex(MethodId, method_ref);空结果=空数组。

    XrefIndex::field_sites

    fn XrefIndex::field_sites(self : XrefIndex, field_ref : Int) -> Array[XrefSite] raise DexError

    目标侧查询:对 field_ref 的字段访问点(Field* 点、target_ref == field_ref)。 排序(冻结):caller 的 method_ref 升序、同 caller 内 offset 升序。 field_ref 越界抛 InvalidIndex(FieldId, field_ref);空结果=空数组。

    XrefIndex::method_sites

    fn XrefIndex::method_sites(self : XrefIndex, method_ref : Int) -> Array[XrefSite] raise DexError

    目标侧查询:与 callers 等价(同序同内容),口径对称显式(契约 §0 ⑤)。 排序(冻结):caller 的 method_ref 升序、同 caller 内 offset 升序。 method_ref 越界抛 InvalidIndex(MethodId, method_ref)。

    XrefIndex::sites

    fn XrefIndex::sites(self : XrefIndex) -> Array[XrefSite]

    全量访问点(副本)。排序(冻结):method_ref 升序、offset 升序。

    XrefIndex::sites_in

    fn XrefIndex::sites_in(self : XrefIndex, method_ref : Int) -> Array[XrefSite] raise DexError

    调用方侧查询:method_ref 方法体内的全部访问点(Call* + Field*)。 排序(冻结):offset 升序。abstract/native 与外部方法(code==None) 返回空数组。method_ref 越界抛 InvalidIndex(MethodId, method_ref); 空结果=空数组。

    XrefIndexExt

    pub struct XrefIndexExt {
    all_sites : Array[XrefSiteExt]
    method_count : Int
    call_site_count : Int
    }

    逐 dex 的扩展访问点索引(不透明 pub struct,与 XrefIndex 同构)。 构建后只读。

    XrefIndexExt::callees

    fn XrefIndexExt::callees(self : XrefIndexExt, method_ref : Int) -> Array[XrefSiteExt] raise DexError

    调用方侧查询:method_ref 发出的扩展调用点。 method_ref 越界抛 InvalidIndex(MethodId, method_ref)。

    XrefIndexExt::callers

    fn XrefIndexExt::callers(self : XrefIndexExt, target_ref : Int) -> Array[XrefSiteExt] raise DexError

    目标侧查询:谁通过 0xFA–0xFD 族调用了 target_ref。 排序(冻结):caller 的 method_ref 升序、同 caller 内 offset 升序。 target_ref 越界(method_count 或 call_site_count)抛 InvalidIndex(MethodId|CallSiteId, target_ref)。

    XrefIndexExt::sites

    全量 site 副本(冻结排序:method_ref 升序 × offset 升序)。

    XrefKind

    pub(all) enum XrefKind {
    XrefCallVirtual
    XrefCallSuper
    XrefCallDirect
    XrefCallStatic
    XrefCallInterface
    XrefFieldReadStatic
    XrefFieldWriteStatic
    XrefFieldReadInstance
    XrefFieldWriteInstance
    }

    访问点类别:五族调用 + 四类字段访问(构造器顺序即冻结顺序)。

    XrefKindExt

    pub(all) enum XrefKindExt {
    XrefExtInvokePolymorphic
    XrefExtInvokePolymorphicRange
    XrefExtInvokeCustom
    XrefExtInvokeCustomRange
    }

    扩展调用点类别(0xFA–0xFF invoke-polymorphic / invoke-custom 体系)。

    XrefSite

    pub(all) struct XrefSite {
    method_ref : Int
    offset : Int
    target_ref : Int
    kind : XrefKind
    }

    单个访问点(冻结布局)。

    XrefSiteExt

    pub(all) struct XrefSiteExt {
    method_ref : Int
    offset : Int
    target_ref : Int
    kind : XrefKindExt
    }

    扩展调用点 site(结构与 XrefSite 对齐,kind 使用扩展枚举)。

    annotation_item

    fn annotation_item(data : Bytes, off : Int) -> Annotation raise DexError

    解码指定偏移处的 annotation_item(u8 visibility + encoded_annotation)。 错误同 class_annotations。

    annotation_set

    fn annotation_set(data : Bytes, off : Int) -> AnnotationSet raise DexError

    解码指定偏移处的 annotation_set_item。off 为文件内偏移(0x70 起)。 错误同 class_annotations。

    annotations_index

    fn annotations_index(data : Bytes) -> AnnotationsIndex raise DexError

    为单份 DEX 字节建立注解索引(一次全表读取 + 头部校验)。 批量遍历所有类时只调用一次,再复用两个查询方法。

    array_payload_view

    fn array_payload_view(data : Bytes, code_off : Int, u : Int) -> ArrayPayloadView raise DexError

    返回 data 中以 (code_off, u) 定位的 fill-array-data-payload 的元素视图。

    • code_off:code_item 偏移;u:payload 相对 insns 区的 code unit 偏移。
    • 返回:element_width 与 elements(每元素 width 字节小端原始序)。
    • 校验:任何越界 / 非 0x0300 ident / size 溢出 → BadCodeItem(code_off, …),不 panic。

    build_xref

    fn build_xref(dex : DexFile) -> XrefIndex raise DexError

    构建单 dex 的访问点索引:对 method_ids 表(DexFile::methods,parse 已回填 code/flags)一次线性扫描,instruction_operands 重解码每个操作数引用。

    • 参数:dex 为 parse 输出;方法身份用 method_ids 索引(Int32)。
    • 返回:XrefIndex,sites 按 (method_ref 升序, offset 升序) 排列(构建序即该序)。
    • 语义:仅 invoke-* 与 iget/iput/sget/sput 产 site;payload 伪指令、 aget/aput、const-string/const-class/类型引用、注解/静态初值的 ValueField/ValueMethod 均不产 site;abstract/native 与外部方法 (code==None)无自身 site,调用它们的点照常计。
    • 错误:仅传播 InvalidInstruction(签名保守带 raise)。

    build_xref_ext

    fn build_xref_ext(dex : DexFile) -> XrefIndexExt raise DexError

    构建扩展调用点索引。O(M+I) 一次线性扫描。
    • 仅 0xFA–0xFD 产 site(0xFE/0xFF const 族无调用目标), 且 instruction_operands 必须返回 IndexMethod(0xFA/0xFB) 或 IndexCallSite(0xFC/0xFD),否则 skip(防御)。
    • site 排序(冻结):method_ref 升序 × offset 升序, 与 build_xref 同契约。

    call_site_name

    fn call_site_name(dex : DexFile, index : Int) -> String raise DexError

    call_site@ 引用解析为可读符号名(DexFile 视图): call_site@N{bsm=…, name=…, type=…, args=[…]};越界抛 InvalidIndex(CallSiteId, index)。

    call_site_ref_name

    fn call_site_ref_name(data : Bytes, index : Int) -> String raise DexError

    call_site@ 引用解析为可读符号名(invoke-custom 的关联标注): call_site@N{bsm=…, name=…, type=…, args=[…]}(见 CallSiteItem::values 布局)。 index 为 call_site_ids 表索引;越界抛 InvalidIndex(CallSiteId, index)。

    call_sites

    fn call_sites(data : Bytes) -> Array[CallSiteItem] raise DexError

    解析 call_site_id_item 表(公开入口,自含:第一参数为原始 DEX 字节)。

    • 返回:表内全部 call_site(表序,values 为已解码 encoded_array); 无该表的 DEX 返回空数组。
    • 错误:同 method_handles;call_site_off 越界抛 BadTableOffset(CallSiteId, …)。
    • 线程:纯函数,无全局状态,可并发。

    catch_handlers

    fn catch_handlers(data : Bytes, list_off : Int) -> Array[CatchHandlerView] raise DexError

    解析 data 偏移 list_off 处的 encoded_catch_handler_list,返回逐 handler 视图。

    • list_off:handler list 的字节偏移(uleb128 计数起点)。
    • 返回:Array[CatchHandlerView],每项含 pairs(全量 type_addr_pairs)与 catch_all_offset(size<=0 时为 Some(addr),否则 None)。
    • 校验:越界 / 坏 uleb/sleb → BadCodeItem(code_off, …),不 panic。

    class_annotations

    fn class_annotations(data : Bytes, class_index : Int) -> AnnotationsDirectory? raise DexError

    解析指定类的注解目录(annotation_directory_item)。

    • 参数:data 为完整单 DEX 字节(调用方持有所有权);class_index 为 class_defs 表位置(与 DexFile::methods 的 class_index 同义)。
    • 返回:Some(AnnotationsDirectory)(class/field/method/parameter 四类); annotations_off == 0 时返回 None。
    • 错误:头部/表校验同 parse(BadMagic/UnsupportedVersion/BadTableOffset…); class_index 越界抛 InvalidIndex(ClassDef, ...);注解结构损坏抛 BadTableOffset(ClassDef, 偏移) 或 UnexpectedEof。
    • 线程:纯函数,无全局状态,可并发。
    • 批量:遍历全类请用 annotations_index(data) 建一次索引再复用查询方法, 单次入口每次都会重建六表(等价实现见索引视图)。
    • 非目标:不做注解语义解释(如 InnerClass 语义还原)、不做多 dex 合并。

    debug_info_view

    fn debug_info_view(data : Bytes, code_off : Int) -> DebugInfoView raise DexError

    展开 code_off 处 code_item 的 debug_info 流为 DebugInfoView。
    • data:完整 DEX 字节(需访问 string_ids / type_ids 表)。
    • code_off:code_item 的字节偏移。
    • debug_info_off == 0 时返回空 events(方法无 debug info)。
    • 越界/截断/坏 uleb/sleb → BadDebugInfo;索引越界 → InvalidIndex。

    disasm

    fn disasm(dex : DexFile, method_ref : Int) -> String raise DexError

    输出 smali 风格反汇编文本;不做 CFG、不做类型推断。 method_ref 为 method_ids 表索引;越界抛 InvalidIndex(MethodId, ...)。

    encoded_array

    fn encoded_array(data : Bytes, off : Int) -> Array[EncodedValue] raise DexError

    解码指定偏移处的 encoded_array(uleb128 size + encoded_value×size)。 注解默认值(AnnotationDefault)、静态初值等场景的通用入口。 错误同 class_annotations。

    field_ref_name

    fn field_ref_name(dex : DexFile, index : Int) -> String raise DexError

    按表解析字段引用为 Lcls;->name:type(与 disasm 文本一致)。

    instruction_operands

    fn instruction_operands(insn : Instruction) -> InsnOperands raise DexError

    计算单条指令的结构化操作数视图(从 Instruction::raw 重解码,纯函数)。

    • 参数:insn 为已解析指令(parse / DexFile::code 输出)。
    • 返回:InsnOperands;switch / 数组 payload 伪指令返回空视图。
    • 错误:未定义 opcode 抛 InvalidInstruction(offset, opcode)。

    instruction_ref_name

    fn instruction_ref_name(dex : DexFile, insn : Instruction) -> String? raise DexError

    一步解析指令的常量池引用名字:invoke→Lcls;->name(params)ret、 const-string→字符串池项、字段引用→Lcls;->name:type、类型引用→类名。 无引用操作数(如算术/跳转指令)返回 None。

    map_items

    fn map_items(data : Bytes) -> Array[MapItem] raise DexError

    返回 data 中 map_list 的结构化视图。

    • 参数:完整 DEX 字节(与 parse 同源)。
    • 返回:按 map_list 表序的 MapItem 数组;map_off = 0 返回空数组。
    • 校验:header 偏移 52 读取 map_off;越界/截断抛 UnexpectedEof; unused 非 0、size 为负、offset 越界抛 BadTableOffset(MapList, …)。

    method_handle_name

    fn method_handle_name(dex : DexFile, index : Int) -> String raise DexError

    method_handle@ 引用解析为可读符号名(DexFile 视图): <kind 标签> <目标>;越界抛 InvalidIndex(MethodHandle, index)。

    method_handle_ref_name

    fn method_handle_ref_name(data : Bytes, index : Int) -> String raise DexError

    method_handle@ 引用解析为可读符号名(method_handles 表项渲染): <kind 标签> <目标>,如 invoke-static Lcls;->m(II)I、put-static Lcls;->f:I。 index 为 method_handles 表索引(与 Instruction 操作数 method_handle@ 同口径); 越界抛 InvalidIndex(MethodHandle, index)。

    method_handles

    fn method_handles(data : Bytes) -> Array[MethodHandleItem] raise DexError

    解析 method_handles_item 表(公开入口,自含:第一参数为原始 DEX 字节)。

    • 返回:表内全部句柄(表序);035 及无该表的 DEX 返回空数组。
    • 错误:头部/表校验同 parse;kind 超范围或 res0 非 0 抛 BadTableOffset(MethodHandle, …),索引越界抛 InvalidIndex(FieldId|MethodId, …)。
    • 线程:纯函数,无全局状态,可并发。

    method_ref_name

    fn method_ref_name(dex : DexFile, index : Int) -> String raise DexError

    按表解析方法引用(invoke-*)为 Lcls;->name(params)ret(与 disasm 文本一致)。

    method_ref_of

    fn method_ref_of(dex : DexFile, m : MethodDef) -> Int?

    (class_index, name_index, proto_index) 三元组反查 method_ids 索引 (DEX 规范三元组唯一)。用于把 class_def 遍历序(direct_methods + virtual_methods)的 MethodDef 桥接为表索引身份;未命中返回 None。 O(M) 线性查找,无 raise。

    parse

    fn parse(data : Bytes) -> DexFile raise DexError

    解析单个 DEX 字节流。

    • 参数:data 为完整 DEX 文件字节;调用方保留所有权,本函数不缓存。
    • 返回:DexFile 纯值,包含六张表、class_def 与已解码的 code_item/指令流。
    • 错误:magic、版本、表偏移、索引越界、非法指令均以 DexError 传播。
    • 线程:无全局可变状态,可并发解析不同 DEX;返回值为只读。
    • 非目标:不做控制流图、不做 Java 反编译、不合并多 dex、不做符号解析。

    proto_name

    fn proto_name(dex : DexFile, index : Int) -> String raise DexError

    proto@ 引用解析为 (参数串)返回类型(DexFile 视图:const-method-type / invoke-polymorphic 的 proto 操作数);越界抛 InvalidIndex(ProtoId, index)。

    resolve_ref_name

    fn resolve_ref_name(dex : DexFile, kind : IndexKind, index : Int) -> String raise DexError

    按 IndexKind 综合解析常量池引用名字。 IndexNone 视为调用方错误,抛 InvalidIndex(ClassDef, index)。

    signature_ok

    fn signature_ok(data : Bytes) -> Bool raise DexError

    计算 data[32..] 的 SHA-1 并与 header[12..32] 的 signature 比对。

    • 参数:data 为完整 DEX 文件字节(至少 32 字节)。
    • 返回:一致为 true,否则 false(值化,不抛 checksum 类错误)。
    • 错误:不足 32 字节抛 DexError::UnexpectedEof(32)。
    • 非目标:不校验 adler32、不影响 parse 结果、不做 APK 签名验签。
    • 注意:SHA-1 在此仅作格式完整性校验,「通过」不等于来源可信。

    static_values

    fn static_values(data : Bytes, class_index : Int) -> Array[EncodedValue] raise DexError

    解析指定类的静态字段初值(class_def.static_values_off → encoded_array)。 加密字符串入口:静态常量字符串/整型初值在此展开为结构化常量值。

    • 返回:与 ClassDef::static_fields 前缀一一对应的值数组; DEX 只编码非默认值的前缀,尾部默认值被省略(返回数组长度 ≤ static_fields 长度)。 static_values_off == 0 时返回空数组。
    • 错误:同 class_annotations。
    • 批量:同 class_annotations,遍历全类请用 annotations_index(data)。

    string_ref_name

    fn string_ref_name(dex : DexFile, index : Int) -> String raise DexError

    按表解析字符串池项(const-string 的字符串池引用)。

    type_ref_name

    fn type_ref_name(dex : DexFile, index : Int) -> String raise DexError

    按表解析类型引用为类名(类型描述符,如 Lcom/foo/Bar;)。