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