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

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

دليل الأنواع

LEB128

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

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

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

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

تنسيق الملف

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

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

• يشير file_size إلى حجم الملف المنطقي، وليس الملف الفعلي. ويمكن استخدامه للتنقّل في جميع الملفات المنطقية في الحاوية.
• يمكن أن تشير ملفات dex المنطقية إلى أي بيانات لاحقة في الحاوية (ولكن ليس البيانات السابقة). ويسمح ذلك لملفات dex بمشاركة البيانات، مثل السلاسل، مع بعضها.
• تكون جميع العناصر المرجعية نسبية إلى الملف الفعلي. لا يكون أيّ إزاحة نسبيًا للعنوان. يضمن ذلك إمكانية مشاركة الأقسام التي تحتوي على Offsets بين الملفات المنطقية.
• يضيف العنوان حقلين جديدَين لوصف حدود الحاوية. هذه عملية تحقّق إضافية من الاتساق وتسهّل نقل الرمز إلى التنسيق الجديد.
• أصبحت 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"

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

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

ملاحظة: تمت إضافة التوافق مع الإصدار 038 من التنسيق في الإصدار 8.0 من نظام التشغيل Android. أضاف الإصدار 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

تعريفات access_flags

مضمّنة في 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_annotation

تنسيق annotation_element

بنية السلسلة

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

SimpleName

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

map_list

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

تمت الإشارة إليه من header_item

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

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

تنسيق map_item

رموز النوع

string_id_item

تظهر في قسم string_ids

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

عنصر_بيانات_السلسلة

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

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

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 هو عنصر مصفوفة_مشفّرة تتطابق عناصره مع الوسيطات المقدَّمة لطريقة رابط التمهيد. الوسائط الثلاث الأولى هي:

1. معرّف طريقة يمثّل طريقة رابط التشغيل المبدئي (VALUE_METHOD_HANDLE).
2. اسم طريقة يجب أن يحلّها رابط Bootstrap (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() وغيرها من طرق 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 بكل طريقة يتم إعلانها لرمي نوع استثناء واحد أو أكثر.