AIDL'deki açıklamalar

AIDL, oluşturulan saplama kodunu da etkileyen açıklamalı öğe hakkında AIDL derleyicisine ek bilgi veren açıklamaları destekler.

Sözdizimi Java'nınkine benzer:

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

Burada AnnotationName , ek açıklamanın adıdır ve AidlEntity , interface Foo , void method() veya int arg gibi bir AIDL varlığıdır. Onu takip eden varlığa bir açıklama eklenir.

Bazı ek açıklamalar, yukarıda gösterildiği gibi parantez içinde ayarlanmış bağımsız değişkenlere sahip olabilir. Argümanı olmayan ek açıklamalar parantez gerektirmez. Örneğin:

@AnnotationName AidlEntity

Bu ek açıklamalar, çok benzer görünseler de Java ek açıklamalarıyla aynı değildir. Kullanıcılar özel AIDL ek açıklamaları tanımlayamaz; ek açıklamaların tümü önceden tanımlanmıştır. Bazı ek açıklamalar yalnızca belirli bir arka ucu etkiler ve diğer arka uçlarda işlem yapılmaz. Bağlanabilecekleri farklı kısıtlamaları vardır.

Aşağıda önceden tanımlanmış AIDL ek açıklamalarının listesi bulunmaktadır:

Ek açıklamalar	Android sürümünde eklendi
nullable	7
utf8InCpp	7
VintfStability	11
UnsupportedAppUsage	10
Hide	11
Backing	11
JavaOnlyStableParcelable	11
JavaDerive	12
JavaPassthrough	12
FixedSize	12
Descriptor	12

Not: AIDL derleyicisi, yorumlarda @hide ve @deprecated ayrıştırır.

null

nullable , açıklamalı varlığın değerinin sağlanamayacağını beyan eder.

Bu açıklama yalnızca yöntem dönüş türlerine, yöntem parametrelerine ve ayrıştırılabilir alanlara eklenebilir.

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

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

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

İlkel türlere ek açıklamalar eklenemez. Aşağıdaki bir hatadır.

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

Bu ek açıklama, Java arka ucu için işlem dışıdır. Bunun nedeni, Java'da tüm ilkel olmayan türlerin başvuru yoluyla iletilmesidir, bu da null olabilir.

CPP arka @nullable T , Android 11 veya önceki sürümlerde std::unique_ptr<T> unique_ptr<T> ile ve Android 12 veya sonraki sürümlerde std::optional<T> ile eşlenir.

NDK arka @nullable T her zaman std::optional<T> ile eşlenir.

T[] veya List<T> gibi liste benzeri bir L türü için @nullable L , std::optional<std::vector<std::optional<T>>> (veya std::unique_ptr<std::vector<std::unique_ptr<T>>> ) ile eşlenir std::unique_ptr<std::vector<std::unique_ptr<T>>> Android 11 veya altı için CPP arka ucu olması durumunda).

Bu haritalamanın bir istisnası vardır. T , IBinder veya bir AIDL arabirimi olduğunda, @nullable . Başka bir deyişle, hem @nullable IBinder hem de IBinder eşit olarak android::sp<IBinder> ile eşlenir; bu, güçlü bir işaretçi olduğu için zaten null olabilir (CPP okumaları hala null yapılabilirliği zorlar, ancak tür hala android::sp<IBinder> ).

Android 13'ten başlayarak, özyinelemeli türleri modellemek için ayrıştırılabilir alanlar için @nullable(heap=true) kullanılabilir. @nullable(heap=true) yöntem parametreleri veya dönüş türleri ile kullanılamaz. Bununla açıklama eklendiğinde alan, CPP/NDK arka uçlarında yığınla ayrılmış bir başvuru std::unique_ptr<T> ile eşlenir. @nullable(heap=true) , Java arka ucunda işlem yapılmaz.

utf8InCpp

utf8InCpp , bir String CPP arka ucu için UTF8 biçiminde temsil edildiğini bildirir. Adından da anlaşılacağı gibi, ek açıklama diğer arka uçlar için bir işlem değildir. Spesifik olarak, String her zaman Java arka ucunda UTF16 ve NDK arka ucunda UTF8'dir.

Bu açıklama, dönüş değerleri, parametreler, sabit bildirimler ve ayrıştırılabilir alanlar dahil olmak üzere String türünün kullanılabileceği her yere eklenebilir.

CPP arka ucu için, @utf8InCpp String , std::string ile eşlenirken, açıklama içermeyen String , UTF16'nın kullanıldığı android::String16 ile eşlenir.

utf8InCpp ek açıklamasının varlığının, dizelerin kablo üzerinden iletilme şeklini değiştirmediğini unutmayın. Dizeler her zaman kablo üzerinden UTF16 olarak iletilir. Bir utf8InCpp açıklamalı dize, iletilmeden önce UTF16'ya dönüştürülür. Bir dize alındığında, utf8InCpp olarak açıklama eklenmişse utf8InCpp .

VintfStability

VintfStability , sistem ve satıcı etki alanlarında kullanıcı tanımlı bir türün (arayüz, parçalanabilir ve numaralandırma) kullanılabileceğini bildirir. Sistem satıcısı birlikte çalışabilirliği hakkında daha fazla bilgi için HAL'ler için AIDL'ye bakın.

Açıklama, türün imzasını değiştirmez, ancak ayarlandığında, satıcı ve sistem süreçlerinde dolaşabilmesi için türün örneği kararlı olarak işaretlenir.

Açıklama, yalnızca aşağıda gösterildiği gibi kullanıcı tanımlı tür bildirimlerine eklenebilir:

@VintfStability
interface IFoo {
    ....
}

@VintfStability
parcelable Data {
    ....
}

@VintfStability
enum Type {
    ....
}

Bir türe VintfStability ile açıklama eklendiğinde, türde başvurulan diğer türler de bu şekilde açıklanmalıdır. Aşağıdaki örnekte, Data ve IBar her ikisi de VintfStability ile açıklanmalıdır.

@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 {...}

Ek olarak, VintfStability ile açıklamalı türleri tanımlayan VintfStability dosyaları, stability özelliği "vintf" olarak ayarlanmış yalnızca aidl_interface Soong modül türü kullanılarak oluşturulabilir.

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

Desteklenmeyen Uygulama Kullanımı

UnsupportedAppUsage ek açıklaması, açıklamalı AIDL türünün, eski uygulamalar için erişilebilir olan SDK olmayan arabirimin bir parçası olduğunu belirtir. Gizli API'ler hakkında daha fazla bilgi için SDK olmayan arabirimlerdeki kısıtlamalara bakın.

UnsupportedAppUsage ek açıklaması, oluşturulan kodun davranışını etkilemez. Açıklama, yalnızca oluşturulan Java sınıfına aynı adı taşıyan Java ek açıklamasıyla açıklama ekler.

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

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

Bu, Java dışı arka uçlar için bir işlem değildir.

destek

Backing açıklaması, bir AIDL numaralandırma türünün depolama türünü belirtir.

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

CPP arka ucunda, yukarıdaki, int32_t türünde bir C++ enum sınıfı yayar.

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

Açıklama atlanırsa, type byte olduğu varsayılır ve bu, CPP arka ucu için int8_t ile eşlenir.

type bağımsız değişkeni yalnızca aşağıdaki integral türlerine ayarlanabilir:

• byte (8 bit genişliğinde)
• int (32 bit genişliğinde)
• long (64 bit genişliğinde)

JavaOnlyStableParcelable

JavaOnlyStableParcelable , ayrıştırılabilir bir bildirimi (tanım değil) kararlı olarak işaretler, böylece diğer kararlı AIDL türlerinden başvurulabilir.

Kararlı AIDL, tüm kullanıcı tanımlı türlerin kararlı olmasını gerektirir. Parçalanabilirler için kararlı olmak, alanlarının AIDL kaynak dosyasında açıkça tanımlanmasını gerektirir.

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
}

Ayrıştırılabilir yapılandırılmamışsa (veya henüz bildirilmişse), başvuru yapılamaz.

parcelable Data; // Data is NOT a structured parcelable

parcelable AnotherData {
    Data d; // Error
}

JavaOnlyStableParcelable , başvurduğunuz ayrıştırılabilir öğe Android SDK'nın bir parçası olarak zaten güvenli bir şekilde mevcut olduğunda denetimi geçersiz kılmanıza olanak tanır.

@JavaOnlyStableParcelable
parcelable Data;

parcelable AnotherData {
    Data d; // OK
}

JavaDerive

JavaDerive , Java arka ucundaki ayrıştırılabilir türler için otomatik olarak yöntemler oluşturur.

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

Açıklama, neyin üretileceğini kontrol etmek için ek parametreler gerektirir. Desteklenen parametreler şunlardır:

• equals=true , equals ve hashCode yöntemlerini üretir.
• toString=true , türün ve alanların adını yazdıran toString yöntemini oluşturur. Örneğin: Data{number: 42, str: foo}

JavaVarsayılan

Android 13'te eklenen JavaDefault , varsayılan uygulama sürüm oluşturma desteğinin oluşturulup oluşturulmayacağını kontrol eder ( setDefaultImpl için). Bu destek artık yerden tasarruf etmek için varsayılan olarak oluşturulmaz.

JavaGeçiş

JavaPassthrough , oluşturulan Java API'sinin isteğe bağlı bir Java ek açıklamasıyla açıklanmasını sağlar.

AIDL'de aşağıdaki açıklamalar

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

olmak

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

oluşturulan Java kodunda.

annotation parametresinin değeri doğrudan yayınlanır. AIDL derleyicisi parametrenin değerine bakmaz. Java düzeyinde herhangi bir sözdizimi hatası varsa, AIDL derleyicisi tarafından değil, Java derleyicisi tarafından yakalanır.

Bu açıklama, herhangi bir AIDL varlığına eklenebilir. Bu ek açıklama, Java dışı arka uçlar için bir işlem değildir.

Sabit Boyut

FixedSize , yapılandırılmış bir ayrıştırılabilir öğeyi sabit boyut olarak işaretler. İşaretlendikten sonra, ayrıştırılabilir öğeye yeni alanların eklenmesine izin verilmeyecektir. Ayrıştırılabilir öğenin tüm alanları, ilkel türler, numaralandırmalar, sabit boyutlu diziler ve FixedSize ile işaretlenmiş diğer parsellenebilirler de dahil olmak üzere sabit boyutlu türler olmalıdır.

Bu, farklı bitlikler arasında herhangi bir garanti sağlamaz ve karma bitlik iletişim için güvenilmemelidir.

tanımlayıcı

Descriptor , bir arabirimin arabirim tanımlayıcısını zorla belirtir.

package android.foo;

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

Yukarıdaki arayüzün tanımlayıcısı android.bar.IWorld şeklindedir. Descriptor ek açıklaması eksikse, tanımlayıcı android.foo.IHello olacaktır.

Bu, önceden yayınlanmış bir arabirimi yeniden adlandırmak için kullanışlıdır. Yeniden adlandırılan arayüzün tanımlayıcısını, yeniden adlandırmadan önce arayüzün tanımlayıcısıyla aynı yapmak, iki arayüzün birbiriyle konuşmasına izin verir.

@yorumlarda gizle

AIDL derleyicisi yorumlarda @hide tanır ve metalava'nın alınması için bunu Java çıktısına iletir. Bu yorum, Android derleme sisteminin AIDL API'lerinin SDK API'leri olmadığını bilmesini sağlar.

@yorumlarda kullanımdan kaldırıldı

AIDL derleyicisi, artık kullanılmaması gereken bir AIDL varlığını tanımlamak için yorumlarda @deprecated etiketini tanır.

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

Her arka uç, kullanımdan kaldırılan varlıkları, kullanımdan kaldırılan varlıklara atıfta bulunursa müşteri kodunun uyarılması için arka uca özel bir açıklama/öznitelikle işaretler. Örneğin, @Deprecated ek açıklaması ve @deprecated etiketi, Java tarafından oluşturulan koda eklenir.