AIDL'deki ek açıklamalar

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

Söz dizimi Java'ya benzer:

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

Burada AnnotationName ek açıklamanın adı, AidlEntity ise interface Foo, void method() veya int arg gibi bir AIDL öğesidir. Bunu takip eden öğeye bir ek açıklama eklenir.

Bazı ek açıklamalarda, yukarıda gösterildiği gibi parantez içinde argümanlar bulunabilir. Bağımsız değişkeni olmayan ek açıklamalarda parantez gerekmez. Örnek:

@AnnotationName AidlEntity

Bu ek açıklamalar, Java ek açıklamalarıyla çok benzer görünse de 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 uçta etkilidir ve diğer arka uçlarda işlem yapmaz. Bu öğelerin eklenebileceği yerlerle ilgili farklı kısıtlamalar vardır.

Önceden tanımlanmış AIDL ek açıklamalarının listesi aşağıda verilmiştir:

boş değer atanabilir

nullable, açıklama eklenen öğenin değerinin sağlanmayabileceğini belirtir.

Bu ek açıklama yalnızca yöntem dönüş türlerine, yöntem parametrelerine ve paketlenebilir 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;
}

Notlar ilkel türlere eklenemez. Aşağıdaki hata oluştu.

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

Bu ek açıklama, Java arka ucu için işlemsizdir. Bunun nedeni, Java'da ilkel olmayan tüm türlerin referansla iletilmesidir. Bu referans null olabilir.

CPP arka ucunda @nullable T, Android 11 veya daha eski sürümlerde std::unique_ptr<T>, Android 12 veya daha yeni sürümlerde ise std::optional<T> ile eşlenir.

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

Rust arka ucunda @nullable T her zaman Option<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>>> ile eşlenir (veya Android 11 veya önceki sürümler için PBM arka ucu durumunda std::unique_ptr<std::vector<std::unique_ptr<T>>> ile eşlenir).

Bu eşlemenin bir istisnası vardır. T IBinder veya bir AIDL arayüzü olduğunda @nullable, Rust hariç tüm arka uçlarda işlem yapmaz. Diğer bir deyişle, hem @nullable IBinder hem de IBinder, güçlü bir işaretçi olduğu için zaten boş olan android::sp<IBinder> ile eşittir (PBM okumaları yine de nulllanabilirliği zorunlu kılar, ancak tür yine de android::sp<IBinder>'dir). Rust'ta, bu türler yalnızca @nullable ek açıklaması olduğunda nullable olur. Açıklama eklenmişse Option<T> ile eşlenir.

Android 13'ten itibaren @nullable(heap=true), yinelemeli türleri modellemek amacıyla ayrıştırılabilir alanlar için kullanılabilir. @nullable(heap=true), yöntem parametreleri veya döndürülen türlerle kullanılamaz. Bu notla ek açıklama eklendiğinde alan, CPP/NDK arka uçlarında yığına ayrılmış bir referans std::unique_ptr<T> ile eşlenir. @nullable(heap=true), Java arka ucunda işlem yapmaz.

utf8InCpp

utf8InCpp, String değerinin CPP arka ucu için UTF8 biçiminde temsil edildiğini belirtir. Adından da anlaşılacağı gibi, ek açıklama diğer arka uçlarda işlem yapmaz. Daha açık belirtmek gerekirse String, Java arka ucunda her zaman UTF16, NDK arka ucunda ise UTF8 olur.

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

CPP arka ucu için AIDL'deki @utf8InCpp String, std::string ile eşlenir. Not olmadan String ise 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. utf8InCpp ek açıklamalı dize, iletilmeden önce UTF16'ya dönüştürülür. Alınan bir dize, utf8InCpp olarak ek açıklama eklenmişse UTF16'dan UTF8'e dönüştürülür.

VintfStability

VintfStability, kullanıcı tanımlı bir türün (arayüz, paketlenebilir ve enum) sistem ve tedarikçi alan adlarında kullanılabileceğini belirtir. Sistem satıcısı birlikte çalışabilirliği hakkında daha fazla bilgi için HAL'ler için AIDL başlıklı makaleyi inceleyin.

Ek açıklama türün imzasını değiştirmez ancak türün ayarlandığı zaman, tedarikçi ve sistem işlemleri arasında gezinebilmesi için türün örneği sabit olarak işaretlenir.

Ek açıklama, yalnızca burada gösterildiği gibi kullanıcı tanımlı tür beyanlarına eklenebilir:

@VintfStability
interface IFoo {
    ....
}

@VintfStability
parcelable Data {
    ....
}

@VintfStability
enum Type {
    ....
}

Bir tür VintfStability ile ek açıklamayla belirtildiğinde, türde referans verilen diğer türler de aynı şekilde ek açıklamayla belirtilmelidir. Aşağıdaki örnekte, hem Data hem de IBar, VintfStability ile ek açıklamaya tabi tutulmalı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 {...}

Ayrıca, VintfStability ile ek açıklama eklenmiş türleri tanımlayan AIDL dosyaları yalnızca stability özelliği "vintf" olarak ayarlanmış aidl_interface Soong modülü türü kullanılarak derlenebilir.

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

UnsupportedAppUsage

UnsupportedAppUsage ek açıklaması, ek açıklamalı AIDL türünün, eski uygulamaların erişilebilir olduğu SDK dışı arayüzün bir parçası olduğunu belirtir. Gizli API'ler hakkında daha fazla bilgi için SDK dışı arayüzlerle ilgili kısıtlamalar bölümüne bakın.

UnsupportedAppUsage ek açıklaması, oluşturulan kodun davranışını etkilemez. Ek açıklama, oluşturulan Java sınıfına yalnızca aynı ada sahip Java ek açıklamasıyla ek açıklama ekler.

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

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

Bu, Java olmayan arka uçlarda işlem yapılmaz.

Destek

Backing ek açıklaması, bir AIDL enum türünün depolama alanını belirtir.

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

Bu, CPP arka ucunda int32_t türüne sahip bir C++ enum sınıfı oluşturur.

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

Ek açıklama atlanırsa type değerinin byte olduğu varsayılır. byte, CPP arka ucu için int8_t ile eşlenir.

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

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

NdkOnlyStableParcelable

NdkOnlyStableParcelable, diğer kararlı AIDL türlerinden referans verilebilmesi için ayrıştırılabilir bir beyanı (tanım değil) stabil olarak işaretler. Bu, JavaOnlyStableParcelable ile benzerdir ancak NdkOnlyStableParcelable, paketlenebilir bir beyanı Java yerine NDK arka ucu için kararlı olarak işaretler.

Bu paketi kullanmak için:

• ndk_header değerini belirtmeniz gerekir.
• Paketlenebilir öğeyi belirten bir NDK kitaplığınız olmalıdır ve kitaplık kitaplığa derlenmelidir. Örneğin, cc_* modülündeki temel derleme sisteminde static_libs veya shared_libs kullanın. aidl_interface için kitaplığı Android.bp'deki additional_shared_libraries altına ekleyin.

JavaOnlyStableParcelable

JavaOnlyStableParcelable, paketlenebilir bir tanımı (tanım değil) diğer sabit AIDL türlerinden referans alınabilmesi için sabit olarak işaretler.

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

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
}

Parseller yapılandırılmamışsa (veya yeni belirtilmişse) referans verilemez.

parcelable Data; // Data is NOT a structured parcelable

parcelable AnotherData {
    Data d; // Error
}

JavaOnlyStableParcelable, referans verdiğiniz parcelable Android SDK'sının bir parçası olarak zaten güvenli bir şekilde kullanılabilir durumda olduğunda kontrolü 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;
}

Ek açıklama, nelerin oluşturulacağını kontrol etmek için ek parametreler gerektirir. Desteklenen parametreler şunlardır:

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

JavaDefault

Android 13'e eklenen JavaDefault, varsayılan uygulama sürümlendirme desteğinin oluşturulup oluşturulmayacağını kontrol eder (setDefaultImpl için). Bu destek, artık yer kazanmak amacıyla varsayılan olarak oluşturulmaz.

JavaPassthrough

JavaPassthrough, oluşturulan Java API'ye rastgele bir Java ek açıklamasıyla ek açıklama eklenmesini sağlar.

AIDL'deki aşağıdaki ek açıklamalar

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

become

@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 bir söz dizimi hatası varsa bu hata AIDL derleyicisi tarafından değil, Java derleyicisi tarafından yakalanır.

Bu ek açıklama, herhangi bir AIDL varlığına eklenebilir. Bu ek açıklama, Java olmayan arka uçlarda işlem yapmaz.

Sabit Boyut

FixedSize, yapılandırılmış bir ayrıştırılabilir öğeyi sabit boyut olarak işaretler. İşaretlenen parçalı alana yeni alan eklenmesine izin verilmez. Paketlenebilir öğenin tüm alanları da temel türler, enum'ler, sabit boyutlu diziler ve FixedSize ile işaretlenmiş diğer paketlenebilir öğeler dahil olmak üzere sabit boyutlu türler olmalıdır.

Bu, farklı bitliklerde herhangi bir garanti sağlamaz ve karma bitlik iletişimi için güvenilmemelidir.

Tanımlayıcı

Descriptor, bir arayüzün arayüz tanımlayıcısını zorla belirtir.

package android.foo;

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

Bu arayüzün tanımlayıcısı android.bar.IWorld şeklindedir. Descriptor ek açıklaması yoksa açıklayıcı android.foo.IHello olur.

Bu işlem, yayınlanmış bir arayüzü yeniden adlandırırken işinize yarayacaktır. Yeniden adlandırılan arayüzün tanımlayıcısını, yeniden adlandırmadan önceki arayüzün tanımlayıcısıyla aynı hale getirmek, iki arayüzün birbiriyle iletişim kurmasına olanak tanır.

@hide in comments

AIDL derleyicisi, yorumlardaki @hide öğesini tanır ve metalava'nın alabilmesi için Java çıkışına iletir. Bu yorum, Android derleme sisteminin AIDL API'lerinin SDK API'si olmadığını bilmesini sağlar.

Yorumlarda @deprecated

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

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

Her arka uç, desteği sonlandırılmış varlıkları arka uca özel bir ek açıklama veya özellikle işaretler. Böylece, kullanımdan kaldırılan varlıklara işaret etmesi halinde istemci kodu uyarılır. Örneğin, @Deprecated ek açıklaması ve @deprecated etiketi, oluşturulan Java koduna eklenir.