تنسيق Dalvik القابل للتنفيذ

يوضّح هذا المستند تخطيط ومحتويات ملفات .dex، والتي تُستخدَم لتخزين مجموعة من تعريفات الفئات وبياناتها الملحقة.

دليل الأنواع

LEB128

‫LEB128 (اختصار Little-Endian Base 128) هو ترميز متغير الطول لكميات عددية صحيحة موجبة أو سالبة عشوائية. تم استعارة التنسيق من مواصفات DWARF3. في ملف .dex، لا يتم استخدام LEB128 إلا لترميز كميات 32 بت.

تتألف كل قيمة مشفّرة بتنسيق LEB128 من بايت واحد إلى خمسة بايتات، تمثّل معًا قيمة واحدة بتنسيق 32 بت. يتم ضبط البت الأكثر أهمية لكل بايت باستثناء البايت الأخير في التسلسل، حيث يتم محو البت الأكثر أهمية. أما وحدات البت السبع المتبقية من كل بايت، فهي تمثّل الحمولة، حيث تمثّل وحدات البت السبع الأقل أهمية من الكمية في البايت الأول، وتمثّل وحدات البت السبع التالية في البايت الثاني، وهكذا. في حالة LEB128 الموقّع (sleb128)، يتم تمديد بت الحمولة الأكثر أهمية في البايت الأخير في التسلسل لإنتاج القيمة النهائية. في حالة الأعداد غير الموقّعة (uleb128)، يتم تفسير أي أجزاء غير ممثّلة بشكل صريح على أنّها 0.

يُستخدَم النوع المتغير uleb128p1 لتمثيل قيمة موقّعة، حيث يكون التمثيل للقيمة زائد واحد مرمّزًا كـ uleb128. يؤدي ذلك إلى أن يكون ترميز -1 (أو القيمة غير الموقّعة 0xffffffff) عبارة عن بايت واحد، ولكن ليس أي رقم سالب آخر، ويكون ذلك مفيدًا في الحالات التي يجب أن يكون فيها الرقم المعروض غير سالب أو -1 (أو 0xffffffff)، ولا يُسمح بأي قيم سالبة أخرى (أو في الحالات التي من غير المحتمل أن تكون هناك حاجة إلى قيم كبيرة غير موقّعة).

في ما يلي بعض الأمثلة على التنسيقات:

تنسيق الملف

تنسيق الحاوية

يقدّم الإصدار 41 تنسيق حاوية جديدًا لبيانات DEX بهدف توفير المساحة. يتيح تنسيق الحاوية هذا دمج عدة ملفات DEX منطقية في ملف مادي واحد. التنسيق الجديد هو في الغالب مجرد تسلسل بسيط للملفات بالتنسيق السابق، مع بعض الاختلافات:

• file_size هو حجم الملف المنطقي، وليس الملف الفعلي. ويمكن استخدامها لتكرار جميع الملفات المنطقية في الحاوية.
• قد تشير ملفات dex المنطقية إلى أي بيانات لاحقة في الحاوية (ولكن ليس إلى البيانات السابقة). يتيح ذلك لملفات dex مشاركة البيانات، مثل السلاسل، بينها.
• جميع الإزاحات مرتبطة بالملف الفعلي. ما مِن إزاحة مرتبطة بالعنوان. يضمن ذلك إمكانية مشاركة الأقسام التي تتضمّن إزاحات بين الملفات المنطقية.
• يضيف العنوان حقلَين جديدَين لوصف حدود الحاوية. هذا هو فحص الاتساق الإضافي الذي يسهّل نقل الرمز إلى التنسيق الجديد.
• لم يعُد يتم استخدام data_size وdata_off. يمكن توزيع البيانات على عدة ملفات منطقية ولا يلزم أن تكون متجاورة.

تعريفات حقل البت والسلسلة والثابت

DEX_FILE_MAGIC

مضمّنة في header_item

مصفوفة/سلسلة الثوابت DEX_FILE_MAGIC هي قائمة بالبايتات التي يجب أن تظهر في بداية ملف .dex ليتم التعرّف عليه على هذا النحو. تحتوي القيمة عمدًا على سطر جديد ("\n" أو 0x0a) وبايت فارغ ("\0" أو 0x00) للمساعدة في رصد بعض أشكال التلف. تتضمّن القيمة أيضًا رقم إصدار التنسيق كأرقام عشرية مكوّنة من ثلاثة أرقام، ومن المتوقّع أن يزداد بشكل منتظم بمرور الوقت مع تطوّر التنسيق.

ubyte[8] DEX_FILE_MAGIC = { 0x64 0x65 0x78 0x0a 0x30 0x33 0x39 0x00 }
                        = "dex\n039\0"

ملاحظة: تمت إضافة إمكانية استخدام الإصدار 041 من التنسيق في إصدار Android 16، ما يتيح استخدام تنسيق الحاوية.

ملاحظة: تمت إضافة إمكانية استخدام الإصدار 040 من التنسيق في إصدار Android 10.0، ما أدّى إلى توسيع مجموعة الأحرف المسموح بها في SimpleNames.

ملاحظة: تمت إضافة إمكانية استخدام الإصدار 039 من التنسيق في إصدار Android 9.0، والذي قدّم رمزين جديدين للوحدات البايت، هما const-method-handle وconst-method-type. (يتم وصف كل منها في جدول ملخّص مجموعة الرموز البرمجية). في نظام التشغيل Android 10، يوسّع الإصدار 039 تنسيق ملف DEX ليشمل معلومات API مخفية لا تنطبق إلا على ملفات DEX في مسار فئة التمهيد.

ملاحظة: تمت إضافة إمكانية استخدام الإصدار 038 من التنسيق في إصدار Android 8.0. أضاف الإصدار 038 رموز بايت جديدة (invoke-polymorphic وinvoke-custom) وبيانات لمعالجة الطرق.

ملاحظة: تمت إضافة إمكانية استخدام الإصدار 037 من التنسيق في الإصدار 7.0 من نظام التشغيل Android. قبل الإصدار 037، كانت معظم إصدارات Android تستخدم الإصدار 035 من التنسيق. الفرق الوحيد بين الإصدارَين 035 و037 هو إضافة طرق تلقائية وتعديل invoke.

ملاحظة: تم استخدام إصدارين سابقين على الأقل من التنسيق في إصدارات برامج متاحة للجميع. على سبيل المثال، تم استخدام الإصدار 009 لإصدارات M3 من منصة Android (تشرين الثاني/نوفمبر - كانون الأول/ديسمبر 2007)، وتم استخدام الإصدار 013 لإصدارات M5 من منصة Android (شباط/فبراير - آذار/مارس 2008). تختلف هذه الإصدارات السابقة من التنسيق بشكل كبير عن الإصدار الموضّح في هذا المستند.

ENDIAN_CONSTANT وREVERSE_ENDIAN_CONSTANT

مضمّنة في header_item

يُستخدَم الثابت ENDIAN_CONSTANT للإشارة إلى ترتيب البايتات في الملف الذي تم العثور عليه فيه. على الرغم من أنّ تنسيق .dex هو little-endian، يمكن أن تختار عمليات التنفيذ إجراء تبديل البايتات. إذا صادف التنفيذ عنوانًا تكون قيمة endian_tag فيه REVERSE_ENDIAN_CONSTANT بدلاً من ENDIAN_CONSTANT، سيعرف أنّ الملف قد تم تبديل البايتات فيه من الشكل المتوقّع.

uint ENDIAN_CONSTANT = 0x12345678;
uint REVERSE_ENDIAN_CONSTANT = 0x78563412;

NO_INDEX

مضمّنة في class_def_item وdebug_info_item

يتم استخدام الثابت NO_INDEX للإشارة إلى عدم توفّر قيمة فهرس.

ملاحظة: لم يتم تحديد هذه القيمة لتكون 0، لأنّها في الواقع عادةً ما تكون فهرسًا صالحًا.

يجب أن تكون القيمة المحدّدة لـ NO_INDEX قابلة للتمثيل كبايت واحد في ترميز uleb128p1.

uint NO_INDEX = 0xffffffff;    // == -1 if treated as a signed int

تعريفات علامات الوصول

مضمّنة في class_def_item وencoded_field وencoded_method وInnerClass

يتم استخدام حقول البتات لهذه العلامات للإشارة إلى إمكانية الوصول إلى الفئات وأعضائها وخصائصها العامة.

* يُسمح فقط بعرضها في التعليقات التوضيحية من النوع InnerClass، ويجب عدم عرضها مطلقًا في class_def_item.

ترميز UTF-8 المعدَّل

كتسوية لتسهيل التوافق مع الأنظمة القديمة، يشفّر تنسيق .dex بيانات السلسلة بتنسيق UTF-8 معدَّل وفقًا لمعيار فعلي، ويُشار إليه من الآن فصاعدًا باسم MUTF-8. هذا النموذج مطابق لمعيار UTF-8، باستثناء ما يلي:

• يتم استخدام عمليات الترميز التي تتضمّن بايت واحد أو بايتَين أو ثلاثة بايتات فقط.
• يتم ترميز نقاط الرموز في النطاق U+10000 … U+10ffff كزوج بديل، ويتم تمثيل كل نقطة منها كقيمة مرمّزة بثلاثة بايتات.
• يتم ترميز نقطة الرمز U+0000 في شكل مكوّن من بايتَين.
• يشير بايت فارغ عادي (القيمة 0) إلى نهاية السلسلة، كما هو الحال في التفسير العادي للغة C.

يمكن تلخيص النقطتين الأوليين أعلاه على النحو التالي: MUTF-8 هو تنسيق ترميز لـ UTF-16، بدلاً من أن يكون تنسيق ترميز أكثر مباشرةً لأحرف Unicode.

تتيح النقطتان الأخيرتان المذكورتان أعلاه إمكانية تضمين نقطة الرمز U+0000 في سلسلة و مع إمكانية معالجتها كسلسلة تنتهي بقيمة فارغة على نمط C.

ومع ذلك، يعني الترميز الخاص U+0000 أنّه على عكس ترميز UTF-8 العادي، لا تشير نتيجة استدعاء دالة C العادية strcmp() على زوج من سلاسل MUTF-8 دائمًا إلى النتيجة الموقّعة بشكل صحيح لمقارنة السلاسل غير المتساوية. عندما يكون الترتيب (وليس المساواة فقط) مهمًا، فإنّ أبسط طريقة لمقارنة سلاسل MUTF-8 هي فك ترميزها حرفًا حرفًا، ومقارنة القيم التي تم فك ترميزها. (ومع ذلك، يمكن أيضًا تنفيذ عمليات أكثر ذكاءً.)

يُرجى الرجوع إلى معيار Unicode للحصول على مزيد من المعلومات حول ترميز الأحرف. في الواقع، يشبه ترميز MUTF-8 ترميز CESU-8 (الأقل شهرة نسبيًا) أكثر من ترميز UTF-8 بحد ذاته.

ترميز encoded_value

مضمّن في annotation_element وencoded_array_item

encoded_value هي جزء مشفّر من البيانات المنظَّمة بشكل هرمي (تقريبًا) وعشوائي. من المفترض أن يكون الترميز مضغوطًا وسهل التحليل.

تنسيقات القيم

تنسيق encoded_array

تنسيق encoded_annotation

تنسيق عنصر التعليق التوضيحي

بنية السلسلة

هناك عدة أنواع من العناصر في ملف .dex تشير في النهاية إلى سلسلة. توضّح تعريفات BNF التالية الصيغة المقبولة لهذه السلاسل.

SimpleName

SimpleName هو أساس بنية أسماء العناصر الأخرى. يتيح تنسيق .dex قدرًا كبيرًا من المرونة هنا (أكثر بكثير من معظم اللغات المصدر الشائعة). باختصار، يتألف الاسم البسيط من أي حرف أبجدي أو رقمي منخفض ASCII، وبعض الرموز المحددة المنخفضة ASCII، ومعظم نقاط الرموز غير ASCII التي ليست رموز تحكّم أو مسافات أو رموز خاصة. بدءًا من الإصدار 040، يسمح التنسيق أيضًا بأحرف المسافة (فئة Unicode Zs). يُرجى العِلم أنّ نقاط الرموز البديلة (في النطاق U+d800 … U+dfff) لا تُعتبر أحرفًا صالحة للاستخدام في الأسماء، ولكن أحرف Unicode الإضافية صالحة (وهي ممثّلة بالبديل الأخير لقاعدة SimpleNameChar)، ويجب تمثيلها في ملف كأزواج من نقاط الرموز البديلة في ترميز MUTF-8.

MemberName

يتم استخدامها من خلال field_id_item وmethod_id_item

MemberName هو اسم أحد أعضاء الفئة، والأعضاء هم الحقول والطرق والفئات الداخلية.

FullClassName

FullClassName هو اسم صف مؤهَّل بالكامل، ويتضمّن محدّد حزمة اختياريًا متبوعًا باسم مطلوب.

TypeDescriptor

يستخدمه type_id_item

TypeDescriptor هو تمثيل لأي نوع، بما في ذلك الأنواع الأساسية والفئات والمصفوفات وvoid. يمكنك الاطّلاع أدناه على معنى الإصدارات المختلفة.

ShortyDescriptor

يستخدمه proto_id_item

ShortyDescriptor هو التمثيل المختصر لنموذج أولي لطريقة، بما في ذلك أنواع الإرجاع والمعلمات، باستثناء أنّه لا يوجد تمييز بين أنواع المراجع المختلفة (الفئة أو المصفوفة). بدلاً من ذلك، يتم تمثيل جميع أنواع المراجع بحرف 'L' واحد.

دلالات TypeDescriptor

في ما يلي معنى كل نوع من أنواع TypeDescriptor.

العناصر والبُنى ذات الصلة

يتضمّن هذا القسم تعريفات لكل عنصر من العناصر ذات المستوى الأعلى التي قد تظهر في ملف .dex.

header_item

تظهر في قسم رأس الصفحة

المطابقة: 4 بايت

قائمة_الخرائط

تظهر في قسم البيانات

يتم الرجوع إليه من header_item

المطابقة: 4 بايت

هذه قائمة بالمحتوى الكامل لملف، بالترتيب. يتضمّن هذا النوع بعض التكرار مقارنةً بالنوع header_item، ولكنّه مصمّم ليكون نموذجًا سهل الاستخدام لتكرار عملية على ملف بأكمله. يجب ألا يظهر نوع معيّن أكثر من مرة في الخريطة، ولكن لا توجد قيود على ترتيب ظهور الأنواع، باستثناء القيود التي يشير إليها بقية التنسيق (على سبيل المثال، يجب أن يظهر القسم header أولاً، يليه القسم string_ids، وما إلى ذلك). بالإضافة إلى ذلك، يجب ترتيب إدخالات الخريطة حسب الإزاحة الأولية ويجب ألا تتداخل.

تنسيق map_item

رموز الأنواع

string_id_item

يظهر في قسم string_ids

المطابقة: 4 بايت

string_data_item

تظهر في قسم البيانات

المحاذاة: بدون (محاذاة على مستوى البايت)

type_id_item

يظهر في قسم type_ids

المطابقة: 4 بايت

proto_id_item

يظهر في قسم proto_ids

المطابقة: 4 بايت

field_id_item

يظهر في قسم field_ids

المطابقة: 4 بايت

method_id_item

يظهر في قسم method_ids

المطابقة: 4 بايت

class_def_item

يظهر في قسم class_defs

المطابقة: 4 بايت

call_site_id_item

تظهر في قسم call_site_ids

المطابقة: 4 بايت

call_site_item

تظهر في قسم البيانات

المحاذاة: بدون (محاذاة البايت)

call_site_item هو encoded_array_item تتوافق عناصره مع الوسيطات المقدَّمة إلى طريقة ربط تمهيدية. الوسيطات الثلاث الأولى هي:

1. معرّف طريقة يمثّل طريقة ربط التشغيل الأوّلي (VALUE_METHOD_HANDLE).
2. اسم طريقة يجب أن يحلّها رابط التمهيد (VALUE_STRING).
3. نوع الطريقة الذي يتوافق مع نوع اسم الطريقة المطلوب حله (VALUE_METHOD_TYPE)

أي وسيطات إضافية هي قيم ثابتة يتم تمريرها إلى طريقة ربط التمهيد. يتم تمرير هذه الوسيطات بالترتيب وبدون أي عمليات تحويل للأنواع.

يجب أن يكون لنوع الإرجاع java.lang.invoke.CallSite مقبض الطريقة الذي يمثّل طريقة ربط التمهيد. أنواع المَعلمات الثلاثة الأولى هي:

1. java.lang.invoke.Lookup
2. java.lang.String
3. java.lang.invoke.MethodType

يتم تحديد أنواع مَعلمات أي وسيطات إضافية من قيمها الثابتة.

method_handle_item

يظهر في قسم method_handles

المطابقة: 4 بايت

رموز أنواع معالجة الطرق

class_data_item

يتم الرجوع إليه من class_def_item

تظهر في قسم البيانات

المحاذاة: بدون (محاذاة على مستوى البايت)

ملاحظة: يجب أن تشير جميع مثيلات field_id وmethod_id الخاصة بالعناصر إلى فئة التعريف نفسها.

تنسيق encoded_field

تنسيق encoded_method

type_list

يتم الرجوع إليه من class_def_item وproto_id_item

تظهر في قسم البيانات

المطابقة: 4 بايت

تنسيق type_item

code_item

مُشار إليها من encoded_method

تظهر في قسم البيانات

المطابقة: 4 بايت

تنسيق try_item

تنسيق encoded_catch_handler_list

تنسيق encoded_catch_handler

تنسيق encoded_type_addr_pair

debug_info_item

يتم الرجوع إليه من خلال code_item

تظهر في قسم البيانات

المحاذاة: بدون (محاذاة على مستوى البايت)

يحدّد كل debug_info_item آلة حالة مستندة إلى الرمز الثنائي ومستوحاة من DWARF3، وعند تفسيرها، تنشئ جدول المواضع ومعلومات المتغيرات المحلية (ربما) لـ code_item. يبدأ التسلسل بعنوان ذي طول متغير (يعتمد طوله على عدد مَعلمات الطريقة)، يليه رموز بايت لآلة الحالة، وينتهي ببايت DBG_END_SEQUENCE.

تتألف آلة الحالة من خمسة سجلات. يمثّل سجلّ address إزاحة التعليمات في insns_item المرتبط بوحدات الرموز المكوّنة من 16 بت. يبدأ سجلّ address عند 0 في بداية كل تسلسل debug_info ويجب أن يزداد بشكل رتيب فقط. يمثّل سجلّ line رقم سطر المصدر الذي يجب ربطه بإدخال جدول المواضع التالي الذي يتم إصداره من خلال آلة الحالة. يتم ضبط قيمته الأولية في عنوان التسلسل، وقد تتغير في اتجاهات موجبة أو سالبة، ولكن يجب ألا تقل عن 1. يمثّل سجلّ source_file ملف المصدر الذي تشير إليه إدخالات أرقام الأسطر. يتم ضبطها مبدئيًا على قيمة source_file_idx في class_def_item. المتغيران الآخران، prologue_end وepilogue_begin، هما علامتان منطقيتان (تمت تهيئتهما إلى false) تشيران إلى ما إذا كان يجب اعتبار الموضع التالي الذي تم إصداره مقدمة أو خاتمة للأسلوب. يجب أن تتتبّع آلة الحالة أيضًا اسم ونوع آخر متغير محلي نشط في كل سجل لرمز DBG_RESTART_LOCAL.

يكون العنوان على النحو التالي:

قيم رمز البايت هي كما يلي:

رموز العمليات الخاصة

تنقل رموز العمليات التي تتضمّن قيمًا بين 0x0a و0xff (شاملة) كلاً من السجلّين line وaddress بمقدار صغير، ثم تُصدر إدخالاً جديدًا في جدول المواضع. في ما يلي صيغة الزيادات:

DBG_FIRST_SPECIAL = 0x0a  // the smallest special opcode
DBG_LINE_BASE   = -4      // the smallest line number increment
DBG_LINE_RANGE  = 15      // the number of line increments represented

adjusted_opcode = opcode - DBG_FIRST_SPECIAL

line += DBG_LINE_BASE + (adjusted_opcode % DBG_LINE_RANGE)
address += (adjusted_opcode / DBG_LINE_RANGE)

annotations_directory_item

يتم الرجوع إليه من class_def_item

تظهر في قسم البيانات

المطابقة: 4 بايت

ملاحظة: يجب أن تشير جميع مثيلات field_id وmethod_id الخاصة بالعناصر إلى فئة التعريف نفسها.

تنسيق field_annotation

تنسيق method_annotation

تنسيق parameter_annotation

annotation_set_ref_list

يتم الرجوع إليها من parameter_annotations_item

تظهر في قسم البيانات

المطابقة: 4 بايت

تنسيق annotation_set_ref_item

annotation_set_item

يتم الرجوع إليه من annotations_directory_item وfield_annotations_item وmethod_annotations_item وannotation_set_ref_item

تظهر في قسم البيانات

المطابقة: 4 بايت

تنسيق annotation_off_item

annotation_item

يتم الرجوع إليها من annotation_set_item

تظهر في قسم البيانات

المحاذاة: بدون (محاذاة على مستوى البايت)

قيم مستوى الظهور

في ما يلي خيارات الحقل visibility في annotation_item:

encoded_array_item

يتم الرجوع إليه من class_def_item

تظهر في قسم البيانات

المحاذاة: بدون (محاذاة على مستوى البايت)

hiddenapi_class_data_item

يحتوي هذا القسم على بيانات حول الواجهات المحظورة التي تستخدمها كل فئة.

ملاحظة: تم طرح ميزة واجهة برمجة التطبيقات المخفية في الإصدار 10.0 من نظام التشغيل Android وهي تنطبق فقط على ملفات DEX الخاصة بالفئات في مسار فئة التمهيد. قد يتم توسيع قائمة العلامات الموضّحة أدناه في الإصدارات المستقبلية من Android. لمزيد من المعلومات، يُرجى الاطّلاع على القيود المفروضة على واجهات برمجة التطبيقات غير التابعة لحزمة SDK.

أنواع علامات الحظر:

التعليقات التوضيحية في النظام

تُستخدَم التعليقات التوضيحية الخاصة بالنظام لتمثيل أجزاء مختلفة من المعلومات الانعكاسية حول الفئات (والطرق والحقول). ولا يمكن الوصول إلى هذه المعلومات بشكل عام إلا بشكل غير مباشر من خلال رمز العميل (غير النظام).

يتم تمثيل التعليقات التوضيحية الخاصة بالنظام في ملفات .dex كتعليقات توضيحية تم ضبط مستوى رؤيتها على VISIBILITY_SYSTEM.

dalvik.annotation.AnnotationDefault

يظهر في الطرق في واجهات التعليقات التوضيحية

يتم إرفاق تعليق توضيحي AnnotationDefault بكل واجهة تعليق توضيحي تريد الإشارة إلى عمليات الربط التلقائية.

dalvik.annotation.EnclosingClass

يظهر في الصفوف

يتم إرفاق التعليق التوضيحي EnclosingClass بكل فئة يتم تعريفها كعضو في فئة أخرى، أو تكون مجهولة الهوية ولكن لم يتم تعريفها ضمن نص الدالة (مثل فئة داخلية اصطناعية). يجب أن يحتوي كل صف يتضمّن هذه التعليق التوضيحي أيضًا على تعليق توضيحي InnerClass. بالإضافة إلى ذلك، يجب ألا يتضمّن الصف كلاً من التعليق التوضيحي EnclosingClass والتعليق التوضيحي EnclosingMethod.

dalvik.annotation.EnclosingMethod

يظهر في الصفوف

يتم إرفاق تعليق توضيحي EnclosingMethod بكل فئة يتم تحديدها داخل نص الدالة. يجب أن يحتوي كل صف يتضمّن هذا التعليق التوضيحي على التعليق التوضيحي InnerClass أيضًا. بالإضافة إلى ذلك، يجب ألا يحتوي الصف على كل من التعليق التوضيحي EnclosingClass والتعليق التوضيحي EnclosingMethod.

dalvik.annotation.InnerClass

يظهر في الصفوف

يتم إرفاق تعليق توضيحي InnerClass بكل فئة يتم تحديدها في النطاق المعجمي لتعريف فئة أخرى. يجب أن يتضمّن أي صف يحتوي على هذه التعليق التوضيحي إما تعليقًا توضيحيًا من النوع EnclosingClass أو تعليقًا توضيحيًا من النوع EnclosingMethod.

dalvik.annotation.MemberClasses

يظهر في الصفوف

يتم إرفاق تعليق توضيحي MemberClasses بكل فئة تحدّد فئات الأعضاء. (فئة العضو هي فئة داخلية مباشرة لها اسم.)

dalvik.annotation.MethodParameters

تظهر في الطرق

ملاحظة: تمت إضافة هذا التعليق التوضيحي بعد الإصدار 7.1 من نظام التشغيل Android. وسيتم تجاهل وجودها في إصدارات Android السابقة.

تكون التعليقات التوضيحية MethodParameters اختيارية ويمكن استخدامها لتوفير بيانات وصفية خاصة بالمعلَمات، مثل أسماء المعلَمات والمعدِّلات.

يمكن حذف التعليق التوضيحي من طريقة أو أداة إنشاء بأمان عندما لا تكون بيانات وصفية للمعلمات مطلوبة في وقت التشغيل. يمكن استخدام java.lang.reflect.Parameter.isNamePresent() للتحقّق مما إذا كانت البيانات الوصفية متوفّرة لمعلَمة معيّنة، وستعود طرق الانعكاس المرتبطة بها، مثل java.lang.reflect.Parameter.getName()، إلى السلوك التلقائي في وقت التشغيل إذا لم تكن المعلومات متوفّرة.

عند تضمين البيانات الوصفية للمَعلمات، يجب أن تتضمّن المجمّعات معلومات للفئات التي تم إنشاؤها، مثل التعدادات، لأنّ البيانات الوصفية للمَعلمات تتضمّن ما إذا كانت المَعلمة اصطناعية أو إلزامية.

يصف التعليق التوضيحي MethodParameters مَعلمات الطريقة الفردية فقط. لذلك، قد تحذف برامج الترجمة التوضيحية بالكامل للدوال الإنشائية والطرق التي لا تحتوي على مَعلمات، وذلك بهدف تقليل حجم الرمز البرمجي وتحسين كفاءة وقت التشغيل.

يجب أن تكون المصفوفات الموضّحة أدناه بالحجم نفسه الخاص ببنية method_id_item dex المرتبطة بالطريقة، وإلا سيتم عرض الخطأ java.lang.reflect.MalformedParametersException في وقت التشغيل.

أي أنّ method_id_item.proto_idx -> proto_id_item.parameters_off -> type_list.size يجب أن تكون هي نفسها names().length وaccessFlags().length.

بما أنّ MethodParameters يصف جميع مَعلمات الطريقة الرسمية، حتى تلك التي لم يتم تعريفها بشكل صريح أو ضِمني في رمز المصدر، قد يختلف حجم المصفوفات عن التوقيع أو غيره من معلومات البيانات الوصفية التي تستند فقط إلى المَعلمات الصريحة المعرَّفة في رمز المصدر. لن تتضمّن MethodParameters أيضًا أي معلومات حول مَعلمات المتلقّي الخاصة بتعليقات توضيحية للأنواع غير المتوفّرة في توقيع الطريقة الفعلي.

dalvik.annotation.Signature

تظهر في الفئات والحقول والطرق

يتم إرفاق تعليق توضيحي Signature بكل فئة أو حقل أو طريقة يتم تحديدها من خلال نوع أكثر تعقيدًا من النوع الذي يمكن تمثيله بواسطة type_id_item. لا يحدّد تنسيق .dex تنسيق التوقيعات، بل يهدف فقط إلى تمثيل أي توقيعات تتطلّبها اللغة المصدر لتنفيذ دلالات تلك اللغة بنجاح. وبالتالي، لا يتم عادةً تحليل التوقيعات (أو التحقّق منها) من خلال عمليات تنفيذ الأجهزة الافتراضية. ويتم ببساطة تسليم التواقيع إلى واجهات برمجة التطبيقات والأدوات ذات المستوى الأعلى (مثل أدوات تصحيح الأخطاء). لذلك، يجب كتابة أي استخدام للتوقيع بطريقة لا تفترض تلقّي توقيعات صالحة فقط، مع الحماية الصريحة من إمكانية مواجهة توقيع غير صالح من الناحية التركيبية.

بما أنّ سلاسل التوقيع تميل إلى تضمين الكثير من المحتوى المكرّر، يتم تعريف التعليق التوضيحي Signature على أنّه مصفوفة من السلاسل، حيث تشير العناصر المكرّرة بشكل طبيعي إلى البيانات الأساسية نفسها، ويتم اعتبار التوقيع هو تسلسل جميع السلاسل في المصفوفة. لا توجد قواعد بشأن كيفية تقسيم التوقيع إلى سلاسل منفصلة، فالأمر يعود بالكامل إلى الأدوات التي تنشئ ملفات .dex.

dalvik.annotation.Throws

تظهر في الطرق

يتم إرفاق تعليق توضيحي Throws بكل طريقة تم تعريفها على أنّها تعرض نوعًا واحدًا أو أكثر من أنواع الاستثناءات.