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/libs/androidfw/include/androidfw/ResourceTypes.h https://justanapplication.wordpress.com/2011/09/13/ (a series of articles, increment date)

    Index

    Constants

    View Source
    const (
    	SortedFlag uint32 = 1 << 0
    	UTF8Flag          = 1 << 8
    )
    View Source
    const MinSDK = 15

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

      View Source
      const NoEntry = 0xFFFFFFFF

      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.
        }

        func (*Attribute) MarshalBinary

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

        func (*Attribute) UnmarshalBinary

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

        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)

          func (*CharData) UnmarshalBinary

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

          type Data

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

          func (*Data) MarshalBinary

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

          func (*Data) UnmarshalBinary

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

          type DataType

          type DataType uint8
          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
            }

            func (*Element) MarshalBinary

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

            func (*Element) UnmarshalBinary

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

            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)

              func (*ElementEnd) UnmarshalBinary

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

              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)

                func (*Entry) UnmarshalBinary

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

                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)

                  func (*Map) UnmarshalBinary

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

                  type Namespace

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

                  func (*Namespace) MarshalBinary

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

                  func (*Namespace) UnmarshalBinary

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

                  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)

                    func (*NodeHeader) UnmarshalBinary

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

                    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)

                      func (*Package) UnmarshalBinary

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

                      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

                        func (*Pool) IsUTF8

                        func (pl *Pool) IsUTF8() bool

                        func (*Pool) MarshalBinary

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

                        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

                          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
                              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

                                func (ResType) String

                                func (i ResType) String() string

                                type Span

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

                                func (*Span) UnmarshalBinary

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

                                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)

                                        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

                                            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)

                                                  func (*Type) UnmarshalBinary

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

                                                  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)

                                                    func (*TypeSpec) UnmarshalBinary

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

                                                    type Value

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

                                                    func (*Value) MarshalBinary

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

                                                    func (*Value) UnmarshalBinary

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

                                                    type XML

                                                    type XML struct {
                                                    	Pool *Pool
                                                    	Map  *Map
                                                    
                                                    	Namespace *Namespace
                                                    	Children  []*Element
                                                    	// contains filtered or unexported fields
                                                    }

                                                    func UnmarshalXML

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

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

                                                      func (*XML) MarshalBinary

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

                                                      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.