التعليقات التوضيحية في AIDL

يدعم AIDL التعليقات التوضيحية التي تمنح مترجم AIDL معلومات إضافية حول العنصر الذي تمت إضافة تعليقات توضيحية له، والذي يؤثر أيضًا في كود التعطل الذي تم إنشاؤه.

تشبه بناء الجملة بنية Java:

@AnnotationName(argument1=value, argument2=value) AidlEntity

هنا، يمثل AnnotationName اسم التعليق التوضيحي، وAidlEntity هو كيان AIDL، مثل interface Foo أو void method() أو int arg إنّ التعليق التوضيحي مرفق بالكيان الذي يليه.

يمكن أن تحتوي بعض التعليقات التوضيحية على وسيطات داخل الأقواس، كما هو موضح أعلاه. لا تحتاج التعليقات التوضيحية التي لا تحتوي على وسيطة إلى الأقواس. مثلاً:

@AnnotationName AidlEntity

هذه التعليقات التوضيحية ليست مماثلة للغة Java على الرغم من أنها تبدو متشابهة إلى حد كبير. لا يمكن للمستخدمين تحديد لغة AIDL مخصّصة التعليقات التوضيحية التعليقات التوضيحية كلها محددة مسبقًا. تؤثر بعض التعليقات التوضيحية فقط خلفية معينة ولا تعمل في الخلفيات الأخرى. لديهم فرق والقيود التي يمكن إرفاقها بها.

في ما يلي قائمة بتعليقات AIDL التوضيحية المحدَّدة مسبقًا:

التعليقات التوضيحية	تمت الإضافة في إصدار Android
nullable	7
utf8InCpp	7
VintfStability	11
UnsupportedAppUsage	10
Hide	11
Backing	11
NdkOnlyStableParcelable	14
JavaOnlyStableParcelable	11
JavaDerive	12
JavaPassthrough	12
FixedSize	12
Descriptor	12

قابلة للقيم الفارغة

يعلن nullable أنّه قد لا يتم تقديم قيمة العنصر الذي تم التعليق عليه.

ويمكن إرفاق هذا التعليق التوضيحي فقط بأنواع إرجاع الطريقة أو معلمات الطريقة والحقول القابلة للقياس والمساواة بين نقاط الاتصال.

interface IFoo {
    // method return types
    @nullable Data method();

    // method parameters
    void method2(in @nullable Data d);
}

parcelable Data {
    // parcelable fields
    @nullable Data d;
}

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

void method(in @nullable int a); // int is a primitive type

هذا التعليق التوضيحي ليس جاهزًا بالنسبة إلى الواجهة الخلفية لـ Java. هذا لأنه في Java، يتم تمرير الأنواع غير الأولية بالإشارة، والتي قد تكون null.

في خلفية CPP، يرتبط @nullable T بـ std::unique_ptr<T> في Android. 11 أو أقل، وإلى std::optional<T> في Android 12 أو أعلى.

في الواجهة الخلفية NDK، يتم ربط @nullable T دائمًا بـ std::optional<T>.

بالنسبة إلى النوع L الذي يشبه القائمة مثل T[] أو List<T>، يتم الربط من خلال @nullable L std::optional<std::vector<std::optional<T>>> (أو std::unique_ptr<std::vector<std::unique_ptr<T>>> في حال استخدام الواجهة الخلفية لخدمة CPP لنظام التشغيل Android 11 أو الإصدارات الأقدم).

هناك استثناء لهذا التعيين. عندما T هي IBinder أو واجهة AIDL، إذن @nullable ليس متاحًا. بعبارة أخرى، يتم ربط @nullable IBinder وIBinder بالتساوي بـ android::sp<IBinder>، والتي يمكن أن تكون القيمة فارغة لأنه يمثّل مؤشرًا قويًا (تظل بيانات صفحة المنتج في خدمة مقارنة الأسعار) فرض قابلية القيم الفارغة، ولكن لا يزال النوع android::sp<IBinder>).

بدءًا من نظام التشغيل Android 13، يمكن استخدام "@nullable(heap=true)" لتنفيذ الحقول القابلة للتحسين لوضع نماذج للأنواع التكرارية. يتعذّر استخدام @nullable(heap=true) مع معلمات الطريقة أو أنواع الإرجاع. عند التعليق عليه، يتم وضع تم تعيينه إلى مرجع مخصّص لعناصر متعدّدة في الحزمة std::unique_ptr<T> ضمن صفحة CPP/NDK. والخلفيات. ميزة "@nullable(heap=true)" ليست عملية في واجهة Java الخلفية.

utf8InCpp

يعلن utf8InCpp أنّ String تم تمثيله بتنسيق UTF8 في صفحة المنتج في خدمة مقارنة الأسعار (CPP). الخلفية. وكما يشير اسمه، لا يمكن استخدام التعليق التوضيحي في الخلفيات الأخرى. على وجه التحديد، يكون String دائمًا بترميز UTF16 في الواجهة الخلفية لـ Java وUTF-8 في NDK الخلفية.

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

بالنسبة إلى الواجهة الخلفية CPP، يرتبط @utf8InCpp String في AIDL بـ std::string، في حين يتم ربط يتم ربط String بدون التعليق التوضيحي بـ android::String16 حيث يتمّ استخدام UTF16.

يُرجى العِلم أنّ توفّر التعليق التوضيحي utf8InCpp لا يغيّر طريقة يتم نقل السلاسل عبر السلك. يتم دائمًا نقل السلاسل بتنسيق UTF16. عبر السلك. يتم تحويل سلسلة utf8InCpp التي تتضمّن تعليقات توضيحية إلى UTF16 قبل أن يتم تحويلها نقل البيانات. عند استلام سلسلة، يتم تحويلها من UTF16 إلى UTF8 إذا كانت تمت إضافة تعليق توضيحي باسم utf8InCpp.

ثبات VintfStability

VintfStability تشير إلى أن نوعًا من تحديد المستخدم (واجهة، أو قطعة، والتعداد) عبر نطاقات النظام والمورِّد. عرض AIDL لـ HALs لمزيد من المعلومات حول إمكانية التشغيل البيني لموردي النظام.

لا يغيّر التعليق التوضيحي توقيع النوع، لكن عند تعيينه، ويتم وضع علامة على مثيل النوع كثابت بحيث يمكن الانتقال عبر عمليات البائع والنظام.

لا يمكن إرفاق التعليق التوضيحي إلا بإعلانات الأنواع التي يحددها المستخدم كما هو موضح هنا:

@VintfStability
interface IFoo {
    ....
}

@VintfStability
parcelable Data {
    ....
}

@VintfStability
enum Type {
    ....
}

عند إضافة تعليقات توضيحية إلى نوع باستخدام VintfStability، أو أي نوع آخر المشار إليها في النوع كما ينبغي أن تتم إضافة تعليقات توضيحية إليها كذلك. في ما يلي مثال، يجب إضافة تعليقات توضيحية إلى كل من Data وIBar باستخدام VintfStability.

@VintfStability
interface IFoo {
    void doSomething(in IBar b); // references IBar
    void doAnother(in Data d); // references Data
}

@VintfStability // required
interface IBar {...}

@VintfStability // required
parcelable Data {...}

بالإضافة إلى ذلك، إنّ ملفات AIDL التي تحدّد الأنواع التي تمت إضافة تعليقات توضيحية إليها باستخدام VintfStability لا يمكن إنشاؤها إلا باستخدام نوع وحدة "سونغ" aidl_interface، مع تم ضبط الخاصية "stability" على "vintf".

aidl_interface {
    name: "my_interface",
    srcs: [...],
    stability: "vintf",
}

استخدام غير متوافق مع التطبيق

يشير التعليق التوضيحي UnsupportedAppUsage إلى أنّ نوع AIDL الذي يتضمّن تعليقات توضيحية هو جزء من الواجهة غير المستندة إلى حزمة تطوير البرامج (SDK) التي كانت متاحة للتطبيقات القديمة. يُرجى الاطّلاع على المقالة القيود المفروضة على المنتجات غير المستندة إلى حزمة تطوير البرامج (SDK). الواجهات لمزيد من المعلومات عن واجهات برمجة التطبيقات المخفية.

لا يؤثّر تعليق UnsupportedAppUsage التوضيحي في سلوك التعليمات البرمجية التي تم إنشاؤها. لا يضيف التعليق التوضيحي سوى تعليقات توضيحية إلى فئة Java التي تم إنشاؤها تعليق توضيحي لـ Java يحمل الاسم نفسه.

// in AIDL
@UnsupportedAppUsage
interface IFoo {...}

// in Java
@android.compat.annotation.UnsupportedAppUsage
public interface IFoo {...}

لا يمكن تنفيذ هذا الإجراء على الخلفيات التي لا تستخدم JavaScript.

دعامة

يحدّد التعليق التوضيحي Backing نوع التخزين لنوع تعداد AIDL.

@Backing(type="int")
enum Color { RED, BLUE, }

في خلفية CPP، ينتج عن ذلك فئة تعداد C++ من النوع int32_t.

enum class Color : int32_t {
    RED = 0,
    BLUE = 1,
}

في حال إسقاط التعليق التوضيحي، يُفترض أن تكون السمة type هي byte، أي الربط إلى int8_t للواجهة الخلفية لخدمة CPP.

يمكن ضبط الوسيطة type على أنواع التكامل التالية فقط:

• byte (عرض 8 بت)
• int (عرض 32 بت)
• long (عرض 64 بت)

شهادة NdkOnlyStableParcelable

يحدّد NdkOnlyStableParcelable تعريفًا قطعيًا (وليس تعريفًا) ثابتة بحيث يمكن الرجوع إليها من أنواع AIDL الأخرى الثابتة. هذا النمط يشبه JavaOnlyStableParcelable، لكن تشير السمة NdkOnlyStableParcelable إلى إعلان قابل للتسليم على أنّه ثابت في NDK. الخلفية بدلاً من Java.

لاستخدام هذا القِطع:

• يجب تحديد ndk_header.
• يجب أن تكون لديك مكتبة NDK تحدد العنصر المطلوب ويجب أن يتم تجميعها في المكتبة. على سبيل المثال، في نظام الإصدار الأساسي على وحدة cc_*، يمكنك استخدام static_libs أو shared_libs. بالنسبة إلى aidl_interface، يمكنك إضافة المكتبة ضمن additional_shared_libraries في Android.bp.

JavaOnlyStableParcelable

يحدّد JavaOnlyStableParcelable تعريفًا قطعيًا (وليس تعريفًا) ثابتة بحيث يمكن الرجوع إليها من أنواع AIDL الأخرى الثابتة.

تتطلب لغة AIDL الثابتة أن تكون جميع الأنواع التي يحدّدها المستخدم ثابتة. بالنسبة عناصر متغيرة، يتطلب استقرارها أن يتم وصف حقولها بشكل صريح ملف مصدر AIDL

parcelable Data { // Data is a structured parcelable.
    int x;
    int y;
}

parcelable AnotherData { // AnotherData is also a structured parcelable
    Data d; // OK, because Data is a structured parcelable
}

إذا كان العنصر غير منظم (أو تم تعريفه للتو)، فلا يمكن المشار إليها.

parcelable Data; // Data is NOT a structured parcelable

parcelable AnotherData {
    Data d; // Error
}

يتيح لك JavaOnlyStableParcelable إلغاء عملية التحقّق عند قطع الطرد الذي تشير إليه متوفر مسبقًا كجزء من حزمة تطوير البرامج (SDK) لنظام التشغيل Android.

@JavaOnlyStableParcelable
parcelable Data;

parcelable AnotherData {
    Data d; // OK
}

لغة JavaDerive

تنشئ ميزة JavaDerive تلقائيًا طرق لأنواع العناصر في خريطة الموقع خلفية Java.

@JavaDerive(equals = true, toString = true)
parcelable Data {
  int number;
  String str;
}

يتطلب التعليق التوضيحي معلمات إضافية للتحكم في تحديد العناصر الإنشاء. المعلمات المتاحة هي:

• تُنشئ equals=true طريقة equals وhashCode.
• تنشئ toString=true طريقة toString تطبع اسم النوع. والحقول. مثلاً: Data{number: 42, str: foo}

JavaDefault

يتحكّم تطبيق JavaDefault، المُضاف في Android 13، في ما إذا كان يتم إنشاء الدعم التلقائي لنُسخ التنفيذ ( setDefaultImpl). لم يعد يتم إنشاء هذا الدعم بشكل افتراضي من أجل لتوفير مساحة.

مرور Java

يسمح JavaPassthrough بإضافة تعليقات توضيحية إلى واجهة برمجة تطبيقات Java التي تم إنشاؤها عشوائيًا. تعليق توضيحي لـ Java.

التعليقات التوضيحية التالية في لغة AIDL

@JavaPassthrough(annotation="@android.annotation.Alice")
@JavaPassthrough(annotation="@com.android.Alice(arg=com.android.Alice.Value.A)")

يصبح

@android.annotation.Alice
@com.android.Alice(arg=com.android.Alice.Value.A)

في رمز Java الذي تم إنشاؤه.

تنبعث قيمة المَعلمة annotation مباشرةً. دورة AIDL لا يأخذ برنامج التجميع في الاعتبار قيمة المعلمة. إذا كان هناك أي لن يكتشف المحول البرمجي لـ AIDL هذا الخطأ في بناء الجملة على مستوى Java، ولكن من خلال المحول البرمجي لـ Java.

يمكن إرفاق هذا التعليق التوضيحي بأي كيان AIDL. هذا التعليق التوضيحي لا يمكن تنفيذه للخلفيات التي لا تستخدم لغة Java.

حجم ثابت

يضع FixedSize علامة على قطعة إعلانية منظَّمة على أنّها ذات حجم ثابت. بمجرد وضع علامة عليه، لن يُسمح بإضافة حقول جديدة إليها. جميع حقول يجب أيضًا أن يكون العنصر الثابت أنواعًا ذات أحجام ثابتة، بما في ذلك الأنواع الأولية. والتعدادات والصفائف ذات الحجم الثابت وغيرها من العناصر التي تم وضع علامة FixedSize عليها.

وهذا لا يوفر أي ضمان عبر البتات المختلفة ولا ينبغي التي يعتمد عليها في التواصل متعدد السرعة.

الواصف

تحدد السمة Descriptor واصف الواجهة للواجهة بقوة.

package android.foo;

@Descriptor(value="android.bar.IWorld")
interface IHello {...}

واصف هذه الواجهة هو android.bar.IWorld. إذا كانت التعليق التوضيحي Descriptor غير متوفّر، سيكون الواصف android.foo.IHello

يفيد ذلك في إعادة تسمية واجهة منشورة من قبل. واصف الواجهة التي تمت إعادة تسميتها تمامًا مثل واصف الواجهة قبل إعادة التسمية، يسمح للواجهتين بالتحدث مع بعضهما.

إخفاء @ في التعليقات

يتعرف المحول البرمجي لـ AIDL على @hide في التعليقات ويمرره إلى إخراج Java لـ Metalava للاستلام. يضمن هذا التعليق تحديث نظام التشغيل أن واجهة برمجة تطبيقات AIDL ليست واجهات برمجة تطبيقات لحزمة تطوير البرامج (SDK).

@deprecated في التعليقات

يتعرّف برنامج تحويل النص إلى كلام (AIDL) على @deprecated في التعليقات كعلامة لتحديد كيان AIDL يجب عدم استخدامه بعد الآن

interface IFoo {
  /** @deprecated use bar() instead */
  void foo();
  void bar();
}

تميّز كل واجهة خلفية عناصر متوقّفة نهائيًا باستخدام تعليق توضيحي أو بحيث يتم تحذير رمز العميل إذا أشار إلى الموقع والكيانات. على سبيل المثال، التعليق التوضيحي @Deprecated و@deprecated بالتعليمات البرمجية التي تم إنشاؤها في Java.