تجزئة الواجهة

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

التنسيق

كل دليل جذر للحزمة (أي يتم تعيين android.hardware إلى يتم الربط بين hardware/interfaces أو vendor.foo و vendor/foo/hardware/interfaces) يجب أن يحتوي على ملف current.txt يعرض جميع ملفات واجهة HIDL التي تم إصدارها.

# current.txt files support comments starting with a '#' character
# this file, for instance, would be vendor/foo/hardware/interfaces/current.txt

# Each line has a SHA-256 hash followed by the name of an interface.
# They have been shortened in this doc for brevity but they are
# 64 characters in length in an actual current.txt file.
d4ed2f0e...995f9ec4 vendor.awesome.foo@1.0::IFoo # comments can also go here

# types.hal files are also noted in current.txt files
c84da9f5...f8ea2648 vendor.awesome.foo@1.0::types

# Multiple hashes can be in the file for the same interface. This can be used
# to note how ABI sustaining changes were made to the interface.
# For instance, here is another hash for IFoo:

# Fixes type where "FooCallback" was misspelled in comment on "FooStruct"
822998d7...74d63b8c vendor.awesome.foo@1.0::IFoo

ملاحظة: للمساعدة في تتبّع علامات التجزئة التي تأتي تفصل Google ملفات HIDL current.txt عن بعضها الأقسام: القسم الأول تم إصداره في Android 8 القسم التالي يتم إصدارها في نظام التشغيل Android 8 MR1. ننصحك بشدة باستخدام تنسيق مشابه في ملف current.txt.

تجزئة باستخدام hidl-gen

يمكنك إضافة تجزئة إلى ملف current.txt يدويًا أو من خلال باستخدام hidl-gen. يقدم مقتطف الرمز التالي أمثلة على الطلبات التي يمكنك استخدامها مع hidl-gen لإدارة ملف current.txt (تم اختصار علامات التجزئة):

hidl-gen -L hash -r vendor.awesome:vendor/awesome/hardware/interfaces -r android.hardware:hardware/interfaces -r android.hidl:system/libhidl/transport vendor.awesome.nfc@1.0::types
9626fd18...f9d298a6 vendor.awesome.nfc@1.0::types
hidl-gen -L hash -r vendor.awesome:vendor/awesome/hardware/interfaces -r android.hardware:hardware/interfaces -r android.hidl:system/libhidl/transport vendor.awesome.nfc@1.0::INfc
07ac2dc9...11e3cf57 vendor.awesome.nfc@1.0::INfc
hidl-gen -L hash -r vendor.awesome:vendor/awesome/hardware/interfaces -r android.hardware:hardware/interfaces -r android.hidl:system/libhidl/transport vendor.awesome.nfc@1.0
9626fd18...f9d298a6 vendor.awesome.nfc@1.0::types
07ac2dc9...11e3cf57 vendor.awesome.nfc@1.0::INfc
f2fe5442...72655de6 vendor.awesome.nfc@1.0::INfcClientCallback
hidl-gen -L hash -r vendor.awesome:vendor/awesome/hardware/interfaces -r android.hardware:hardware/interfaces -r android.hidl:system/libhidl/transport vendor.awesome.nfc@1.0 >> vendor/awesome/hardware/interfaces/current.txt

تحذير: لا تستبدل تجزئة واجهة إصدارة سابقًا. عند تغيير مثل هذه الواجهة، أضف تجزئة جديدة في نهاية ملف current.txt. للحصول على التفاصيل، يمكنك الرجوع إلى استقرار واجهة التطبيق الثنائية (ABI):

كل مكتبة تعريفات واجهة تم إنشاؤها بواسطة hidl-gen يتضمن تجزئات، والتي يمكن استردادها من خلال استدعاء IBase::getHashChain عند إنشاء "hidl-gen" تتحقق من الملف current.txt في الدليل الجذري حزمة HAL لمعرفة ما إذا كان قد تم تغيير HAL أم لا:

• إذا لم يتم العثور على تجزئة HAL، تُعتبر الواجهة غير منشورة (في والتطوير) وتدفق التجميع.
• وفي حال العثور على تجزئات، يتم التحقّق منها في الواجهة الحالية:
  • إذا تطابقت الواجهة مع التجزئة، تتم متابعة التجميع.
  • إذا لم تتطابق الواجهة مع تجزئة، ستتوقف عملية التحويل البرمجي لأن هذا يعني أنه يتم تغيير الواجهة التي تم إصدارها سابقًا.
    • ولإجراء تغيير للحفاظ على واجهة التطبيق الثنائية (ABI) (راجع استقرار واجهة التطبيق الثنائية (ABI))، وملف current.txt يجب تعديله قبل أن تتمكن من متابعة التجميع.
    • ويجب إجراء جميع التغييرات الأخرى من خلال ترقية بسيطة أو رئيسية للإصدار من واجهة pyplot.

ثبات واجهة التطبيق الثنائية (ABI)

يضم واجهة التطبيق الثنائية (ABI) النظام الثنائي الارتباطات/اصطلاحات الاتصال/وما إلى ذلك. في حال تغيير واجهة التطبيق الثنائية (ABI) أو واجهة برمجة التطبيقات، لن تظهر أطول تعمل مع system.img عامة تم تجميعها باستخدام من الواجهات الرسمية.

التأكد من تحديد إصدارات من الواجهات وأن واجهة التطبيق الثنائية (ABI) الثابتة هي مهمة لعدة أسباب:

• ويضمن أن يجتاز التنفيذ لديك حزمة اختبار المورّد (VTS)، التي يضعك على المسار الصحيح لإنشاء وكالات السفر عبر الإنترنت المستندة إلى إطار العمل فقط.
• وبصفتك المصنّع الأصلي للجهاز، فإنّه يمكّنك من تقديم حزمة دعم للوحة المفاتيح وسهلة الاستخدام ومتوافقة.
• وهو يساعدك على تتبُّع الواجهات التي يمكن إصدارها. ضع في اعتبارك current.txt خريطة لدليل واجهات تتيح لك الاطّلاع على سجلّ وحالة جميع الواجهات المقدَّمة في جذر الحزمة.

عند إضافة تجزئة جديدة لواجهة لها إدخال في current.txt، احرص على إضافة علامات التجزئة التي تمثّل فقط الواجهات التي تحافظ على ثبات واجهة التطبيق الثنائية (ABI). راجِع أنواع التغييرات التالية:

التغييرات مسموح بها	تغيير تعليق (ما لم يغيّر ذلك معنى طريقة) تغيير اسم مَعلمة تغيير اسم معلمة إرجاع. تغيير التعليقات التوضيحية
التغييرات غير مسموح بها	إعادة ترتيب الوسيطات والطرق وما إلى ذلك. إعادة تسمية واجهة أو نقلها إلى حزمة جديدة. تتم إعادة تسمية حزمة. إضافة طريقة/حقل هيكل/إلخ. في أي مكان على الواجهة. تمثّل هذه السمة أي ثغرة أمنية قد تعيق إمكانية مشاهدة الفيديو بلغة C++. إلخ