AIDL'deki açıklamalar

AIDL, AIDL derleyicisine açıklamalı öğe hakkında ekstra bilgi veren ve aynı zamanda oluşturulan saplama kodunu da etkileyen ek açıklamaları destekler.

Sözdizimi Java'nınkine benzer:

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

Burada AnnotationName , ek açıklamanın adıdır ve AidlEntity interface Foo , void method() veya int arg gibi bir AIDL varlığıdır. Onu takip eden varlığa bir açıklama eklenir.

Bazı ek açıklamalarda yukarıda gösterildiği gibi parantez içinde bağımsız değişkenler bulunabilir. Bağımsız değişken içermeyen ek açıklamalarda parantez kullanılmasına gerek yoktur. Örneğin:

@AnnotationName AidlEntity

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

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

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

geçersiz kılınabilir

nullable , açıklamalı varlığın değerinin sağlanamayacağını bildirir.

Bu ek açıklama yalnızca yöntem dönüş 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 ilkel 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 dışıdır. Bunun nedeni, Java'da ilkel olmayan tüm türlerin referans olarak iletilmesidir ve bu da null olabilir.

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

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

T[] veya List<T> gibi liste benzeri bir L türü için @nullable L , std::optional<std::vector<std::optional<T>>> (veya std::unique_ptr<std::vector<std::unique_ptr<T>>> ile eşleşir std::unique_ptr<std::vector<std::unique_ptr<T>>> Android 11 veya daha düşük sürümler için CPP arka ucu olması durumunda).

Bu eşlemenin bir istisnası vardır. T , IBinder veya AIDL arayüzü olduğunda, @nullable işlem dışıdır. Başka bir deyişle, hem @nullable IBinder hem de IBinder eşit olarak android::sp<IBinder> ile eşleşir; bu zaten güçlü bir işaretçi olduğundan null yapılabilir (CPP okumaları hala null edilebilirliği zorlar, ancak tür hala android::sp<IBinder> dir). ).

Android 13'ten başlayarak, özyinelemeli türleri modellemek amacıyla parsellenebilir alanlar için @nullable(heap=true) kullanılabilir. @nullable(heap=true) yöntem parametreleriyle veya dönüş türleriyle kullanılamaz. Bununla açıklama eklendiğinde alan, CPP/NDK arka uçlarında yığınla ayrılmış bir referans std::unique_ptr<T> ile eşlenir. @nullable(heap=true) Java arka ucunda işlem dışıdır.

utf8InCpp

utf8InCpp CPP arka ucu için bir String UTF8 formatında temsil edildiğini bildirir. Adından da anlaşılacağı gibi, ek açıklama diğer arka uçlar için işlem dışıdır. Özellikle, String her zaman Java arka ucunda UTF16'dır ve NDK arka ucunda UTF8'dir.

Bu ek açıklama, dönüş değerleri, 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şleşirken, ek açıklama içermeyen String UTF16'nın kullanıldığı android::String16 ile eşleşir.

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

VintfKararlılık

VintfStability , sistem ve satıcı etki alanlarında kullanıcı tanımlı bir türün (arayüz, parçalanabilir ve numaralandırma) kullanılabileceğini bildirir. Sistem-satıcı birlikte çalışabilirliği hakkında daha fazla bilgi için HAL'ler için AIDL'ye bakın.

Ek açıklama, türün imzasını değiştirmez ancak ayarlandığında türün örneği, satıcı ve sistem süreçleri arasında seyahat edebilmesi için kararlı olarak işaretlenir.

Ek açıklama yalnızca aşağıda 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 ile açıklama eklendiğinde, türde başvurulan diğer herhangi bir türe de bu şekilde açıklama eklenmelidir. Aşağıdaki örnekte Data ve IBar her ikisinin de VintfStability ile açıklanması gerekir.

@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 {...}

Ek olarak, VintfStability ile açıklamalı türleri tanımlayan AIDL dosyaları yalnızca aidl_interface Soong modül türü kullanılarak, stability özelliği "vintf" olarak ayarlanarak oluşturulabilir.

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

Desteklenmeyen Uygulama Kullanımı

UnsupportedAppUsage ek açıklaması, açıklamalı AIDL türünün eski uygulamalar için erişilebilen SDK olmayan arayüzün bir parçası olduğunu belirtir. Gizli API'ler hakkında daha fazla bilgi için bkz . SDK olmayan arayüzlerdeki kısıtlamalar .

UnsupportedAppUsage ek açıklaması, oluşturulan kodun davranışını etkilemez. Ek açıklama yalnızca oluşturulan Java sınıfına aynı adı taşıyan Java ek açıklamasıyla 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 dışıdır.

Destek

Backing açıklaması, bir AIDL numaralandırma türünün depolama türünü belirtir.

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

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

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

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

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

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

NdkOnlyStableParcelable

NdkOnlyStableParcelable diğer kararlı AIDL türlerinden başvurulabilmesi için ayrıştırılabilir bir bildirimi (tanım değil) kararlı olarak işaretler. Bu, JavaOnlyStableParcelable benzer, ancak NdkOnlyStableParcelable ayrıştırılabilir bir bildirimi Java yerine NDK arka ucu için kararlı olarak işaretler.

Bu parsellenebiliri kullanmak için: * ndk_header belirtmelisiniz. * Parsellenebilirliği belirten bir NDK kütüphaneniz olmalı ve kütüphane kütüphaneye derlenmelidir. Örneğin, bir cc_* modülündeki çekirdek derleme sisteminde, static_libs veya shared_libs kullanın. aidl_interface için kitaplığı Android.bp additional_shared_libraries altına ekleyin.

JavaOnlyStableParcelable

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

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

Parsellenebilir yapılandırılmamışsa (veya henüz bildirilmişse), bu durumda ona referans verilemez.

parcelable Data; // Data is NOT a structured parcelable

parcelable AnotherData {
    Data d; // Error
}

JavaOnlyStableParcelable referansta bulunduğunuz parsellenebilirin Android SDK'nın bir parçası olarak güvenli bir şekilde mevcut olması durumunda kontrolü geçersiz kılmanıza olanak tanır.

@JavaOnlyStableParcelable
parcelable Data;

parcelable AnotherData {
    Data d; // OK
}

JavaDeri

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

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

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

  • equals=true equals ve hashCode yöntemlerini üretir.
  • toString=true türün ve alanların adını yazdıran toString yöntemini oluşturur. Örneğin: 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şturulmadığını kontrol eder ( setDefaultImpl için). Bu destek artık yerden tasarruf etmek için varsayılan olarak oluşturulmamaktadır.

Java Geçişi

JavaPassthrough oluşturulan Java API'sine rastgele bir Java açıklamasıyla açıklama eklenmesine olanak tanır.

AIDL'de aşağıdaki 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)

oluşturulan Java kodunda.

annotation parametresinin değeri doğrudan yayılır. AIDL derleyicisi parametrenin değerine bakmaz. Java düzeyinde herhangi bir sözdizimi hatası varsa, AIDL derleyicisi tarafından değil, Java derleyicisi tarafından yakalanacaktır.

Bu ek açıklama herhangi bir AIDL varlığına eklenebilir. Bu ek açıklama Java dışı arka uçlar için işlem dışıdır.

Sabit Boyut

FixedSize yapılandırılmış bir parsellenebiliri sabit boyut olarak işaretler. İşaretlendikten sonra parsellenebilire yeni alanların eklenmesine izin verilmeyecektir. İlkel türler, numaralandırmalar, sabit boyutlu diziler ve FixedSize ile işaretlenmiş diğer parsellenebilirler dahil olmak üzere parsellenebilirin tüm alanları aynı zamanda sabit boyutlu türler olmalıdır.

Bu, farklı bitliklerde herhangi bir garanti sağlamaz ve karışık bitlik iletişimde buna 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 {...}

Yukarıdaki arayüzün tanımlayıcısı android.bar.IWorld . Descriptor ek açıklaması eksikse tanımlayıcı android.foo.IHello olacaktır.

Bu, önceden 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 önce arayüzün tanımlayıcısıyla aynı yapmak, iki arayüzün birbiriyle konuşmasını sağlar.

@yorumlarda gizle

AIDL derleyicisi yorumlardaki @hide tanır ve bunu metalava'nın alınması 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, yorumlardaki @deprecated öğesini artık kullanılmaması gereken bir AIDL varlığını tanımlayan bir etiket olarak tanır.

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

Her arka uç, kullanımdan kaldırılmış varlıkları arka uca özgü bir açıklama/öznitelik ile işaretler, böylece kullanımdan kaldırılmış varlıklara atıfta bulunursa istemci kodu uyarılır. Örneğin, @Deprecated ek açıklaması ve @deprecated etiketi Java tarafından oluşturulan koda eklenir.