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_interface
Nowg 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 sistemindestatic_libs
veyashared_libs
kullanın.aidl_interface
için kitaplığıAndroid.bp
içindekiadditional_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
vehashCode
yöntemleri oluşturur.toString=true
, tür ve alanların adını yazdırantoString
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.