1 page.title=Dalvik Executable format 2 @jd:body 3 4 <!-- 5 Copyright 2015 The Android Open Source Project 6 7 Licensed under the Apache License, Version 2.0 (the "License"); 8 you may not use this file except in compliance with the License. 9 You may obtain a copy of the License at 10 11 http://www.apache.org/licenses/LICENSE-2.0 12 13 Unless required by applicable law or agreed to in writing, software 14 distributed under the License is distributed on an "AS IS" BASIS, 15 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 16 See the License for the specific language governing permissions and 17 limitations under the License. 18 --> 19 <p>This document describes the layout and contents of <code>.dex</code> 20 files, which are used to hold a set of class definitions and their associated 21 adjunct data.</p> 22 23 <h2 id="types">Guide to types</h2> 24 25 <table class="guide"> 26 <thead> 27 <tr> 28 <th>Name</th> 29 <th>Description</th> 30 </tr> 31 </thead> 32 <tbody> 33 <tr> 34 <td>byte</td> 35 <td>8-bit signed int</td> 36 </tr> 37 <tr> 38 <td>ubyte</td> 39 <td>8-bit unsigned int</td> 40 </tr> 41 <tr> 42 <td>short</td> 43 <td>16-bit signed int, little-endian</td> 44 </tr> 45 <tr> 46 <td>ushort</td> 47 <td>16-bit unsigned int, little-endian</td> 48 </tr> 49 <tr> 50 <td>int</td> 51 <td>32-bit signed int, little-endian</td> 52 </tr> 53 <tr> 54 <td>uint</td> 55 <td>32-bit unsigned int, little-endian</td> 56 </tr> 57 <tr> 58 <td>long</td> 59 <td>64-bit signed int, little-endian</td> 60 </tr> 61 <tr> 62 <td>ulong</td> 63 <td>64-bit unsigned int, little-endian</td> 64 </tr> 65 <tr> 66 <td>sleb128</td> 67 <td>signed LEB128, variable-length (see below)</td> 68 </tr> 69 <tr> 70 <td>uleb128</td> 71 <td>unsigned LEB128, variable-length (see below)</td> 72 </tr> 73 <tr> 74 <td>uleb128p1</td> 75 <td>unsigned LEB128 plus <code>1</code>, variable-length (see below)</td> 76 </tr> 77 </tbody> 78 </table> 79 80 <h3 id="leb128">LEB128</h3> 81 82 <p>LEB128 ("<b>L</b>ittle-<b>E</b>ndian <b>B</b>ase <b>128</b>") is a 83 variable-length encoding for 84 arbitrary signed or unsigned integer quantities. The format was 85 borrowed from the <a href="http://dwarfstd.org/Dwarf3Std.php">DWARF3</a> 86 specification. In a <code>.dex</code> file, LEB128 is only ever used to 87 encode 32-bit quantities.</p> 88 89 <p>Each LEB128 encoded value consists of one to five 90 bytes, which together represent a single 32-bit value. Each 91 byte has its most significant bit set except for the final byte in the 92 sequence, which has its most significant bit clear. The remaining 93 seven bits of each byte are payload, with the least significant seven 94 bits of the quantity in the first byte, the next seven in the second 95 byte and so on. In the case of a signed LEB128 (<code>sleb128</code>), 96 the most significant payload bit of the final byte in the sequence is 97 sign-extended to produce the final value. In the unsigned case 98 (<code>uleb128</code>), any bits not explicitly represented are 99 interpreted as <code>0</code>. 100 101 <table class="leb128Bits"> 102 <thead> 103 <tr><th colspan="16">Bitwise diagram of a two-byte LEB128 value</th></tr> 104 <tr> 105 <th colspan="8">First byte</td> 106 <th colspan="8">Second byte</td> 107 </tr> 108 </thead> 109 <tbody> 110 <tr> 111 <td class="start1"><code>1</code></td> 112 <td>bit<sub>6</sub></td> 113 <td>bit<sub>5</sub></td> 114 <td>bit<sub>4</sub></td> 115 <td>bit<sub>3</sub></td> 116 <td>bit<sub>2</sub></td> 117 <td>bit<sub>1</sub></td> 118 <td>bit<sub>0</sub></td> 119 <td class="start2"><code>0</code></td> 120 <td>bit<sub>13</sub></td> 121 <td>bit<sub>12</sub></td> 122 <td>bit<sub>11</sub></td> 123 <td>bit<sub>10</sub></td> 124 <td>bit<sub>9</sub></td> 125 <td>bit<sub>8</sub></td> 126 <td class="end2">bit<sub>7</sub></td> 127 </tr> 128 </tbody> 129 </table> 130 131 <p>The variant <code>uleb128p1</code> is used to represent a signed 132 value, where the representation is of the value <i>plus one</i> encoded 133 as a <code>uleb128</code>. This makes the encoding of <code>-1</code> 134 (alternatively thought of as the unsigned value <code>0xffffffff</code>) 135 — but no other negative number — a single byte, and is 136 useful in exactly those cases where the represented number must either 137 be non-negative or <code>-1</code> (or <code>0xffffffff</code>), 138 and where no other negative values are allowed (or where large unsigned 139 values are unlikely to be needed).</p> 140 141 <p>Here are some examples of the formats:</p> 142 143 <table class="leb128"> 144 <thead> 145 <tr> 146 <th>Encoded Sequence</th> 147 <th>As <code>sleb128</code></th> 148 <th>As <code>uleb128</code></th> 149 <th>As <code>uleb128p1</code></th> 150 </tr> 151 </thead> 152 <tbody> 153 <tr><td>00</td><td>0</td><td>0</td><td>-1</td></tr> 154 <tr><td>01</td><td>1</td><td>1</td><td>0</td></tr> 155 <tr><td>7f</td><td>-1</td><td>127</td><td>126</td></tr> 156 <tr><td>80 7f</td><td>-128</td><td>16256</td><td>16255</td></tr> 157 </tbody> 158 </table> 159 160 <h2 id="file-layout">File layout</h2> 161 162 <table class="format"> 163 <thead> 164 <tr> 165 <th>Name</th> 166 <th>Format</th> 167 <th>Description</th> 168 </tr> 169 </thead> 170 <tbody> 171 <tr> 172 <td>header</td> 173 <td>header_item</td> 174 <td>the header</td> 175 </tr> 176 <tr> 177 <td>string_ids</td> 178 <td>string_id_item[]</td> 179 <td>string identifiers list. These are identifiers for all the strings 180 used by this file, either for internal naming (e.g., type descriptors) 181 or as constant objects referred to by code. This list must be sorted 182 by string contents, using UTF-16 code point values (not in a 183 locale-sensitive manner), and it must not contain any duplicate entries. 184 </td> 185 </tr> 186 <tr> 187 <td>type_ids</td> 188 <td>type_id_item[]</td> 189 <td>type identifiers list. These are identifiers for all types (classes, 190 arrays, or primitive types) referred to by this file, whether defined 191 in the file or not. This list must be sorted by <code>string_id</code> 192 index, and it must not contain any duplicate entries. 193 </td> 194 </tr> 195 <tr> 196 <td>proto_ids</td> 197 <td>proto_id_item[]</td> 198 <td>method prototype identifiers list. These are identifiers for all 199 prototypes referred to by this file. This list must be sorted in 200 return-type (by <code>type_id</code> index) major order, and then 201 by arguments (also by <code>type_id</code> index). The list must not 202 contain any duplicate entries. 203 </td> 204 </tr> 205 <tr> 206 <td>field_ids</td> 207 <td>field_id_item[]</td> 208 <td>field identifiers list. These are identifiers for all fields 209 referred to by this file, whether defined in the file or not. This 210 list must be sorted, where the defining type (by <code>type_id</code> 211 index) is the major order, field name (by <code>string_id</code> index) 212 is the intermediate order, and type (by <code>type_id</code> index) 213 is the minor order. The list must not contain any duplicate entries. 214 </td> 215 </tr> 216 <tr> 217 <td>method_ids</td> 218 <td>method_id_item[]</td> 219 <td>method identifiers list. These are identifiers for all methods 220 referred to by this file, whether defined in the file or not. This 221 list must be sorted, where the defining type (by <code>type_id</code> 222 index) is the major order, method name (by <code>string_id</code> 223 index) is the intermediate order, and method prototype (by 224 <code>proto_id</code> index) is the minor order. The list must not 225 contain any duplicate entries. 226 </td> 227 </tr> 228 <tr> 229 <td>class_defs</td> 230 <td>class_def_item[]</td> 231 <td>class definitions list. The classes must be ordered such that a given 232 class's superclass and implemented interfaces appear in the 233 list earlier than the referring class. Furthermore, it is invalid for 234 a definition for the same-named class to appear more than once in 235 the list. 236 </td> 237 </tr> 238 <tr> 239 <td>data</td> 240 <td>ubyte[]</td> 241 <td>data area, containing all the support data for the tables listed above. 242 Different items have different alignment requirements, and 243 padding bytes are inserted before each item if necessary to achieve 244 proper alignment. 245 </td> 246 </tr> 247 <tr> 248 <td>link_data</td> 249 <td>ubyte[]</td> 250 <td>data used in statically linked files. The format of the data in 251 this section is left unspecified by this document. 252 This section is empty in unlinked files, and runtime implementations 253 may use it as they see fit. 254 </td> 255 </tr> 256 </tbody> 257 </table> 258 259 <h2 id="definitions">Bitfield, string and constant definitions</h2> 260 261 <h3 id="dex-file-magic">DEX_FILE_MAGIC</h3> 262 <h4>embedded in header_item</h4> 263 264 <p>The constant array/string <code>DEX_FILE_MAGIC</code> is the list of 265 bytes that must appear at the beginning of a <code>.dex</code> file 266 in order for it to be recognized as such. The value intentionally 267 contains a newline (<code>"\n"</code> or <code>0x0a</code>) and a 268 null byte (<code>"\0"</code> or <code>0x00</code>) in order to help 269 in the detection of certain forms of corruption. The value also 270 encodes a format version number as three decimal digits, which is 271 expected to increase monotonically over time as the format evolves.</p> 272 273 <pre> 274 ubyte[8] DEX_FILE_MAGIC = { 0x64 0x65 0x78 0x0a 0x30 0x33 0x37 0x00 } 275 = "dex\n037\0" 276 </pre> 277 278 <p class="note"><strong>Note:</strong> At least a couple earlier versions of the format have 279 been used in widely-available public software releases. For example, 280 version <code>009</code> was used for the M3 releases of the 281 Android platform (November–December 2007), 282 and version <code>013</code> was used for the M5 releases of the Android 283 platform (February–March 2008). In several respects, these earlier 284 versions of the format differ significantly from the version described in this 285 document.</p> 286 287 <p class="note"><strong>Note:</strong> Support for version <code>037</code> of 288 the format was added in the Android N release. Prior to this release most 289 versions of Android have used version <code>035</code> of the format. The only 290 difference between versions <code>035</code> and <code>037</code> is the 291 addition of default methods and the adjustment of the <code>invoke</code> 292 instruction semantics to support this feature. Due to a Dalvik bug present in 293 older versions of Android, Dex version <code>036</code> has been skipped. 294 Dex version <code>036</code> is not valid for any version of Android and never 295 will be.</p> 296 297 <h3 id="endian-constant">ENDIAN_CONSTANT and REVERSE_ENDIAN_CONSTANT</h3> 298 <h4>embedded in header_item</h4> 299 300 <p>The constant <code>ENDIAN_CONSTANT</code> is used to indicate the 301 endianness of the file in which it is found. Although the standard 302 <code>.dex</code> format is little-endian, implementations may choose 303 to perform byte-swapping. Should an implementation come across a 304 header whose <code>endian_tag</code> is <code>REVERSE_ENDIAN_CONSTANT</code> 305 instead of <code>ENDIAN_CONSTANT</code>, it would know that the file 306 has been byte-swapped from the expected form.</p> 307 308 <pre> 309 uint ENDIAN_CONSTANT = 0x12345678; 310 uint REVERSE_ENDIAN_CONSTANT = 0x78563412; 311 </pre> 312 313 <h3 id="no-index">NO_INDEX</h3> 314 <h4>embedded in class_def_item and debug_info_item</h4> 315 316 <p>The constant <code>NO_INDEX</code> is used to indicate that 317 an index value is absent.</p> 318 319 <p class="note"><strong>Note:</strong> This value isn't defined to be 320 <code>0</code>, because that is in fact typically a valid index.</p> 321 322 <p>The chosen value for <code>NO_INDEX</code> is 323 representable as a single byte in the <code>uleb128p1</code> encoding.</p> 324 325 <pre> 326 uint NO_INDEX = 0xffffffff; // == -1 if treated as a signed int 327 </pre> 328 329 <h3 id="access-flags">access_flags definitions</h3> 330 <h4>embedded in class_def_item, encoded_field, encoded_method, and 331 InnerClass</h4> 332 333 <p>Bitfields of these flags are used to indicate the accessibility and 334 overall properties of classes and class members.</p> 335 336 <table class="accessFlags"> 337 <thead> 338 <tr> 339 <th>Name</th> 340 <th>Value</th> 341 <th>For Classes (and <code>InnerClass</code> annotations)</th> 342 <th>For Fields</th> 343 <th>For Methods</th> 344 </tr> 345 </thead> 346 <tbody> 347 <tr> 348 <td>ACC_PUBLIC</td> 349 <td>0x1</td> 350 <td><code>public</code>: visible everywhere</td> 351 <td><code>public</code>: visible everywhere</td> 352 <td><code>public</code>: visible everywhere</td> 353 </tr> 354 <tr> 355 <td>ACC_PRIVATE</td> 356 <td>0x2</td> 357 <td><super>*</super> 358 <code>private</code>: only visible to defining class 359 </td> 360 <td><code>private</code>: only visible to defining class</td> 361 <td><code>private</code>: only visible to defining class</td> 362 </tr> 363 <tr> 364 <td>ACC_PROTECTED</td> 365 <td>0x4</td> 366 <td><super>*</super> 367 <code>protected</code>: visible to package and subclasses 368 </td> 369 <td><code>protected</code>: visible to package and subclasses</td> 370 <td><code>protected</code>: visible to package and subclasses</td> 371 </tr> 372 <tr> 373 <td>ACC_STATIC</td> 374 <td>0x8</td> 375 <td><super>*</super> 376 <code>static</code>: is not constructed with an outer 377 <code>this</code> reference</td> 378 <td><code>static</code>: global to defining class</td> 379 <td><code>static</code>: does not take a <code>this</code> argument</td> 380 </tr> 381 <tr> 382 <td>ACC_FINAL</td> 383 <td>0x10</td> 384 <td><code>final</code>: not subclassable</td> 385 <td><code>final</code>: immutable after construction</td> 386 <td><code>final</code>: not overridable</td> 387 </tr> 388 <tr> 389 <td>ACC_SYNCHRONIZED</td> 390 <td>0x20</td> 391 <td> </td> 392 <td> </td> 393 <td><code>synchronized</code>: associated lock automatically acquired 394 around call to this method. <p class="note"><strong>Note:</strong> This is only valid to set when 395 <code>ACC_NATIVE</code> is also set. </p></td> 396 </tr> 397 <tr> 398 <td>ACC_VOLATILE</td> 399 <td>0x40</td> 400 <td> </td> 401 <td><code>volatile</code>: special access rules to help with thread 402 safety</td> 403 <td> </td> 404 </tr> 405 <tr> 406 <td>ACC_BRIDGE</td> 407 <td>0x40</td> 408 <td> </td> 409 <td> </td> 410 <td>bridge method, added automatically by compiler as a type-safe 411 bridge</td> 412 </tr> 413 <tr> 414 <td>ACC_TRANSIENT</td> 415 <td>0x80</td> 416 <td> </td> 417 <td><code>transient</code>: not to be saved by default serialization</td> 418 <td> </td> 419 </tr> 420 <tr> 421 <td>ACC_VARARGS</td> 422 <td>0x80</td> 423 <td> </td> 424 <td> </td> 425 <td>last argument should be treated as a "rest" argument by compiler</td> 426 </tr> 427 <tr> 428 <td>ACC_NATIVE</td> 429 <td>0x100</td> 430 <td> </td> 431 <td> </td> 432 <td><code>native</code>: implemented in native code</td> 433 </tr> 434 <tr> 435 <td>ACC_INTERFACE</td> 436 <td>0x200</td> 437 <td><code>interface</code>: multiply-implementable abstract class</td> 438 <td> </td> 439 <td> </td> 440 </tr> 441 <tr> 442 <td>ACC_ABSTRACT</td> 443 <td>0x400</td> 444 <td><code>abstract</code>: not directly instantiable</td> 445 <td> </td> 446 <td><code>abstract</code>: unimplemented by this class</td> 447 </tr> 448 <tr> 449 <td>ACC_STRICT</td> 450 <td>0x800</td> 451 <td> </td> 452 <td> </td> 453 <td><code>strictfp</code>: strict rules for floating-point arithmetic</td> 454 </tr> 455 <tr> 456 <td>ACC_SYNTHETIC</td> 457 <td>0x1000</td> 458 <td>not directly defined in source code</td> 459 <td>not directly defined in source code</td> 460 <td>not directly defined in source code</td> 461 </tr> 462 <tr> 463 <td>ACC_ANNOTATION</td> 464 <td>0x2000</td> 465 <td>declared as an annotation class</td> 466 <td> </td> 467 <td> </td> 468 </tr> 469 <tr> 470 <td>ACC_ENUM</td> 471 <td>0x4000</td> 472 <td>declared as an enumerated type</td> 473 <td>declared as an enumerated value</td> 474 <td> </td> 475 </tr> 476 <tr> 477 <td><i>(unused)</i></td> 478 <td>0x8000</td> 479 <td> </td> 480 <td> </td> 481 <td> </td> 482 </tr> 483 <tr> 484 <td>ACC_CONSTRUCTOR</td> 485 <td>0x10000</td> 486 <td> </td> 487 <td> </td> 488 <td>constructor method (class or instance initializer)</td> 489 </tr> 490 <tr> 491 <td>ACC_DECLARED_<br/>SYNCHRONIZED</td> 492 <td>0x20000</td> 493 <td> </td> 494 <td> </td> 495 <td>declared <code>synchronized</code>. <p class="note"><strong>Note:</strong> This has no effect on 496 execution (other than in reflection of this flag, per se).</p> 497 </td> 498 </tr> 499 </tbody> 500 </table> 501 502 <p><super>*</super> Only allowed on for <code>InnerClass</code> annotations, 503 and must not ever be on in a <code>class_def_item</code>.</p> 504 505 <h3 id="mutf-8">MUTF-8 (Modified UTF-8) Encoding</h3> 506 507 <p>As a concession to easier legacy support, the <code>.dex</code> format 508 encodes its string data in a de facto standard modified UTF-8 form, hereafter 509 referred to as MUTF-8. This form is identical to standard UTF-8, except:</p> 510 511 <ul> 512 <li>Only the one-, two-, and three-byte encodings are used.</li> 513 <li>Code points in the range <code>U+10000</code> … 514 <code>U+10ffff</code> are encoded as a surrogate pair, each of 515 which is represented as a three-byte encoded value.</li> 516 <li>The code point <code>U+0000</code> is encoded in two-byte form.</li> 517 <li>A plain null byte (value <code>0</code>) indicates the end of 518 a string, as is the standard C language interpretation.</li> 519 </ul> 520 521 <p>The first two items above can be summarized as: MUTF-8 522 is an encoding format for UTF-16, instead of being a more direct 523 encoding format for Unicode characters.</p> 524 525 <p>The final two items above make it simultaneously possible to include 526 the code point <code>U+0000</code> in a string <i>and</i> still manipulate 527 it as a C-style null-terminated string.</p> 528 529 <p>However, the special encoding of <code>U+0000</code> means that, unlike 530 normal UTF-8, the result of calling the standard C function 531 <code>strcmp()</code> on a pair of MUTF-8 strings does not always 532 indicate the properly signed result of comparison of <i>unequal</i> strings. 533 When ordering (not just equality) is a concern, the most straightforward 534 way to compare MUTF-8 strings is to decode them character by character, 535 and compare the decoded values. (However, more clever implementations are 536 also possible.)</p> 537 538 <p>Please refer to <a href="http://unicode.org">The Unicode 539 Standard</a> for further information about character encoding. 540 MUTF-8 is actually closer to the (relatively less well-known) encoding 541 <a href="http://www.unicode.org/reports/tr26/">CESU-8</a> than to UTF-8 542 per se.</p> 543 544 <h3 id="encoding">encoded_value encoding</h3> 545 <h4>embedded in annotation_element and encoded_array_item </h4> 546 547 <p>An <code>encoded_value</code> is an encoded piece of (nearly) 548 arbitrary hierarchically structured data. The encoding is meant to 549 be both compact and straightforward to parse.</p> 550 551 <table class="format"> 552 <thead> 553 <tr> 554 <th>Name</th> 555 <th>Format</th> 556 <th>Description</th> 557 </tr> 558 </thead> 559 <tbody> 560 <tr> 561 <td>(value_arg << 5) | value_type</td> 562 <td>ubyte</td> 563 <td>byte indicating the type of the immediately subsequent 564 <code>value</code> along 565 with an optional clarifying argument in the high-order three bits. 566 See below for the various <code>value</code> definitions. 567 In most cases, <code>value_arg</code> encodes the length of 568 the immediately-subsequent <code>value</code> in bytes, as 569 <code>(size - 1)</code>, e.g., <code>0</code> means that 570 the value requires one byte, and <code>7</code> means it requires 571 eight bytes; however, there are exceptions as noted below. 572 </td> 573 </tr> 574 <tr> 575 <td>value</td> 576 <td>ubyte[]</td> 577 <td>bytes representing the value, variable in length and interpreted 578 differently for different <code>value_type</code> bytes, though 579 always little-endian. See the various value definitions below for 580 details. 581 </td> 582 </tr> 583 </tbody> 584 </table> 585 586 <h3 id="value-formats">Value formats</h3> 587 588 <table class="encodedValue"> 589 <thead> 590 <tr> 591 <th>Type Name</th> 592 <th><code>value_type</code></th> 593 <th><code>value_arg</code> Format</th> 594 <th><code>value</code> Format</th> 595 <th>Description</th> 596 </tr> 597 </thead> 598 <tbody> 599 <tr> 600 <td>VALUE_BYTE</td> 601 <td>0x00</td> 602 <td><i>(none; must be <code>0</code>)</i></td> 603 <td>ubyte[1]</td> 604 <td>signed one-byte integer value</td> 605 </tr> 606 <tr> 607 <td>VALUE_SHORT</td> 608 <td>0x02</td> 609 <td>size - 1 (0…1)</td> 610 <td>ubyte[size]</td> 611 <td>signed two-byte integer value, sign-extended</td> 612 </tr> 613 <tr> 614 <td>VALUE_CHAR</td> 615 <td>0x03</td> 616 <td>size - 1 (0…1)</td> 617 <td>ubyte[size]</td> 618 <td>unsigned two-byte integer value, zero-extended</td> 619 </tr> 620 <tr> 621 <td>VALUE_INT</td> 622 <td>0x04</td> 623 <td>size - 1 (0…3)</td> 624 <td>ubyte[size]</td> 625 <td>signed four-byte integer value, sign-extended</td> 626 </tr> 627 <tr> 628 <td>VALUE_LONG</td> 629 <td>0x06</td> 630 <td>size - 1 (0…7)</td> 631 <td>ubyte[size]</td> 632 <td>signed eight-byte integer value, sign-extended</td> 633 </tr> 634 <tr> 635 <td>VALUE_FLOAT</td> 636 <td>0x10</td> 637 <td>size - 1 (0…3)</td> 638 <td>ubyte[size]</td> 639 <td>four-byte bit pattern, zero-extended <i>to the right</i>, and 640 interpreted as an IEEE754 32-bit floating point value 641 </td> 642 </tr> 643 <tr> 644 <td>VALUE_DOUBLE</td> 645 <td>0x11</td> 646 <td>size - 1 (0…7)</td> 647 <td>ubyte[size]</td> 648 <td>eight-byte bit pattern, zero-extended <i>to the right</i>, and 649 interpreted as an IEEE754 64-bit floating point value 650 </td> 651 </tr> 652 <tr> 653 <td>VALUE_STRING</td> 654 <td>0x17</td> 655 <td>size - 1 (0…3)</td> 656 <td>ubyte[size]</td> 657 <td>unsigned (zero-extended) four-byte integer value, 658 interpreted as an index into 659 the <code>string_ids</code> section and representing a string value 660 </td> 661 </tr> 662 <tr> 663 <td>VALUE_TYPE</td> 664 <td>0x18</td> 665 <td>size - 1 (0…3)</td> 666 <td>ubyte[size]</td> 667 <td>unsigned (zero-extended) four-byte integer value, 668 interpreted as an index into 669 the <code>type_ids</code> section and representing a reflective 670 type/class value 671 </td> 672 </tr> 673 <tr> 674 <td>VALUE_FIELD</td> 675 <td>0x19</td> 676 <td>size - 1 (0…3)</td> 677 <td>ubyte[size]</td> 678 <td>unsigned (zero-extended) four-byte integer value, 679 interpreted as an index into 680 the <code>field_ids</code> section and representing a reflective 681 field value 682 </td> 683 </tr> 684 <tr> 685 <td>VALUE_METHOD</td> 686 <td>0x1a</td> 687 <td>size - 1 (0…3)</td> 688 <td>ubyte[size]</td> 689 <td>unsigned (zero-extended) four-byte integer value, 690 interpreted as an index into 691 the <code>method_ids</code> section and representing a reflective 692 method value 693 </td> 694 </tr> 695 <tr> 696 <td>VALUE_ENUM</td> 697 <td>0x1b</td> 698 <td>size - 1 (0…3)</td> 699 <td>ubyte[size]</td> 700 <td>unsigned (zero-extended) four-byte integer value, 701 interpreted as an index into 702 the <code>field_ids</code> section and representing the value of 703 an enumerated type constant 704 </td> 705 </tr> 706 <tr> 707 <td>VALUE_ARRAY</td> 708 <td>0x1c</td> 709 <td><i>(none; must be <code>0</code>)</i></td> 710 <td>encoded_array</td> 711 <td>an array of values, in the format specified by 712 "<code>encoded_array</code> format" below. The size 713 of the <code>value</code> is implicit in the encoding. 714 </td> 715 </tr> 716 <tr> 717 <td>VALUE_ANNOTATION</td> 718 <td>0x1d</td> 719 <td><i>(none; must be <code>0</code>)</i></td> 720 <td>encoded_annotation</td> 721 <td>a sub-annotation, in the format specified by 722 "<code>encoded_annotation</code> format" below. The size 723 of the <code>value</code> is implicit in the encoding. 724 </td> 725 </tr> 726 <tr> 727 <td>VALUE_NULL</td> 728 <td>0x1e</td> 729 <td><i>(none; must be <code>0</code>)</i></td> 730 <td><i>(none)</i></td> 731 <td><code>null</code> reference value</td> 732 </tr> 733 <tr> 734 <td>VALUE_BOOLEAN</td> 735 <td>0x1f</td> 736 <td>boolean (0…1)</td> 737 <td><i>(none)</i></td> 738 <td>one-bit value; <code>0</code> for <code>false</code> and 739 <code>1</code> for <code>true</code>. The bit is represented in the 740 <code>value_arg</code>. 741 </td> 742 </tr> 743 </tbody> 744 </table> 745 746 <h3 id="encoded-array">encoded_array format</h3> 747 748 <table class="format"> 749 <thead> 750 <tr> 751 <th>Name</th> 752 <th>Format</th> 753 <th>Description</th> 754 </tr> 755 </thead> 756 <tbody> 757 <tr> 758 <td>size</td> 759 <td>uleb128</td> 760 <td>number of elements in the array</td> 761 </tr> 762 <tr> 763 <td>values</td> 764 <td>encoded_value[size]</td> 765 <td>a series of <code>size</code> <code>encoded_value</code> byte 766 sequences in the format specified by this section, concatenated 767 sequentially. 768 </td> 769 </tr> 770 </tbody> 771 </table> 772 773 <h3 id="encoded-annotation">encoded_annotation format</h3> 774 775 <table class="format"> 776 <thead> 777 <tr> 778 <th>Name</th> 779 <th>Format</th> 780 <th>Description</th> 781 </tr> 782 </thead> 783 <tbody> 784 <tr> 785 <td>type_idx</td> 786 <td>uleb128</td> 787 <td>type of the annotation. This must be a class (not array or primitive) 788 type. 789 </td> 790 </tr> 791 <tr> 792 <td>size</td> 793 <td>uleb128</td> 794 <td>number of name-value mappings in this annotation</td> 795 </tr> 796 <tr> 797 <td>elements</td> 798 <td>annotation_element[size]</td> 799 <td>elements of the annotation, represented directly in-line (not as 800 offsets). Elements must be sorted in increasing order by 801 <code>string_id</code> index. 802 </td> 803 </tr> 804 </tbody> 805 </table> 806 807 <h3 id="annotation-element">annotation_element format</h3> 808 809 <table class="format"> 810 <thead> 811 <tr> 812 <th>Name</th> 813 <th>Format</th> 814 <th>Description</th> 815 </tr> 816 </thead> 817 <tbody> 818 <tr> 819 <td>name_idx</td> 820 <td>uleb128</td> 821 <td>element name, represented as an index into the 822 <code>string_ids</code> section. The string must conform to the 823 syntax for <i>MemberName</i>, defined above. 824 </td> 825 </tr> 826 <tr> 827 <td>value</td> 828 <td>encoded_value</td> 829 <td>element value</td> 830 </tr> 831 </tbody> 832 </table> 833 834 <h2 id="string-syntax">String syntax</h2> 835 836 <p>There are several kinds of item in a <code>.dex</code> file which 837 ultimately refer to a string. The following BNF-style definitions 838 indicate the acceptable syntax for these strings.</p> 839 840 <h3 id="simplename"><i>SimpleName</i></h3> 841 842 <p>A <i>SimpleName</i> is the basis for the syntax of the names of other 843 things. The <code>.dex</code> format allows a fair amount of latitude 844 here (much more than most common source languages). In brief, a simple 845 name consists of any low-ASCII alphabetic character or digit, a few 846 specific low-ASCII symbols, and most non-ASCII code points that are not 847 control, space, or special characters. Note that surrogate code points 848 (in the range <code>U+d800</code> … <code>U+dfff</code>) are not 849 considered valid name characters, per se, but Unicode supplemental 850 characters <i>are</i> valid (which are represented by the final 851 alternative of the rule for <i>SimpleNameChar</i>), and they should be 852 represented in a file as pairs of surrogate code points in the MUTF-8 853 encoding.</p> 854 855 <table class="bnf"> 856 <tr><td colspan="2" class="def"><i>SimpleName</i> →</td></tr> 857 <tr> 858 <td/> 859 <td><i>SimpleNameChar</i> (<i>SimpleNameChar</i>)*</td> 860 </tr> 861 862 <tr><td colspan="2" class="def"><i>SimpleNameChar</i> →</td></tr> 863 <tr> 864 <td/> 865 <td><code>'A'</code> … <code>'Z'</code></td> 866 </tr> 867 <tr> 868 <td class="bar">|</td> 869 <td><code>'a'</code> … <code>'z'</code></td> 870 </tr> 871 <tr> 872 <td class="bar">|</td> 873 <td><code>'0'</code> … <code>'9'</code></td> 874 </tr> 875 <tr> 876 <td class="bar">|</td> 877 <td><code>'$'</code></td> 878 </tr> 879 <tr> 880 <td class="bar">|</td> 881 <td><code>'-'</code></td> 882 </tr> 883 <tr> 884 <td class="bar">|</td> 885 <td><code>'_'</code></td> 886 </tr> 887 <tr> 888 <td class="bar">|</td> 889 <td><code>U+00a1</code> … <code>U+1fff</code></td> 890 </tr> 891 <tr> 892 <td class="bar">|</td> 893 <td><code>U+2010</code> … <code>U+2027</code></td> 894 </tr> 895 <tr> 896 <td class="bar">|</td> 897 <td><code>U+2030</code> … <code>U+d7ff</code></td> 898 </tr> 899 <tr> 900 <td class="bar">|</td> 901 <td><code>U+e000</code> … <code>U+ffef</code></td> 902 </tr> 903 <tr> 904 <td class="bar">|</td> 905 <td><code>U+10000</code> … <code>U+10ffff</code></td> 906 </tr> 907 </table> 908 909 <h3 id="membername"><i>MemberName</i></h3> 910 <h4>used by field_id_item and method_id_item</h4> 911 912 <p>A <i>MemberName</i> is the name of a member of a class, members being 913 fields, methods, and inner classes.</p> 914 915 <table class="bnf"> 916 <tr><td colspan="2" class="def"><i>MemberName</i> →</td></tr> 917 <tr> 918 <td/> 919 <td><i>SimpleName</i></td> 920 </tr> 921 <tr> 922 <td class="bar">|</td> 923 <td><code>'<'</code> <i>SimpleName</i> <code>'>'</code></td> 924 </tr> 925 </table> 926 927 <h3 id="fullclassname"><i>FullClassName</i></h3> 928 929 <p>A <i>FullClassName</i> is a fully-qualified class name, including an 930 optional package specifier followed by a required name.</p> 931 932 <table class="bnf"> 933 <tr><td colspan="2" class="def"><i>FullClassName</i> →</td></tr> 934 <tr> 935 <td/> 936 <td><i>OptionalPackagePrefix</i> <i>SimpleName</i></td> 937 </tr> 938 939 <tr><td colspan="2" class="def"><i>OptionalPackagePrefix</i> →</td></tr> 940 <tr> 941 <td/> 942 <td>(<i>SimpleName</i> <code>'/'</code>)*</td> 943 </tr> 944 </table> 945 946 <h3 id="typedescriptor"><i>TypeDescriptor</i></h3> 947 <h4>used by type_id_item</h4> 948 949 <p>A <i>TypeDescriptor</i> is the representation of any type, including 950 primitives, classes, arrays, and <code>void</code>. See below for 951 the meaning of the various versions.</p> 952 953 <table class="bnf"> 954 <tr><td colspan="2" class="def"><i>TypeDescriptor</i> →</td></tr> 955 <tr> 956 <td/> 957 <td><code>'V'</code></td> 958 </tr> 959 <tr> 960 <td class="bar">|</td> 961 <td><i>FieldTypeDescriptor</i></td> 962 </tr> 963 964 <tr><td colspan="2" class="def"><i>FieldTypeDescriptor</i> →</td></tr> 965 <tr> 966 <td/> 967 <td><i>NonArrayFieldTypeDescriptor</i></td> 968 </tr> 969 <tr> 970 <td class="bar">|</td> 971 <td>(<code>'['</code> * 1…255) 972 <i>NonArrayFieldTypeDescriptor</i></td> 973 </tr> 974 975 <tr> 976 <td colspan="2" class="def"><i>NonArrayFieldTypeDescriptor</i>→</td> 977 </tr> 978 <tr> 979 <td/> 980 <td><code>'Z'</code></td> 981 </tr> 982 <tr> 983 <td class="bar">|</td> 984 <td><code>'B'</code></td> 985 </tr> 986 <tr> 987 <td class="bar">|</td> 988 <td><code>'S'</code></td> 989 </tr> 990 <tr> 991 <td class="bar">|</td> 992 <td><code>'C'</code></td> 993 </tr> 994 <tr> 995 <td class="bar">|</td> 996 <td><code>'I'</code></td> 997 </tr> 998 <tr> 999 <td class="bar">|</td> 1000 <td><code>'J'</code></td> 1001 </tr> 1002 <tr> 1003 <td class="bar">|</td> 1004 <td><code>'F'</code></td> 1005 </tr> 1006 <tr> 1007 <td class="bar">|</td> 1008 <td><code>'D'</code></td> 1009 </tr> 1010 <tr> 1011 <td class="bar">|</td> 1012 <td><code>'L'</code> <i>FullClassName</i> <code>';'</code></td> 1013 </tr> 1014 </table> 1015 1016 <h3 id="shortydescriptor"><i>ShortyDescriptor</i></h3> 1017 <h4>used by proto_id_item</h4> 1018 1019 <p>A <i>ShortyDescriptor</i> is the short form representation of a method 1020 prototype, including return and parameter types, except that there is 1021 no distinction between various reference (class or array) types. Instead, 1022 all reference types are represented by a single <code>'L'</code> character.</p> 1023 1024 <table class="bnf"> 1025 <tr><td colspan="2" class="def"><i>ShortyDescriptor</i> →</td></tr> 1026 <tr> 1027 <td/> 1028 <td><i>ShortyReturnType</i> (<i>ShortyFieldType</i>)*</td> 1029 </tr> 1030 1031 <tr><td colspan="2" class="def"><i>ShortyReturnType</i> →</td></tr> 1032 <tr> 1033 <td/> 1034 <td><code>'V'</code></td> 1035 </tr> 1036 <tr> 1037 <td class="bar">|</td> 1038 <td><i>ShortyFieldType</i></td> 1039 </tr> 1040 1041 <tr><td colspan="2" class="def"><i>ShortyFieldType</i> →</td></tr> 1042 <tr> 1043 <td/> 1044 <td><code>'Z'</code></td> 1045 </tr> 1046 <tr> 1047 <td class="bar">|</td> 1048 <td><code>'B'</code></td> 1049 </tr> 1050 <tr> 1051 <td class="bar">|</td> 1052 <td><code>'S'</code></td> 1053 </tr> 1054 <tr> 1055 <td class="bar">|</td> 1056 <td><code>'C'</code></td> 1057 </tr> 1058 <tr> 1059 <td class="bar">|</td> 1060 <td><code>'I'</code></td> 1061 </tr> 1062 <tr> 1063 <td class="bar">|</td> 1064 <td><code>'J'</code></td> 1065 </tr> 1066 <tr> 1067 <td class="bar">|</td> 1068 <td><code>'F'</code></td> 1069 </tr> 1070 <tr> 1071 <td class="bar">|</td> 1072 <td><code>'D'</code></td> 1073 </tr> 1074 <tr> 1075 <td class="bar">|</td> 1076 <td><code>'L'</code></td> 1077 </tr> 1078 </table> 1079 1080 <h3 id="typedescriptor"><i>TypeDescriptor</i> Semantics</h3> 1081 1082 <p>This is the meaning of each of the variants of <i>TypeDescriptor</i>.</p> 1083 1084 <table class="descriptor"> 1085 <thead> 1086 <tr> 1087 <th>Syntax</th> 1088 <th>Meaning</th> 1089 </tr> 1090 </thead> 1091 <tbody> 1092 <tr> 1093 <td>V</td> 1094 <td><code>void</code>; only valid for return types</td> 1095 </tr> 1096 <tr> 1097 <td>Z</td> 1098 <td><code>boolean</code></td> 1099 </tr> 1100 <tr> 1101 <td>B</td> 1102 <td><code>byte</code></td> 1103 </tr> 1104 <tr> 1105 <td>S</td> 1106 <td><code>short</code></td> 1107 </tr> 1108 <tr> 1109 <td>C</td> 1110 <td><code>char</code></td> 1111 </tr> 1112 <tr> 1113 <td>I</td> 1114 <td><code>int</code></td> 1115 </tr> 1116 <tr> 1117 <td>J</td> 1118 <td><code>long</code></td> 1119 </tr> 1120 <tr> 1121 <td>F</td> 1122 <td><code>float</code></td> 1123 </tr> 1124 <tr> 1125 <td>D</td> 1126 <td><code>double</code></td> 1127 </tr> 1128 <tr> 1129 <td>L<i>fully/qualified/Name</i>;</td> 1130 <td>the class <code><i>fully.qualified.Name</i></code></td> 1131 </tr> 1132 <tr> 1133 <td>[<i>descriptor</i></td> 1134 <td>array of <code><i>descriptor</i></code>, usable recursively for 1135 arrays-of-arrays, though it is invalid to have more than 255 1136 dimensions. 1137 </td> 1138 </tr> 1139 </tbody> 1140 </table> 1141 1142 <h2 id="items">Items and related structures</h2> 1143 1144 <p>This section includes definitions for each of the top-level items that 1145 may appear in a <code>.dex</code> file. 1146 1147 <h3 id="header-item">header_item</h3> 1148 <h4>appears in the header section</h4> 1149 <h4>alignment: 4 bytes</h4> 1150 1151 <table class="format"> 1152 <thead> 1153 <tr> 1154 <th>Name</th> 1155 <th>Format</th> 1156 <th>Description</th> 1157 </tr> 1158 </thead> 1159 <tbody> 1160 <tr> 1161 <td>magic</td> 1162 <td>ubyte[8] = DEX_FILE_MAGIC</td> 1163 <td>magic value. See discussion above under "<code>DEX_FILE_MAGIC</code>" 1164 for more details. 1165 </td> 1166 </tr> 1167 <tr> 1168 <td>checksum</td> 1169 <td>uint</td> 1170 <td>adler32 checksum of the rest of the file (everything but 1171 <code>magic</code> and this field); used to detect file corruption 1172 </td> 1173 </tr> 1174 <tr> 1175 <td>signature</td> 1176 <td>ubyte[20]</td> 1177 <td>SHA-1 signature (hash) of the rest of the file (everything but 1178 <code>magic</code>, <code>checksum</code>, and this field); used 1179 to uniquely identify files 1180 </td> 1181 </tr> 1182 <tr> 1183 <td>file_size</td> 1184 <td>uint</td> 1185 <td>size of the entire file (including the header), in bytes 1186 </tr> 1187 <tr> 1188 <td>header_size</td> 1189 <td>uint = 0x70</td> 1190 <td>size of the header (this entire section), in bytes. This allows for at 1191 least a limited amount of backwards/forwards compatibility without 1192 invalidating the format. 1193 </td> 1194 </tr> 1195 <tr> 1196 <td>endian_tag</td> 1197 <td>uint = ENDIAN_CONSTANT</td> 1198 <td>endianness tag. See discussion above under "<code>ENDIAN_CONSTANT</code> 1199 and <code>REVERSE_ENDIAN_CONSTANT</code>" for more details. 1200 </td> 1201 </tr> 1202 <tr> 1203 <td>link_size</td> 1204 <td>uint</td> 1205 <td>size of the link section, or <code>0</code> if this file isn't 1206 statically linked</td> 1207 </tr> 1208 <tr> 1209 <td>link_off</td> 1210 <td>uint</td> 1211 <td>offset from the start of the file to the link section, or 1212 <code>0</code> if <code>link_size == 0</code>. The offset, if non-zero, 1213 should be to an offset into the <code>link_data</code> section. The 1214 format of the data pointed at is left unspecified by this document; 1215 this header field (and the previous) are left as hooks for use by 1216 runtime implementations. 1217 </td> 1218 </tr> 1219 <tr> 1220 <td>map_off</td> 1221 <td>uint</td> 1222 <td>offset from the start of the file to the map item, or 1223 <code>0</code> if this file has no map. The offset, if non-zero, 1224 should be to an offset into the <code>data</code> section, 1225 and the data should be in the format specified by "<code>map_list</code>" 1226 below. 1227 </td> 1228 </tr> 1229 <tr> 1230 <td>string_ids_size</td> 1231 <td>uint</td> 1232 <td>count of strings in the string identifiers list</td> 1233 </tr> 1234 <tr> 1235 <td>string_ids_off</td> 1236 <td>uint</td> 1237 <td>offset from the start of the file to the string identifiers list, or 1238 <code>0</code> if <code>string_ids_size == 0</code> (admittedly a 1239 strange edge case). The offset, if non-zero, 1240 should be to the start of the <code>string_ids</code> section. 1241 </td> 1242 </tr> 1243 <tr> 1244 <td>type_ids_size</td> 1245 <td>uint</td> 1246 <td>count of elements in the type identifiers list</td> 1247 </tr> 1248 <tr> 1249 <td>type_ids_off</td> 1250 <td>uint</td> 1251 <td>offset from the start of the file to the type identifiers list, or 1252 <code>0</code> if <code>type_ids_size == 0</code> (admittedly a 1253 strange edge case). The offset, if non-zero, 1254 should be to the start of the <code>type_ids</code> 1255 section. 1256 </td> 1257 </tr> 1258 <tr> 1259 <td>proto_ids_size</td> 1260 <td>uint</td> 1261 <td>count of elements in the prototype identifiers list</td> 1262 </tr> 1263 <tr> 1264 <td>proto_ids_off</td> 1265 <td>uint</td> 1266 <td>offset from the start of the file to the prototype identifiers list, or 1267 <code>0</code> if <code>proto_ids_size == 0</code> (admittedly a 1268 strange edge case). The offset, if non-zero, 1269 should be to the start of the <code>proto_ids</code> 1270 section. 1271 </td> 1272 </tr> 1273 <tr> 1274 <td>field_ids_size</td> 1275 <td>uint</td> 1276 <td>count of elements in the field identifiers list</td> 1277 </tr> 1278 <tr> 1279 <td>field_ids_off</td> 1280 <td>uint</td> 1281 <td>offset from the start of the file to the field identifiers list, or 1282 <code>0</code> if <code>field_ids_size == 0</code>. The offset, if 1283 non-zero, should be to the start of the <code>field_ids</code> 1284 section.</td> 1285 </td> 1286 </tr> 1287 <tr> 1288 <td>method_ids_size</td> 1289 <td>uint</td> 1290 <td>count of elements in the method identifiers list</td> 1291 </tr> 1292 <tr> 1293 <td>method_ids_off</td> 1294 <td>uint</td> 1295 <td>offset from the start of the file to the method identifiers list, or 1296 <code>0</code> if <code>method_ids_size == 0</code>. The offset, if 1297 non-zero, should be to the start of the <code>method_ids</code> 1298 section.</td> 1299 </tr> 1300 <tr> 1301 <td>class_defs_size</td> 1302 <td>uint</td> 1303 <td>count of elements in the class definitions list</td> 1304 </tr> 1305 <tr> 1306 <td>class_defs_off</td> 1307 <td>uint</td> 1308 <td>offset from the start of the file to the class definitions list, or 1309 <code>0</code> if <code>class_defs_size == 0</code> (admittedly a 1310 strange edge case). The offset, if non-zero, 1311 should be to the start of the <code>class_defs</code> section. 1312 </td> 1313 </tr> 1314 <tr> 1315 <td>data_size</td> 1316 <td>uint</td> 1317 <td>Size of <code>data</code> section in bytes. Must be an even 1318 multiple of sizeof(uint).</td> 1319 </tr> 1320 <tr> 1321 <td>data_off</td> 1322 <td>uint</td> 1323 <td>offset from the start of the file to the start of the 1324 <code>data</code> section. 1325 </td> 1326 </tr> 1327 </tbody> 1328 </table> 1329 1330 <h3 id="map-list">map_list</h3> 1331 <h4>appears in the data section</h4> 1332 <h4>referenced from header_item</h4> 1333 <h4>alignment: 4 bytes</h4> 1334 1335 <p>This is a list of the entire contents of a file, in order. It 1336 contains some redundancy with respect to the <code>header_item</code> 1337 but is intended to be an easy form to use to iterate over an entire 1338 file. A given type must appear at most once in a map, but there is no 1339 restriction on what order types may appear in, other than the 1340 restrictions implied by the rest of the format (e.g., a 1341 <code>header</code> section must appear first, followed by a 1342 <code>string_ids</code> section, etc.). Additionally, the map entries must 1343 be ordered by initial offset and must not overlap.</p> 1344 1345 <table class="format"> 1346 <thead> 1347 <tr> 1348 <th>Name</th> 1349 <th>Format</th> 1350 <th>Description</th> 1351 </tr> 1352 </thead> 1353 <tbody> 1354 <tr> 1355 <td>size</td> 1356 <td>uint</td> 1357 <td>size of the list, in entries</td> 1358 </tr> 1359 <tr> 1360 <td>list</td> 1361 <td>map_item[size]</td> 1362 <td>elements of the list</td> 1363 </tr> 1364 </tbody> 1365 </table> 1366 1367 <h3 id="map-item">map_item format</h3> 1368 1369 <table class="format"> 1370 <thead> 1371 <tr> 1372 <th>Name</th> 1373 <th>Format</th> 1374 <th>Description</th> 1375 </tr> 1376 </thead> 1377 <tbody> 1378 <tr> 1379 <td>type</td> 1380 <td>ushort</td> 1381 <td>type of the items; see table below</td> 1382 </tr> 1383 <tr> 1384 <td>unused</td> 1385 <td>ushort</td> 1386 <td><i>(unused)</i></td> 1387 </tr> 1388 <tr> 1389 <td>size</td> 1390 <td>uint</td> 1391 <td>count of the number of items to be found at the indicated offset</td> 1392 </tr> 1393 <tr> 1394 <td>offset</td> 1395 <td>uint</td> 1396 <td>offset from the start of the file to the items in question</td> 1397 </tr> 1398 </tbody> 1399 </table> 1400 1401 1402 <h3 id="type-codes">Type Codes</h3> 1403 1404 <table class="typeCodes"> 1405 <thead> 1406 <tr> 1407 <th>Item Type</th> 1408 <th>Constant</th> 1409 <th>Value</th> 1410 <th>Item Size In Bytes</th> 1411 </tr> 1412 </thead> 1413 <tbody> 1414 <tr> 1415 <td>header_item</td> 1416 <td>TYPE_HEADER_ITEM</td> 1417 <td>0x0000</td> 1418 <td>0x70</td> 1419 </tr> 1420 <tr> 1421 <td>string_id_item</td> 1422 <td>TYPE_STRING_ID_ITEM</td> 1423 <td>0x0001</td> 1424 <td>0x04</td> 1425 </tr> 1426 <tr> 1427 <td>type_id_item</td> 1428 <td>TYPE_TYPE_ID_ITEM</td> 1429 <td>0x0002</td> 1430 <td>0x04</td> 1431 </tr> 1432 <tr> 1433 <td>proto_id_item</td> 1434 <td>TYPE_PROTO_ID_ITEM</td> 1435 <td>0x0003</td> 1436 <td>0x0c</td> 1437 </tr> 1438 <tr> 1439 <td>field_id_item</td> 1440 <td>TYPE_FIELD_ID_ITEM</td> 1441 <td>0x0004</td> 1442 <td>0x08</td> 1443 </tr> 1444 <tr> 1445 <td>method_id_item</td> 1446 <td>TYPE_METHOD_ID_ITEM</td> 1447 <td>0x0005</td> 1448 <td>0x08</td> 1449 </tr> 1450 <tr> 1451 <td>class_def_item</td> 1452 <td>TYPE_CLASS_DEF_ITEM</td> 1453 <td>0x0006</td> 1454 <td>0x20</td> 1455 </tr> 1456 <tr> 1457 <td>map_list</td> 1458 <td>TYPE_MAP_LIST</td> 1459 <td>0x1000</td> 1460 <td>4 + (item.size * 12)</td> 1461 </tr> 1462 <tr> 1463 <td>type_list</td> 1464 <td>TYPE_TYPE_LIST</td> 1465 <td>0x1001</td> 1466 <td>4 + (item.size * 2)</td> 1467 </tr> 1468 <tr> 1469 <td>annotation_set_ref_list</td> 1470 <td>TYPE_ANNOTATION_SET_REF_LIST</td> 1471 <td>0x1002</td> 1472 <td>4 + (item.size * 4)</td> 1473 </tr> 1474 <tr> 1475 <td>annotation_set_item</td> 1476 <td>TYPE_ANNOTATION_SET_ITEM</td> 1477 <td>0x1003</td> 1478 <td>4 + (item.size * 4)</td> 1479 </tr> 1480 <tr> 1481 <td>class_data_item</td> 1482 <td>TYPE_CLASS_DATA_ITEM</td> 1483 <td>0x2000</td> 1484 <td><i>implicit; must parse</i></td> 1485 </tr> 1486 <tr> 1487 <td>code_item</td> 1488 <td>TYPE_CODE_ITEM</td> 1489 <td>0x2001</td> 1490 <td><i>implicit; must parse</i></td> 1491 </tr> 1492 <tr> 1493 <td>string_data_item</td> 1494 <td>TYPE_STRING_DATA_ITEM</td> 1495 <td>0x2002</td> 1496 <td><i>implicit; must parse</i></td> 1497 </tr> 1498 <tr> 1499 <td>debug_info_item</td> 1500 <td>TYPE_DEBUG_INFO_ITEM</td> 1501 <td>0x2003</td> 1502 <td><i>implicit; must parse</i></td> 1503 </tr> 1504 <tr> 1505 <td>annotation_item</td> 1506 <td>TYPE_ANNOTATION_ITEM</td> 1507 <td>0x2004</td> 1508 <td><i>implicit; must parse</i></td> 1509 </tr> 1510 <tr> 1511 <td>encoded_array_item</td> 1512 <td>TYPE_ENCODED_ARRAY_ITEM</td> 1513 <td>0x2005</td> 1514 <td><i>implicit; must parse</i></td> 1515 </tr> 1516 <tr> 1517 <td>annotations_directory_item</td> 1518 <td>TYPE_ANNOTATIONS_DIRECTORY_ITEM</td> 1519 <td>0x2006</td> 1520 <td><i>implicit; must parse</i></td> 1521 </tr> 1522 </tbody> 1523 </table> 1524 1525 1526 <h3 id="string-item">string_id_item</h3> 1527 <h4>appears in the string_ids section</h4> 1528 <h4>alignment: 4 bytes</h4> 1529 1530 <table class="format"> 1531 <thead> 1532 <tr> 1533 <th>Name</th> 1534 <th>Format</th> 1535 <th>Description</th> 1536 </tr> 1537 </thead> 1538 <tbody> 1539 <tr> 1540 <td>string_data_off</td> 1541 <td>uint</td> 1542 <td>offset from the start of the file to the string data for this 1543 item. The offset should be to a location 1544 in the <code>data</code> section, and the data should be in the 1545 format specified by "<code>string_data_item</code>" below. 1546 There is no alignment requirement for the offset. 1547 </td> 1548 </tr> 1549 </tbody> 1550 </table> 1551 1552 <h3 id="string-data-item">string_data_item</h3> 1553 <h4>appears in the data section</h4> 1554 <h4>alignment: none (byte-aligned)</h4> 1555 1556 <table class="format"> 1557 <thead> 1558 <tr> 1559 <th>Name</th> 1560 <th>Format</th> 1561 <th>Description</th> 1562 </tr> 1563 </thead> 1564 <tbody> 1565 <tr> 1566 <td>utf16_size</td> 1567 <td>uleb128</td> 1568 <td>size of this string, in UTF-16 code units (which is the "string 1569 length" in many systems). That is, this is the decoded length of 1570 the string. (The encoded length is implied by the position of 1571 the <code>0</code> byte.)</td> 1572 </tr> 1573 <tr> 1574 <td>data</td> 1575 <td>ubyte[]</td> 1576 <td>a series of MUTF-8 code units (a.k.a. octets, a.k.a. bytes) 1577 followed by a byte of value <code>0</code>. See 1578 "MUTF-8 (Modified UTF-8) Encoding" above for details and 1579 discussion about the data format. 1580 <p class="note"><strong>Note:</strong> It is acceptable to have a string which includes 1581 (the encoded form of) UTF-16 surrogate code units (that is, 1582 <code>U+d800</code> … <code>U+dfff</code>) 1583 either in isolation or out-of-order with respect to the usual 1584 encoding of Unicode into UTF-16. It is up to higher-level uses of 1585 strings to reject such invalid encodings, if appropriate.</p> 1586 </td> 1587 </tr> 1588 </tbody> 1589 </table> 1590 1591 <h3 id="type-id-item">type_id_item</h3> 1592 <h4>appears in the type_ids section</h4> 1593 <h4>alignment: 4 bytes</h4> 1594 1595 <table class="format"> 1596 <thead> 1597 <tr> 1598 <th>Name</th> 1599 <th>Format</th> 1600 <th>Description</th> 1601 </tr> 1602 </thead> 1603 <tbody> 1604 <tr> 1605 <td>descriptor_idx</td> 1606 <td>uint</td> 1607 <td>index into the <code>string_ids</code> list for the descriptor 1608 string of this type. The string must conform to the syntax for 1609 <i>TypeDescriptor</i>, defined above. 1610 </td> 1611 </tr> 1612 </tbody> 1613 </table> 1614 1615 <h3 id="proto-id-item">proto_id_item</h3> 1616 <h4>appears in the proto_ids section</h4> 1617 <h4>alignment: 4 bytes</h4> 1618 1619 <table class="format"> 1620 <thead> 1621 <tr> 1622 <th>Name</th> 1623 <th>Format</th> 1624 <th>Description</th> 1625 </tr> 1626 </thead> 1627 <tbody> 1628 <tr> 1629 <td>shorty_idx</td> 1630 <td>uint</td> 1631 <td>index into the <code>string_ids</code> list for the short-form 1632 descriptor string of this prototype. The string must conform to the 1633 syntax for <i>ShortyDescriptor</i>, defined above, and must correspond 1634 to the return type and parameters of this item. 1635 </td> 1636 </tr> 1637 <tr> 1638 <td>return_type_idx</td> 1639 <td>uint</td> 1640 <td>index into the <code>type_ids</code> list for the return type 1641 of this prototype 1642 </td> 1643 </tr> 1644 <tr> 1645 <td>parameters_off</td> 1646 <td>uint</td> 1647 <td>offset from the start of the file to the list of parameter types 1648 for this prototype, or <code>0</code> if this prototype has no 1649 parameters. This offset, if non-zero, should be in the 1650 <code>data</code> section, and the data there should be in the 1651 format specified by <code>"type_list"</code> below. Additionally, there 1652 should be no reference to the type <code>void</code> in the list. 1653 </td> 1654 </tr> 1655 </tbody> 1656 </table> 1657 1658 <h3 id="field-id-item">field_id_item</h3> 1659 <h4>appears in the field_ids section</h4> 1660 <h4>alignment: 4 bytes</h4> 1661 1662 <table class="format"> 1663 <thead> 1664 <tr> 1665 <th>Name</th> 1666 <th>Format</th> 1667 <th>Description</th> 1668 </tr> 1669 </thead> 1670 <tbody> 1671 <tr> 1672 <td>class_idx</td> 1673 <td>ushort</td> 1674 <td>index into the <code>type_ids</code> list for the definer of this 1675 field. This must be a class type, and not an array or primitive type. 1676 </td> 1677 </tr> 1678 <tr> 1679 <td>type_idx</td> 1680 <td>ushort</td> 1681 <td>index into the <code>type_ids</code> list for the type of 1682 this field 1683 </td> 1684 </tr> 1685 <tr> 1686 <td>name_idx</td> 1687 <td>uint</td> 1688 <td>index into the <code>string_ids</code> list for the name of this 1689 field. The string must conform to the syntax for <i>MemberName</i>, 1690 defined above. 1691 </td> 1692 </tr> 1693 </tbody> 1694 </table> 1695 1696 <h3 id="method-id-item">method_id_item</h3> 1697 <h4>appears in the method_ids section</h4> 1698 <h4>alignment: 4 bytes</h4> 1699 1700 <table class="format"> 1701 <thead> 1702 <tr> 1703 <th>Name</th> 1704 <th>Format</th> 1705 <th>Description</th> 1706 </tr> 1707 </thead> 1708 <tbody> 1709 <tr> 1710 <td>class_idx</td> 1711 <td>ushort</td> 1712 <td>index into the <code>type_ids</code> list for the definer of this 1713 method. This must be a class or array type, and not a primitive type. 1714 </td> 1715 </tr> 1716 <tr> 1717 <td>proto_idx</td> 1718 <td>ushort</td> 1719 <td>index into the <code>proto_ids</code> list for the prototype of 1720 this method 1721 </td> 1722 </tr> 1723 <tr> 1724 <td>name_idx</td> 1725 <td>uint</td> 1726 <td>index into the <code>string_ids</code> list for the name of this 1727 method. The string must conform to the syntax for <i>MemberName</i>, 1728 defined above. 1729 </td> 1730 </tr> 1731 </tbody> 1732 </table> 1733 1734 <h3 id="class-def-item">class_def_item</h3> 1735 <h4>appears in the class_defs section</h4> 1736 <h4>alignment: 4 bytes</h4> 1737 1738 <table class="format"> 1739 <thead> 1740 <tr> 1741 <th>Name</th> 1742 <th>Format</th> 1743 <th>Description</th> 1744 </tr> 1745 </thead> 1746 <tbody> 1747 <tr> 1748 <td>class_idx</td> 1749 <td>uint</td> 1750 <td>index into the <code>type_ids</code> list for this class. 1751 This must be a class type, and not an array or primitive type. 1752 </td> 1753 </tr> 1754 <tr> 1755 <td>access_flags</td> 1756 <td>uint</td> 1757 <td>access flags for the class (<code>public</code>, <code>final</code>, 1758 etc.). See "<code>access_flags</code> Definitions" for details. 1759 </td> 1760 </tr> 1761 <tr> 1762 <td>superclass_idx</td> 1763 <td>uint</td> 1764 <td>index into the <code>type_ids</code> list for the superclass, or 1765 the constant value <code>NO_INDEX</code> if this class has no 1766 superclass (i.e., it is a root class such as <code>Object</code>). 1767 If present, this must be a class type, and not an array or primitive type. 1768 </td> 1769 </tr> 1770 <tr> 1771 <td>interfaces_off</td> 1772 <td>uint</td> 1773 <td>offset from the start of the file to the list of interfaces, or 1774 <code>0</code> if there are none. This offset 1775 should be in the <code>data</code> section, and the data 1776 there should be in the format specified by 1777 "<code>type_list</code>" below. Each of the elements of the list 1778 must be a class type (not an array or primitive type), and there 1779 must not be any duplicates. 1780 </td> 1781 </tr> 1782 <tr> 1783 <td>source_file_idx</td> 1784 <td>uint</td> 1785 <td>index into the <code>string_ids</code> list for the name of the 1786 file containing the original source for (at least most of) this class, 1787 or the special value <code>NO_INDEX</code> to represent a lack of 1788 this information. The <code>debug_info_item</code> of any given method 1789 may override this source file, but the expectation is that most classes 1790 will only come from one source file. 1791 </td> 1792 </tr> 1793 <tr> 1794 <td>annotations_off</td> 1795 <td>uint</td> 1796 <td>offset from the start of the file to the annotations structure 1797 for this class, or <code>0</code> if there are no annotations on 1798 this class. This offset, if non-zero, should be in the 1799 <code>data</code> section, and the data there should be in 1800 the format specified by "<code>annotations_directory_item</code>" below, 1801 with all items referring to this class as the definer. 1802 </td> 1803 </tr> 1804 <tr> 1805 <td>class_data_off</td> 1806 <td>uint</td> 1807 <td>offset from the start of the file to the associated 1808 class data for this item, or <code>0</code> if there is no class 1809 data for this class. (This may be the case, for example, if this class 1810 is a marker interface.) The offset, if non-zero, should be in the 1811 <code>data</code> section, and the data there should be in the 1812 format specified by "<code>class_data_item</code>" below, with all 1813 items referring to this class as the definer. 1814 </td> 1815 </tr> 1816 <tr> 1817 <td>static_values_off</td> 1818 <td>uint</td> 1819 <td>offset from the start of the file to the list of initial 1820 values for <code>static</code> fields, or <code>0</code> if there 1821 are none (and all <code>static</code> fields are to be initialized with 1822 <code>0</code> or <code>null</code>). This offset should be in the 1823 <code>data</code> section, and the data there should be in the 1824 format specified by "<code>encoded_array_item</code>" below. The size 1825 of the array must be no larger than the number of <code>static</code> 1826 fields declared by this class, and the elements correspond to the 1827 <code>static</code> fields in the same order as declared in the 1828 corresponding <code>field_list</code>. The type of each array 1829 element must match the declared type of its corresponding field. 1830 If there are fewer elements in the array than there are 1831 <code>static</code> fields, then the leftover fields are initialized 1832 with a type-appropriate <code>0</code> or <code>null</code>. 1833 </td> 1834 </tr> 1835 </tbody> 1836 </table> 1837 1838 <h3 id="class-data-item">class_data_item</h3> 1839 <h4>referenced from class_def_item</h4> 1840 <h4>appears in the data section</h4> 1841 <h4>alignment: none (byte-aligned)</h4> 1842 1843 <table class="format"> 1844 <thead> 1845 <tr> 1846 <th>Name</th> 1847 <th>Format</th> 1848 <th>Description</th> 1849 </tr> 1850 </thead> 1851 <tbody> 1852 <tr> 1853 <td>static_fields_size</td> 1854 <td>uleb128</td> 1855 <td>the number of static fields defined in this item</td> 1856 </tr> 1857 <tr> 1858 <td>instance_fields_size</td> 1859 <td>uleb128</td> 1860 <td>the number of instance fields defined in this item</td> 1861 </tr> 1862 <tr> 1863 <td>direct_methods_size</td> 1864 <td>uleb128</td> 1865 <td>the number of direct methods defined in this item</td> 1866 </tr> 1867 <tr> 1868 <td>virtual_methods_size</td> 1869 <td>uleb128</td> 1870 <td>the number of virtual methods defined in this item</td> 1871 </tr> 1872 <tr> 1873 <td>static_fields</td> 1874 <td>encoded_field[static_fields_size]</td> 1875 <td>the defined static fields, represented as a sequence of 1876 encoded elements. The fields must be sorted by 1877 <code>field_idx</code> in increasing order. 1878 </td> 1879 </tr> 1880 <tr> 1881 <td>instance_fields</td> 1882 <td>encoded_field[instance_fields_size]</td> 1883 <td>the defined instance fields, represented as a sequence of 1884 encoded elements. The fields must be sorted by 1885 <code>field_idx</code> in increasing order. 1886 </td> 1887 </tr> 1888 <tr> 1889 <td>direct_methods</td> 1890 <td>encoded_method[direct_methods_size]</td> 1891 <td>the defined direct (any of <code>static</code>, <code>private</code>, 1892 or constructor) methods, represented as a sequence of 1893 encoded elements. The methods must be sorted by 1894 <code>method_idx</code> in increasing order. 1895 </td> 1896 </tr> 1897 <tr> 1898 <td>virtual_methods</td> 1899 <td>encoded_method[virtual_methods_size]</td> 1900 <td>the defined virtual (none of <code>static</code>, <code>private</code>, 1901 or constructor) methods, represented as a sequence of 1902 encoded elements. This list should <i>not</i> include inherited 1903 methods unless overridden by the class that this item represents. The 1904 methods must be sorted by <code>method_idx</code> in increasing order. 1905 </td> 1906 </tr> 1907 </tbody> 1908 </table> 1909 1910 <p class="note"><strong>Note:</strong> All elements' <code>field_id</code>s and 1911 <code>method_id</code>s must refer to the same defining class.</p> 1912 1913 <h3 id="encoded-field-format">encoded_field format</h3> 1914 1915 <table class="format"> 1916 <thead> 1917 <tr> 1918 <th>Name</th> 1919 <th>Format</th> 1920 <th>Description</th> 1921 </tr> 1922 </thead> 1923 <tbody> 1924 <tr> 1925 <td>field_idx_diff</td> 1926 <td>uleb128</td> 1927 <td>index into the <code>field_ids</code> list for the identity of this 1928 field (includes the name and descriptor), represented as a difference 1929 from the index of previous element in the list. The index of the 1930 first element in a list is represented directly. 1931 </td> 1932 </tr> 1933 <tr> 1934 <td>access_flags</td> 1935 <td>uleb128</td> 1936 <td>access flags for the field (<code>public</code>, <code>final</code>, 1937 etc.). See "<code>access_flags</code> Definitions" for details. 1938 </td> 1939 </tr> 1940 </tbody> 1941 </table> 1942 1943 <h3 id="encoded-method">encoded_method format</h3> 1944 1945 <table class="format"> 1946 <thead> 1947 <tr> 1948 <th>Name</th> 1949 <th>Format</th> 1950 <th>Description</th> 1951 </tr> 1952 </thead> 1953 <tbody> 1954 <tr> 1955 <td>method_idx_diff</td> 1956 <td>uleb128</td> 1957 <td>index into the <code>method_ids</code> list for the identity of this 1958 method (includes the name and descriptor), represented as a difference 1959 from the index of previous element in the list. The index of the 1960 first element in a list is represented directly. 1961 </td> 1962 </tr> 1963 <tr> 1964 <td>access_flags</td> 1965 <td>uleb128</td> 1966 <td>access flags for the method (<code>public</code>, <code>final</code>, 1967 etc.). See "<code>access_flags</code> Definitions" for details. 1968 </td> 1969 </tr> 1970 <tr> 1971 <td>code_off</td> 1972 <td>uleb128</td> 1973 <td>offset from the start of the file to the code structure for this 1974 method, or <code>0</code> if this method is either <code>abstract</code> 1975 or <code>native</code>. The offset should be to a location in the 1976 <code>data</code> section. The format of the data is specified by 1977 "<code>code_item</code>" below. 1978 </td> 1979 </tr> 1980 </tbody> 1981 </table> 1982 1983 <h3 id="type-list">type_list</h3> 1984 <h4>referenced from class_def_item and proto_id_item</h4> 1985 <h4>appears in the data section</h4> 1986 <h4>alignment: 4 bytes</h4> 1987 1988 <table class="format"> 1989 <thead> 1990 <tr> 1991 <th>Name</th> 1992 <th>Format</th> 1993 <th>Description</th> 1994 </tr> 1995 </thead> 1996 <tbody> 1997 <tr> 1998 <td>size</td> 1999 <td>uint</td> 2000 <td>size of the list, in entries</td> 2001 </tr> 2002 <tr> 2003 <td>list</td> 2004 <td>type_item[size]</td> 2005 <td>elements of the list</td> 2006 </tr> 2007 </tbody> 2008 </table> 2009 2010 <h3 id="type-item-format">type_item format</h3> 2011 2012 <table class="format"> 2013 <thead> 2014 <tr> 2015 <th>Name</th> 2016 <th>Format</th> 2017 <th>Description</th> 2018 </tr> 2019 </thead> 2020 <tbody> 2021 <tr> 2022 <td>type_idx</td> 2023 <td>ushort</td> 2024 <td>index into the <code>type_ids</code> list</td> 2025 </tr> 2026 </tbody> 2027 </table> 2028 2029 <h3 id="code-item">code_item</h3> 2030 <h4>referenced from encoded_method</h4> 2031 <h4>appears in the data section</h4> 2032 <h4>alignment: 4 bytes</h4> 2033 2034 <table class="format"> 2035 <thead> 2036 <tr> 2037 <th>Name</th> 2038 <th>Format</th> 2039 <th>Description</th> 2040 </tr> 2041 </thead> 2042 <tbody> 2043 <tr> 2044 <td>registers_size</td> 2045 <td>ushort</td> 2046 <td>the number of registers used by this code</td> 2047 </tr> 2048 <tr> 2049 <td>ins_size</td> 2050 <td>ushort</td> 2051 <td>the number of words of incoming arguments to the method that this 2052 code is for</td> 2053 </tr> 2054 <tr> 2055 <td>outs_size</td> 2056 <td>ushort</td> 2057 <td>the number of words of outgoing argument space required by this 2058 code for method invocation 2059 </td> 2060 </tr> 2061 <tr> 2062 <td>tries_size</td> 2063 <td>ushort</td> 2064 <td>the number of <code>try_item</code>s for this instance. If non-zero, 2065 then these appear as the <code>tries</code> array just after the 2066 <code>insns</code> in this instance. 2067 </td> 2068 </tr> 2069 <tr> 2070 <td>debug_info_off</td> 2071 <td>uint</td> 2072 <td>offset from the start of the file to the debug info (line numbers + 2073 local variable info) sequence for this code, or <code>0</code> if 2074 there simply is no information. The offset, if non-zero, should be 2075 to a location in the <code>data</code> section. The format of 2076 the data is specified by "<code>debug_info_item</code>" below. 2077 </td> 2078 </tr> 2079 <tr> 2080 <td>insns_size</td> 2081 <td>uint</td> 2082 <td>size of the instructions list, in 16-bit code units</td> 2083 </tr> 2084 <tr> 2085 <td>insns</td> 2086 <td>ushort[insns_size]</td> 2087 <td>actual array of bytecode. The format of code in an <code>insns</code> 2088 array is specified by the companion document 2089 <a href="dalvik-bytecode.html">Dalvik bytecode</a>. Note 2090 that though this is defined as an array of <code>ushort</code>, there 2091 are some internal structures that prefer four-byte alignment. Also, 2092 if this happens to be in an endian-swapped file, then the swapping is 2093 <i>only</i> done on individual <code>ushort</code>s and not on the 2094 larger internal structures. 2095 </td> 2096 </tr> 2097 <tr> 2098 <td>padding</td> 2099 <td>ushort <i>(optional)</i> = 0</td> 2100 <td>two bytes of padding to make <code>tries</code> four-byte aligned. 2101 This element is only present if <code>tries_size</code> is non-zero 2102 and <code>insns_size</code> is odd. 2103 </td> 2104 </tr> 2105 <tr> 2106 <td>tries</td> 2107 <td>try_item[tries_size] <i>(optional)</i></td> 2108 <td>array indicating where in the code exceptions are caught and 2109 how to handle them. Elements of the array must be non-overlapping in 2110 range and in order from low to high address. This element is only 2111 present if <code>tries_size</code> is non-zero. 2112 </td> 2113 </tr> 2114 <tr> 2115 <td>handlers</td> 2116 <td>encoded_catch_handler_list <i>(optional)</i></td> 2117 <td>bytes representing a list of lists of catch types and associated 2118 handler addresses. Each <code>try_item</code> has a byte-wise offset 2119 into this structure. This element is only present if 2120 <code>tries_size</code> is non-zero. 2121 </td> 2122 </tr> 2123 </tbody> 2124 </table> 2125 2126 <h3 id="type-item">try_item format</h3> 2127 2128 <table class="format"> 2129 <thead> 2130 <tr> 2131 <th>Name</th> 2132 <th>Format</th> 2133 <th>Description</th> 2134 </tr> 2135 </thead> 2136 <tbody> 2137 <tr> 2138 <td>start_addr</td> 2139 <td>uint</td> 2140 <td>start address of the block of code covered by this entry. The address 2141 is a count of 16-bit code units to the start of the first covered 2142 instruction. 2143 </td> 2144 </tr> 2145 <tr> 2146 <td>insn_count</td> 2147 <td>ushort</td> 2148 <td>number of 16-bit code units covered by this entry. The last code 2149 unit covered (inclusive) is <code>start_addr + insn_count - 1</code>. 2150 </td> 2151 </tr> 2152 <tr> 2153 <td>handler_off</td> 2154 <td>ushort</td> 2155 <td>offset in bytes from the start of the associated 2156 <code>encoded_catch_hander_list</code> to the 2157 <code>encoded_catch_handler</code> for this entry. This must be an 2158 offset to the start of an <code>encoded_catch_handler</code>. 2159 </td> 2160 </tr> 2161 </tbody> 2162 </table> 2163 2164 <h3 id="encoded-catch-handlerlist">encoded_catch_handler_list format</h3> 2165 2166 <table class="format"> 2167 <thead> 2168 <tr> 2169 <th>Name</th> 2170 <th>Format</th> 2171 <th>Description</th> 2172 </tr> 2173 </thead> 2174 <tbody> 2175 <tr> 2176 <td>size</td> 2177 <td>uleb128</td> 2178 <td>size of this list, in entries</td> 2179 </tr> 2180 <tr> 2181 <td>list</td> 2182 <td>encoded_catch_handler[handlers_size]</td> 2183 <td>actual list of handler lists, represented directly (not as offsets), 2184 and concatenated sequentially</td> 2185 </tr> 2186 </tbody> 2187 </table> 2188 2189 <h3 id="encoded-catch-handler">encoded_catch_handler format</h3> 2190 2191 <table class="format"> 2192 <thead> 2193 <tr> 2194 <th>Name</th> 2195 <th>Format</th> 2196 <th>Description</th> 2197 </tr> 2198 </thead> 2199 <tbody> 2200 <tr> 2201 <td>size</td> 2202 <td>sleb128</td> 2203 <td>number of catch types in this list. If non-positive, then this is 2204 the negative of the number of catch types, and the catches are followed 2205 by a catch-all handler. For example: A <code>size</code> of <code>0</code> 2206 means that there is a catch-all but no explicitly typed catches. 2207 A <code>size</code> of <code>2</code> means that there are two explicitly 2208 typed catches and no catch-all. And a <code>size</code> of <code>-1</code> 2209 means that there is one typed catch along with a catch-all. 2210 </td> 2211 </tr> 2212 <tr> 2213 <td>handlers</td> 2214 <td>encoded_type_addr_pair[abs(size)]</td> 2215 <td>stream of <code>abs(size)</code> encoded items, one for each caught 2216 type, in the order that the types should be tested. 2217 </td> 2218 </tr> 2219 <tr> 2220 <td>catch_all_addr</td> 2221 <td>uleb128 <i>(optional)</i></td> 2222 <td>bytecode address of the catch-all handler. This element is only 2223 present if <code>size</code> is non-positive. 2224 </td> 2225 </tr> 2226 </tbody> 2227 </table> 2228 2229 <h3 id="encoded-type-addr-pair">encoded_type_addr_pair format</h3> 2230 2231 <table class="format"> 2232 <thead> 2233 <tr> 2234 <th>Name</th> 2235 <th>Format</th> 2236 <th>Description</th> 2237 </tr> 2238 </thead> 2239 <tbody> 2240 <tr> 2241 <td>type_idx</td> 2242 <td>uleb128</td> 2243 <td>index into the <code>type_ids</code> list for the type of the 2244 exception to catch 2245 </td> 2246 </tr> 2247 <tr> 2248 <td>addr</td> 2249 <td>uleb128</td> 2250 <td>bytecode address of the associated exception handler</td> 2251 </tr> 2252 </tbody> 2253 </table> 2254 2255 <h3 id="debug-info-item">debug_info_item</h3> 2256 <h4>referenced from code_item</h4> 2257 <h4>appears in the data section</h4> 2258 <h4>alignment: none (byte-aligned)</h4> 2259 2260 <p>Each <code>debug_info_item</code> defines a DWARF3-inspired byte-coded 2261 state machine that, when interpreted, emits the positions 2262 table and (potentially) the local variable information for a 2263 <code>code_item</code>. The sequence begins with a variable-length 2264 header (the length of which depends on the number of method 2265 parameters), is followed by the state machine bytecodes, and ends 2266 with an <code>DBG_END_SEQUENCE</code> byte.</p> 2267 2268 <p>The state machine consists of five registers. The 2269 <code>address</code> register represents the instruction offset in the 2270 associated <code>insns_item</code> in 16-bit code units. The 2271 <code>address</code> register starts at <code>0</code> at the beginning of each 2272 <code>debug_info</code> sequence and must only monotonically increase. 2273 The <code>line</code> register represents what source line number 2274 should be associated with the next positions table entry emitted by 2275 the state machine. It is initialized in the sequence header, and may 2276 change in positive or negative directions but must never be less than 2277 <code>1</code>. The <code>source_file</code> register represents the 2278 source file that the line number entries refer to. It is initialized to 2279 the value of <code>source_file_idx</code> in <code>class_def_item</code>. 2280 The other two variables, <code>prologue_end</code> and 2281 <code>epilogue_begin</code>, are boolean flags (initialized to 2282 <code>false</code>) that indicate whether the next position emitted 2283 should be considered a method prologue or epilogue. The state machine 2284 must also track the name and type of the last local variable live in 2285 each register for the <code>DBG_RESTART_LOCAL</code> code.</p> 2286 2287 <p>The header is as follows:</p> 2288 2289 <table class="format"> 2290 <thead> 2291 <tr> 2292 <th>Name</th> 2293 <th>Format</th> 2294 <th>Description</th> 2295 </tr> 2296 </thead> 2297 <tbody> 2298 <tr> 2299 <td>line_start</td> 2300 <td>uleb128</td> 2301 <td>the initial value for the state machine's <code>line</code> register. 2302 Does not represent an actual positions entry. 2303 </td> 2304 </tr> 2305 <tr> 2306 <td>parameters_size</td> 2307 <td>uleb128</td> 2308 <td>the number of parameter names that are encoded. There should be 2309 one per method parameter, excluding an instance method's <code>this</code>, 2310 if any. 2311 </td> 2312 </tr> 2313 <tr> 2314 <td>parameter_names</td> 2315 <td>uleb128p1[parameters_size]</td> 2316 <td>string index of the method parameter name. An encoded value of 2317 <code>NO_INDEX</code> indicates that no name 2318 is available for the associated parameter. The type descriptor 2319 and signature are implied from the method descriptor and signature. 2320 </td> 2321 </tr> 2322 </tbody> 2323 </table> 2324 2325 <p>The byte code values are as follows:</p> 2326 2327 <table class="debugByteCode"> 2328 <thead> 2329 <tr> 2330 <th>Name</th> 2331 <th>Value</th> 2332 <th>Format</th> 2333 <th>Arguments</th> 2334 <th>Description</th> 2335 </tr> 2336 </thead> 2337 <tbody> 2338 <tr> 2339 <td>DBG_END_SEQUENCE</td> 2340 <td>0x00</td> 2341 <td></td> 2342 <td><i>(none)</i></td> 2343 <td>terminates a debug info sequence for a <code>code_item</code></td> 2344 </tr> 2345 <tr> 2346 <td>DBG_ADVANCE_PC</td> 2347 <td>0x01</td> 2348 <td>uleb128 addr_diff</td> 2349 <td><code>addr_diff</code>: amount to add to address register</td> 2350 <td>advances the address register without emitting a positions entry</td> 2351 </tr> 2352 <tr> 2353 <td>DBG_ADVANCE_LINE</td> 2354 <td>0x02</td> 2355 <td>sleb128 line_diff</td> 2356 <td><code>line_diff</code>: amount to change line register by</td> 2357 <td>advances the line register without emitting a positions entry</td> 2358 </tr> 2359 <tr> 2360 <td>DBG_START_LOCAL</td> 2361 <td>0x03</td> 2362 <td>uleb128 register_num<br/> 2363 uleb128p1 name_idx<br/> 2364 uleb128p1 type_idx 2365 </td> 2366 <td><code>register_num</code>: register that will contain local<br/> 2367 <code>name_idx</code>: string index of the name<br/> 2368 <code>type_idx</code>: type index of the type 2369 </td> 2370 <td>introduces a local variable at the current address. Either 2371 <code>name_idx</code> or <code>type_idx</code> may be 2372 <code>NO_INDEX</code> to indicate that that value is unknown. 2373 </td> 2374 </tr> 2375 <tr> 2376 <td>DBG_START_LOCAL_EXTENDED</td> 2377 <td>0x04</td> 2378 <td>uleb128 register_num<br/> 2379 uleb128p1 name_idx<br/> 2380 uleb128p1 type_idx<br/> 2381 uleb128p1 sig_idx 2382 </td> 2383 <td><code>register_num</code>: register that will contain local<br/> 2384 <code>name_idx</code>: string index of the name<br/> 2385 <code>type_idx</code>: type index of the type<br/> 2386 <code>sig_idx</code>: string index of the type signature 2387 </td> 2388 <td>introduces a local with a type signature at the current address. 2389 Any of <code>name_idx</code>, <code>type_idx</code>, or 2390 <code>sig_idx</code> may be <code>NO_INDEX</code> 2391 to indicate that that value is unknown. (If <code>sig_idx</code> is 2392 <code>-1</code>, though, the same data could be represented more 2393 efficiently using the opcode <code>DBG_START_LOCAL</code>.) 2394 <p class="note"><strong>Note:</strong> See the discussion under 2395 "<code>dalvik.annotation.Signature</code>" below for caveats about 2396 handling signatures.</p> 2397 </td> 2398 </tr> 2399 <tr> 2400 <td>DBG_END_LOCAL</td> 2401 <td>0x05</td> 2402 <td>uleb128 register_num</td> 2403 <td><code>register_num</code>: register that contained local</td> 2404 <td>marks a currently-live local variable as out of scope at the current 2405 address 2406 </td> 2407 </tr> 2408 <tr> 2409 <td>DBG_RESTART_LOCAL</td> 2410 <td>0x06</td> 2411 <td>uleb128 register_num</td> 2412 <td><code>register_num</code>: register to restart</td> 2413 <td>re-introduces a local variable at the current address. The name 2414 and type are the same as the last local that was live in the specified 2415 register. 2416 </td> 2417 </tr> 2418 <tr> 2419 <td>DBG_SET_PROLOGUE_END</td> 2420 <td>0x07</td> 2421 <td></td> 2422 <td><i>(none)</i></td> 2423 <td>sets the <code>prologue_end</code> state machine register, 2424 indicating that the next position entry that is added should be 2425 considered the end of a method prologue (an appropriate place for 2426 a method breakpoint). The <code>prologue_end</code> register is 2427 cleared by any special (<code>>= 0x0a</code>) opcode. 2428 </td> 2429 </tr> 2430 <tr> 2431 <td>DBG_SET_EPILOGUE_BEGIN</td> 2432 <td>0x08</td> 2433 <td></td> 2434 <td><i>(none)</i></td> 2435 <td>sets the <code>epilogue_begin</code> state machine register, 2436 indicating that the next position entry that is added should be 2437 considered the beginning of a method epilogue (an appropriate place 2438 to suspend execution before method exit). 2439 The <code>epilogue_begin</code> register is cleared by any special 2440 (<code>>= 0x0a</code>) opcode. 2441 </td> 2442 </tr> 2443 <tr> 2444 <td>DBG_SET_FILE</td> 2445 <td>0x09</td> 2446 <td>uleb128p1 name_idx</td> 2447 <td><code>name_idx</code>: string index of source file name; 2448 <code>NO_INDEX</code> if unknown 2449 </td> 2450 <td>indicates that all subsequent line number entries make reference to this 2451 source file name, instead of the default name specified in 2452 <code>code_item</code> 2453 </td> 2454 </tr> 2455 <tr> 2456 <td><i>Special Opcodes</i></td> 2457 <!-- When updating the range below, make sure to search for other 2458 instances of 0x0a in this section. --> 2459 <td>0x0a…0xff</td> 2460 <td></td> 2461 <td><i>(none)</i></td> 2462 <td>advances the <code>line</code> and <code>address</code> registers, 2463 emits a position entry, and clears <code>prologue_end</code> and 2464 <code>epilogue_begin</code>. See below for description. 2465 </td> 2466 </tr> 2467 </tbody> 2468 </table> 2469 2470 <h3 id="opcodes">Special opcodes</h3> 2471 2472 <p>Opcodes with values between <code>0x0a</code> and <code>0xff</code> 2473 (inclusive) move both the <code>line</code> and <code>address</code> 2474 registers by a small amount and then emit a new position table entry. 2475 The formula for the increments are as follows:</p> 2476 2477 <pre> 2478 DBG_FIRST_SPECIAL = 0x0a // the smallest special opcode 2479 DBG_LINE_BASE = -4 // the smallest line number increment 2480 DBG_LINE_RANGE = 15 // the number of line increments represented 2481 2482 adjusted_opcode = opcode - DBG_FIRST_SPECIAL 2483 2484 line += DBG_LINE_BASE + (adjusted_opcode % DBG_LINE_RANGE) 2485 address += (adjusted_opcode / DBG_LINE_RANGE) 2486 </pre> 2487 2488 <h3 id="annotations-directory">annotations_directory_item</h3> 2489 <h4>referenced from class_def_item</h4> 2490 <h4>appears in the data section</h4> 2491 <h4>alignment: 4 bytes</h4> 2492 2493 <table class="format"> 2494 <thead> 2495 <tr> 2496 <th>Name</th> 2497 <th>Format</th> 2498 <th>Description</th> 2499 </tr> 2500 </thead> 2501 <tbody> 2502 <tr> 2503 <td>class_annotations_off</td> 2504 <td>uint</td> 2505 <td>offset from the start of the file to the annotations made directly 2506 on the class, or <code>0</code> if the class has no direct annotations. 2507 The offset, if non-zero, should be to a location in the 2508 <code>data</code> section. The format of the data is specified 2509 by "<code>annotation_set_item</code>" below. 2510 </td> 2511 </tr> 2512 <tr> 2513 <td>fields_size</td> 2514 <td>uint</td> 2515 <td>count of fields annotated by this item</td> 2516 </tr> 2517 <tr> 2518 <td>annotated_methods_size</td> 2519 <td>uint</td> 2520 <td>count of methods annotated by this item</td> 2521 </tr> 2522 <tr> 2523 <td>annotated_parameters_size</td> 2524 <td>uint</td> 2525 <td>count of method parameter lists annotated by this item</td> 2526 </tr> 2527 <tr> 2528 <td>field_annotations</td> 2529 <td>field_annotation[fields_size] <i>(optional)</i></td> 2530 <td>list of associated field annotations. The elements of the list must 2531 be sorted in increasing order, by <code>field_idx</code>. 2532 </td> 2533 </tr> 2534 <tr> 2535 <td>method_annotations</td> 2536 <td>method_annotation[methods_size] <i>(optional)</i></td> 2537 <td>list of associated method annotations. The elements of the list must 2538 be sorted in increasing order, by <code>method_idx</code>. 2539 </td> 2540 </tr> 2541 <tr> 2542 <td>parameter_annotations</td> 2543 <td>parameter_annotation[parameters_size] <i>(optional)</i></td> 2544 <td>list of associated method parameter annotations. The elements of the 2545 list must be sorted in increasing order, by <code>method_idx</code>. 2546 </td> 2547 </tr> 2548 </tbody> 2549 </table> 2550 2551 <p class="note"><strong>Note:</strong> All elements' <code>field_id</code>s and 2552 <code>method_id</code>s must refer to the same defining class.</p> 2553 2554 <h3 id="field-annotation">field_annotation format</h3> 2555 2556 <table class="format"> 2557 <thead> 2558 <tr> 2559 <th>Name</th> 2560 <th>Format</th> 2561 <th>Description</th> 2562 </tr> 2563 </thead> 2564 <tbody> 2565 <tr> 2566 <td>field_idx</td> 2567 <td>uint</td> 2568 <td>index into the <code>field_ids</code> list for the identity of the 2569 field being annotated 2570 </td> 2571 </tr> 2572 <tr> 2573 <td>annotations_off</td> 2574 <td>uint</td> 2575 <td>offset from the start of the file to the list of annotations for 2576 the field. The offset should be to a location in the <code>data</code> 2577 section. The format of the data is specified by 2578 "<code>annotation_set_item</code>" below. 2579 </td> 2580 </tr> 2581 </tbody> 2582 </table> 2583 2584 <h3 id="method-annotation">method_annotation format</h3> 2585 2586 <table class="format"> 2587 <thead> 2588 <tr> 2589 <th>Name</th> 2590 <th>Format</th> 2591 <th>Description</th> 2592 </tr> 2593 </thead> 2594 <tbody> 2595 <tr> 2596 <td>method_idx</td> 2597 <td>uint</td> 2598 <td>index into the <code>method_ids</code> list for the identity of the 2599 method being annotated 2600 </td> 2601 </tr> 2602 <tr> 2603 <td>annotations_off</td> 2604 <td>uint</td> 2605 <td>offset from the start of the file to the list of annotations for 2606 the method. The offset should be to a location in the 2607 <code>data</code> section. The format of the data is specified by 2608 "<code>annotation_set_item</code>" below. 2609 </td> 2610 </tr> 2611 </tbody> 2612 </table> 2613 2614 <h3 id="parameter-annotation">parameter_annotation format</h3> 2615 2616 <table class="format"> 2617 <thead> 2618 <tr> 2619 <th>Name</th> 2620 <th>Format</th> 2621 <th>Description</th> 2622 </tr> 2623 </thead> 2624 <tbody> 2625 <tr> 2626 <td>method_idx</td> 2627 <td>uint</td> 2628 <td>index into the <code>method_ids</code> list for the identity of the 2629 method whose parameters are being annotated 2630 </td> 2631 </tr> 2632 <tr> 2633 <td>annotations_off</td> 2634 <td>uint</td> 2635 <td>offset from the start of the file to the list of annotations for 2636 the method parameters. The offset should be to a location in the 2637 <code>data</code> section. The format of the data is specified by 2638 "<code>annotation_set_ref_list</code>" below. 2639 </td> 2640 </tr> 2641 </tbody> 2642 </table> 2643 2644 <h3 id="set-ref-list">annotation_set_ref_list</h3> 2645 <h4>referenced from parameter_annotations_item</h4> 2646 <h4>appears in the data section</h4> 2647 <h4>alignment: 4 bytes</h4> 2648 2649 <table class="format"> 2650 <thead> 2651 <tr> 2652 <th>Name</th> 2653 <th>Format</th> 2654 <th>Description</th> 2655 </tr> 2656 </thead> 2657 <tbody> 2658 <tr> 2659 <td>size</td> 2660 <td>uint</td> 2661 <td>size of the list, in entries</td> 2662 </tr> 2663 <tr> 2664 <td>list</td> 2665 <td>annotation_set_ref_item[size]</td> 2666 <td>elements of the list</td> 2667 </tr> 2668 </tbody> 2669 </table> 2670 2671 <h3 id="set-ref-item">annotation_set_ref_item format</h3> 2672 2673 <table class="format"> 2674 <thead> 2675 <tr> 2676 <th>Name</th> 2677 <th>Format</th> 2678 <th>Description</th> 2679 </tr> 2680 </thead> 2681 <tbody> 2682 <tr> 2683 <td>annotations_off</td> 2684 <td>uint</td> 2685 <td>offset from the start of the file to the referenced annotation set 2686 or <code>0</code> if there are no annotations for this element. 2687 The offset, if non-zero, should be to a location in the <code>data</code> 2688 section. The format of the data is specified by 2689 "<code>annotation_set_item</code>" below. 2690 </td> 2691 </tr> 2692 </tbody> 2693 </table> 2694 2695 <h3 id="annotation-set-item">annotation_set_item</h3> 2696 <h4>referenced from annotations_directory_item, field_annotations_item, 2697 method_annotations_item, and annotation_set_ref_item</h4> 2698 <h4>appears in the data section</h4> 2699 <h4>alignment: 4 bytes</h4> 2700 2701 <table class="format"> 2702 <thead> 2703 <tr> 2704 <th>Name</th> 2705 <th>Format</th> 2706 <th>Description</th> 2707 </tr> 2708 </thead> 2709 <tbody> 2710 <tr> 2711 <td>size</td> 2712 <td>uint</td> 2713 <td>size of the set, in entries</td> 2714 </tr> 2715 <tr> 2716 <td>entries</td> 2717 <td>annotation_off_item[size]</td> 2718 <td>elements of the set. The elements must be sorted in increasing order, 2719 by <code>type_idx</code>. 2720 </td> 2721 </tr> 2722 </tbody> 2723 </table> 2724 2725 <h3 id="off-item">annotation_off_item format</h3> 2726 2727 <table class="format"> 2728 <thead> 2729 <tr> 2730 <th>Name</th> 2731 <th>Format</th> 2732 <th>Description</th> 2733 </tr> 2734 </thead> 2735 <tbody> 2736 <tr> 2737 <td>annotation_off</td> 2738 <td>uint</td> 2739 <td>offset from the start of the file to an annotation. 2740 The offset should be to a location in the <code>data</code> section, 2741 and the format of the data at that location is specified by 2742 "<code>annotation_item</code>" below. 2743 </td> 2744 </tr> 2745 </tbody> 2746 </table> 2747 2748 2749 <h3 id="annotation-item">annotation_item</h3> 2750 <h4>referenced from annotation_set_item</h4> 2751 <h4>appears in the data section</h4> 2752 <h4>alignment: none (byte-aligned)</h4> 2753 2754 <table class="format"> 2755 <thead> 2756 <tr> 2757 <th>Name</th> 2758 <th>Format</th> 2759 <th>Description</th> 2760 </tr> 2761 </thead> 2762 <tbody> 2763 <tr> 2764 <td>visibility</td> 2765 <td>ubyte</td> 2766 <td>intended visibility of this annotation (see below)</td> 2767 </tr> 2768 <tr> 2769 <td>annotation</td> 2770 <td>encoded_annotation</td> 2771 <td>encoded annotation contents, in the format described by 2772 "<code>encoded_annotation</code> format" under 2773 "<code>encoded_value</code> encoding" above. 2774 </td> 2775 </tr> 2776 </tbody> 2777 </table> 2778 2779 <h3 id="visibility">Visibility values</h3> 2780 2781 <p>These are the options for the <code>visibility</code> field in an 2782 <code>annotation_item</code>:</p> 2783 2784 <table class="format"> 2785 <thead> 2786 <tr> 2787 <th>Name</th> 2788 <th>Value</th> 2789 <th>Description</th> 2790 </tr> 2791 </thead> 2792 <tbody> 2793 <tr> 2794 <td>VISIBILITY_BUILD</td> 2795 <td>0x00</td> 2796 <td>intended only to be visible at build time (e.g., during compilation 2797 of other code) 2798 </td> 2799 </tr> 2800 <tr> 2801 <td>VISIBILITY_RUNTIME</td> 2802 <td>0x01</td> 2803 <td>intended to visible at runtime</td> 2804 </tr> 2805 <tr> 2806 <td>VISIBILITY_SYSTEM</td> 2807 <td>0x02</td> 2808 <td>intended to visible at runtime, but only to the underlying system 2809 (and not to regular user code) 2810 </td> 2811 </tr> 2812 </tbody> 2813 </table> 2814 2815 <h3 id="encoded-array-item">encoded_array_item</h3> 2816 <h4>referenced from class_def_item</h4> 2817 <h4>appears in the data section</h4> 2818 <h4>alignment: none (byte-aligned)</h4> 2819 2820 <table class="format"> 2821 <thead> 2822 <tr> 2823 <th>Name</th> 2824 <th>Format</th> 2825 <th>Description</th> 2826 </tr> 2827 </thead> 2828 <tbody> 2829 <tr> 2830 <td>value</td> 2831 <td>encoded_array</td> 2832 <td>bytes representing the encoded array value, in the format specified 2833 by "<code>encoded_array</code> Format" under "<code>encoded_value</code> 2834 Encoding" above. 2835 </td> 2836 </tr> 2837 </tbody> 2838 </table> 2839 2840 <h2 id="system-annotation">System annotations</h2> 2841 2842 <p>System annotations are used to represent various pieces of reflective 2843 information about classes (and methods and fields). This information is 2844 generally only accessed indirectly by client (non-system) code.</p> 2845 2846 <p>System annotations are represented in <code>.dex</code> files as 2847 annotations with visibility set to <code>VISIBILITY_SYSTEM</code>. 2848 2849 <h3 id="dalvik-annotation-default">dalvik.annotation.AnnotationDefault</h3> 2850 <h4>appears on methods in annotation interfaces</h4> 2851 2852 <p>An <code>AnnotationDefault</code> annotation is attached to each 2853 annotation interface which wishes to indicate default bindings.</p> 2854 2855 <table class="format"> 2856 <thead> 2857 <tr> 2858 <th>Name</th> 2859 <th>Format</th> 2860 <th>Description</th> 2861 </tr> 2862 </thead> 2863 <tbody> 2864 <tr> 2865 <td>value</td> 2866 <td>Annotation</td> 2867 <td>the default bindings for this annotation, represented as an annotation 2868 of this type. The annotation need not include all names defined by the 2869 annotation; missing names simply do not have defaults. 2870 </td> 2871 </tr> 2872 </tbody> 2873 </table> 2874 2875 <h3 id="dalvik-enclosingclass">dalvik.annotation.EnclosingClass</h3> 2876 <h4>appears on classes</h4> 2877 2878 <p>An <code>EnclosingClass</code> annotation is attached to each class 2879 which is either defined as a member of another class, per se, or is 2880 anonymous but not defined within a method body (e.g., a synthetic 2881 inner class). Every class that has this annotation must also have an 2882 <code>InnerClass</code> annotation. Additionally, a class must not have 2883 both an <code>EnclosingClass</code> and an 2884 <code>EnclosingMethod</code> annotation.</p> 2885 2886 <table class="format"> 2887 <thead> 2888 <tr> 2889 <th>Name</th> 2890 <th>Format</th> 2891 <th>Description</th> 2892 </tr> 2893 </thead> 2894 <tbody> 2895 <tr> 2896 <td>value</td> 2897 <td>Class</td> 2898 <td>the class which most closely lexically scopes this class</td> 2899 </tr> 2900 </tbody> 2901 </table> 2902 2903 <h3 id="dalvik-enclosingmethod">dalvik.annotation.EnclosingMethod</h3> 2904 <h4>appears on classes</h4> 2905 2906 <p>An <code>EnclosingMethod</code> annotation is attached to each class 2907 which is defined inside a method body. Every class that has this 2908 annotation must also have an <code>InnerClass</code> annotation. 2909 Additionally, a class must not have both an <code>EnclosingClass</code> 2910 and an <code>EnclosingMethod</code> annotation.</p> 2911 2912 <table class="format"> 2913 <thead> 2914 <tr> 2915 <th>Name</th> 2916 <th>Format</th> 2917 <th>Description</th> 2918 </tr> 2919 </thead> 2920 <tbody> 2921 <tr> 2922 <td>value</td> 2923 <td>Method</td> 2924 <td>the method which most closely lexically scopes this class</td> 2925 </tr> 2926 </tbody> 2927 </table> 2928 2929 <h3 id="dalvik-innerclass">dalvik.annotation.InnerClass</h3> 2930 <h4>appears on classes</h4> 2931 2932 <p>An <code>InnerClass</code> annotation is attached to each class 2933 which is defined in the lexical scope of another class's definition. 2934 Any class which has this annotation must also have <i>either</i> an 2935 <code>EnclosingClass</code> annotation <i>or</i> an 2936 <code>EnclosingMethod</code> annotation.</p> 2937 2938 <table class="format"> 2939 <thead> 2940 <tr> 2941 <th>Name</th> 2942 <th>Format</th> 2943 <th>Description</th> 2944 </tr> 2945 </thead> 2946 <tbody> 2947 <tr> 2948 <td>name</td> 2949 <td>String</td> 2950 <td>the originally declared simple name of this class (not including any 2951 package prefix). If this class is anonymous, then the name is 2952 <code>null</code>. 2953 </td> 2954 </tr> 2955 <tr> 2956 <td>accessFlags</td> 2957 <td>int</td> 2958 <td>the originally declared access flags of the class (which may differ 2959 from the effective flags because of a mismatch between the execution 2960 models of the source language and target virtual machine) 2961 </td> 2962 </tr> 2963 </tbody> 2964 </table> 2965 2966 <h3 id="dalvik-memberclasses">dalvik.annotation.MemberClasses</h3> 2967 <h4>appears on classes</h4> 2968 2969 <p>A <code>MemberClasses</code> annotation is attached to each class 2970 which declares member classes. (A member class is a direct inner class 2971 that has a name.)</p> 2972 2973 <table class="format"> 2974 <thead> 2975 <tr> 2976 <th>Name</th> 2977 <th>Format</th> 2978 <th>Description</th> 2979 </tr> 2980 </thead> 2981 <tbody> 2982 <tr> 2983 <td>value</td> 2984 <td>Class[]</td> 2985 <td>array of the member classes</td> 2986 </tr> 2987 </tbody> 2988 </table> 2989 2990 <h3 id="dalvik-signature">dalvik.annotation.Signature</h3> 2991 <h4>appears on classes, fields, and methods</h4> 2992 2993 <p>A <code>Signature</code> annotation is attached to each class, 2994 field, or method which is defined in terms of a more complicated type 2995 than is representable by a <code>type_id_item</code>. The 2996 <code>.dex</code> format does not define the format for signatures; it 2997 is merely meant to be able to represent whatever signatures a source 2998 language requires for successful implementation of that language's 2999 semantics. As such, signatures are not generally parsed (or verified) 3000 by virtual machine implementations. The signatures simply get handed 3001 off to higher-level APIs and tools (such as debuggers). Any use of a 3002 signature, therefore, should be written so as not to make any 3003 assumptions about only receiving valid signatures, explicitly guarding 3004 itself against the possibility of coming across a syntactically 3005 invalid signature.</p> 3006 3007 <p>Because signature strings tend to have a lot of duplicated content, 3008 a <code>Signature</code> annotation is defined as an <i>array</i> of 3009 strings, where duplicated elements naturally refer to the same 3010 underlying data, and the signature is taken to be the concatenation of 3011 all the strings in the array. There are no rules about how to pull 3012 apart a signature into separate strings; that is entirely up to the 3013 tools that generate <code>.dex</code> files.</p> 3014 3015 <table class="format"> 3016 <thead> 3017 <tr> 3018 <th>Name</th> 3019 <th>Format</th> 3020 <th>Description</th> 3021 </tr> 3022 </thead> 3023 <tbody> 3024 <tr> 3025 <td>value</td> 3026 <td>String[]</td> 3027 <td>the signature of this class or member, as an array of strings that 3028 is to be concatenated together</td> 3029 </tr> 3030 </tbody> 3031 </table> 3032 3033 <h3 id="dalvik-throws">dalvik.annotation.Throws</h3> 3034 <h4>appears on methods</h4> 3035 3036 <p>A <code>Throws</code> annotation is attached to each method which is 3037 declared to throw one or more exception types.</p> 3038 3039 <table class="format"> 3040 <thead> 3041 <tr> 3042 <th>Name</th> 3043 <th>Format</th> 3044 <th>Description</th> 3045 </tr> 3046 </thead> 3047 <tbody> 3048 <tr> 3049 <td>value</td> 3050 <td>Class[]</td> 3051 <td>the array of exception types thrown</td> 3052 </tr> 3053 </tbody> 3054 </table> 3055
