AIDL'deki ek açıklamalar

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

Söz dizimi Java'ya benzer:

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

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

Bazı ek açıklamalar, yukarıda gösterildiği gibi parantez içinde ayarlanan bağımsız değişkenlere sahip olabilir. Bağımsız değişkeni olmayan notlarda parantez kullanılması gerekmez. Örneğin:

@AnnotationName AidlEntity

Bu notlar, çok benzer görünmelerine rağmen Java notlarıyla aynı değildir. Kullanıcılar özel AIDL ek açıklamaları tanımlayamaz. Tüm ek açıklamalar önceden tanımlanmıştır. Bazı ek açıklamalar yalnızca belirli bir arka ucu etkiler ve diğer arka uçlarda işlem yapmaz. Bunların eklenebileceği yerlerle ilgili farklı kısıtlamalar vardır.

Önceden tanımlanmış AIDL ek açıklamalarının listesi:

null değer alabilir

nullable, açıklama eklenen öğenin değerinin sağlanamayacağını 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;
}

Açıklamalar temel türlere 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 yapmaz. Bunun nedeni, Java'da tüm ilkel olmayan türlerin referansla iletilmesidir. Bu durum null olabilir.

CPP arka ucunda @nullable T, Android 11 veya daha eski sürümlerde std::unique_ptr<T>'ye, Android 12 veya daha yeni sürümlerde ise std::optional<T>'ye 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 tür için L, @nullable L, std::optional<std::vector<std::optional<T>>> ile eşlenir (veya Android 11 ya da daha eski sürümlerdeki PBM arka ucu için std::unique_ptr<std::vector<std::unique_ptr<T>>>).

Bu eşlemenin bir istisnası vardır. T, IBinder veya bir AIDL arayüzü olduğunda @nullable, Rust hariç tüm arka uçlar için işlem yapmaz. Başka bir deyişle, hem @nullable IBinder hem de IBinder, android::sp<IBinder> ile eşit şekilde eşlenir. android::sp<IBinder>, güçlü bir işaretçi olduğu için zaten boş değer atanabilir (CPP okumaları boş değer atanabilirliği zorunlu kılmaya devam eder ancak tür yine de android::sp<IBinder>'dir). Rust'ta bu türler yalnızca @nullable ile açıklama eklenirse nullable olur. Açıklama eklenirse Option<T> ile eşlenir.

Android 13'ten itibaren, yinelemeli türleri modellemek için @nullable(heap=true) kullanılabilir. @nullable(heap=true), yöntem parametreleri veya dönüş türleriyle kullanılamaz. Bu açıklama eklendiğinde alan, CPP/NDK arka uçlarında yığın olarak ayrılmış bir referansa std::unique_ptr<T> eşlenir. @nullable(heap=true), Java arka ucunda işlem yapmaz.

utf8InCpp

utf8InCpp, CPP arka ucu için String öğesinin UTF8 biçiminde temsil edildiğini belirtir. Adından da anlaşılacağı gibi, ek açıklama diğer arka uçlar için işlem yapmaz. Özellikle String, Java arka ucunda her zaman UTF16, NDK arka ucunda ise UTF8'dir.

Bu ek açıklama, dönüş değerleri, parametreler, sabit bildirimleri ve paketlenebilir 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. Açıklama olmadan String ise UTF16'nın kullanıldığı android::String16 ile eşlenir.

utf8InCpp açıklamasının varlığının, dizelerin kablo üzerinden iletilme şeklini değiştirmediğini unutmayın. Dizeler her zaman UTF16 olarak iletilir. utf8InCpp ek açıklamalı bir dize, iletilmeden önce UTF16'ya dönüştürülür. Bir dize alındığında, utf8InCpp olarak 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 satıcı alanlarında kullanılabileceğini belirtir. Sistem-satıcı 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 ayarlandığında türün örneği kararlı olarak işaretlenir. Böylece, tedarikçi ve sistem süreçleri arasında taşınabilir.

Açıklama yalnızca kullanıcı tanımlı tür bildirimlerine eklenebilir.

@VintfStability
interface IFoo {
    ....
}

@VintfStability
parcelable Data {
    ....
}

@VintfStability
enum Type {
    ....
}

Bir tür VintfStability ile açıklama eklenmişse türde referans verilen diğer türler de bu şekilde açıklama eklenmelidir. Aşağıdaki örnekte, hem Data hem de IBar, VintfStability ile açıklama eklenmelidir.

@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 açıklama eklenmiş türleri tanımlayan AIDL dosyaları yalnızca aidl_interface Soong modül türü kullanılarak oluşturulabilir ve stability özelliği "vintf" olarak ayarlanır.

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

UnsupportedAppUsage

UnsupportedAppUsage ek açıklaması, ek açıklama eklenen AIDL türünün eski uygulamalar tarafından erişilebilen SDK dışı arayüzün bir parçası olduğunu gösterir. Gizli API'ler hakkında daha fazla bilgi için SDK olmayan arayüzlerdeki kısıtlamalar başlıklı makaleyi inceleyin.

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

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

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

Bu, Java olmayan arka uçlar için işlem yapmaz.

Yedekleme

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

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

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

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

Açıklama çıkarılırsa type değerinin byte olduğu varsayılır. Bu değer, 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şliğinde)

NdkOnlyStableParcelable

NdkOnlyStableParcelable, diğer sabit AIDL türlerinden referans verilebilmesi için paketlenebilir bir bildirimi (tanım değil) sabit olarak işaretler. Bu, JavaOnlyStableParcelable'ye benzer ancak NdkOnlyStableParcelable, Java yerine NDK arka ucu için paketlenebilir bir bildirimi kararlı olarak işaretler.

Bu paketlenebilir öğeyi kullanmak için:

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

JavaOnlyStableParcelable

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

Kararlı AIDL, kullanıcı tanımlı tüm türlerin kararlı olmasını gerektirir. Parcelable'lar için kararlı olmak, alanlarının AIDL kaynak dosyasında açıkça açıklanması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
}

Parcelable yapılandırılmamışsa (veya yalnızca bildirilmişse) referans verilemez.

parcelable Data; // Data is NOT a structured parcelable

parcelable AnotherData {
    Data d; // Error
}

JavaOnlyStableParcelable, referans verdiğiniz paketlenebilir öğe Android SDK'sının bir parçası olarak zaten güvenli bir şekilde kullanılabiliyorsa kontrolü geçersiz kılmanıza olanak tanır.

@JavaOnlyStableParcelable
parcelable Data;

parcelable AnotherData {
    Data d; // OK
}

JavaDerive

JavaDerive Java arka ucunda parcelable türleri için otomatik olarak yöntemler oluşturur.

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

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

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

JavaDefault

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

JavaPassthrough

JavaPassthrough, oluşturulan Java API'nin rastgele bir Java ek açıklamasıyla açıklanmasına olanak tanır.

AIDL'deki aşağıdaki ek 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 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 öğesine eklenebilir. Bu ek açıklama, Java dışı arka uçlar için işlem yapmaz.

RustDerive

RustDerive, oluşturulan Rust türleri için özellikleri otomatik olarak uygular.

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

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

Bu özelliklerin açıklamaları için https://doc.rust-lang.org adresini ziyaret edin.

FixedSize

FixedSize, yapılandırılmış bir paketlenebilir öğeyi sabit boyutlu olarak işaretler. İşaretlendikten sonra pakete yeni alanlar eklenemez. Paketlenebilir öğenin tüm alanları, temel türler, numaralandırmalar, sabit boyutlu diziler ve FixedSize ile işaretlenmiş diğer paketlenebilir öğeler dahil olmak üzere sabit boyutlu türler olmalıdır.

Bu, farklı bit sayıları arasında herhangi bir garanti sağlamaz ve karışık bit sayısı iletişiminde kullanılmamalıdır.

Tanımlayıcı

Descriptor bir arayüzün arayüz tanımlayıcısını zorunlu olarak belirtir.

package android.foo;

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

Bu arayüzün tanımlayıcısı android.bar.IWorld'dır. Descriptor ek açıklaması eksikse tanımlayıcı android.foo.IHello olur.

Bu, daha önce yayınlanmış bir arayüzü yeniden adlandırmak için kullanışlıdır. Yeniden adlandırılan arayüzün tanımlayıcısını, yeniden adlandırma işleminden önceki arayüzün tanımlayıcısıyla aynı yapmak, iki arayüzün birbiriyle iletişim kurmasını sağlar.

@hide in comments

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

Yorumlarda @deprecated

AIDL derleyicisi, yorumlardaki @deprecated işaretini artık kullanılmaması gereken bir AIDL öğesini tanımlayan etiket olarak tanır.

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

Her arka uç, arka uca özgü bir ek açıklama veya özellik ile kullanımdan kaldırılan öğeleri işaretler. Böylece, istemci kodu kullanımdan kaldırılan öğelere başvurursa uyarılır. Örneğin, @Deprecated ek açıklaması ve @deprecated etiketi, Java ile oluşturulan koda eklenir.