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