AIDL'deki ek açıklamalar

AIDL, AIDL derleyicisine ek bilgi veren ek açıklamaları destekler ek açıklamalı öğeyle ilgili olarak, oluşturulan saplama kodunu da etkiler.

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

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

Burada, ek açıklamanın adı AnnotationName, AidlEntity ise ek açıklamanın adıdır. interface Foo, void method() veya int arg gibi bir AIDL varlığı. ek açıklama, kendisinden sonra gelen varlığa 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 Java ile aynı değildir ancak birbirlerine çok benziyorlar. Kullanıcılar özel AIDL tanımlayamaz ek açıklamalar; ek açıklamaların tümü önceden tanımlanmıştır. Bazı ek açıklamalar yalnızca diğer arka uçlarda işlem yapmaz. Birbirinden farklı ek kısıtlamalara sahip olması gerekir.

Ö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önüş türlerine, yöntem parametrelerine, ve ayrıştırılabilir alanları.

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 primitif olmayan türler, referansla iletilir. Bu değer null olabilir.

PBM arka ucunda @nullable T, Android'de std::unique_ptr<T> ile eşlenir. 11 veya önceki bir sürüme, Android'de std::optional<T> sürümüne kadar 12 veya üzeri olmalıdır.

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>>> (veya PBM arka ucu durumunda std::unique_ptr<std::vector<std::unique_ptr<T>>> .

Bu eşlemenin bir istisnası vardır. T olduğunda IBinder veya bir AIDL arayüzü, @nullable işlemsiz. Başka bir deyişle, hem @nullable IBinder ve IBinder, android::sp<IBinder> ile eşit olarak eşlenir. Bu, Güçlü bir işaretçi olduğu için zaten null olabilir (PBM hâlâ null değeri zorunlu kıl, ancak tür yine de android::sp<IBinder>.)

@nullable(heap=true), Android 13'ten itibaren şunun için kullanılabilir: ayrıştırılabilir alanları kullanarak özyinelemeli türleri modelleyebilir. @nullable(heap=true) kullanılamıyor yöntemini kullanın. Not eklendiğinde, alan PBM/NDK'da yığınla ayrılmış bir std::unique_ptr<T> referansına eşlenir. arka uçlar. @nullable(heap=true), Java arka ucunda işlemsizdir.

utf8InCpp

utf8InCpp, String öğesinin PBM için UTF8 biçiminde temsil edildiğini bildirir arka uçta olması gerekir. 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'da UTF8'dir arka uçta olması gerekir.

Bu ek açıklama, String türünün kullanılabildiği her yere eklenebilir. dahil olmak üzere, dönüş değerleri, parametreler, sabit bildirimler ve ayrıştırılabilir alanları.

PBM 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, çalışma şeklini değiştirmediğini unutmayın. dizeler kablo üzerinden iletilir. Dizeler her zaman UTF16 olarak aktarılır işe yarıyor. utf8InCpp ek açıklamalı bir dizesi, işleyeceğiz. Alınan dizeler UTF16'dan UTF8'e dönüştürülür. utf8InCpp olarak notlandırıldı.

Eski İstikrar

VintfStability, kullanıcı tanımlı bir türün (arayüz, ayrıştırılabilir, ve enum) sistem ve tedarikçi alanlarında kullanılabilir. Görüntüleyin HAL'ler için AIDL: birlikte çalışabilirliği sağlayabilirsiniz.

Ek açıklama, türün imzasını değiştirmez ancak belirtildiğinde türün örneği, seyahat edebilmesi için sabit olarak işaretlenir hem de tedarikçiyle ve sistemle alakalı bilgiler içerebilir.

Ek açıklama, yalnızca gösterildiği gibi kullanıcı tanımlı tür bildirimlerine eklenebilir buradan inceleyebilirsiniz:

@VintfStability
interface IFoo {
    ....
}

@VintfStability
parcelable Data {
    ....
}

@VintfStability
enum Type {
    ....
}

Bir türe VintfStability ek açıklaması yapıldığında, aynı zamanda bu şekilde ek açıklama da eklenmelidir. Sonraki örneğin, Data ve 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 ile açıklama eklenen türleri tanımlayan AIDL dosyaları yalnızca aidl_interface Mostg modül türü kullanılarak oluşturulabilir. stability özelliği "vintf" olarak ayarlandı.

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

DesteklenmeyenUygulama Kullanımı

UnsupportedAppUsage ek açıklaması, açıklama eklenen AIDL türünün kullanıma sunulan SDK dışı arayüzün bir parçasıdır. SDK dışı kısıtlamalara göz atın arayüzler bakın.

UnsupportedAppUsage ek açıklaması, oluşturulmuş kod. Ek açıklama, oluşturulan Java sınıfına yalnızca Aynı ada sahip Java ek açıklaması.

// 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 öğesinin byte olduğu varsayılır ve bu, PBM arka ucu için int8_t olarak ayarlanır.

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, paketlenebilir beyanı işaret ediyor (tanım değil) diğer kararlı AIDL türlerinden referans alınabilmesi için kararlı olarak çalışır. Bu JavaOnlyStableParcelable gibidir, ancak NdkOnlyStableParcelable, paketlenebilir beyanı NDK için sabit olarak işaretler arka uç sağlar.

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 olacak şekilde derlenebilir. Örneğin, bir sanal makinedeki çekirdek derleme sisteminde cc_* modülünü, static_libs veya shared_libs kullanın. aidl_interface için, Android.bp konumunda additional_shared_libraries altındaki kitaplık.

JavaOnlyStableParcelable

JavaOnlyStableParcelable, paketlenebilir beyanı işaret ediyor (tanım değil) diğer kararlı AIDL türlerinden referans alınabilmesi için kararlı olarak çalışır.

Kararlı AIDL, kullanıcı tanımlı tüm türlerin kararlı olmasını gerektirir. Örneğin, olması için, bu kriterlere uygun kriterlere ve mevcut AIDL kaynak dosyası.

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 sadece beyan edilmişse) yapılamaz. referans alın.

parcelable Data; // Data is NOT a structured parcelable

parcelable AnotherData {
    Data d; // Error
}

JavaOnlyStableParcelable, ayrıştırılabilir öğe olduğunda kontrolü geçersiz kılmanıza olanak tanır. Android SDK'sının bir parçası olarak güvenli bir şekilde kullanılabiliyor.

@JavaOnlyStableParcelable
parcelable Data;

parcelable AnotherData {
    Data d; // OK
}

JavaDerive

JavaDerive, Java arka ucu.

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

Bu ek açıklama, gösterilecek öğeleri kontrol etmek için ek parametrelere üretir. Desteklenen parametreler şunlardır:

• equals=true, equals ve hashCode yöntemleri oluşturur.
• toString=true, türün adını yazdıran toString yöntemi oluşturur birlikte çalışır. Örnek: Data{number: 42, str: foo}

JavaVarsayılan

Android 13'te eklenen JavaDefault, şunları kontrol eder: varsayılan uygulama sürüm oluşturma desteği oluşturulur ( setDefaultImpl) tıklayın. Bu destek, yıl sonuna kadar tasarruf edin.

JavaGeçişi

JavaPassthrough, oluşturulan Java API'ye rastgele bir ek açıklama eklenmesine olanak tanır Java ek açıklaması.

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 derleyici, parametrenin değerine bakmaz. Varsa Java düzeyinde söz dizimi hatası; AIDL derleyicisi tarafından değil, Java derleyicisi.

Bu ek açıklama, herhangi bir AIDL varlığına eklenebilir. Bu ek açıklama, işlemsiz arka uçları için daha iyi bir çözümdür.

Sabit Boyut

FixedSize, yapılandırılmış bir ayrıştırılabilir öğeyi sabit boyut olarak işaretler. İşaretlendikten sonra, ayrıştırılabilir öğe içine yeni alan eklenmesine izin verilmez. Tüm alanları ayrıştırılabilir öğe ayrıca, ilkel türler dahil olmak üzere sabit boyutlu türler olmalıdır. enum'lar, sabit boyutlu diziler ve FixedSize ile işaretlenen diğer ayrıştırıcılar.

Bu, farklı bölümler için herhangi bir garanti vermez ve karma bitlikte iletişimde temel alınır.

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. Öğe Descriptor ek açıklaması eksik; açıklayıcı android.foo.IHello.

Bu, yayınlanmış bir arayüzü yeniden adlandırırken işinize yarayacaktır. Proje yönetiminin arayüzün tanımlayıcısıyla aynı şekilde, yeniden adlandırılan arayüzün tanımlayıcısı İki arayüzün birbiriyle iletişim kurmasına izin vermeden önce.

@yorumlarda gizle

AIDL derleyicisi, yorumlarda @hide öğesini tanır ve iletir metalava için Java çıktısını verir. Bu yorum, Android'in derleme sistemi AIDL API'lerinin SDK API'leri olmadığını bilir.

@yorumlarda kullanımdan kaldırıldı

AIDL derleyicisi, yorumlardaki @deprecated öğesini bir etiket olarak tanır ve Artık kullanılmaması gereken AIDL varlığı.

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çıklamayla veya özelliğini kullanmanız gerekir. Böylece, istemcinin kodu kullanımdan kaldırılan varlıklarından oluşur. Örneğin, @Deprecated ek açıklaması ve @deprecated etiketi, Java tarafından oluşturulan koda eklenir.