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ına çok benzese 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 hiçbir 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:

Ek Açıklamalar Android sürümüne eklendi
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

nullable, ek açıklamaya sahip öğ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;
}

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şlem yapmaz. 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şlemede bir istisna 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 eşit olarak android::sp<IBinder> ile eşlenir. android::sp<IBinder>, güçlü bir işaretçi olduğu için zaten boş değer kabul edebilir (CPP okumaları, boş değer kabul edilebilirliği zorunlu kılmaya devam eder ancak tür yine de android::sp<IBinder> olur). Rust'ta bu türler yalnızca @nullable ile ek açıklama eklenirse nullable olur. Açıklama eklenmişse Option<T> ile eşlenir.

Android 13'ten itibaren, @nullable(heap=true), yinelenen türleri modellemek için bölünebilir 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 beyanlar 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. 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 ayarlandığında türün örneği, tedarikçi firma ve sistem süreçleri arasında taşınabilmesi için kararlı 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 için erişilebilir olan SDK dışı arayüzün bir parçası olduğunu belirtir. Gizli API'ler hakkında daha fazla bilgi için SDK olmayan arayüzlerde kısıtlamalar başlıklı makaleyi inceleyin.

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 yapmaz.

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şliğinde)

NdkOnlyStableParcelable

NdkOnlyStableParcelable, paketlenebilir bir tanımı (tanım değil) diğer sabit AIDL türlerinden referans alınabilmesi için sabit 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
}

Paketlenebilir öğe yapılandırılmamışsa (veya yalnızca tanımlanmışsa) referans veremez.

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 ucunda paketlenebilir 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öntemlerini 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'nin keyfi bir Java ek açıklamasıyla eklenmesine 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)")

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ğerini incelemez. 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 öğesine eklenebilir. Bu ek açıklama, Java olmayan arka uçlarda işlem yapmaz.

RustDerive

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

Ek açıklama, nelerin 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 adresine bakın.

FixedSize

FixedSize, yapılandırılmış bir paketlenebilir öğeyi sabit boyut olarak işaretler. İşaretlenen bölünebilir 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. Descriptor ek açıklaması yoksa 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ı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, yorumlardaki @deprecated değerini artık kullanılmaması gereken bir AIDL öğesini tanımlayan bir etiket olarak tanır.

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

Her arka uç, desteği sonlandırılan öğeleri arka uca özgü bir ek açıklama veya özellikle işaretler. Böylece, desteği sonlandırılan öğelere referans veren istemci kodu uyarı alır. Örneğin, @Deprecated ek açıklama ve @deprecated etiketi, oluşturulan Java koduna eklenir.