حاشیه نویسی در AIDL

AIDL از حاشیه‌نویسی‌هایی پشتیبانی می‌کند که به کامپایلر AIDL اطلاعات اضافی در مورد عنصر حاشیه‌نویسی شده می‌دهند، که این اطلاعات بر کد ناقص تولید شده نیز تأثیر می‌گذارد.

سینتکس آن مشابه جاوا است:

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

در اینجا، AnnotationName نام حاشیه‌نویسی است و AidlEntity یک موجودیت AIDL مانند interface Foo ، void method() یا int arg است. یک حاشیه‌نویسی به موجودیتی که پس از آن می‌آید، پیوست می‌شود.

همانطور که در مثال قبلی نشان داده شد، برخی از حاشیه‌نویسی‌ها می‌توانند آرگومان‌هایی داشته باشند که درون پرانتز قرار می‌گیرند. حاشیه‌نویس‌هایی که آرگومان ندارند، نیازی به پرانتز ندارند. برای مثال:

@AnnotationName AidlEntity

این حاشیه‌نویسی‌ها با حاشیه‌نویسی‌های جاوا یکسان نیستند، اگرچه شبیه به هم به نظر می‌رسند. همه حاشیه‌نویسی‌ها از پیش تعریف شده‌اند و محدودیت‌هایی برای محل الصاق آنها وجود دارد. برخی از حاشیه‌نویسی‌ها فقط روی یک backend خاص تأثیر می‌گذارند و در backendهای دیگر غیرفعال هستند.

در اینجا لیستی از حاشیه‌نویسی‌های از پیش تعریف‌شده‌ی AIDL آمده است:

حاشیه‌نویسی‌ها در نسخه اندروید اضافه شد
nullable ۷
utf8InCpp ۷
VintfStability ۱۱
UnsupportedAppUsage ۱۰
Hide ۱۱
Backing ۱۱
NdkOnlyStableParcelable ۱۴
JavaOnlyStableParcelable ۱۱
JavaDerive ۱۲
JavaPassthrough ۱۲
FixedSize ۱۲
Descriptor ۱۲

قابل تهی‌سازی

nullable اعلام می‌کند که مقدار موجودیت حاشیه‌نویسی شده می‌تواند تهی (null) باشد.

شما می‌توانید این حاشیه‌نویسی را فقط به انواع بازگشتی متد، پارامترهای متد و فیلدهای parcelable پیوست کنید:

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

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

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

حاشیه‌نویسی‌ها را نمی‌توان به انواع اولیه (primitive types) پیوست کرد. خطای زیر رخ می‌دهد:

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

این حاشیه‌نویسی برای بک‌اند جاوا نیازی به عملیات ندارد. در جاوا، تمام انواع غیراولیه از طریق ارجاع ارسال می‌شوند که می‌تواند null باشد.

در بک‌اند CPP، @nullable T در اندروید ۱۱ یا پایین‌تر به std::unique_ptr<T> و در اندروید ۱۲ یا بالاتر به std::optional<T> نگاشت می‌شود.

در بک‌اند NDK، @nullable T به std::optional<T> نگاشت می‌شود.

در بک‌اند Rust، @nullable T به Option<T> نگاشت می‌شود.

برای یک نوع L لیست مانند مانند T[] یا List<T> ، @nullable L به std::optional<std::vector<std::optional<T>>> (یا std::unique_ptr<std::vector<std::unique_ptr<T>>> در مورد بک‌اند CPP برای اندروید ۱۱ یا پایین‌تر) نگاشت می‌شود.

یک استثنا برای این نگاشت وجود دارد. وقتی T برابر IBinder یا یک رابط AIDL باشد، @nullable برای همه backendها به جز Rust غیرفعال است. به عبارت دیگر، هم @nullable IBinder و هم IBinder به طور یکسان به android::sp<IBinder> نگاشت می‌شوند، که از قبل nullable است زیرا یک اشاره‌گر قوی است (CPP reads همچنان nullability را اعمال می‌کند، اما نوع آن هنوز android::sp<IBinder> است). در Rust، این نوع‌ها فقط در صورتی nullable هستند که با @nullable حاشیه‌نویسی شوند. در صورت حاشیه‌نویسی، به Option<T> نگاشت می‌شوند.

از اندروید ۱۳ به بعد، می‌توان از @nullable(heap=true) برای فیلدهای parcelable جهت مدل‌سازی انواع بازگشتی استفاده کرد. @nullable(heap=true) را نمی‌توان با پارامترهای متد یا انواع بازگشتی استفاده کرد. هنگامی که با آن حاشیه‌نویسی می‌شود، فیلد به یک مرجع تخصیص‌یافته std::unique_ptr<T> heap در cpp و ndk backend نگاشت می‌شود. @nullable(heap=true) در جاوا backend بدون عملیات است.

utf8InCpp

utf8InCpp اعلام می‌کند که String برای backend CPP با فرمت UTF8 نمایش داده می‌شود. همانطور که از نامش پیداست، این حاشیه‌نویسی برای سایر backendها قابل استفاده نیست. به طور خاص، String همیشه در backend جاوا UTF16 و در backend NDK UTF8 است.

این حاشیه‌نویسی می‌تواند در هر جایی که نوع String قابل استفاده است، از جمله مقادیر بازگشتی، پارامترها، اعلان‌های ثابت و فیلدهای قابل تقسیم‌بندی، پیوست شود.

برای بک‌اند CPP، @utf8InCpp String در AIDL به std::string نگاشت می‌شود، که در آن String بدون حاشیه‌نویسی به android::String16 نگاشت می‌شود که در آن از UTF16 استفاده شده است.

پایداری وینت‌اف

VintfStability اعلام می‌کند که یک نوع تعریف‌شده توسط کاربر (interface، parcelable و enum) می‌تواند در دامنه‌های سیستم و فروشنده استفاده شود. برای اطلاعات بیشتر در مورد قابلیت همکاری سیستم-فروشنده، به AIDL برای HALها مراجعه کنید.

این حاشیه‌نویسی، امضای نوع را تغییر نمی‌دهد، اما وقتی تنظیم می‌شود، نمونه‌ی آن نوع به عنوان پایدار علامت‌گذاری می‌شود تا بتواند در فرآیندهای فروشنده و سیستم حرکت کند.

این حاشیه‌نویسی فقط می‌تواند به اعلان‌های نوع تعریف‌شده توسط کاربر، همانطور که در اینجا نشان داده شده است، پیوست شود:

@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 Soong ساخته شوند، و ویژگی stability روی vintf تنظیم شود:

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

استفاده از برنامه پشتیبانی نشده

حاشیه‌نویسی UnsupportedAppUsage نشان می‌دهد که نوع AIDL حاشیه‌نویسی‌شده بخشی از رابط غیر SDK است که برای برنامه‌های قدیمی قابل دسترسی بوده است. برای اطلاعات بیشتر در مورد APIهای پنهان ، به محدودیت‌های رابط‌های غیر SDK مراجعه کنید.

حاشیه‌نویسی UnsupportedAppUsage بر رفتار کد تولید شده تأثیری ندارد. این حاشیه‌نویسی فقط کلاس جاوای تولید شده را با حاشیه‌نویسی جاوا با همین نام حاشیه‌نویسی می‌کند:

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

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

این یک گزینه‌ی ممنوعه برای بک‌اندهای غیر جاوا است.

حاشیه‌نویسی پشتیبان

حاشیه‌نویسی Backing نوع ذخیره‌سازی یک نوع شمارشی AIDL را مشخص می‌کند:

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

در پشت صحنه CPP، این یک کلاس شمارشی C++ از نوع int32_t منتشر می‌کند: 

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

اگر حاشیه‌نویسی حذف شود، type byte فرض می‌شود که برای backend CPP به int8_t نگاشت می‌شود.

آرگومان type را فقط می‌توان روی انواع صحیح زیر تنظیم کرد:

  • byte (عرض ۸ بیت)
  • int (با پهنای ۳۲ بیت)
  • long (با عرض ۶۴ بیت)

NdkOnlyStableParcelable

NdkOnlyStableParcelable یک اعلان parcelable (نه تعریف) را به عنوان پایدار علامت‌گذاری می‌کند تا بتوان از سایر انواع پایدار AIDL به آن ارجاع داد. این مانند JavaOnlyStableParcelable است، اما NdkOnlyStableParcelable یک اعلان parcelable را به جای جاوا، برای backend NDK به عنوان پایدار علامت‌گذاری می‌کند.

برای استفاده از این بسته:

  • شما باید ndk_header را مشخص کنید.
  • شما باید یک کتابخانه NDK داشته باشید که parcelable را مشخص کند و کتابخانه باید در کتابخانه کامپایل شود. برای مثال، در سیستم ساخت اصلی روی یک ماژول cc_* ، از static_libs یا shared_libs استفاده کنید. برای aidl_interface ، کتابخانه را در زیر additional_shared_libraries در Android.bp اضافه کنید.

JavaOnlyStableParcelable

JavaOnlyStableParcelable یک اعلان parcelable (نه تعریف) را به عنوان پایدار علامت‌گذاری می‌کند تا بتوان از سایر انواع AIDL پایدار به آن ارجاع داد.

AIDL پایدار مستلزم آن است که تمام انواع تعریف‌شده توسط کاربر پایدار باشند. برای parcelableها، پایدار بودن مستلزم آن است که فیلدهای آن به صراحت در فایل منبع 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 بدون ساختار باشد (یا فقط تعریف شده باشد)، نمی‌توان به آن ارجاع داد: 

parcelable Data; // Data is NOT a structured parcelable

parcelable AnotherData {
    Data d; // Error
}

JavaOnlyStableParcelable به شما امکان می‌دهد تا زمانی که parcelable مورد ارجاع شما به عنوان بخشی از SDK اندروید به طور ایمن در دسترس است، بررسی را لغو کنید: 

@JavaOnlyStableParcelable
parcelable Data;

parcelable AnotherData {
    Data d; // OK
}

جاوا درایو

JavaDerive به طور خودکار متدهایی را برای انواع parcelable در backend جاوا تولید می‌کند: 

@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 که در اندروید ۱۳ اضافه شده است، کنترل می‌کند که آیا پشتیبانی از نسخه‌بندی پیاده‌سازی پیش‌فرض (برای setDefaultImpl ) ایجاد می‌شود یا خیر. این پشتیبانی دیگر به طور پیش‌فرض ایجاد نمی‌شود تا در فضا صرفه‌جویی شود.

جاوا پس‌راو

JavaPassthrough به API جاوای تولید شده اجازه می‌دهد تا با یک حاشیه‌نویسی دلخواه جاوا حاشیه‌نویسی شود.

این حاشیه‌نویسی‌ها در 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)

مقدار پارامتر annotation مستقیماً منتشر می‌شود. کامپایلر AIDL مقدار پارامتر را بررسی نمی‌کند. اگر هرگونه خطای نحوی در سطح جاوا وجود داشته باشد، توسط کامپایلر AIDL شناسایی نمی‌شود، بلکه توسط کامپایلر جاوا شناسایی می‌شود.

این حاشیه‌نویسی می‌تواند به هر موجودیت AIDL متصل شود. این حاشیه‌نویسی برای backend های غیر جاوایی، گزینه‌ای نیست.

RustDeriv

RustDerive به طور خودکار ویژگی‌هایی را برای انواع Rust تولید شده پیاده‌سازی می‌کند.

این حاشیه‌نویسی به پارامترهای اضافی برای کنترل آنچه تولید می‌شود نیاز دارد. پارامترهای پشتیبانی‌شده عبارتند از:

  • Copy=true
  • Clone=true
  • Ord=true
  • PartialOrd=true
  • Eq=true
  • PartialEq=true
  • Hash=true

برای توضیحات این ویژگی‌ها، به مستندات Rust مراجعه کنید.

اندازه ثابت

FixedSize یک parcelable ساختاریافته را به عنوان اندازه ثابت علامت‌گذاری می‌کند. پس از علامت‌گذاری، نمی‌توانید فیلدهای جدیدی به parcelable اضافه کنید. همه فیلدهای parcelable باید از نوع با اندازه ثابت باشند، از جمله انواع اولیه، enumها، آرایه‌های با اندازه ثابت و سایر parcelableهای علامت‌گذاری شده با FixedSize .

توصیفگر

Descriptor به اجبار توصیفگر رابط یک رابط را مشخص می‌کند: 

package android.foo;

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

توصیفگر این رابط android.bar.IWorld است. اگر حاشیه‌نویسی Descriptor وجود نداشته باشد، توصیفگر android.foo.IHello خواهد بود.

این برای تغییر نام یک رابط کاربری که قبلاً منتشر شده است مفید است. یکسان کردن توصیف‌گر رابط کاربری تغییر نام داده شده با توصیف‌گر رابط کاربری قبل از تغییر نام، به دو رابط کاربری اجازه می‌دهد تا با یکدیگر ارتباط برقرار کنند.

@hide در نظرات

کامپایلر AIDL، @hide در کامنت‌ها تشخیص می‌دهد و آن را به خروجی جاوا ارسال می‌کند تا توسط metalava دریافت شود. این کامنت به سیستم ساخت اندروید کمک می‌کند تا تشخیص دهد که APIهای AIDL، APIهای SDK نیستند.

@deprecated در نظرات

کامپایلر AIDL، @deprecated در نظرات به عنوان برچسبی برای شناسایی یک موجودیت AIDL که دیگر نباید استفاده شود، تشخیص می‌دهد: 

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

هر backend موجودیت‌های منسوخ‌شده را با یک حاشیه‌نویسی یا ویژگی مختص backend علامت‌گذاری می‌کند تا در صورت ارجاع کد کلاینت به موجودیت‌های منسوخ‌شده، به آن هشدار داده شود. برای مثال، حاشیه‌نویسی @Deprecated و تگ @deprecated به کد تولید شده توسط جاوا پیوست شده‌اند.