AIDL'deki ek açıklamalar

AIDL, ek açıklama eklenmiş öğe hakkında AIDL derleyicisine ek bilgi veren ek açıklamaları destekler. Bu bilgiler, oluşturulan kaba 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, onu takip eden varlığa eklenir.

Bazı ek açıklamalar, önceki örnekte gösterildiği gibi parantez içinde bağımsız değişkenler içerebilir. Bağımsız değişkeni olmayan notlar için parantez gerekmez. Örneğin:

@AnnotationName AidlEntity

Bu notlar, Java notlarına benzese de aynı değildir. Tüm ek açıklamalar önceden tanımlanmıştır ve nereye eklenebilecekleri konusunda kısıtlamalar vardır. Bazı ek açıklamalar yalnızca belirli bir arka ucu etkiler ve diğer arka uçlarda işlem yapmaz.

Önceden tanımlanmış AIDL ek açıklamalarının listesini aşağıda bulabilirsiniz:

nullable

nullable, açıklama eklenen öğenin değerinin boş olabileceğini belirtir.

Bu ek açıklamayı yalnızca yöntem dönüş türlerine, yöntem parametrelerine ve paketlenebilir alanlara ekleyebilirsiniz:

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. Java'da tüm ilkel olmayan türler referansla iletilir. Bu durum null olabilir.

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

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

Rust arka ucunda @nullable T, 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 önceki 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 AIDL arayüzü olduğunda @nullable, Java, CPP ve NDK arka uçları için işlem yapmaz. Ör neğin, CPP arka ucunda hem @nullable IBinder hem de IBinder, android::sp<IBinder> ile eşit şekilde eş lenir. , güçlü bir işaretçi olduğundan zaten boş değer atanabilir. (CPP ve NDK okumaları boş değer atanabilirliği zorunlu kılmaya devam eder ancak tür android::sp<IBinder> veya ndk::SpAIBinder olarak kalır.)

Rust arka ucunda, Default (IBinder, AIDL arayüzleri, ParcelFileDescriptor ve yapılandırılmamış parcelable'lar) uygulamayan türler, bağlamlarına bağlı olarak Option<T> ile eşlenir:

• Yöntem dönüş türleri, in parametreleri ve inout parametreleri: Bu türler yalnızca @nullable ile açıklama eklenmişse ve Option<T> (veya in parametreleri için Option<&T> ve inout parametreleri için &mut Option<T>) ile eşlenmişse null olabilir. @nullable olmadan doğrudan T (veya &T ve &mut T) ile eşlenir.
• Parcelable alanları ve out parametreleri: Oluşturulan Rust parcelable'ları Default ve out parametreleri varsayılan olarak başlatıldığından, bu türler @nullable olmadan bile her zaman Option<T> ile eşlenir (bu bağlamlardaki sabit boyutlu diziler [Option<T>; N] ile, out parametrelerindeki dinamik diziler ise Vec<Option<T>> ile eşlenir). @nullable ile açıklama eklenmediğinde, paketleme sırasında çalışma zamanında boş olmama durumu yine zorunlu kılınır (değer None ise StatusCode::UNEXPECTED_NULL döndürülür).

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

utf8InCpp

utf8InCpp, CPP arka ucu için String öğesinin UTF8 biçiminde temsil edildiğini beyan eder. 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. Burada, ek açıklama içermeyen String, UTF16'nın kullanıldığı android::String16 ile eşlenir.

VintfStability

VintfStability, kullanıcı tanımlı bir türün (arayüz, paketlenebilir ve enum) sistem ve satıcı alanlarında kullanılabileceğini beyan eder. 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, satıcı 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ürlere 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 ek açıklama eklenmiş türleri tanımlayan AIDL dosyaları yalnızca aidl_interface Soong modül türü kullanılarak oluşturulabilir. Bu türde, 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 olmayan arayüzün bir parçası olduğunu gösterir. 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, yalnızca aynı ada sahip Java ek açıklamasıyla oluşturulan Java sınıfına ek 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 işlem yapmayan bir işlemdir.

Backing ek açıklaması

Backing ek 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,
}

Ek 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.
• Paketlenebilir öğeyi 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 tarihinde additional_shared_libraries bölümüne 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ı olabilmek, 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 parcelable Android SDK'nın bir parçası olarak güvenli bir şekilde kullanılabildiğinde 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;
}

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 (ör. Data{number: 42, str: foo}).

JavaDefault (desteği sonlandırıldı)

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. Yerden tasarruf etmek için bu destek artık varsayılan olarak oluşturulmaz.

JavaPassthrough

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

AIDL'deki bu ek açıklamalar:

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

oluşturulan Java kodunda aşağıdaki gibi olur:

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

annotation parametresinin değeri doğrudan yayınlanır. AIDL derleyicisi, parametrenin değerini incelemez. 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 Rust belgelerine bakın.

FixedSize

FixedSize, yapılandırılmış bir paketlenebilir öğeyi sabit boyutlu olarak işaretler. İşaretlendikten sonra, paketlenebilir nesneye yeni alanlar ekleyemezsiniz. Parcelable'ın tüm alanları, ilkel türler, numaralandırmalar, sabit boyutlu diziler ve FixedSize ile işaretlenmiş diğer parcelable'lar dahil olmak üzere sabit boyutlu türler olmalıdır.

FixedSize nesneler, ndk arka ucunda sabit boyutlara ve hizalamalara sahiptir.

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 birbirleriyle iletişim kurmasını sağlar.

@hide in comments

AIDL derleyicisi, yorumlardaki @hide öğesini 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ı tanımasını sağlar.

Yorumlarda @deprecated

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

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

Her arka uç, arka uca özgü bir 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.