binres

package
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 10, 2023 License: BSD-3-Clause Imports: 16 Imported by: 0

Documentation

Overview

Package binres implements encoding and decoding of android binary resources.

Binary resource structs support unmarshalling the binary output of aapt. Implementations of marshalling for each struct must produce the exact input sent to unmarshalling. This allows tests to validate each struct representation of the binary format as follows:

  • unmarshal the output of aapt
  • marshal the struct representation
  • perform byte-to-byte comparison with aapt output per chunk header and body

This process should strive to make structs idiomatic to make parsing xml text into structs trivial.

Once the struct representation is validated, tests for parsing xml text into structs can become self-referential as the following holds true:

  • the unmarshalled input of aapt output is the only valid target
  • the unmarshalled input of xml text may be compared to the unmarshalled input of aapt output to identify errors, e.g. text-trims, wrong flags, etc

This provides validation, byte-for-byte, for producing binary xml resources.

It should be made clear that unmarshalling binary resources is currently only in scope for proving that the BinaryMarshaler works correctly. Any other use is currently out of scope.

A simple view of binary xml document structure: 

XML
  Pool
  Map
  Namespace
  [...node]

Additional resources: https://android.googlesource.com/platform/frameworks/base/+/master/include/androidfw/ResourceTypes.h https://justanapplication.wordpress.com/2011/09/13/ (a series of articles, increment date)

Index

Constants

View Source 
const (
	// SortedFlag is 1 if the pool is sorted
	SortedFlag uint32 = 1 << 0
	// UTF8Flag is 1 if the pool uses utf8 strings
	UTF8Flag = 1 << 8
)
View Source 
const MinSDK = 15

MinSDK is the targeted sdk version for support by package binres.

View Source 
const NoEntry = 0xFFFFFFFF

NoEntry marks a key with no value in the table

Variables

This section is empty.

Functions

func PackResources 

func PackResources() ([]byte, error)

PackResources produces a stripped down gzip version of the resources.arsc from api jar.

Types

type Attribute 

type Attribute struct {
	NS         PoolRef
	Name       PoolRef
	RawValue   PoolRef // The original raw string value of this attribute.
	TypedValue Data    // Processesd typed value of this attribute.
}

Attribute represents an XML attribute

func (*Attribute) MarshalBinary 

func (attr *Attribute) MarshalBinary() ([]byte, error)

MarshalBinary outputs the binary format from a given attribute

func (*Attribute) UnmarshalBinary 

func (attr *Attribute) UnmarshalBinary(bin []byte) error

UnmarshalBinary creates the attribute end from binary data

type CharData 

type CharData struct {
	NodeHeader
	RawData   PoolRef // raw character data
	TypedData Data    // typed value of character data
}

CharData represents a CDATA node and includes ref to node's text value.

func (*CharData) MarshalBinary 

func (cdt *CharData) MarshalBinary() ([]byte, error)

MarshalBinary outputs the binary format from given character data

func (*CharData) UnmarshalBinary 

func (cdt *CharData) UnmarshalBinary(bin []byte) error

UnmarshalBinary creates the character data from binary data

type Data 

type Data struct {
	ByteSize uint16
	Res0     uint8 // always 0, useful for debugging bad read offsets
	Type     DataType
	Value    uint32
}

Data is the raw data stored in a value

func (*Data) MarshalBinary 

func (d *Data) MarshalBinary() ([]byte, error)

MarshalBinary outputs the binary format from a given data item

func (*Data) UnmarshalBinary 

func (d *Data) UnmarshalBinary(bin []byte) error

UnmarshalBinary creates the data item from binary data

type DataType 

type DataType uint8

DataType marks the type of a data item in a value 

const (
	DataNull             DataType = 0x00 // either 0 or 1 for resource undefined or empty
	DataReference        DataType = 0x01 // ResTable_ref, a reference to another resource table entry
	DataAttribute        DataType = 0x02 // attribute resource identifier
	DataString           DataType = 0x03 // index into the containing resource table's global value string pool
	DataFloat            DataType = 0x04 // single-precision floating point number
	DataDimension        DataType = 0x05 // complex number encoding a dimension value, such as "100in"
	DataFraction         DataType = 0x06 // complex number encoding a fraction of a container
	DataDynamicReference DataType = 0x07 // dynamic ResTable_ref, which needs to be resolved before it can be used like a TYPE_REFERENCE.
	DataIntDec           DataType = 0x10 // raw integer value of the form n..n
	DataIntHex           DataType = 0x11 // raw integer value of the form 0xn..n
	DataIntBool          DataType = 0x12 // either 0 or 1, for input "false" or "true"
	DataIntColorARGB8    DataType = 0x1c // raw integer value of the form #aarrggbb
	DataIntColorRGB8     DataType = 0x1d // raw integer value of the form #rrggbb
	DataIntColorARGB4    DataType = 0x1e // raw integer value of the form #argb
	DataIntColorRGB4     DataType = 0x1f // raw integer value of the form #rgb
)

explicitly defined for clarity and resolvability with apt source

func (DataType) String 

func (i DataType) String() string

type Element 

type Element struct {
	NodeHeader
	NS             PoolRef
	Name           PoolRef // name of node if element, otherwise chardata if CDATA
	AttributeStart uint16  // byte offset where attrs start
	AttributeSize  uint16  // byte size of attrs
	AttributeCount uint16  // length of attrs
	IDIndex        uint16  // Index (1-based) of the "id" attribute. 0 if none.
	ClassIndex     uint16  // Index (1-based) of the "class" attribute. 0 if none.
	StyleIndex     uint16  // Index (1-based) of the "style" attribute. 0 if none.

	Children []*Element
	// contains filtered or unexported fields
}

Element represents an XML element

func (*Element) MarshalBinary 

func (el *Element) MarshalBinary() ([]byte, error)

MarshalBinary outputs the binary format from a given element

func (*Element) UnmarshalBinary 

func (el *Element) UnmarshalBinary(buf []byte) error

UnmarshalBinary creates an element from binary data

type ElementEnd 

type ElementEnd struct {
	NodeHeader
	NS   PoolRef
	Name PoolRef // name of node if binElement, raw chardata if binCharData
}

ElementEnd marks the end of an element node, either Element or CharData.

func (*ElementEnd) MarshalBinary 

func (el *ElementEnd) MarshalBinary() ([]byte, error)

MarshalBinary outputs the binary format from a given element end

func (*ElementEnd) UnmarshalBinary 

func (el *ElementEnd) UnmarshalBinary(bin []byte) error

UnmarshalBinary creates the element end from binary data

type Entry 

type Entry struct {
	// contains filtered or unexported fields
}

Entry is a resource key typically followed by a value or resource map.

func (*Entry) MarshalBinary 

func (nt *Entry) MarshalBinary() ([]byte, error)

MarshalBinary outputs the binary format from a given entry

func (*Entry) UnmarshalBinary 

func (nt *Entry) UnmarshalBinary(bin []byte) error

UnmarshalBinary creates an entry from binary data

type Map 

type Map struct {
	// contains filtered or unexported fields
}

Map contains a uint32 slice mapping strings in the string pool back to resource identifiers. The i'th element of the slice is also the same i'th element of the string pool.

func (*Map) MarshalBinary 

func (m *Map) MarshalBinary() ([]byte, error)

MarshalBinary outputs the binary format from a given map

func (*Map) UnmarshalBinary 

func (m *Map) UnmarshalBinary(bin []byte) error

UnmarshalBinary creates the map from binary data

type Namespace 

type Namespace struct {
	NodeHeader
	// contains filtered or unexported fields
}

Namespace represents an XML namespace

func (*Namespace) MarshalBinary 

func (ns *Namespace) MarshalBinary() ([]byte, error)

MarshalBinary outputs the binary format from a given namespace

func (*Namespace) UnmarshalBinary 

func (ns *Namespace) UnmarshalBinary(bin []byte) error

UnmarshalBinary creates a namespace from binary data

type NodeHeader 

type NodeHeader struct {
	LineNumber uint32  // line number in source file this element appears
	Comment    PoolRef // optional xml comment associated with element, MaxUint32 if none
	// contains filtered or unexported fields
}

NodeHeader is header all xml node types have, providing additional information regarding an xml node over binChunkHeader.

func (*NodeHeader) MarshalBinary 

func (hdr *NodeHeader) MarshalBinary() ([]byte, error)

MarshalBinary outputs the binary format from a given header

func (*NodeHeader) UnmarshalBinary 

func (hdr *NodeHeader) UnmarshalBinary(bin []byte) error

UnmarshalBinary creates a node header from binary data

type Package 

type Package struct {
	// contains filtered or unexported fields
}

Package contains a collection of resource data types.

func (*Package) MarshalBinary 

func (pkg *Package) MarshalBinary() ([]byte, error)

MarshalBinary outputs the binary format from a given package

func (*Package) UnmarshalBinary 

func (pkg *Package) UnmarshalBinary(bin []byte) error

UnmarshalBinary creates a pakage from binary data

type Pool 

type Pool struct {
	// contains filtered or unexported fields
}

Pool is a container for string and style span collections.

Pool has the following structure marshalled: 

	chunkHeader
 uint32 number of strings in this pool
 uint32 number of style spans in pool
 uint32 SortedFlag, UTF8Flag
 uint32 index of string data from header
 uint32 index of style data from header
 []uint32 string indices starting at zero
 []uint16 or []uint8 concatenation of string entries

UTF-16 entries are as follows: 

uint16 string length, exclusive
uint16 [optional] low word if high bit of length set
[n]byte data
uint16 0x0000 terminator

UTF-8 entries are as follows: 

uint8 character length, exclusive
uint8 [optional] low word if high bit of character length set
uint8 byte length, exclusive
uint8 [optional] low word if high bit of byte length set
[n]byte data
uint8 0x00 terminator

func (*Pool) IsSorted 

func (pl *Pool) IsSorted() bool

IsSorted returns true if the sorted flag is set

func (*Pool) IsUTF8 

func (pl *Pool) IsUTF8() bool

IsUTF8 returns true if the UTF8Flag is set

func (*Pool) MarshalBinary 

func (pl *Pool) MarshalBinary() ([]byte, error)

MarshalBinary outputs the binary format from a given pool

func (*Pool) RefByName 

func (pl *Pool) RefByName(s string) (PoolRef, error)

RefByName returns the PoolRef of s, or error if not exists.

func (*Pool) UnmarshalBinary 

func (pl *Pool) UnmarshalBinary(bin []byte) error

UnmarshalBinary creates the pool from binary data

type PoolRef 

type PoolRef uint32

PoolRef is the i'th string in a pool.

func (PoolRef) Resolve 

func (ref PoolRef) Resolve(pl *Pool) string

Resolve returns the string entry of PoolRef in pl.

type ResType 

type ResType uint16

ResType is the type of a resource 

const (
	ResNull       ResType = 0x0000
	ResStringPool ResType = 0x0001
	ResTable      ResType = 0x0002
	ResXML        ResType = 0x0003

	ResXMLStartNamespace ResType = 0x0100
	ResXMLEndNamespace   ResType = 0x0101
	ResXMLStartElement   ResType = 0x0102
	ResXMLEndElement     ResType = 0x0103
	ResXMLCharData       ResType = 0x0104

	ResXMLResourceMap ResType = 0x0180

	ResTablePackage  ResType = 0x0200
	ResTableType     ResType = 0x0201
	ResTableTypeSpec ResType = 0x0202
	ResTableLibrary  ResType = 0x0203
)

explicitly defined for clarity and resolvability with apt source

func (ResType) IsSupported 

func (t ResType) IsSupported() bool

IsSupported returns if a type is supported

func (ResType) String 

func (i ResType) String() string

type Span 

type Span struct {
	// contains filtered or unexported fields
}

Span marks a span of characters

func (*Span) UnmarshalBinary 

func (spn *Span) UnmarshalBinary(bin []byte) error

UnmarshalBinary creates the span from binary data

type Table 

type Table struct {
	// contains filtered or unexported fields
}

Table is a container for packaged resources. Resource values within a package are obtained through pool while resource names and identifiers are obtained through each package's type and key pools respectively.

func NewMipmapTable 

func NewMipmapTable(pkgname string) (*Table, string)

NewMipmapTable returns a resource table initialized for a single xxxhdpi mipmap resource and the path to write resource data to.

func OpenSDKTable 

func OpenSDKTable() (*Table, error)

OpenSDKTable decodes resources.arsc from sdk platform jar.

func OpenTable 

func OpenTable() (*Table, error)

OpenTable decodes the prepacked resources.arsc for the supported sdk platform.

func (*Table) MarshalBinary 

func (tbl *Table) MarshalBinary() ([]byte, error)

MarshalBinary outputs the binary format from a given table

func (*Table) RefByName 

func (tbl *Table) RefByName(name string) (TableRef, error)

RefByName returns the TableRef by a given name. The ref may be used to resolve the associated Entry and is used for the generation of binary manifest files.

func (*Table) SpecByName 

func (tbl *Table) SpecByName(name string) (int, *Package, int, *TypeSpec, error)

SpecByName parses the spec name from an entry string if necessary and returns the Package and TypeSpec associated with that name along with their respective indices.

For example: 

tbl.SpecByName("@android:style/Theme.NoTitleBar")
tbl.SpecByName("style")

Both locate the spec by name "style".

func (*Table) UnmarshalBinary 

func (tbl *Table) UnmarshalBinary(bin []byte) error

UnmarshalBinary creates the table from binary data

type TableRef 

type TableRef uint32

TableRef uniquely identifies entries within a resource table.

func (TableRef) Resolve 

func (ref TableRef) Resolve(tbl *Table) (*Entry, error)

Resolve returns the Entry of TableRef in the given table.

A TableRef is structured as follows: 

0xpptteeee
pp: package index
tt: type spec index in package
eeee: entry index in type spec

The package and type spec values start at 1 for the first item, to help catch cases where they have not been supplied.

type Type 

type Type struct {
	// contains filtered or unexported fields
}

Type provides a collection of entries for a specific device configuration.

func (*Type) MarshalBinary 

func (typ *Type) MarshalBinary() ([]byte, error)

MarshalBinary outputs the binary format from a given type

func (*Type) UnmarshalBinary 

func (typ *Type) UnmarshalBinary(bin []byte) error

UnmarshalBinary creates the type from binary data

type TypeSpec 

type TypeSpec struct {
	// contains filtered or unexported fields
}

TypeSpec provides a specification for the resources defined by a particular type.

func (*TypeSpec) MarshalBinary 

func (spec *TypeSpec) MarshalBinary() ([]byte, error)

MarshalBinary outputs the binary format from a given type spec

func (*TypeSpec) UnmarshalBinary 

func (spec *TypeSpec) UnmarshalBinary(bin []byte) error

UnmarshalBinary creates the type spec from binary data

type Value 

type Value struct {
	// contains filtered or unexported fields
}

Value is resource value associated with a key

func (*Value) MarshalBinary 

func (val *Value) MarshalBinary() ([]byte, error)

MarshalBinary outputs the binary format from a given value

func (*Value) UnmarshalBinary 

func (val *Value) UnmarshalBinary(bin []byte) error

UnmarshalBinary creates the pool from binary data

type XML 

type XML struct {
	Pool *Pool
	Map  *Map

	Namespace *Namespace
	Children  []*Element
	// contains filtered or unexported fields
}

XML represents an XML text file in memory

func UnmarshalXML 

func UnmarshalXML(r io.Reader, withIcon bool, targetSDK int) (*XML, error)

UnmarshalXML decodes an AndroidManifest.xml document returning type XML containing decoded resources.

func (*XML) MarshalBinary 

func (bx *XML) MarshalBinary() ([]byte, error)

MarshalBinary formats the XML in memory to it's text appearance

func (*XML) RawValueByName 

func (bx *XML) RawValueByName(elname string, attrname xml.Name) (string, error)

RawValueByName returns the original raw string value of first matching element attribute, or error if not exists. Given <manifest package="VAL" ...> then RawValueByName("manifest", xml.Name{Local: "package"}) returns "VAL".

func (*XML) UnmarshalBinary 

func (bx *XML) UnmarshalBinary(buf []byte) error

UnmarshalBinary decodes all resource chunks in buf returning any error encountered.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.