AIDL hỗ trợ các chú thích cung cấp cho trình biên dịch AIDL thông tin bổ sung về phần tử được chú thích, điều này cũng ảnh hưởng đến mã sơ khai đã tạo.
Cú pháp tương tự như của Java:
@AnnotationName(argument1=value, argument2=value) AidlEntity
Ở đây, AnnotationName
là tên của chú thích và AidlEntity
là một thực thể AIDL như interface Foo
, void method()
hoặc int arg
. Chú thích được đính kèm với thực thể theo sau nó.
Một số chú thích có thể có các đối số được đặt bên trong dấu ngoặc đơn, như được hiển thị ở trên. Các chú thích không có đối số không cần dấu ngoặc đơn. Ví dụ:
@AnnotationName AidlEntity
Các chú thích này không giống với các chú thích Java, mặc dù chúng trông rất giống nhau. Người dùng không thể xác định chú thích AIDL tùy chỉnh; các chú thích đều được xác định trước. Một số chú thích chỉ ảnh hưởng đến một phần phụ trợ nhất định và không có trong các phần phụ trợ khác. Chúng có các hạn chế khác nhau mà chúng có thể được gắn vào.
Dưới đây là danh sách các chú thích AIDL được xác định trước:
Chú thích | Đã thêm vào phiên bản Android |
---|---|
nullable | 7 |
utf8InCpp | 7 |
VintfStability | 11 |
UnsupportedAppUsage | 10 |
Hide | 11 |
Backing | 11 |
JavaOnlyStableParcelable | 11 |
JavaDerive | 12 |
JavaPassthrough | 12 |
FixedSize | 12 |
Descriptor | 12 |
vô hiệu
nullable
tuyên bố rằng giá trị của thực thể được chú thích có thể không được cung cấp.
Chú thích này chỉ có thể được đính kèm với các kiểu trả về phương thức, tham số phương thức và các trường có thể phân chia.
interface IFoo {
// method return types
@nullable Data method();
// method parameters
void method2(in @nullable Data d);
}
parcelable Data {
// parcelable fields
@nullable Data d;
}
Không thể đính kèm chú thích vào kiểu nguyên thủy. Sau đây là một lỗi.
void method(in @nullable int a); // int is a primitive type
Chú thích này không phù hợp với chương trình phụ trợ Java. Điều này là do, trong Java, tất cả các kiểu không nguyên thủy đều được truyền bằng tham chiếu, có thể là null
.
Trong phần phụ trợ CPP, @nullable T
ánh xạ tới std::unique_ptr<T>
trong Android 11 trở xuống và std::optional<T>
trong Android 12 trở lên.
Trong phần phụ trợ NDK, @nullable T
luôn ánh xạ tới std::optional<T>
.
Đối với kiểu danh sách giống như L
, chẳng hạn như T[]
hoặc List<T>
, @nullable L
ánh xạ tới std::optional<std::vector<std::optional<T>>>
(hoặc std::unique_ptr<std::vector<std::unique_ptr<T>>>
trong trường hợp phụ trợ CPP cho Android 11 trở xuống).
Có một ngoại lệ cho ánh xạ này. Khi T
là IBinder
hoặc giao diện AIDL, @nullable
là cấm. Nói cách khác, cả @nullable IBinder
và IBinder
đều ánh xạ như nhau tới android::sp<IBinder>
, đã có giá trị nullable vì nó là một con trỏ mạnh (CPP đọc vẫn thực thi tính nullability, nhưng kiểu vẫn là android::sp<IBinder>
).
Bắt đầu với Android T (thử nghiệm AOSP), @nullable(heap=true)
có thể được sử dụng cho các trường có thể phân chia để lập mô hình các kiểu đệ quy. @nullable(heap=true)
không thể được sử dụng với các tham số phương thức hoặc kiểu trả về. Khi được chú thích với nó, trường được ánh xạ tới tham chiếu được phân bổ theo heap std::unique_ptr<T>
trong phần phụ trợ CPP / NDK. @nullable(heap=true)
là no-op trong chương trình phụ trợ Java.
utf8InCpp
utf8InCpp
tuyên bố rằng một String
được biểu diễn ở định dạng UTF8 cho phần phụ trợ CPP. Như tên của nó đã chỉ ra, chú thích không phải là lựa chọn cho các phần phụ trợ khác. Cụ thể, String
luôn là UTF16 trong chương trình phụ trợ Java và UTF8 trong chương trình phụ trợ NDK.
Chú thích này có thể được đính kèm ở bất kỳ đâu mà kiểu String
có thể được sử dụng, bao gồm giá trị trả về, tham số, khai báo hằng và các trường có thể phân chia.
Đối với phần phụ trợ CPP, @utf8InCpp String
trong AIDL ánh xạ tới std::string
, trong khi String
không có chú thích sẽ ánh xạ tới android::String16
nơi UTF16 được sử dụng.
Lưu ý rằng sự tồn tại của chú thích utf8InCpp
không thay đổi cách các chuỗi được truyền qua dây. Chuỗi luôn được truyền dưới dạng UTF16 qua dây. Một chuỗi chú thích utf8InCpp
được chuyển đổi thành UTF16 trước khi nó được truyền đi. Khi một chuỗi được nhận, nó được chuyển đổi từ UTF16 sang UTF8 nếu nó được chú thích là utf8InCpp
.
VintfStability
VintfStability
tuyên bố rằng một kiểu do người dùng xác định (giao diện, có thể phân loại và enum) có thể được sử dụng trên toàn hệ thống và miền của nhà cung cấp. Xem AIDL cho HAL để biết thêm về khả năng tương tác giữa nhà cung cấp hệ thống.
Chú thích không thay đổi chữ ký của loại, nhưng khi nó được đặt, phiên bản của loại được đánh dấu là ổn định để nó có thể di chuyển qua các quy trình của nhà cung cấp và hệ thống.
Chú thích chỉ có thể được đính kèm vào khai báo kiểu do người dùng xác định như được hiển thị bên dưới:
@VintfStability
interface IFoo {
....
}
@VintfStability
parcelable Data {
....
}
@VintfStability
enum Type {
....
}
Khi một kiểu được chú thích bằng VintfStability
, bất kỳ kiểu nào khác được tham chiếu trong kiểu cũng phải được chú thích như vậy. Trong ví dụ dưới đây, Data
và IBar
đều phải được chú thích bằng VintfStability
.
@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 {...}
Ngoài ra, các tệp AIDL xác định các loại được chú thích bằng VintfStability
chỉ có thể được tạo bằng cách sử dụng loại mô-đun aidl_interface
Soong, với thuộc stability
được đặt thành "vintf"
.
aidl_interface {
name: "my_interface",
srcs: [...],
stability: "vintf",
}
Không được hỗ trợAppUsage
Chú thích UnsupportedAppUsage
biểu thị rằng loại AIDL được chú thích là một phần của giao diện không phải SDK có thể truy cập được cho các ứng dụng cũ. Xem Hạn chế đối với giao diện không phải SDK để biết thêm thông tin về các API ẩn.
Chú thích Ứng dụng UnsupportedAppUsage
không ảnh hưởng đến hoạt động của mã được tạo. Chú thích chỉ chú thích lớp Java được tạo với chú thích Java cùng tên.
// in AIDL
@UnsupportedAppUsage
interface IFoo {...}
// in Java
@android.compat.annotation.UnsupportedAppUsage
public interface IFoo {...}
Đây là điều không cần thiết cho các chương trình phụ trợ không phải Java.
Sao lưu
Chú thích Backing
lưu chỉ định kiểu lưu trữ của kiểu enum AIDL.
@Backing(type="int")
enum Color { RED, BLUE, }
Trong phần phụ trợ CPP, phần trên tạo ra một lớp enum C ++ kiểu int32_t
.
enum class Color : int32_t {
RED = 0,
BLUE = 1,
}
Nếu chú thích bị bỏ qua, type
được giả định là byte
, ánh xạ tới int8_t
cho phần phụ trợ CPP.
Đối số type
chỉ có thể được đặt thành các kiểu tích phân sau:
-
byte
(rộng 8 bit) -
int
(rộng 32-bit) -
long
(rộng 64 bit)
JavaOnlyStableParcelable
JavaOnlyStableParcelable
đánh dấu một khai báo parcelable (không phải định nghĩa) là ổn định để nó có thể được tham chiếu từ các loại AIDL ổn định khác.
AIDL ổn định yêu cầu tất cả các loại do người dùng xác định phải ổn định. Đối với bưu kiện, việc ổn định yêu cầu các trường của nó được mô tả rõ ràng trong tệp nguồn AIDL.
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
}
Nếu parcelable không có cấu trúc (hoặc chỉ được khai báo), thì nó không thể được tham chiếu.
parcelable Data; // Data is NOT a structured parcelable
parcelable AnotherData {
Data d; // Error
}
JavaOnlyStableParcelable
cho phép bạn ghi đè kiểm tra khi bưu kiện mà bạn đang tham chiếu đã có sẵn một cách an toàn như một phần của Android SDK.
@JavaOnlyStableParcelable
parcelable Data;
parcelable AnotherData {
Data d; // OK
}
JavaDerive
JavaDerive
tự động tạo ra các phương thức cho các kiểu có thể thay thế trong chương trình phụ trợ Java.
@JavaDerive(equals = true, toString = true)
parcelable Data {
int number;
String str;
}
Chú thích yêu cầu các tham số bổ sung để kiểm soát nội dung sẽ tạo. Các thông số được hỗ trợ là:
-
equals=true
tạo ra các phương thứcequals
vàhashCode
. -
toString=true
tạo ra phương thứctoString
in ra tên của kiểu và các trường. Ví dụ:Data{number: 42, str: foo}
JavaDefault
JavaDefault
, được thêm vào Android T (thử nghiệm AOSP), kiểm soát việc hỗ trợ lập phiên bản triển khai mặc định có được tạo hay không (cho setDefaultImpl
). Hỗ trợ này không còn được tạo theo mặc định để tiết kiệm dung lượng.
JavaPassthrough
JavaPassthrough
cho phép chú thích Java API đã tạo bằng một chú thích Java tùy ý.
Các chú thích sau trong AIDL
@JavaPassthrough(annotation="@android.annotation.Alice")
@JavaPassthrough(annotation="@com.android.Alice(arg=com.android.Alice.Value.A)")
trở thành
@android.annotation.Alice
@com.android.Alice(arg=com.android.Alice.Value.A)
trong mã Java được tạo.
Giá trị của tham số annotation
được phát trực tiếp. Trình biên dịch AIDL không xem xét giá trị của tham số. Nếu có bất kỳ lỗi cú pháp cấp Java nào, nó sẽ không bị trình biên dịch AIDL bắt mà bởi trình biên dịch Java.
Chú thích này có thể được đính kèm với bất kỳ thực thể AIDL nào. Chú thích này không phù hợp với các phần mềm phụ trợ không phải Java.
Kích thước cố định
FixedSize
đánh dấu một gói có cấu trúc là kích thước cố định. Sau khi được đánh dấu, bưu kiện sẽ không được phép thêm các trường mới vào đó. Tất cả các trường của thửa đất cũng phải là loại có kích thước cố định, bao gồm các loại nguyên thủy, enum, mảng có kích thước cố định và các thửa khác được đánh dấu bằng FixedSize
.
Điều này không cung cấp bất kỳ đảm bảo nào giữa các bitness khác nhau và không nên dựa vào giao tiếp bitness hỗn hợp.
Bộ mô tả
Bộ Descriptor
bắt buộc chỉ định bộ mô tả giao diện của một giao diện.
package android.foo;
@Descriptor(value="android.bar.IWorld")
interface IHello {...}
Bộ mô tả của giao diện trên là android.bar.IWorld
. Nếu chú thích Bộ mô Descriptor
bị thiếu, bộ mô tả sẽ là android.foo.IHello
.
Điều này rất hữu ích để đổi tên một giao diện đã được xuất bản. Làm cho bộ mô tả của giao diện được đổi tên giống như bộ mô tả của giao diện trước khi đổi tên cho phép hai giao diện nói chuyện với nhau.
@hide trong nhận xét
Trình biên dịch AIDL nhận ra @hide
trong các nhận xét và chuyển nó qua đầu ra Java để nhận metalava. Nhận xét này đảm bảo rằng hệ thống xây dựng Android biết rằng API AIDL không phải là API SDK.
@deprecated trong nhận xét
Trình biên dịch AIDL nhận ra @deprecated
trong nhận xét dưới dạng thẻ để xác định một thực thể AIDL không còn được sử dụng nữa.
interface IFoo {
/** @deprecated use bar() instead */
void foo();
void bar();
}
Mỗi chương trình phụ trợ đánh dấu các thực thể không dùng nữa bằng chú thích / thuộc tính dành riêng cho phần mềm phụ trợ để mã khách hàng được cảnh báo nếu nó tham chiếu đến các thực thể không được dùng nữa. Ví dụ: chú thích @Deprecated
và thẻ @deprecated
được đính kèm với mã do Java tạo.