AIDL, oluşturulan saplama kodunu da etkileyen açıklamalı öğe hakkında AIDL derleyicisine ek bilgi veren 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çıklamalar, yukarıda gösterildiği gibi parantez içinde ayarlanmış bağımsız değişkenlere sahip olabilir. Argümanı olmayan ek açıklamalar parantez gerektirmez. Örneğin:
@AnnotationName AidlEntity
Bu ek açıklamalar, çok benzer görünseler de Java ek açıklamaları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 ve diğer arka uçlarda işlem yapılmaz. Bağlanabilecekleri farklı kısıtlamaları vardır.
Aşağıda önceden tanımlanmış AIDL ek açıklamalarının listesi bulunmaktadır:
Ek açıklamalar | Android sürümünde eklendi |
---|---|
nullable | 7 |
utf8InCpp | 7 |
VintfStability | 11 |
UnsupportedAppUsage | 10 |
Hide | 11 |
Backing | 11 |
JavaOnlyStableParcelable | 11 |
JavaDerive | 12 |
JavaPassthrough | 12 |
FixedSize | 12 |
Descriptor | 12 |
null
nullable
, açıklamalı varlığın değerinin sağlanamayacağını beyan eder.
Bu 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;
}
İlkel türlere ek açıklamalar 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 tüm ilkel olmayan türlerin başvuru yoluyla iletilmesidir, bu da null
olabilir.
CPP arka @nullable T
, Android 11 veya önceki sürümlerde std::unique_ptr<T>
unique_ptr<T> ile ve Android 12 veya sonraki sürümlerde std::optional<T>
ile eşlenir.
NDK arka @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 std::unique_ptr<std::vector<std::unique_ptr<T>>>
) ile eşlenir std::unique_ptr<std::vector<std::unique_ptr<T>>>
Android 11 veya altı için CPP arka ucu olması durumunda).
Bu haritalamanın bir istisnası vardır. T
, IBinder
veya bir AIDL arabirimi olduğunda, @nullable
. Başka bir deyişle, hem @nullable IBinder
hem de IBinder
eşit olarak android::sp<IBinder>
ile eşlenir; bu, güçlü bir işaretçi olduğu için zaten null olabilir (CPP okumaları hala null yapılabilirliği zorlar, ancak tür hala android::sp<IBinder>
).
Android 13'ten başlayarak, özyinelemeli türleri modellemek için ayrıştırılabilir alanlar için @nullable(heap=true)
kullanılabilir. @nullable(heap=true)
yöntem parametreleri veya dönüş türleri ile kullanılamaz. Bununla açıklama eklendiğinde alan, CPP/NDK arka uçlarında yığınla ayrılmış bir başvuru std::unique_ptr<T>
ile eşlenir. @nullable(heap=true)
, Java arka ucunda işlem yapılmaz.
utf8InCpp
utf8InCpp
, bir String
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. Spesifik olarak, String
her zaman Java arka ucunda UTF16 ve NDK arka ucunda UTF8'dir.
Bu açıklama, dönüş değerleri, parametreler, sabit bildirimler ve ayrıştırılabilir alanlar dahil olmak üzere String
türünün kullanılabileceği her yere eklenebilir.
CPP arka ucu için, @utf8InCpp String
, std::string
ile eşlenirken, 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 iletilir. Bir utf8InCpp
açıklamalı dize, iletilmeden önce UTF16'ya dönüştürülür. Bir dize alındığında, utf8InCpp olarak açıklama eklenmişse utf8InCpp
.
VintfStability
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ısı birlikte çalışabilirliği hakkında daha fazla bilgi için HAL'ler için AIDL'ye bakın.
Açıklama, türün imzasını değiştirmez, ancak ayarlandığında, satıcı ve sistem süreçlerinde dolaşabilmesi için türün örneği kararlı olarak işaretlenir.
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 türler de bu şekilde açıklanmalıdır. Aşağıdaki örnekte, Data
ve IBar
her ikisi de VintfStability
ile açıklanmalıdır.
@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 VintfStability
dosyaları, stability
özelliği "vintf"
olarak ayarlanmış yalnızca aidl_interface
Soong modül türü kullanılarak 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şilebilir olan SDK olmayan arabirimin bir parçası olduğunu belirtir. Gizli API'ler hakkında daha fazla bilgi için SDK olmayan arabirimlerdeki kısıtlamalara bakın.
UnsupportedAppUsage
ek açıklaması, oluşturulan kodun davranışını etkilemez. 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 bir işlem değildir.
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ıdaki, int32_t
türünde bir C++ enum sınıfı yayar.
enum class Color : int32_t {
RED = 0,
BLUE = 1,
}
Açıklama atlanırsa, type
byte
olduğu varsayılır ve bu, CPP 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şliğinde) -
int
(32 bit genişliğinde) -
long
(64 bit genişliğinde)
JavaOnlyStableParcelable
JavaOnlyStableParcelable
, ayrıştırılabilir bir bildirimi (tanım değil) kararlı olarak işaretler, böylece diğer kararlı AIDL türlerinden başvurulabilir.
Kararlı AIDL, tüm kullanıcı tanımlı 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
}
Ayrıştırılabilir yapılandırılmamışsa (veya henüz bildirilmişse), başvuru yapılamaz.
parcelable Data; // Data is NOT a structured parcelable
parcelable AnotherData {
Data d; // Error
}
JavaOnlyStableParcelable
, başvurduğunuz ayrıştırılabilir öğe Android SDK'nın bir parçası olarak zaten güvenli bir şekilde mevcut olduğunda denetimi geçersiz kılmanıza olanak tanır.
@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;
}
Açıklama, neyin üretileceğini kontrol etmek için ek parametreler gerektirir. Desteklenen parametreler şunlardır:
-
equals=true
,equals
vehashCode
yöntemlerini üretir. -
toString=true
, türün ve alanların adını yazdırantoString
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şturulmayacağını kontrol eder ( setDefaultImpl
için). Bu destek artık yerden tasarruf etmek için varsayılan olarak oluşturulmaz.
JavaGeçiş
JavaPassthrough
, oluşturulan Java API'sinin isteğe bağlı bir Java ek açıklamasıyla açıklanmasını sağlar.
AIDL'de aşağıdaki açıklamalar
@JavaPassthrough(annotation="@android.annotation.Alice")
@JavaPassthrough(annotation="@com.android.Alice(arg=com.android.Alice.Value.A)")
olmak
@android.annotation.Alice
@com.android.Alice(arg=com.android.Alice.Value.A)
oluşturulan Java kodunda.
annotation
parametresinin değeri doğrudan yayınlanı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 yakalanır.
Bu açıklama, herhangi bir AIDL varlığına eklenebilir. Bu ek açıklama, Java dışı arka uçlar için bir işlem değildir.
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 alanların eklenmesine izin verilmeyecektir. Ayrıştırılabilir öğenin tüm alanları, ilkel türler, numaralandırmalar, sabit boyutlu diziler ve FixedSize
ile işaretlenmiş diğer parsellenebilirler de dahil olmak üzere sabit boyutlu türler olmalıdır.
Bu, farklı bitlikler arasında herhangi bir garanti sağlamaz ve karma bitlik iletişim için güvenilmemelidir.
tanımlayıcı
Descriptor
, bir arabirimin arabirim 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
şeklindedir. Descriptor
ek açıklaması eksikse, tanımlayıcı android.foo.IHello
olacaktır.
Bu, önceden yayınlanmış bir arabirimi 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ına izin verir.
@yorumlarda gizle
AIDL derleyicisi yorumlarda @hide
tanır ve metalava'nın alınması için bunu Java çıktısı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
etiketini tanır.
interface IFoo {
/** @deprecated use bar() instead */
void foo();
void bar();
}
Her arka uç, kullanımdan kaldırılan varlıkları, kullanımdan kaldırılan varlıklara atıfta bulunursa müşteri kodunun uyarılması için arka uca özel bir açıklama/öznitelikle işaretler. Örneğin, @Deprecated
ek açıklaması ve @deprecated
etiketi, Java tarafından oluşturulan koda eklenir.