Home | History | Annotate | Download | only in libdex 
      1 /*
      2  * Copyright (C) 2008 The Android Open Source Project
      3  *
      4  * Licensed under the Apache License, Version 2.0 (the "License");
      5  * you may not use this file except in compliance with the License.
      6  * You may obtain a copy of the License at
      7  *
      8  *      http://www.apache.org/licenses/LICENSE-2.0
      9  *
     10  * Unless required by applicable law or agreed to in writing, software
     11  * distributed under the License is distributed on an "AS IS" BASIS,
     12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
     13  * See the License for the specific language governing permissions and
     14  * limitations under the License.
     15  */
     16 
     17 /*
     18  * Access .dex (Dalvik Executable Format) files.  The code here assumes that
     19  * the DEX file has been rewritten (byte-swapped, word-aligned) and that
     20  * the contents can be directly accessed as a collection of C arrays.  Please
     21  * see docs/dalvik/dex-format.html for a detailed description.
     22  *
     23  * The structure and field names were chosen to match those in the DEX spec.
     24  *
     25  * It's generally assumed that the DEX file will be stored in shared memory,
     26  * obviating the need to copy code and constant pool entries into newly
     27  * allocated storage.  Maintaining local pointers to items in the shared area
     28  * is valid and encouraged.
     29  *
     30  * All memory-mapped structures are 32-bit aligned unless otherwise noted.
     31  */
     32 
     33 #ifndef LIBDEX_DEXFILE_H_
     34 #define LIBDEX_DEXFILE_H_
     35 
     36 #ifndef LOG_TAG
     37 # define LOG_TAG "libdex"
     38 #endif
     39 
     40 #include <stdbool.h>
     41 #include <stdint.h>
     42 #include <stdio.h>
     43 #include <assert.h>
     44 #include "cutils/log.h"
     45 
     46 /*
     47  * If "very verbose" logging is enabled, make it equivalent to ALOGV.
     48  * Otherwise, make it disappear.
     49  *
     50  * Define this above the #include "Dalvik.h" to enable for only a
     51  * single file.
     52  */
     53 /* #define VERY_VERBOSE_LOG */
     54 #if defined(VERY_VERBOSE_LOG)
     55 # define LOGVV      ALOGV
     56 # define IF_LOGVV() IF_ALOGV()
     57 #else
     58 # define LOGVV(...) ((void)0)
     59 # define IF_LOGVV() if (false)
     60 #endif
     61 
     62 /*
     63  * These match the definitions in the VM specification.
     64  */
     65 typedef uint8_t             u1;
     66 typedef uint16_t            u2;
     67 typedef uint32_t            u4;
     68 typedef uint64_t            u8;
     69 typedef int8_t              s1;
     70 typedef int16_t             s2;
     71 typedef int32_t             s4;
     72 typedef int64_t             s8;
     73 
     74 #include "libdex/SysUtil.h"
     75 
     76 /*
     77  * gcc-style inline management -- ensures we have a copy of all functions
     78  * in the library, so code that links against us will work whether or not
     79  * it was built with optimizations enabled.
     80  */
     81 #ifndef _DEX_GEN_INLINES             /* only defined by DexInlines.c */
     82 # define DEX_INLINE extern __inline__
     83 #else
     84 # define DEX_INLINE
     85 #endif
     86 
     87 /* DEX file magic number */
     88 #define DEX_MAGIC       "dex\n"
     89 
     90 /* The version for android N, encoded in 4 bytes of ASCII. This differentiates dex files that may
     91  * use default methods.
     92  */
     93 #define DEX_MAGIC_VERS_37  "037\0"
     94 
     95 /* current version, encoded in 4 bytes of ASCII */
     96 #define DEX_MAGIC_VERS  "036\0"
     97 
     98 /*
     99  * older but still-recognized version (corresponding to Android API
    100  * levels 13 and earlier
    101  */
    102 #define DEX_MAGIC_VERS_API_13  "035\0"
    103 
    104 /* same, but for optimized DEX header */
    105 #define DEX_OPT_MAGIC   "dey\n"
    106 #define DEX_OPT_MAGIC_VERS  "036\0"
    107 
    108 #define DEX_DEP_MAGIC   "deps"
    109 
    110 /*
    111  * 160-bit SHA-1 digest.
    112  */
    113 enum { kSHA1DigestLen = 20,
    114        kSHA1DigestOutputLen = kSHA1DigestLen*2 +1 };
    115 
    116 /* general constants */
    117 enum {
    118     kDexEndianConstant = 0x12345678,    /* the endianness indicator */
    119     kDexNoIndex = 0xffffffff,           /* not a valid index value */
    120 };
    121 
    122 /*
    123  * Enumeration of all the primitive types.
    124  */
    125 enum PrimitiveType {
    126     PRIM_NOT        = 0,       /* value is a reference type, not a primitive type */
    127     PRIM_VOID       = 1,
    128     PRIM_BOOLEAN    = 2,
    129     PRIM_BYTE       = 3,
    130     PRIM_SHORT      = 4,
    131     PRIM_CHAR       = 5,
    132     PRIM_INT        = 6,
    133     PRIM_LONG       = 7,
    134     PRIM_FLOAT      = 8,
    135     PRIM_DOUBLE     = 9,
    136 };
    137 
    138 /*
    139  * access flags and masks; the "standard" ones are all <= 0x4000
    140  *
    141  * Note: There are related declarations in vm/oo/Object.h in the ClassFlags
    142  * enum.
    143  */
    144 enum {
    145     ACC_PUBLIC       = 0x00000001,       // class, field, method, ic
    146     ACC_PRIVATE      = 0x00000002,       // field, method, ic
    147     ACC_PROTECTED    = 0x00000004,       // field, method, ic
    148     ACC_STATIC       = 0x00000008,       // field, method, ic
    149     ACC_FINAL        = 0x00000010,       // class, field, method, ic
    150     ACC_SYNCHRONIZED = 0x00000020,       // method (only allowed on natives)
    151     ACC_SUPER        = 0x00000020,       // class (not used in Dalvik)
    152     ACC_VOLATILE     = 0x00000040,       // field
    153     ACC_BRIDGE       = 0x00000040,       // method (1.5)
    154     ACC_TRANSIENT    = 0x00000080,       // field
    155     ACC_VARARGS      = 0x00000080,       // method (1.5)
    156     ACC_NATIVE       = 0x00000100,       // method
    157     ACC_INTERFACE    = 0x00000200,       // class, ic
    158     ACC_ABSTRACT     = 0x00000400,       // class, method, ic
    159     ACC_STRICT       = 0x00000800,       // method
    160     ACC_SYNTHETIC    = 0x00001000,       // field, method, ic
    161     ACC_ANNOTATION   = 0x00002000,       // class, ic (1.5)
    162     ACC_ENUM         = 0x00004000,       // class, field, ic (1.5)
    163     ACC_CONSTRUCTOR  = 0x00010000,       // method (Dalvik only)
    164     ACC_DECLARED_SYNCHRONIZED =
    165                        0x00020000,       // method (Dalvik only)
    166     ACC_CLASS_MASK =
    167         (ACC_PUBLIC | ACC_FINAL | ACC_INTERFACE | ACC_ABSTRACT
    168                 | ACC_SYNTHETIC | ACC_ANNOTATION | ACC_ENUM),
    169     ACC_INNER_CLASS_MASK =
    170         (ACC_CLASS_MASK | ACC_PRIVATE | ACC_PROTECTED | ACC_STATIC),
    171     ACC_FIELD_MASK =
    172         (ACC_PUBLIC | ACC_PRIVATE | ACC_PROTECTED | ACC_STATIC | ACC_FINAL
    173                 | ACC_VOLATILE | ACC_TRANSIENT | ACC_SYNTHETIC | ACC_ENUM),
    174     ACC_METHOD_MASK =
    175         (ACC_PUBLIC | ACC_PRIVATE | ACC_PROTECTED | ACC_STATIC | ACC_FINAL
    176                 | ACC_SYNCHRONIZED | ACC_BRIDGE | ACC_VARARGS | ACC_NATIVE
    177                 | ACC_ABSTRACT | ACC_STRICT | ACC_SYNTHETIC | ACC_CONSTRUCTOR
    178                 | ACC_DECLARED_SYNCHRONIZED),
    179 };
    180 
    181 /* annotation constants */
    182 enum {
    183     kDexVisibilityBuild         = 0x00,     /* annotation visibility */
    184     kDexVisibilityRuntime       = 0x01,
    185     kDexVisibilitySystem        = 0x02,
    186 
    187     kDexAnnotationByte          = 0x00,
    188     kDexAnnotationShort         = 0x02,
    189     kDexAnnotationChar          = 0x03,
    190     kDexAnnotationInt           = 0x04,
    191     kDexAnnotationLong          = 0x06,
    192     kDexAnnotationFloat         = 0x10,
    193     kDexAnnotationDouble        = 0x11,
    194     kDexAnnotationString        = 0x17,
    195     kDexAnnotationType          = 0x18,
    196     kDexAnnotationField         = 0x19,
    197     kDexAnnotationMethod        = 0x1a,
    198     kDexAnnotationEnum          = 0x1b,
    199     kDexAnnotationArray         = 0x1c,
    200     kDexAnnotationAnnotation    = 0x1d,
    201     kDexAnnotationNull          = 0x1e,
    202     kDexAnnotationBoolean       = 0x1f,
    203 
    204     kDexAnnotationValueTypeMask = 0x1f,     /* low 5 bits */
    205     kDexAnnotationValueArgShift = 5,
    206 };
    207 
    208 /* map item type codes */
    209 enum {
    210     kDexTypeHeaderItem               = 0x0000,
    211     kDexTypeStringIdItem             = 0x0001,
    212     kDexTypeTypeIdItem               = 0x0002,
    213     kDexTypeProtoIdItem              = 0x0003,
    214     kDexTypeFieldIdItem              = 0x0004,
    215     kDexTypeMethodIdItem             = 0x0005,
    216     kDexTypeClassDefItem             = 0x0006,
    217     kDexTypeMapList                  = 0x1000,
    218     kDexTypeTypeList                 = 0x1001,
    219     kDexTypeAnnotationSetRefList     = 0x1002,
    220     kDexTypeAnnotationSetItem        = 0x1003,
    221     kDexTypeClassDataItem            = 0x2000,
    222     kDexTypeCodeItem                 = 0x2001,
    223     kDexTypeStringDataItem           = 0x2002,
    224     kDexTypeDebugInfoItem            = 0x2003,
    225     kDexTypeAnnotationItem           = 0x2004,
    226     kDexTypeEncodedArrayItem         = 0x2005,
    227     kDexTypeAnnotationsDirectoryItem = 0x2006,
    228 };
    229 
    230 /* auxillary data section chunk codes */
    231 enum {
    232     kDexChunkClassLookup            = 0x434c4b50,   /* CLKP */
    233     kDexChunkRegisterMaps           = 0x524d4150,   /* RMAP */
    234 
    235     kDexChunkEnd                    = 0x41454e44,   /* AEND */
    236 };
    237 
    238 /* debug info opcodes and constants */
    239 enum {
    240     DBG_END_SEQUENCE         = 0x00,
    241     DBG_ADVANCE_PC           = 0x01,
    242     DBG_ADVANCE_LINE         = 0x02,
    243     DBG_START_LOCAL          = 0x03,
    244     DBG_START_LOCAL_EXTENDED = 0x04,
    245     DBG_END_LOCAL            = 0x05,
    246     DBG_RESTART_LOCAL        = 0x06,
    247     DBG_SET_PROLOGUE_END     = 0x07,
    248     DBG_SET_EPILOGUE_BEGIN   = 0x08,
    249     DBG_SET_FILE             = 0x09,
    250     DBG_FIRST_SPECIAL        = 0x0a,
    251     DBG_LINE_BASE            = -4,
    252     DBG_LINE_RANGE           = 15,
    253 };
    254 
    255 /*
    256  * Direct-mapped "header_item" struct.
    257  */
    258 struct DexHeader {
    259     u1  magic[8];           /* includes version number */
    260     u4  checksum;           /* adler32 checksum */
    261     u1  signature[kSHA1DigestLen]; /* SHA-1 hash */
    262     u4  fileSize;           /* length of entire file */
    263     u4  headerSize;         /* offset to start of next section */
    264     u4  endianTag;
    265     u4  linkSize;
    266     u4  linkOff;
    267     u4  mapOff;
    268     u4  stringIdsSize;
    269     u4  stringIdsOff;
    270     u4  typeIdsSize;
    271     u4  typeIdsOff;
    272     u4  protoIdsSize;
    273     u4  protoIdsOff;
    274     u4  fieldIdsSize;
    275     u4  fieldIdsOff;
    276     u4  methodIdsSize;
    277     u4  methodIdsOff;
    278     u4  classDefsSize;
    279     u4  classDefsOff;
    280     u4  dataSize;
    281     u4  dataOff;
    282 };
    283 
    284 /*
    285  * Direct-mapped "map_item".
    286  */
    287 struct DexMapItem {
    288     u2 type;              /* type code (see kDexType* above) */
    289     u2 unused;
    290     u4 size;              /* count of items of the indicated type */
    291     u4 offset;            /* file offset to the start of data */
    292 };
    293 
    294 /*
    295  * Direct-mapped "map_list".
    296  */
    297 struct DexMapList {
    298     u4  size;               /* #of entries in list */
    299     DexMapItem list[1];     /* entries */
    300 };
    301 
    302 /*
    303  * Direct-mapped "string_id_item".
    304  */
    305 struct DexStringId {
    306     u4 stringDataOff;      /* file offset to string_data_item */
    307 };
    308 
    309 /*
    310  * Direct-mapped "type_id_item".
    311  */
    312 struct DexTypeId {
    313     u4  descriptorIdx;      /* index into stringIds list for type descriptor */
    314 };
    315 
    316 /*
    317  * Direct-mapped "field_id_item".
    318  */
    319 struct DexFieldId {
    320     u2  classIdx;           /* index into typeIds list for defining class */
    321     u2  typeIdx;            /* index into typeIds for field type */
    322     u4  nameIdx;            /* index into stringIds for field name */
    323 };
    324 
    325 /*
    326  * Direct-mapped "method_id_item".
    327  */
    328 struct DexMethodId {
    329     u2  classIdx;           /* index into typeIds list for defining class */
    330     u2  protoIdx;           /* index into protoIds for method prototype */
    331     u4  nameIdx;            /* index into stringIds for method name */
    332 };
    333 
    334 /*
    335  * Direct-mapped "proto_id_item".
    336  */
    337 struct DexProtoId {
    338     u4  shortyIdx;          /* index into stringIds for shorty descriptor */
    339     u4  returnTypeIdx;      /* index into typeIds list for return type */
    340     u4  parametersOff;      /* file offset to type_list for parameter types */
    341 };
    342 
    343 /*
    344  * Direct-mapped "class_def_item".
    345  */
    346 struct DexClassDef {
    347     u4  classIdx;           /* index into typeIds for this class */
    348     u4  accessFlags;
    349     u4  superclassIdx;      /* index into typeIds for superclass */
    350     u4  interfacesOff;      /* file offset to DexTypeList */
    351     u4  sourceFileIdx;      /* index into stringIds for source file name */
    352     u4  annotationsOff;     /* file offset to annotations_directory_item */
    353     u4  classDataOff;       /* file offset to class_data_item */
    354     u4  staticValuesOff;    /* file offset to DexEncodedArray */
    355 };
    356 
    357 /*
    358  * Direct-mapped "type_item".
    359  */
    360 struct DexTypeItem {
    361     u2  typeIdx;            /* index into typeIds */
    362 };
    363 
    364 /*
    365  * Direct-mapped "type_list".
    366  */
    367 struct DexTypeList {
    368     u4  size;               /* #of entries in list */
    369     DexTypeItem list[1];    /* entries */
    370 };
    371 
    372 /*
    373  * Direct-mapped "code_item".
    374  *
    375  * The "catches" table is used when throwing an exception,
    376  * "debugInfo" is used when displaying an exception stack trace or
    377  * debugging. An offset of zero indicates that there are no entries.
    378  */
    379 struct DexCode {
    380     u2  registersSize;
    381     u2  insSize;
    382     u2  outsSize;
    383     u2  triesSize;
    384     u4  debugInfoOff;       /* file offset to debug info stream */
    385     u4  insnsSize;          /* size of the insns array, in u2 units */
    386     u2  insns[1];
    387     /* followed by optional u2 padding */
    388     /* followed by try_item[triesSize] */
    389     /* followed by uleb128 handlersSize */
    390     /* followed by catch_handler_item[handlersSize] */
    391 };
    392 
    393 /*
    394  * Direct-mapped "try_item".
    395  */
    396 struct DexTry {
    397     u4  startAddr;          /* start address, in 16-bit code units */
    398     u2  insnCount;          /* instruction count, in 16-bit code units */
    399     u2  handlerOff;         /* offset in encoded handler data to handlers */
    400 };
    401 
    402 /*
    403  * Link table.  Currently undefined.
    404  */
    405 struct DexLink {
    406     u1  bleargh;
    407 };
    408 
    409 
    410 /*
    411  * Direct-mapped "annotations_directory_item".
    412  */
    413 struct DexAnnotationsDirectoryItem {
    414     u4  classAnnotationsOff;  /* offset to DexAnnotationSetItem */
    415     u4  fieldsSize;           /* count of DexFieldAnnotationsItem */
    416     u4  methodsSize;          /* count of DexMethodAnnotationsItem */
    417     u4  parametersSize;       /* count of DexParameterAnnotationsItem */
    418     /* followed by DexFieldAnnotationsItem[fieldsSize] */
    419     /* followed by DexMethodAnnotationsItem[methodsSize] */
    420     /* followed by DexParameterAnnotationsItem[parametersSize] */
    421 };
    422 
    423 /*
    424  * Direct-mapped "field_annotations_item".
    425  */
    426 struct DexFieldAnnotationsItem {
    427     u4  fieldIdx;
    428     u4  annotationsOff;             /* offset to DexAnnotationSetItem */
    429 };
    430 
    431 /*
    432  * Direct-mapped "method_annotations_item".
    433  */
    434 struct DexMethodAnnotationsItem {
    435     u4  methodIdx;
    436     u4  annotationsOff;             /* offset to DexAnnotationSetItem */
    437 };
    438 
    439 /*
    440  * Direct-mapped "parameter_annotations_item".
    441  */
    442 struct DexParameterAnnotationsItem {
    443     u4  methodIdx;
    444     u4  annotationsOff;             /* offset to DexAnotationSetRefList */
    445 };
    446 
    447 /*
    448  * Direct-mapped "annotation_set_ref_item".
    449  */
    450 struct DexAnnotationSetRefItem {
    451     u4  annotationsOff;             /* offset to DexAnnotationSetItem */
    452 };
    453 
    454 /*
    455  * Direct-mapped "annotation_set_ref_list".
    456  */
    457 struct DexAnnotationSetRefList {
    458     u4  size;
    459     DexAnnotationSetRefItem list[1];
    460 };
    461 
    462 /*
    463  * Direct-mapped "annotation_set_item".
    464  */
    465 struct DexAnnotationSetItem {
    466     u4  size;
    467     u4  entries[1];                 /* offset to DexAnnotationItem */
    468 };
    469 
    470 /*
    471  * Direct-mapped "annotation_item".
    472  *
    473  * NOTE: this structure is byte-aligned.
    474  */
    475 struct DexAnnotationItem {
    476     u1  visibility;
    477     u1  annotation[1];              /* data in encoded_annotation format */
    478 };
    479 
    480 /*
    481  * Direct-mapped "encoded_array".
    482  *
    483  * NOTE: this structure is byte-aligned.
    484  */
    485 struct DexEncodedArray {
    486     u1  array[1];                   /* data in encoded_array format */
    487 };
    488 
    489 /*
    490  * Lookup table for classes.  It provides a mapping from class name to
    491  * class definition.  Used by dexFindClass().
    492  *
    493  * We calculate this at DEX optimization time and embed it in the file so we
    494  * don't need the same hash table in every VM.  This is slightly slower than
    495  * a hash table with direct pointers to the items, but because it's shared
    496  * there's less of a penalty for using a fairly sparse table.
    497  */
    498 struct DexClassLookup {
    499     int     size;                       // total size, including "size"
    500     int     numEntries;                 // size of table[]; always power of 2
    501     struct {
    502         u4      classDescriptorHash;    // class descriptor hash code
    503         int     classDescriptorOffset;  // in bytes, from start of DEX
    504         int     classDefOffset;         // in bytes, from start of DEX
    505     } table[1];
    506 };
    507 
    508 /*
    509  * Header added by DEX optimization pass.  Values are always written in
    510  * local byte and structure padding.  The first field (magic + version)
    511  * is guaranteed to be present and directly readable for all expected
    512  * compiler configurations; the rest is version-dependent.
    513  *
    514  * Try to keep this simple and fixed-size.
    515  */
    516 struct DexOptHeader {
    517     u1  magic[8];           /* includes version number */
    518 
    519     u4  dexOffset;          /* file offset of DEX header */
    520     u4  dexLength;
    521     u4  depsOffset;         /* offset of optimized DEX dependency table */
    522     u4  depsLength;
    523     u4  optOffset;          /* file offset of optimized data tables */
    524     u4  optLength;
    525 
    526     u4  flags;              /* some info flags */
    527     u4  checksum;           /* adler32 checksum covering deps/opt */
    528 
    529     /* pad for 64-bit alignment if necessary */
    530 };
    531 
    532 #define DEX_OPT_FLAG_BIG            (1<<1)  /* swapped to big-endian */
    533 
    534 #define DEX_INTERFACE_CACHE_SIZE    128     /* must be power of 2 */
    535 
    536 /*
    537  * Structure representing a DEX file.
    538  *
    539  * Code should regard DexFile as opaque, using the API calls provided here
    540  * to access specific structures.
    541  */
    542 struct DexFile {
    543     /* directly-mapped "opt" header */
    544     const DexOptHeader* pOptHeader;
    545 
    546     /* pointers to directly-mapped structs and arrays in base DEX */
    547     const DexHeader*    pHeader;
    548     const DexStringId*  pStringIds;
    549     const DexTypeId*    pTypeIds;
    550     const DexFieldId*   pFieldIds;
    551     const DexMethodId*  pMethodIds;
    552     const DexProtoId*   pProtoIds;
    553     const DexClassDef*  pClassDefs;
    554     const DexLink*      pLinkData;
    555 
    556     /*
    557      * These are mapped out of the "auxillary" section, and may not be
    558      * included in the file.
    559      */
    560     const DexClassLookup* pClassLookup;
    561     const void*         pRegisterMapPool;       // RegisterMapClassPool
    562 
    563     /* points to start of DEX file data */
    564     const u1*           baseAddr;
    565 
    566     /* track memory overhead for auxillary structures */
    567     int                 overhead;
    568 
    569     /* additional app-specific data structures associated with the DEX */
    570     //void*               auxData;
    571 };
    572 
    573 /*
    574  * Utility function -- rounds up to the nearest power of 2.
    575  */
    576 u4 dexRoundUpPower2(u4 val);
    577 
    578 /*
    579  * Parse an optimized or unoptimized .dex file sitting in memory.
    580  *
    581  * On success, return a newly-allocated DexFile.
    582  */
    583 DexFile* dexFileParse(const u1* data, size_t length, int flags);
    584 
    585 /* bit values for "flags" argument to dexFileParse */
    586 enum {
    587     kDexParseDefault            = 0,
    588     kDexParseVerifyChecksum     = 1,
    589     kDexParseContinueOnError    = (1 << 1),
    590 };
    591 
    592 /*
    593  * Fix the byte ordering of all fields in the DEX file, and do
    594  * structural verification. This is only required for code that opens
    595  * "raw" DEX files, such as the DEX optimizer.
    596  *
    597  * Return 0 on success.
    598  */
    599 int dexSwapAndVerify(u1* addr, int len);
    600 
    601 /*
    602  * Detect the file type of the given memory buffer via magic number.
    603  * Call dexSwapAndVerify() on an unoptimized DEX file, do nothing
    604  * but return successfully on an optimized DEX file, and report an
    605  * error for all other cases.
    606  *
    607  * Return 0 on success.
    608  */
    609 int dexSwapAndVerifyIfNecessary(u1* addr, int len);
    610 
    611 /*
    612  * Check to see if the file magic and format version in the given
    613  * header are recognized as valid. Returns true if they are
    614  * acceptable.
    615  */
    616 bool dexHasValidMagic(const DexHeader* pHeader);
    617 
    618 /*
    619  * Compute DEX checksum.
    620  */
    621 u4 dexComputeChecksum(const DexHeader* pHeader);
    622 
    623 /*
    624  * Free a DexFile structure, along with any associated structures.
    625  */
    626 void dexFileFree(DexFile* pDexFile);
    627 
    628 /*
    629  * Create class lookup table.
    630  */
    631 DexClassLookup* dexCreateClassLookup(DexFile* pDexFile);
    632 
    633 /*
    634  * Find a class definition by descriptor.
    635  */
    636 const DexClassDef* dexFindClass(const DexFile* pFile, const char* descriptor);
    637 
    638 /*
    639  * Set up the basic raw data pointers of a DexFile. This function isn't
    640  * meant for general use.
    641  */
    642 void dexFileSetupBasicPointers(DexFile* pDexFile, const u1* data);
    643 
    644 /* return the DexMapList of the file, if any */
    645 DEX_INLINE const DexMapList* dexGetMap(const DexFile* pDexFile) {
    646     u4 mapOff = pDexFile->pHeader->mapOff;
    647 
    648     if (mapOff == 0) {
    649         return NULL;
    650     } else {
    651         return (const DexMapList*) (pDexFile->baseAddr + mapOff);
    652     }
    653 }
    654 
    655 /* return the const char* string data referred to by the given string_id */
    656 DEX_INLINE const char* dexGetStringData(const DexFile* pDexFile,
    657         const DexStringId* pStringId) {
    658     const u1* ptr = pDexFile->baseAddr + pStringId->stringDataOff;
    659 
    660     // Skip the uleb128 length.
    661     while (*(ptr++) > 0x7f) /* empty */ ;
    662 
    663     return (const char*) ptr;
    664 }
    665 /* return the StringId with the specified index */
    666 DEX_INLINE const DexStringId* dexGetStringId(const DexFile* pDexFile, u4 idx) {
    667     assert(idx < pDexFile->pHeader->stringIdsSize);
    668     return &pDexFile->pStringIds[idx];
    669 }
    670 /* return the UTF-8 encoded string with the specified string_id index */
    671 DEX_INLINE const char* dexStringById(const DexFile* pDexFile, u4 idx) {
    672     const DexStringId* pStringId = dexGetStringId(pDexFile, idx);
    673     return dexGetStringData(pDexFile, pStringId);
    674 }
    675 
    676 /* Return the UTF-8 encoded string with the specified string_id index,
    677  * also filling in the UTF-16 size (number of 16-bit code points).*/
    678 const char* dexStringAndSizeById(const DexFile* pDexFile, u4 idx,
    679         u4* utf16Size);
    680 
    681 /* return the TypeId with the specified index */
    682 DEX_INLINE const DexTypeId* dexGetTypeId(const DexFile* pDexFile, u4 idx) {
    683     assert(idx < pDexFile->pHeader->typeIdsSize);
    684     return &pDexFile->pTypeIds[idx];
    685 }
    686 
    687 /*
    688  * Get the descriptor string associated with a given type index.
    689  * The caller should not free() the returned string.
    690  */
    691 DEX_INLINE const char* dexStringByTypeIdx(const DexFile* pDexFile, u4 idx) {
    692     const DexTypeId* typeId = dexGetTypeId(pDexFile, idx);
    693     return dexStringById(pDexFile, typeId->descriptorIdx);
    694 }
    695 
    696 /* return the MethodId with the specified index */
    697 DEX_INLINE const DexMethodId* dexGetMethodId(const DexFile* pDexFile, u4 idx) {
    698     assert(idx < pDexFile->pHeader->methodIdsSize);
    699     return &pDexFile->pMethodIds[idx];
    700 }
    701 
    702 /* return the FieldId with the specified index */
    703 DEX_INLINE const DexFieldId* dexGetFieldId(const DexFile* pDexFile, u4 idx) {
    704     assert(idx < pDexFile->pHeader->fieldIdsSize);
    705     return &pDexFile->pFieldIds[idx];
    706 }
    707 
    708 /* return the ProtoId with the specified index */
    709 DEX_INLINE const DexProtoId* dexGetProtoId(const DexFile* pDexFile, u4 idx) {
    710     assert(idx < pDexFile->pHeader->protoIdsSize);
    711     return &pDexFile->pProtoIds[idx];
    712 }
    713 
    714 /*
    715  * Get the parameter list from a ProtoId. The returns NULL if the ProtoId
    716  * does not have a parameter list.
    717  */
    718 DEX_INLINE const DexTypeList* dexGetProtoParameters(
    719     const DexFile *pDexFile, const DexProtoId* pProtoId) {
    720     if (pProtoId->parametersOff == 0) {
    721         return NULL;
    722     }
    723     return (const DexTypeList*)
    724         (pDexFile->baseAddr + pProtoId->parametersOff);
    725 }
    726 
    727 /* return the ClassDef with the specified index */
    728 DEX_INLINE const DexClassDef* dexGetClassDef(const DexFile* pDexFile, u4 idx) {
    729     assert(idx < pDexFile->pHeader->classDefsSize);
    730     return &pDexFile->pClassDefs[idx];
    731 }
    732 
    733 /* given a ClassDef pointer, recover its index */
    734 DEX_INLINE u4 dexGetIndexForClassDef(const DexFile* pDexFile,
    735     const DexClassDef* pClassDef)
    736 {
    737     assert(pClassDef >= pDexFile->pClassDefs &&
    738            pClassDef < pDexFile->pClassDefs + pDexFile->pHeader->classDefsSize);
    739     return pClassDef - pDexFile->pClassDefs;
    740 }
    741 
    742 /* get the interface list for a DexClass */
    743 DEX_INLINE const DexTypeList* dexGetInterfacesList(const DexFile* pDexFile,
    744     const DexClassDef* pClassDef)
    745 {
    746     if (pClassDef->interfacesOff == 0)
    747         return NULL;
    748     return (const DexTypeList*)
    749         (pDexFile->baseAddr + pClassDef->interfacesOff);
    750 }
    751 /* return the Nth entry in a DexTypeList. */
    752 DEX_INLINE const DexTypeItem* dexGetTypeItem(const DexTypeList* pList,
    753     u4 idx)
    754 {
    755     assert(idx < pList->size);
    756     return &pList->list[idx];
    757 }
    758 /* return the type_idx for the Nth entry in a TypeList */
    759 DEX_INLINE u4 dexTypeListGetIdx(const DexTypeList* pList, u4 idx) {
    760     const DexTypeItem* pItem = dexGetTypeItem(pList, idx);
    761     return pItem->typeIdx;
    762 }
    763 
    764 /* get the static values list for a DexClass */
    765 DEX_INLINE const DexEncodedArray* dexGetStaticValuesList(
    766     const DexFile* pDexFile, const DexClassDef* pClassDef)
    767 {
    768     if (pClassDef->staticValuesOff == 0)
    769         return NULL;
    770     return (const DexEncodedArray*)
    771         (pDexFile->baseAddr + pClassDef->staticValuesOff);
    772 }
    773 
    774 /* get the annotations directory item for a DexClass */
    775 DEX_INLINE const DexAnnotationsDirectoryItem* dexGetAnnotationsDirectoryItem(
    776     const DexFile* pDexFile, const DexClassDef* pClassDef)
    777 {
    778     if (pClassDef->annotationsOff == 0)
    779         return NULL;
    780     return (const DexAnnotationsDirectoryItem*)
    781         (pDexFile->baseAddr + pClassDef->annotationsOff);
    782 }
    783 
    784 /* get the source file string */
    785 DEX_INLINE const char* dexGetSourceFile(
    786     const DexFile* pDexFile, const DexClassDef* pClassDef)
    787 {
    788     if (pClassDef->sourceFileIdx == 0xffffffff)
    789         return NULL;
    790     return dexStringById(pDexFile, pClassDef->sourceFileIdx);
    791 }
    792 
    793 /* get the size, in bytes, of a DexCode */
    794 size_t dexGetDexCodeSize(const DexCode* pCode);
    795 
    796 /* Get the list of "tries" for the given DexCode. */
    797 DEX_INLINE const DexTry* dexGetTries(const DexCode* pCode) {
    798     const u2* insnsEnd = &pCode->insns[pCode->insnsSize];
    799 
    800     // Round to four bytes.
    801     if ((((uintptr_t) insnsEnd) & 3) != 0) {
    802         insnsEnd++;
    803     }
    804 
    805     return (const DexTry*) insnsEnd;
    806 }
    807 
    808 /* Get the base of the encoded data for the given DexCode. */
    809 DEX_INLINE const u1* dexGetCatchHandlerData(const DexCode* pCode) {
    810     const DexTry* pTries = dexGetTries(pCode);
    811     return (const u1*) &pTries[pCode->triesSize];
    812 }
    813 
    814 /* get a pointer to the start of the debugging data */
    815 DEX_INLINE const u1* dexGetDebugInfoStream(const DexFile* pDexFile,
    816     const DexCode* pCode)
    817 {
    818     if (pCode->debugInfoOff == 0) {
    819         return NULL;
    820     } else {
    821         return pDexFile->baseAddr + pCode->debugInfoOff;
    822     }
    823 }
    824 
    825 /* DexClassDef convenience - get class descriptor */
    826 DEX_INLINE const char* dexGetClassDescriptor(const DexFile* pDexFile,
    827     const DexClassDef* pClassDef)
    828 {
    829     return dexStringByTypeIdx(pDexFile, pClassDef->classIdx);
    830 }
    831 
    832 /* DexClassDef convenience - get superclass descriptor */
    833 DEX_INLINE const char* dexGetSuperClassDescriptor(const DexFile* pDexFile,
    834     const DexClassDef* pClassDef)
    835 {
    836     if (pClassDef->superclassIdx == 0)
    837         return NULL;
    838     return dexStringByTypeIdx(pDexFile, pClassDef->superclassIdx);
    839 }
    840 
    841 /* DexClassDef convenience - get class_data_item pointer */
    842 DEX_INLINE const u1* dexGetClassData(const DexFile* pDexFile,
    843     const DexClassDef* pClassDef)
    844 {
    845     if (pClassDef->classDataOff == 0)
    846         return NULL;
    847     return (const u1*) (pDexFile->baseAddr + pClassDef->classDataOff);
    848 }
    849 
    850 /* Get an annotation set at a particular offset. */
    851 DEX_INLINE const DexAnnotationSetItem* dexGetAnnotationSetItem(
    852     const DexFile* pDexFile, u4 offset)
    853 {
    854     if (offset == 0) {
    855         return NULL;
    856     }
    857     return (const DexAnnotationSetItem*) (pDexFile->baseAddr + offset);
    858 }
    859 /* get the class' annotation set */
    860 DEX_INLINE const DexAnnotationSetItem* dexGetClassAnnotationSet(
    861     const DexFile* pDexFile, const DexAnnotationsDirectoryItem* pAnnoDir)
    862 {
    863     return dexGetAnnotationSetItem(pDexFile, pAnnoDir->classAnnotationsOff);
    864 }
    865 
    866 /* get the class' field annotation list */
    867 DEX_INLINE const DexFieldAnnotationsItem* dexGetFieldAnnotations(
    868     const DexFile* pDexFile, const DexAnnotationsDirectoryItem* pAnnoDir)
    869 {
    870     (void) pDexFile;
    871     if (pAnnoDir->fieldsSize == 0)
    872         return NULL;
    873 
    874     // Skip past the header to the start of the field annotations.
    875     return (const DexFieldAnnotationsItem*) &pAnnoDir[1];
    876 }
    877 
    878 /* get field annotation list size */
    879 DEX_INLINE int dexGetFieldAnnotationsSize(const DexFile* pDexFile,
    880     const DexAnnotationsDirectoryItem* pAnnoDir)
    881 {
    882     (void) pDexFile;
    883     return pAnnoDir->fieldsSize;
    884 }
    885 
    886 /* return a pointer to the field's annotation set */
    887 DEX_INLINE const DexAnnotationSetItem* dexGetFieldAnnotationSetItem(
    888     const DexFile* pDexFile, const DexFieldAnnotationsItem* pItem)
    889 {
    890     return dexGetAnnotationSetItem(pDexFile, pItem->annotationsOff);
    891 }
    892 
    893 /* get the class' method annotation list */
    894 DEX_INLINE const DexMethodAnnotationsItem* dexGetMethodAnnotations(
    895     const DexFile* pDexFile, const DexAnnotationsDirectoryItem* pAnnoDir)
    896 {
    897     (void) pDexFile;
    898     if (pAnnoDir->methodsSize == 0)
    899         return NULL;
    900 
    901     /*
    902      * Skip past the header and field annotations to the start of the
    903      * method annotations.
    904      */
    905     const u1* addr = (const u1*) &pAnnoDir[1];
    906     addr += pAnnoDir->fieldsSize * sizeof (DexFieldAnnotationsItem);
    907     return (const DexMethodAnnotationsItem*) addr;
    908 }
    909 
    910 /* get method annotation list size */
    911 DEX_INLINE int dexGetMethodAnnotationsSize(const DexFile* pDexFile,
    912     const DexAnnotationsDirectoryItem* pAnnoDir)
    913 {
    914     (void) pDexFile;
    915     return pAnnoDir->methodsSize;
    916 }
    917 
    918 /* return a pointer to the method's annotation set */
    919 DEX_INLINE const DexAnnotationSetItem* dexGetMethodAnnotationSetItem(
    920     const DexFile* pDexFile, const DexMethodAnnotationsItem* pItem)
    921 {
    922     return dexGetAnnotationSetItem(pDexFile, pItem->annotationsOff);
    923 }
    924 
    925 /* get the class' parameter annotation list */
    926 DEX_INLINE const DexParameterAnnotationsItem* dexGetParameterAnnotations(
    927     const DexFile* pDexFile, const DexAnnotationsDirectoryItem* pAnnoDir)
    928 {
    929     (void) pDexFile;
    930     if (pAnnoDir->parametersSize == 0)
    931         return NULL;
    932 
    933     /*
    934      * Skip past the header, field annotations, and method annotations
    935      * to the start of the parameter annotations.
    936      */
    937     const u1* addr = (const u1*) &pAnnoDir[1];
    938     addr += pAnnoDir->fieldsSize * sizeof (DexFieldAnnotationsItem);
    939     addr += pAnnoDir->methodsSize * sizeof (DexMethodAnnotationsItem);
    940     return (const DexParameterAnnotationsItem*) addr;
    941 }
    942 
    943 /* get method annotation list size */
    944 DEX_INLINE int dexGetParameterAnnotationsSize(const DexFile* pDexFile,
    945     const DexAnnotationsDirectoryItem* pAnnoDir)
    946 {
    947     (void) pDexFile;
    948     return pAnnoDir->parametersSize;
    949 }
    950 
    951 /* return the parameter annotation ref list */
    952 DEX_INLINE const DexAnnotationSetRefList* dexGetParameterAnnotationSetRefList(
    953     const DexFile* pDexFile, const DexParameterAnnotationsItem* pItem)
    954 {
    955     if (pItem->annotationsOff == 0) {
    956         return NULL;
    957     }
    958     return (const DexAnnotationSetRefList*) (pDexFile->baseAddr + pItem->annotationsOff);
    959 }
    960 
    961 /* get method annotation list size */
    962 DEX_INLINE int dexGetParameterAnnotationSetRefSize(const DexFile* pDexFile,
    963     const DexParameterAnnotationsItem* pItem)
    964 {
    965     if (pItem->annotationsOff == 0) {
    966         return 0;
    967     }
    968     return dexGetParameterAnnotationSetRefList(pDexFile, pItem)->size;
    969 }
    970 
    971 /* return the Nth entry from an annotation set ref list */
    972 DEX_INLINE const DexAnnotationSetRefItem* dexGetParameterAnnotationSetRef(
    973     const DexAnnotationSetRefList* pList, u4 idx)
    974 {
    975     assert(idx < pList->size);
    976     return &pList->list[idx];
    977 }
    978 
    979 /* given a DexAnnotationSetRefItem, return the DexAnnotationSetItem */
    980 DEX_INLINE const DexAnnotationSetItem* dexGetSetRefItemItem(
    981     const DexFile* pDexFile, const DexAnnotationSetRefItem* pItem)
    982 {
    983     return dexGetAnnotationSetItem(pDexFile, pItem->annotationsOff);
    984 }
    985 
    986 /* return the Nth annotation offset from a DexAnnotationSetItem */
    987 DEX_INLINE u4 dexGetAnnotationOff(
    988     const DexAnnotationSetItem* pAnnoSet, u4 idx)
    989 {
    990     assert(idx < pAnnoSet->size);
    991     return pAnnoSet->entries[idx];
    992 }
    993 
    994 /* return the Nth annotation item from a DexAnnotationSetItem */
    995 DEX_INLINE const DexAnnotationItem* dexGetAnnotationItem(
    996     const DexFile* pDexFile, const DexAnnotationSetItem* pAnnoSet, u4 idx)
    997 {
    998     u4 offset = dexGetAnnotationOff(pAnnoSet, idx);
    999     if (offset == 0) {
   1000         return NULL;
   1001     }
   1002     return (const DexAnnotationItem*) (pDexFile->baseAddr + offset);
   1003 }
   1004 
   1005 /*
   1006  * Get the type descriptor character associated with a given primitive
   1007  * type. This returns '\0' if the type is invalid.
   1008  */
   1009 char dexGetPrimitiveTypeDescriptorChar(PrimitiveType type);
   1010 
   1011 /*
   1012  * Get the type descriptor string associated with a given primitive
   1013  * type.
   1014  */
   1015 const char* dexGetPrimitiveTypeDescriptor(PrimitiveType type);
   1016 
   1017 /*
   1018  * Get the boxed type descriptor string associated with a given
   1019  * primitive type. This returns NULL for an invalid type, including
   1020  * particularly for type "void". In the latter case, even though there
   1021  * is a class Void, there's no such thing as a boxed instance of it.
   1022  */
   1023 const char* dexGetBoxedTypeDescriptor(PrimitiveType type);
   1024 
   1025 /*
   1026  * Get the primitive type constant from the given descriptor character.
   1027  * This returns PRIM_NOT (note: this is a 0) if the character is invalid
   1028  * as a primitive type descriptor.
   1029  */
   1030 PrimitiveType dexGetPrimitiveTypeFromDescriptorChar(char descriptorChar);
   1031 
   1032 #endif  // LIBDEX_DEXFILE_H_
   1033