AIDL'deki ek açıklamalar

AIDL, AIDL derleyicisine açıklama eklenen öğe hakkında ekstra bilgi veren ek açıklamaları destekler ve bu durum, oluşturulan saplama kodunu da etkiler.

Söz dizimi Java'nın söz dizimine benzer:

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

Burada AnnotationName, ek açıklamanın adını, AidlEntity ise interface Foo, void method() veya int arg gibi bir AIDL varlığıdır. Ardından gelen öğeye bir not eklenir.

Bazı ek açıklamalarda, yukarıda gösterildiği gibi parantez içinde ayarlanan bağımsız değişkenler olabilir. Bağımsız değişkeni olmayan ek açıklamalarda paranteze gerek yoktur. Örnek:

@AnnotationName AidlEntity

Bu ek açıklamalar, çok benzer görünmelerine rağmen Java notları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, diğer arka uçlarda işlem yapmaz. Eklenebilecek 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

boş değer atanabilir

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

Bu ek açıklama yalnızca yöntem döndürme 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;
}

Ek 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şlemsizdir. Bunun nedeni, Java'da temel olmayan tüm türlerin, null olabilecek referansla geçirilmesidir.

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

NDK arka ucunda @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>>> ile (veya Android 11 ya da önceki CPP arka ucunda std::unique_ptr<std::vector<std::unique_ptr<T>>>) eşlenir.

Bu eşlemenin bir istisnası vardır. T, IBinder veya AIDL arayüzü olduğunda @nullable ile işlem yapılamaz. 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ı boşluğu zorunlu kılmaya devam eder ancak tür yine de android::sp<IBinder> olur).

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önüş türleriyle kullanılamaz. Açıklama eklendiğinde alan, PPP/NDK arka uçlarında yığınla ayrılmış bir referansla (std::unique_ptr<T>) eşlenir. @nullable(heap=true), Java arka ucunda işlemsizdir.

utf8InCpp

utf8InCpp, String öğesinin 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. Özellikle String, Java arka ucunda her zaman UTF16 ve NDK arka uçta her zaman UTF8'dir.

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.

PBM arka ucu için AIDL'deki @utf8InCpp String, std::string ile eşlenirken ek 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 aktarılır. utf8InCpp ek açıklamalı bir dizesi, iletilmeden önce UTF16'ya dönüştürülür. Alınan dizeler, utf8InCpp olarak işaretlenmişse UTF16'dan UTF8'e dönüştürülür.

Eski İstikrar

VintfStability, sistem ve tedarikçi alanlarında kullanıcı tanımlı bir türün (arayüz, ayrıştırılabilir ve numaralandırma) kullanılabileceğini bildirir. Sistem tedarikçi firmasının birlikte çalışabilirliği hakkında daha fazla bilgi edinmek için HAL'ler için AIDL'yi 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 bildirimlerine eklenebilir:

@VintfStability
interface IFoo {
    ....
}

@VintfStability
parcelable Data {
    ....
}

@VintfStability
enum Type {
    ....
}

Bir türe VintfStability ek açıklaması eklendiğinde, tür içinde referans verilen diğer türler de bu şekilde ek açıklama yapmalıdır. Aşağıdaki örnekte hem Data hem de IBar için VintfStability ek açıklaması verilmelidir.

@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 ek açıklaması olan türleri tanımlayan AIDL dosyaları yalnızca stability özelliği "vintf" olarak ayarlanarak aidl_interfaceNowg modül türü kullanılarak oluşturulabilir.

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

DesteklenmeyenUygulama Kullanımı

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ı adlı Java ek açıklamasını ekler.

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

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

Bu, Java dışı arka uçlar için işlemsiz bir uygulamadır.

Destekleniyor

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

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

Bu, PBM arka ucunda int32_t türünde bir C++ sıralama 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 ve bu da PBM 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şlik)
• int (32 bit genişlik)
• 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 benzeridir ancak NdkOnlyStableParcelable, ayrıştırılabilir bir beyanı Java yerine NDK arka ucu için kararlı olarak işaretler.

Bu ayrıştırılabilir öğeyi kullanmak için:

• ndk_header belirtmelisiniz.
• Ayrıştırılabilir öğeyi belirten bir NDK kitaplığınızın olması ve kitaplığın kitaplıkta derlenmesi gerekir. Örneğin, cc_* modülündeki temel derleme sisteminde static_libs veya shared_libs kullanın. aidl_interface için kitaplığı Android.bp içindeki additional_shared_libraries altına ekleyin.

JavaOnlyStableParcelable

JavaOnlyStableParcelable, diğer kararlı AIDL türlerinden referans verilebilmesi için ayrıştırılabilir bir beyanı (tanım değil) stabil olarak işaretler.

Kararlı AIDL, kullanıcı tanımlı tüm türlerin kararlı olmasını gerektirir. Ayrıştırma alanlarının kararlı olması için ilgili alanların AIDL kaynak dosyasında açıkça açıklanması 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, başvuruda bulunduğunuz ayrıştırılabilir öğe Android SDK'nın bir parçası olarak zaten güvenli bir şekilde kullanılabilir olduğunda kontrolü geçersiz kılmanıza olanak sağlar.

@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, oluşturulacak öğeyi kontrol etmek için ek parametrelere ihtiyaç duyar. Desteklenen parametreler şunlardır:

• equals=true, equals ve hashCode yöntemleri oluşturur.
• toString=true, tür ve alanların adını yazdıran toString yöntemi oluşturur. Örnek: 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). Yerden tasarruf etmek için bu destek artık varsayılan olarak oluşturulmamaktadır.

JavaGeçişi

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

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

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

haline gelmek

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

kodu yer alır.

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 varlığına eklenebilir. Bu ek açıklama, Java olmayan arka uçlar için işlemsizdir.

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 alan eklenemez. Ayrıştırılabilir öğenin tüm alanları aynı zamanda temel türler, sıralamalar, sabit boyutlu diziler ve FixedSize ile işaretlenen diğer ayrıştırılabilir öğeler dahil olmak üzere sabit boyutlu türler olmalıdır.

Bu, farklı bit parçaları için herhangi bir garanti sağlamaz ve karma bitlik iletişimde buna güvenilmemelidir.

Açıklayı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, 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 önce arayüzün tanımlayıcısıyla aynı yapmak, iki arayüzün birbiriyle iletişim kurmasını sağlar.

@yorumlarda gizle

AIDL derleyicisi, yorumlarda @hide öğesini tanır ve metalava'nın teslim alması için Java çıkışı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 öğ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, Java tarafından oluşturulan koda eklidir.